Credit Risk Scoring

Production-ready credit risk scoring project for the Home Credit Default Risk dataset. It includes customer-level feature engineering, Weight of Evidence encoding, Logistic Regression baseline, Optuna-tuned LightGBM, Platt calibration, SHAP explainability, lift/gain analysis, and Fairlearn fairness reporting.

Architecture

Home Credit Kaggle CSV files
        |
        v
src/preprocess.py
  - load application and optional related tables
  - clean target, gender, missing values, and anomalous employment days
        |
        v
src/features.py
  - bureau/installment/previous application aggregates
  - ratio and interaction terms
  - WOE encoding fitted on training data only
        |
        v
src/train.py
  - Logistic Regression interpretability baseline
  - LightGBM tuned with Optuna
  - Platt scaling calibration
        |
        v
src/evaluate.py
  - ROC-AUC, PR-AUC, Gini, KS
  - lift/gain charts
  - SHAP global bar, beeswarm, waterfall
  - reliability diagram
        |
        v
src/fairness.py
  - demographic parity and equalized odds
  - gender and age-group fairness report

Dataset

Download Home Credit Default Risk from Kaggle:

https://www.kaggle.com/c/home-credit-default-risk/data

Expected files:

data/application_train.csv
data/application_test.csv
data/bureau.csv
data/bureau_balance.csv
data/previous_application.csv
data/installments_payments.csv
data/credit_card_balance.csv
data/POS_CASH_balance.csv

The pipeline can train with application_train.csv alone. The optional related tables improve the aggregate features.

Setup

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

On macOS or Linux:

source .venv/bin/activate

Reproduce Training

python src/train.py --data-dir data --output-dir outputs --model-dir models --n-trials 30

Artifacts written by the training run:

outputs/metrics.json
outputs/model_results_table.csv
outputs/lift_gain_table.csv
outputs/test_scores.csv
outputs/charts/lift_chart.png
outputs/charts/gain_chart.png
outputs/charts/reliability_diagram.png
outputs/shap/shap_global_bar.png
outputs/shap/shap_beeswarm.png
outputs/shap/shap_waterfall.png
outputs/fairness/fairness_report.json
models/logistic_regression_model.pkl
models/lightgbm_model.pkl
models/calibrated_lightgbm_model.pkl
models/woe_encoder.pkl

Notebooks

Run notebooks in order:

1. notebooks/01_eda.ipynb
2. notebooks/02_feature_engineering.ipynb
3. notebooks/03_modeling.ipynb
4. notebooks/04_fairness_analysis.ipynb

Feature Engineering Strategy

• Application ratios: credit-to-income, annuity-to-income, annuity-to-credit, goods-to-credit, employment-to-age.
• External score interactions: mean, standard deviation, min, max, and credit ratio interaction.
• Bureau aggregates: numeric mean, max, min, sum, standard deviation, credit-active status counts, and bureau balance summaries.
• Previous application aggregates: numeric aggregates and contract status counts.
• Installment aggregates: payment ratio, payment difference, late payment days, and grouped statistics.
• WOE encoding: categorical variables and selected risk drivers are encoded using training-only Weight of Evidence mappings to support scorecard-style interpretation.

Model Results Table

The training run writes outputs/model_results_table.csv with this schema:

Model	ROC_AUC	PR_AUC	Gini	KS
Logistic Regression	Generated by training	Generated by training	Generated by training	Generated by training
LightGBM	Generated by training	Generated by training	Generated by training	Generated by training
LightGBM Calibrated	Generated by training	Generated by training	Generated by training	Generated by training

Fairness Findings Summary

Fairness analysis is generated at outputs/fairness/fairness_report.json. It reports:

• Overall accuracy, precision, recall, and ROC-AUC.
• Selection rate, true positive rate, false positive rate, and accuracy by gender.
• Selection rate, true positive rate, false positive rate, and accuracy by age group.
• Demographic parity difference and equalized odds difference for both group definitions.

Interpretation guidance: lower demographic parity and equalized odds differences indicate smaller observed disparities, but fairness review should consider business policy, regulatory context, and threshold selection before deployment.