lr-tuning

LR Scorecard Parameter Tuning (portable)

The LR scorecard tuningsole entry point, based on _vendor/tuning/lr_engine.LRTuningEngine。

Core design: WoE binning parameters and LR regularization parametersjoint search, ensuring the optimal combination.

---

Tuning Workflow

基线 LR 模型 → 诊断分析(过拟合/欠拟合) → 约束空间构造 → Optuna 搜索 → 最优参数 → 迭代

---

Execution Mode

Mode	Trigger Condition	Behavior
Interactive(default)	User says "tune parameters"/"help me tune the LR"	Pause each round to wait for user feedback
AUTO	User says "auto-tune"/"help me tune to optimal"	Agent iterates automatically until convergence

---

Parameter Description

Parameter	Required	Default Value	Description
--data_path / -d	✅	-	Data file path
--target / -t	✅	-	Target variable column name
--features		Automatically inferred	Feature list, comma-separated
--time_col		busi_dt	Time column name
--train_filter		Automatically split	Training set filter condition
--val_filter		val_ratio split out	Validation set filter condition
--oot_filter		Split by time	OOT condition
--oot_ratio		0.20	OOT proportion
--val_ratio		0.25	Val proportion
--random_seed		42	Random seed
--exclude_cols		-	Excluded columns
--max_n_bins		8	Current WoE number of bins
--iv_threshold		0.02	Current IV threshold
--C		1.0	Reciprocal of current regularization strength
--regularization		l2	Regularization type
--round / -r		0	Current round
--max_rounds		5	Maximum tuning rounds
--auto		-	Auto-tuning mode (flag)
--metric		auc	Evaluation metric
--model_name		Automatically generated	Model name
--output_dir		./outputs/<ts>	Artifact output directory
--config		-	JSON configuration path

---

Search Space

Parameter	Type	Range	Description
max_n_bins	int	3-15	WoE number of bins (larger is finer)
iv_threshold	float(log)	0.005-0.10	IV screening threshold (lower means more features enter the model)
C	float(log)	0.01-100	Reciprocal of regularization strength (larger means weaker regularization)
regularization	categorical	l1/l2/elasticnet	Regularization type

---

Diagnosis-Driven Strategy

Diagnosis	C	iv_threshold	max_n_bins
Overfitting	↓ Tighten	↑ Raise (reduce features)	↓ Decrease
Underfitting	↑ Relax	↓ Lower (more features)	↑ Increase
Good fit	± Fine-tune	± Fine-tune	± Fine-tune

---

Execution Method

Interactive Mode (Single Round)

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label \
  --round 1 --output_dir ./outputs/lr_tuning

AUTO Mode

python scripts/tuner.py \
  --data_path ./data.parquet --target y_label \
  --auto --max_rounds 5 --output_dir ./outputs/lr_tuning

---

Tuning Strategy

Strategy 1: Anti-Overfitting

Applicable Conditions：Train-OOT Gap > 0.05

Adjustment Direction：

• C: current value × 0.5 (tighten regularization)
• iv_threshold: current value × 1.5 (reduce features entering the model)
• max_n_bins: current value - 1 (lower binning granularity)

Strategy 2: Enhance fitting

Applicable conditions: OOT AUC < 0.58 and Gap < 0.03

Adjustment direction：

• C: current value × 2 (relax regularization)
• iv_threshold: current value × 0.5 (increase features entering the model)
• max_n_bins: current value + 2 (improve binning granularity)

Strategy 3: Fine-tuning

Applicable conditions: Gap ∈ [0.03, 0.05], the model is in good condition

Adjustment direction：

• C: small adjustment ±20%
• max_n_bins: fine-tune ±1
• Other parameters remain unchanged

Strategy 4: Convergence determination

Condition: for 2 consecutive rounds, OOT metric improvement < 0.001

Behavior: stop tuning and output the final result

---

Output format specification

After each round of tuning,mustoutput the following structured information:

### 第 N 轮 LR 调优结果

**参数变化**:
| 参数 | 上一轮 | 本轮 | 调整原因 |
|------|-------|------|----------|
| C | 1.0 | 0.5 | 收紧正则化 |
| iv_threshold | 0.02 | 0.03 | 减少入模特征 |
| max_n_bins | 8 | 6 | 降低过拟合 |

**效果对比**:
| 指标 | 上一轮 | 本轮 | 变化 |
|------|-------|------|------|
| OOT AUC | 0.72 | 0.73 | +0.01 ✓ |
| OOT KS | 0.17 | 0.18 | +0.01 ✓ |
| Gap | 0.06 | 0.04 | -0.02 ✓ |

**诊断结论**: 轻微过拟合（Gap 下降但仍 > 0.03）

**下一步建议**: 可继续微调 C 值，或接受当前结果

---

Relationship with other skills

Skill	Responsibility	Relationship
lr-modeling	Baseline modeling	Prerequisite: it must first be used to train a baseline model
model-comparison	Multi-algorithm comparison	Follow-up: can be fairly compared with XGB/DNN
xgb-tuning	XGBoost parameter tuning	Parallel: parameter tuning for different algorithms on the same data

---

Notes

1. Data requirement: the target variable must be a 0/1 binary classification
2. Joint search: joint optimization of WoE binning and LR parameters to ensure the optimal combination
3. Convergence determination: automatically stops when the improvement is less than 0.001 for 2 consecutive rounds
4. Maximum rounds: up to 5 rounds by default
5. Artifact location: the model and report are saved to <output_dir>/models/ and <output_dir>/