lr-modeling

LR Scorecard Modeling (portable)

Perform binary classification scorecard modeling based on WoE (Weight of Evidence) encoding + Logistic Regression.

Core workflow: raw features → optimal WoE binning encoding → LR training → scorecard conversion

Applicable scenarios：

• Risk control scorecard development (standard A/B/C cards)
• Business scenarios requiring strong interpretability
• Regulatory compliance requires model white-boxing

---

Parameter description

Parameter	Required	Default value	Description
--data_path / -d	✅	-	Data file path (parquet/csv)
--target / -t	✅	-	Target variable column name (0/1 binary classification)
--time_col		busi_dt	Time column name
--train_filter		Automatic splitting	Training set filter condition (pandas query)
--oot_filter		Split out by time	OOT cross-time test set condition
--oot_ratio		0.20	If not passed --oot_filter the proportion for splitting OOT by time
--val_ratio		0.25	Proportion of val split from train_full
--random_seed		42	Random seed
--exclude_cols		-	Excluded columns, comma-separated
--features		-	Specified feature list, comma-separated; if not passed, automatically filter by IV
--max_n_bins		8	Maximum number of bins for WoE binning
--min_bin_size		0.05	Minimum binning ratio
--iv_threshold		0.02	IV screening threshold (features below this value are excluded)
--regularization		l2	Regularization type:l1 / l2 / elasticnet
--C		1.0	Regularization strength (smaller means stronger regularization)
--max_iter		1000	LR maximum number of iterations
--base_score		600	Scorecard base score
--pdo		50	Scorecard PDO (points to double the odds)
--base_odds		50.0	Base Odds (good-to-bad ratio)
--model_name		Automatically generated	Model name
--report_output		Automatically generated	Report output path
--output_dir		./outputs/<ts>	Artifact output directory
--config		-	JSON configuration file path

---

Execution method

python scripts/modeling.py \
  --data_path ./data.parquet --target y_label \
  --time_col busi_dt \
  --exclude_cols "cust_code,busi_dt" \
  --output_dir ./outputs/lr_run

Specify features for modeling:

python scripts/modeling.py \
  --data_path ./data.parquet --target y_label \
  --features "feat1,feat2,feat3,feat4" \
  --regularization l1 --C 0.5 \
  --output_dir ./outputs/lr_run

---

Common scenarios

Scenario 1: Quick modeling with default parameters

python scripts/modeling.py --data_path ./data.parquet --target y_label --output_dir ./outputs/lr_run

Scenario 2: Modeling with specified features

python scripts/modeling.py --data_path ./data.parquet --target y_label \
  --features "feat1,feat2,feat3" --output_dir ./outputs/lr_run

Scenario 3: Custom scorecard parameters

python scripts/modeling.py --data_path ./data.parquet --target y_label \
  --base_score 650 --pdo 40 --output_dir ./outputs/lr_run

---

Output artifacts

1. Modeling report(Markdown) — includes data splitting, WoE binning table, LR coefficient table, scorecard conversion table, three-stage evaluation metrics, stability analysis
2. Model file(joblib) — LR model + WoE encoder serialization
3. Scorecard table(JSON) — binning-score mapping that can be directly used for deployment
4. result.json — structured artifact list

---

Comparison with other modeling Skills

Dimension	lr-modeling	xgb-modeling	dnn-modeling
Algorithm	Logistic Regression	XGBoost	MLP (PyTorch)
Feature encoding	WoE binning encoding	Raw features input directly	StandardScaler
Interpretability	White-box (coefficient × WoE = contribution)	Black-box (requires SHAP explanation)	Weak
Nonlinear capability	Weak (introduced only through binning)	Strong (naturally supported by tree structure)	Strong (multi-layer activation)
Applicable scenarios	Scorecard / compliance / white-box	High precision / feature interactions	High-dimensional complex interactions
Evaluation system	AUC/KS/BCR/PSI	AUC/KS/BCR/PSI	AUC/KS/BCR/PSI

---

Upstream and downstream relationships

• Preceding：data-profiling → feature-analysis / univariate-analysis(feature selection)
• Following：lr-tuning(hyperparameter tuning and optimization),model-comparison(multi-algorithm comparison)
• Parallel: with xgb-modeling / dnn-modeling can be compared horizontally (same data, different algorithms)

---

Notes

1. Target variable: must be 0/1 binary classification
2. Time split: it is recommended to split by time to ensure OOT is future data
3. Feature selection: if not passing --features , automatically select by IV (threshold --iv_threshold）
4. WoE binning: use optbinning for optimal binning, at most --max_n_bins bins per feature
5. Scorecard formula：Score = base_score - factor × ln(odds), where factor = pdo / ln(2)
6. No hyperparameter tuning provided: if hyperparameter tuning is needed, switch to lr-tuning(search WoE binning + LR regularization parameters)
7. Model saving: the model and scorecard are saved to <output_dir>/models/