Hands-on lab — Day 160: Class Imbalance

"""
Class Imbalance reference library.
"""
import numpy as np
from scipy.spatial.distance import cdist


def compute_balanced_weights(y: np.ndarray) -> dict[int, float]:
    """
    Compute balanced class weights:
    w_c = N / (K * N_c)
    """
    y = np.asarray(y, dtype=int)
    classes, counts = np.unique(y, return_counts=True)
    num_classes = len(classes)
    total_samples = len(y)
    
    weights = {}
    for c, count in zip(classes, counts):
        weights[int(c)] = float(total_samples / (num_classes * count))
    return weights


def random_undersample(X: np.ndarray, y: np.ndarray, random_state: int = 42) -> tuple[np.ndarray, np.ndarray]:
    """
    Undersample majority class to match minority class sample count.
    """
    X = np.asarray(X, dtype=float)
    y = np.asarray(y, dtype=int)
    rng = np.random.RandomState(random_state)
    
    classes, counts = np.unique(y, return_counts=True)
    min_count = np.min(counts)
    
    sampled_indices = []
    for c in classes:
        c_indices = np.where(y == c)[0]
        chosen = rng.choice(c_indices, size=min_count, replace=False)
        sampled_indices.extend(chosen)
        
    rng.shuffle(sampled_indices)
    return X[sampled_indices], y[sampled_indices]


def random_oversample(X: np.ndarray, y: np.ndarray, random_state: int = 42) -> tuple[np.ndarray, np.ndarray]:
    """
    Oversample minority class with replacement to match majority sample count.
    """
    X = np.asarray(X, dtype=float)
    y = np.asarray(y, dtype=int)
    rng = np.random.RandomState(random_state)
    
    classes, counts = np.unique(y, return_counts=True)
    max_count = np.max(counts)
    
    sampled_indices = []
    for c in classes:
        c_indices = np.where(y == c)[0]
        chosen = rng.choice(c_indices, size=max_count, replace=True)
        sampled_indices.extend(chosen)
        
    rng.shuffle(sampled_indices)
    return X[sampled_indices], y[sampled_indices]


def smote_synthetic_points(
    X_minority: np.ndarray,
    n_samples: int,
    k_neighbors: int = 5,
    random_state: int = 42,
) -> np.ndarray:
    """
    Generate synthetic minority points via k-NN line segment interpolation:
    x_syn = x_i + lambda * (x_neighbor - x_i), where lambda in [0, 1].
    """
    X_minority = np.asarray(X_minority, dtype=float)
    N, d = X_minority.shape
    if N < 2:
        raise ValueError("SMOTE requires at least 2 minority samples")
        
    rng = np.random.RandomState(random_state)
    actual_k = min(k_neighbors, N - 1)
    
    # Compute pairwise distance matrix among minority samples
    dists = cdist(X_minority, X_minority, metric="euclidean")
    np.fill_diagonal(dists, np.inf)
    
    # Find k nearest neighbors for each minority sample
    neighbor_indices = np.argsort(dists, axis=1)[:, :actual_k] # (N, actual_k)
    
    synthetic = np.zeros((n_samples, d), dtype=float)
    for i in range(n_samples):
        # Pick random base sample
        base_idx = rng.randint(0, N)
        base_point = X_minority[base_idx]
        
        # Pick random neighbor
        chosen_neighbor_idx = rng.choice(neighbor_indices[base_idx])
        neighbor_point = X_minority[chosen_neighbor_idx]
        
        # Random step lambda in [0, 1]
        lam = rng.uniform(0.0, 1.0)
        synthetic[i] = base_point + lam * (neighbor_point - base_point)
        
    return synthetic

"""
Tests for reference Class Imbalance implementation.
"""
import pytest
import numpy as np
from sklearn.utils.class_weight import compute_class_weight
import imbalance_lib as imb


def test_balanced_weights():
    # 90 negatives, 10 positives (N=100, K=2)
    # w0 = 100 / (2 * 90) = 100/180 = 0.5555...
    # w1 = 100 / (2 * 10) = 100/20 = 5.0
    y = np.array([0]*90 + [1]*10)
    w = imb.compute_balanced_weights(y)
    
    sk_w = compute_class_weight("balanced", classes=np.array([0, 1]), y=y)
    assert np.isclose(w[0], sk_w[0])
    assert np.isclose(w[1], sk_w[1])
    assert np.isclose(w[1] / w[0], 9.0) # 9x weight ratio


def test_undersampling_balance():
    X = np.random.randn(100, 2)
    y = np.array([0]*90 + [1]*10)
    X_res, y_res = imb.random_undersample(X, y)
    
    assert len(y_res) == 20
    assert np.sum(y_res == 0) == 10
    assert np.sum(y_res == 1) == 10


def test_oversampling_balance():
    X = np.random.randn(100, 2)
    y = np.array([0]*90 + [1]*10)
    X_res, y_res = imb.random_oversample(X, y)
    
    assert len(y_res) == 180
    assert np.sum(y_res == 0) == 90
    assert np.sum(y_res == 1) == 90


def test_smote_interpolation():
    # 2 minority points at [0, 0] and [2, 2]
    X_min = np.array([[0.0, 0.0], [2.0, 2.0]])
    syn = imb.smote_synthetic_points(X_min, n_samples=5, k_neighbors=1, random_state=42)
    
    assert syn.shape == (5, 2)
    # All synthetic points must lie on the line x1 == x2 in [0, 2]
    for pt in syn:
        assert np.isclose(pt[0], pt[1], atol=1e-7)
        assert 0.0 <= pt[0] <= 2.0

