Hands-on lab — Day 170: Feature Scaling and Encoding

"""
Feature Scaling and Encoding reference library implementation.
"""
import numpy as np
from sklearn.model_selection import KFold


class StandardScalerScratch:
    """
    Standardize features: z = (x - mu) / sigma
    """
    def __init__(self):
        self.mean_ = None
        self.scale_ = None

    def fit(self, X: np.ndarray):
        X = np.asarray(X, dtype=float)
        self.mean_ = np.mean(X, axis=0)
        self.scale_ = np.std(X, axis=0)
        # Avoid division by zero for constant features
        self.scale_ = np.where(self.scale_ < 1e-9, 1.0, self.scale_)
        return self

    def transform(self, X: np.ndarray) -> np.ndarray:
        X = np.asarray(X, dtype=float)
        return (X - self.mean_) / self.scale_

    def fit_transform(self, X: np.ndarray) -> np.ndarray:
        return self.fit(X).transform(X)


class RobustScalerScratch:
    """
    Robust scaling using median and Interquartile Range (IQR = Q75 - Q25):
    z = (x - median) / IQR
    """
    def __init__(self):
        self.center_ = None
        self.scale_ = None

    def fit(self, X: np.ndarray):
        X = np.asarray(X, dtype=float)
        self.center_ = np.median(X, axis=0)
        q25 = np.percentile(X, 25, axis=0)
        q75 = np.percentile(X, 75, axis=0)
        iqr = q75 - q25
        self.scale_ = np.where(iqr < 1e-9, 1.0, iqr)
        return self

    def transform(self, X: np.ndarray) -> np.ndarray:
        X = np.asarray(X, dtype=float)
        return (X - self.center_) / self.scale_

    def fit_transform(self, X: np.ndarray) -> np.ndarray:
        return self.fit(X).transform(X)


def out_of_fold_target_encode(
    categories: np.ndarray, target: np.ndarray, cv: int = 5, smoothing: float = 10.0, random_state: int = 42
) -> np.ndarray:
    """
    Compute leak-free Out-of-Fold smoothed target encoding:
    S_c = (n_c * mean_c + smoothing * global_mean) / (n_c + smoothing)
    """
    categories = np.asarray(categories)
    target = np.asarray(target, dtype=float)
    n_samples = len(categories)
    encoded = np.zeros(n_samples, dtype=float)
    
    kf = KFold(n_splits=cv, shuffle=True, random_state=random_state)
    
    for train_idx, val_idx in kf.split(categories, target):
        cat_tr, y_tr = categories[train_idx], target[train_idx]
        cat_va = categories[val_idx]
        
        global_mean = np.mean(y_tr)
        
        # Compute category statistics on training fold ONLY
        unique_cats, counts = np.unique(cat_tr, return_counts=True)
        cat_sums = {c: np.sum(y_tr[cat_tr == c]) for c in unique_cats}
        cat_counts = dict(zip(unique_cats, counts))
        
        # Apply smoothed formula to validation fold
        val_encoded = np.zeros(len(cat_va))
        for i, c in enumerate(cat_va):
            if c in cat_counts:
                n_c = cat_counts[c]
                sum_c = cat_sums[c]
                val_encoded[i] = (sum_c + smoothing * global_mean) / (n_c + smoothing)
            else:
                # Unseen category gets global training mean
                val_encoded[i] = global_mean
                
        encoded[val_idx] = val_encoded
        
    return encoded

"""
Tests for reference feature scaling and encoding.
"""
import pytest
import numpy as np
import scaling_encoding_lib as se


def test_standard_scaler_mean_and_variance():
    rng = np.random.default_rng(42)
    X = rng.normal(loc=10.0, scale=3.0, size=(1000, 3))
    
    scaler = se.StandardScalerScratch()
    X_std = scaler.fit_transform(X)
    
    assert np.allclose(np.mean(X_std, axis=0), 0.0, atol=1e-7)
    assert np.allclose(np.std(X_std, axis=0), 1.0, atol=1e-7)


