harsh040506/model-evaluation

ML Model Evaluation

Comprehensive, rigorous model evaluation from offline metrics to production monitoring.

---

The Evaluation Pyramid

          Production metrics (online)
              A/B test / shadow deployment
           ──────────────────────────────
          Error analysis + slice analysis
              Calibration + robustness
       ──────────────────────────────────────
              Core task metrics
          (accuracy, F1, RMSE, BLEU...)

Work bottom-up. Core metrics are a prerequisite, not a destination.

---

Metric Reference by Task

Classification

| Metric | Formula | Use when | |--------|---------|---------| | Accuracy | correct / total | Balanced classes, simple baseline | | Precision | TP / (TP + FP) | False positives are costly (spam, fraud) | | Recall | TP / (TP + FN) | False negatives are costly (cancer screening, fraud detection) | | F1 | 2 × (P × R) / (P + R) | Imbalanced classes, balance P and R | | AUROC | Area under ROC curve | Compare models regardless of threshold | | AUPRC | Area under PR curve | Heavily imbalanced datasets (rare event detection) |

Never use accuracy alone on imbalanced datasets. A model that always predicts "negative" on a 99:1 dataset has 99% accuracy but is useless.

from sklearn.metrics import (
    classification_report, confusion_matrix, roc_auc_score, 
    average_precision_score, f1_score
)

# Complete classification report
print(classification_report(y_true, y_pred, target_names=class_names))

# AUROC (for binary)
auroc = roc_auc_score(y_true, y_prob[:, 1])

# AUPRC (better for imbalanced)
auprc = average_precision_score(y_true, y_prob[:, 1])

print(f"AUROC: {auroc:.4f}")
print(f"AUPRC: {auprc:.4f}")

Regression