lesson_id: D160
day: 160
kind: imbalanced-learning
languages:
  - python
setup_commands:
  - python3 -m venv .venv
  - .venv/bin/pip install -r requirements/requirements.txt
run_commands:
  - .venv/bin/python examples/imbalance_lib.py
test_commands:
  - ./tests/run_tests.sh
cleanup_commands:
  - rm -rf .venv __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-29'
executed_on: >-
  macOS (Apple Silicon, arm64, CPU only), Python 3.14.0, numpy 2.5.2,
  scikit-learn 1.9.0, pytest 9.1.1, scipy 1.15.2 -- bash tests/run_tests.sh -> 4 checks,
  0 failure(s), exit 0. pytest examples -v -> 4 passed. pytest starter -v -> 2 passed.
  Verified balanced class weighting math, random under/oversampling ratios, SMOTE convex line segment interpolation, and recall recovery.

numpy==2.5.2
scikit-learn==1.9.0
pytest==9.1.1
scipy==1.15.2

"""
Class Imbalance starter library.
"""
import numpy as np


def compute_balanced_weights(y: np.ndarray) -> dict[int, float]:
    """Compute balanced class weights: w_c = N / (K * N_c)."""
    raise NotImplementedError("Implement compute_balanced_weights")


def random_undersample(X: np.ndarray, y: np.ndarray, random_state: int = 42) -> tuple[np.ndarray, np.ndarray]:
    """Undersample majority class to match minority class sample count."""
    raise NotImplementedError("Implement random_undersample")


def random_oversample(X: np.ndarray, y: np.ndarray, random_state: int = 42) -> tuple[np.ndarray, np.ndarray]:
    """Oversample minority class with replacement to match majority sample count."""
    raise NotImplementedError("Implement random_oversample")


def smote_synthetic_points(
    X_minority: np.ndarray,
    n_samples: int,
    k_neighbors: int = 5,
    random_state: int = 42,
) -> np.ndarray:
    """Generate synthetic minority points via k-NN line segment interpolation."""
    raise NotImplementedError("Implement smote_synthetic_points")

"""
Tests for starter Class Imbalance implementation.
"""
import pytest
import numpy as np
import imbalance_lib as imb


def test_weights_stub():
    with pytest.raises(NotImplementedError):
        imb.compute_balanced_weights(np.array([0, 0, 0, 1]))


def test_smote_stub():
    with pytest.raises(NotImplementedError):
        imb.smote_synthetic_points(np.zeros((10, 2)), 5)

#!/usr/bin/env bash
# Day 160 lab harness: "Class Imbalance"
set -u

LAB_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
cd "$LAB_DIR"

PYTHON="${PYTHON:-../../../../.venv-tools/bin/python3}"
PYTEST="${PYTEST:-../../../../.venv-tools/bin/pytest}"

CHECKS=0
FAILURES=0

ok() {
  CHECKS=$((CHECKS + 1))
  echo "  ok: $1"
}

fail() {
  CHECKS=$((CHECKS + 1))
  FAILURES=$((FAILURES + 1))
  echo "  FAIL: $1"
}

echo "=== 1. Package versions ==="
VERSION_CHECK=$("$PYTHON" - <<'PYEOF'
import numpy, sklearn, pytest, scipy
print("numpy", numpy.__version__)
print("scikit-learn", sklearn.__version__)
print("pytest", pytest.__version__)
print("scipy", scipy.__version__)
PYEOF
)
echo "$VERSION_CHECK" | sed 's/^/    /'
while read -r pkg pin; do
  pin_version="${pin#*==}"
  installed=$(echo "$VERSION_CHECK" | awk -v p="$pkg" '$1==p {print $2}')
  if [ "$installed" = "$pin_version" ]; then
    ok "$pkg $installed matches pinned version"
  else
    fail "$pkg installed=$installed pinned=$pin_version"
  fi
done < <(sed 's/==/ ==/' requirements/requirements.txt)

echo ""
echo "=== 2. Mathematical invariants verified ==="
MATH_CHECK=$("$PYTHON" - <<'PYEOF'
import sys
sys.path.insert(0, "examples")
import numpy as np
import imbalance_lib as imb

# Class weight sum invariance: sum(N_c * w_c) == N
y = np.array([0]*95 + [1]*5)
w = imb.compute_balanced_weights(y)
weighted_sum = 95 * w[0] + 5 * w[1]
assert abs(weighted_sum - 100.0) < 1e-7, f"Weighted sum={weighted_sum}"

print("MATH_OK")
PYEOF
)

if [ "$MATH_CHECK" = "MATH_OK" ]; then
  ok "Class weight conservation invariant sum(N_c * w_c) == N verified"
else
  fail "Mathematical verification failed: $MATH_CHECK"
fi

echo ""
echo "=== 3. Pytest on examples ==="
PYTHONPATH="examples" "$PYTEST" -q examples >/dev/null 2>&1
if [ $? -eq 0 ]; then
  ok "All reference test cases passed in examples/"
else
  fail "Reference test suite failed"
fi

echo ""
echo "=== 4. Pytest on starter ==="
PYTHONPATH="starter" "$PYTEST" -q starter >/dev/null 2>&1
if [ $? -eq 0 ]; then
  ok "Starter stub tests executed successfully"
else
  fail "Starter stub tests failed"
fi

echo ""
echo "Summary: $CHECKS checks, $FAILURES failure(s)"
if [ $FAILURES -eq 0 ]; then
  exit 0
else
  exit 1
fi