def test_robust_scaler_outlier_resilience():
    # Data with extreme outliers
    X = np.array([[1.0], [2.0], [3.0], [4.0], [5.0], [10000.0]])
    
    scaler = se.RobustScalerScratch()
    X_rob = scaler.fit_transform(X)
    
    # Median is (3+4)/2 = 3.5 -> centered around 0
    assert np.isclose(np.median(X_rob, axis=0)[0], 0.0, atol=1e-7)


def test_oof_target_encoding_leak_free():
    # 3 categories: High (target=1.0), Low (target=0.0), Mix (target=0.5)
    cats = np.array(["High"] * 50 + ["Low"] * 50 + ["Mix"] * 50)
    target = np.array([1.0] * 50 + [0.0] * 50 + [0.0] * 25 + [1.0] * 25)
    
    encoded = se.out_of_fold_target_encode(cats, target, cv=5, smoothing=5.0)
    
    # "High" encoded values should be significantly higher than "Low"
    assert np.mean(encoded[:50]) > 0.80
    assert np.mean(encoded[50:100]) < 0.20
    assert len(encoded) == 150

lesson_id: D170
day: 170
kind: feature-engineering-primitives
languages:
  - python
setup_commands:
  - python3 -m venv .venv
  - .venv/bin/pip install -r requirements/requirements.txt
run_commands:
  - .venv/bin/python examples/scaling_encoding_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 -> 3 passed. pytest starter -v -> 2 passed.
  Verified StandardScaler, RobustScaler, and out-of-fold smoothed Target Encoding.

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

"""
Feature Scaling and Encoding starter library.
"""
import numpy as np


class StandardScalerScratch:
    """Standardize features by removing mean and scaling to unit variance."""
    def __init__(self):
        self.mean_ = None
        self.scale_ = None

    def fit(self, X: np.ndarray):
        raise NotImplementedError("Implement fit")

    def transform(self, X: np.ndarray) -> np.ndarray:
        raise NotImplementedError("Implement transform")

    def fit_transform(self, X: np.ndarray) -> np.ndarray:
        return self.fit(X).transform(X)


class RobustScalerScratch:
    """Scale features using statistics robust to outliers (Median and IQR)."""
    def __init__(self):
        self.center_ = None
        self.scale_ = None

    def fit(self, X: np.ndarray):
        raise NotImplementedError("Implement fit")

    def transform(self, X: np.ndarray) -> np.ndarray:
        raise NotImplementedError("Implement transform")


def out_of_fold_target_encode(categories: np.ndarray, target: np.ndarray, cv: int = 5, smoothing: float = 10.0, random_state: int = 42) -> np.ndarray:
    """Compute leak-free smoothed out-of-fold target encoding for a categorical column."""
    raise NotImplementedError("Implement out_of_fold_target_encode")

"""
Tests for starter feature scaling and encoding.
"""
import pytest
import numpy as np
import scaling_encoding_lib as se


def test_standard_scaler_stub():
    scaler = se.StandardScalerScratch()
    with pytest.raises(NotImplementedError):
        scaler.fit(np.array([[1.0, 2.0], [3.0, 4.0]]))


def test_target_encode_stub():
    with pytest.raises(NotImplementedError):
        se.out_of_fold_target_encode(np.array(["A", "B"]), np.array([1, 0]))

#!/usr/bin/env bash
# Day 170 lab harness: "Feature Scaling and Encoding"
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 scaling_encoding_lib as se

# StandardScaler Zero-Mean Unit-Variance Invariant
X = np.array([[1.0, 100.0], [2.0, 200.0], [3.0, 300.0]])
scaler = se.StandardScalerScratch()
X_s = scaler.fit_transform(X)
assert np.allclose(np.mean(X_s, axis=0), 0.0), "Mean must be zero"
assert np.allclose(np.std(X_s, axis=0), 1.0), "Variance must be 1.0"

# OOF Target Encoding Bounds
cats = np.array(["A", "A", "B", "B", "C", "C"] * 10)
y = np.array([1, 1, 0, 0, 1, 0] * 10)
enc = se.out_of_fold_target_encode(cats, y, cv=3, smoothing=2.0)
assert len(enc) == 60
assert np.all((enc >= 0.0) & (enc <= 1.0))

print("MATH_OK")
PYEOF
)

if [ "$MATH_CHECK" = "MATH_OK" ]; then
  ok "StandardScaler and Target Encoding mathematical invariants 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