| Metric | Formula | Interpretation | |--------|---------|---------------| | MAE | mean(|y - ŷ|) | Average absolute error in target units | | RMSE | √mean((y - ŷ)²) | Penalizes large errors more than MAE | | R² | 1 - SS_res/SS_tot | Fraction of variance explained (1.0 = perfect) | | MAPE | mean(|y - ŷ| / y) | Relative error (don't use when y can be near zero) |

from sklearn.metrics import mean_absolute_error, mean_squared_error, r2_score
import numpy as np

mae = mean_absolute_error(y_true, y_pred)
rmse = np.sqrt(mean_squared_error(y_true, y_pred))
r2 = r2_score(y_true, y_pred)

print(f"MAE: {mae:.4f}")
print(f"RMSE: {rmse:.4f}")
print(f"R²: {r2:.4f}")

# Residual analysis (critical — aggregate metrics can hide problems)
residuals = y_true - y_pred
# Should be centered at zero with no systematic pattern

Text Generation

| Metric | What it measures | Limitation | |--------|-----------------|-----------| | BLEU | N-gram overlap with reference | Poor for paraphrase, over-penalizes length | | ROUGE-L | Longest common subsequence | Misses semantic similarity | | BERTScore | Semantic similarity using BERT embeddings | Slower, requires model | | Human eval | Actual quality judgment | Expensive, ground truth |

from evaluate import load

bleu = load("bleu")
rouge = load("rouge")
bertscore = load("bertscore")

# BLEU
result = bleu.compute(predictions=predictions, references=references)

# ROUGE
result = rouge.compute(predictions=predictions, references=references)

# BERTScore (semantic similarity)
result = bertscore.compute(predictions=predictions, references=references, lang="en")
print(f"BERTScore F1: {sum(result['f1'])/len(result['f1']):.4f}")

Human evaluation of 50–100 samples is essential for generation tasks. Automated metrics miss fluency, relevance, factual accuracy, and tone.

---

Slice Analysis

Why it matters: A model with 92% overall accuracy can have 60% accuracy on an important subgroup. Aggregate metrics hide this.

What to slice on

1. Data attributes: text length, category, time period, region, data source
2. Demographic groups (if applicable): age range, gender, language, country
3. Prediction confidence: high confidence, uncertain (0.45–0.55 prob), low confidence
4. Error types: false positives vs. false negatives separately

import pandas as pd
from sklearn.metrics import f1_score

def slice_analysis(df: pd.DataFrame, prediction_col: str, label_col: str, 
                   slice_col: str) -> pd.DataFrame:
    """Compute F1 per slice of a categorical column."""
    results = []
    
    # Overall
    overall_f1 = f1_score(df[label_col], df[prediction_col], average='macro')
    results.append({"slice": "OVERALL", "n": len(df), "f1": overall_f1})
    
    # Per slice
    for slice_val, group in df.groupby(slice_col):
        slice_f1 = f1_score(group[label_col], group[prediction_col], average='macro')
        results.append({
            "slice": f"{slice_col}={slice_val}",
            "n": len(group),
            "f1": slice_f1,
            "delta": slice_f1 - overall_f1,
        })
    
    result_df = pd.DataFrame(results).sort_values("f1")
    return result_df

# Flag slices with >5% degradation
analysis = slice_analysis(test_df, "prediction", "label", "category")
at_risk = analysis[analysis["delta"] < -0.05]
print("Underperforming slices:")
print(at_risk)

---

Calibration

A calibrated model produces probability estimates that match empirical frequencies.

Overconfident: Model says 95% confidence, but is right only 80% of the time. Underconfident: Model says 50% confidence on cases it's actually right 80% of the time.

import matplotlib.pyplot as plt
from sklearn.calibration import calibration_curve
from sklearn.metrics import brier_score_loss

# Reliability diagram
fraction_of_positives, mean_predicted_value = calibration_curve(
    y_true, y_prob, n_bins=10, normalize=True
)

plt.figure(figsize=(8, 6))
plt.plot(mean_predicted_value, fraction_of_positives, 's-', label='Our model')
plt.plot([0, 1], [0, 1], 'k--', label='Perfectly calibrated')
plt.xlabel('Mean predicted probability')
plt.ylabel('Fraction actually positive')
plt.title('Calibration Curve (Reliability Diagram)')
plt.legend()
plt.tight_layout()
plt.savefig('calibration.png')

# Expected Calibration Error (ECE) — lower is better
brier = brier_score_loss(y_true, y_prob)
print(f"Brier score: {brier:.4f}")  # 0 = perfect

To improve calibration:

• Platt scaling (logistic regression on model outputs)
• Temperature scaling (scale logits before softmax)
• Isotonic regression (non-parametric, more flexible)

---

Fairness Evaluation

For models affecting people, always evaluate fairness metrics across protected groups.

Key Metrics

| Metric | Definition | When to use | |--------|-----------|------------| | Demographic parity | Similar prediction rates across groups | Hiring, loan approval | | Equal opportunity | Similar TPR across groups | High-stakes decisions | | Predictive parity | Similar PPV across groups | Risk scoring | | Individual fairness | Similar people → similar predictions | Always |

def fairness_analysis(df: pd.DataFrame, prediction_col: str, label_col: str, 
                      group_col: str) -> pd.DataFrame:
    results = []
    for group, data in df.groupby(group_col):
        tp = ((data[prediction_col] == 1) & (data[label_col] == 1)).sum()
        fp = ((data[prediction_col] == 1) & (data[label_col] == 0)).sum()
        fn = ((data[prediction_col] == 0) & (data[label_col] == 1)).sum()
        tn = ((data[prediction_col] == 0) & (data[label_col] == 0)).sum()
        
        results.append({
            "group": group,
            "n": len(data),
            "positive_rate": (tp + fp) / len(data),          # Demographic parity
            "tpr": tp / (tp + fn) if (tp + fn) > 0 else None, # Equal opportunity
            "fpr": fp / (fp + tn) if (fp + tn) > 0 else None,
            "ppv": tp / (tp + fp) if (tp + fp) > 0 else None, # Predictive parity
        })
    
    return pd.DataFrame(results)

Report any metric gap > 5 percentage points as a finding requiring investigation.

---

Production Monitoring

Offline metrics don't guarantee production performance. Monitor:

Data Drift

from scipy.stats import ks_2samp

def detect_drift(training_data: pd.Series, production_data: pd.Series, 
                 threshold: float = 0.05) -> dict:
    """Kolmogorov-Smirnov test for distribution shift."""
    statistic, p_value = ks_2samp(training_data, production_data)
    return {
        "drift_detected": p_value < threshold,
        "ks_statistic": statistic,
        "p_value": p_value,
    }

Model Performance Monitoring

Track these metrics in production (with delayed labels when available):

• Prediction distribution — is the model predicting more positives than expected?
• Confidence distribution — are scores shifting toward uncertain range?
• Error rate (when labels arrive) — compare to offline baseline
• Latency P99 — performance regression from model serving layer

When to Retrain

| Signal | Action | |--------|--------| | Data drift detected (KS test fails) | Evaluate impact; retrain if metrics degrade | | Offline metrics drop > 2% | Immediate retraining trigger | | Concept drift (world has changed) | Schedule retrain | | New labeled data available | Scheduled retraining (weekly/monthly) |

Deeper Reference

For complete evaluation framework implementations and metrics reference tables, see:

• references/evaluation-frameworks.md — scikit-learn, HuggingFace Evaluate, and RAGAS evaluation pipelines with slice analysis and fairness auditing
• references/metrics-reference.md — decision guide for metric selection, threshold recommendations, and statistical significance testing for A/B experiments