segment-modeling

Segmented Autonomous Exploration (portable)

Under the segmentation strategy specified by the user or autonomously discovered by the AI, split customer groups to train sub-models, and automatically explore the optimal segmentation scheme.

Core Concept：

探索空间（策略 × 参数 × 组合）
        │
        ▼
Try → Measure → Keep/Discard → Repeat
        │
        ▼
    最优分群方案 + 子模型

---

Three Segmentation Strategies

Strategy	Description	Applicable Scenario
Rule-based Segmentation	User-specified rules (e.g., age < 30）	Has business prior knowledge
Clustering Segmentation	Unsupervised automatic discovery such as K-Means	Explore the intrinsic structure of the data
Decision Tree Segmentation	Supervised search for the optimal split point	Directly optimize the target variable

---

Parameter Description

Parameter	Required	Default Value	Description
--data_path	✅	-	Data file path (parquet/csv)
--target	✅	-	Target variable column name (0/1 binary classification)
--mode		auto	Mode: auto(autonomous exploration) / manual(specified strategy)
--max_rounds		5	Maximum number of autonomous exploration rounds
--segment_rules		-	Rule-based segmentation, JSON format
--segment_col		-	Directly specify the segmentation column name
--n_clusters		3	Number of clusters for clustering segmentation
--tree_depth		2	Decision tree segmentation depth
--tree_features		-	Features used by the decision tree, comma-separated
--min_segment_ratio		0.05	Minimum segment proportion (<5% will warn)
--merge_strategy		route	Aggregation strategy: route / stacking
--metric		ks	Optimization metric (auc/ks)
--significance		2.0	Significance threshold (MAD multiple)
--time_col		busi_dt	Time column name
--train_filter		-	Training set filter condition
--val_filter		-	Validation set filter condition
--output_dir		./outputs/<ts>	Artifact output directory
--config		-	JSON configuration file

---

Execution Method

Autonomously explore the optimal segmentation

python scripts/run_segment.py \
  --data_path ./data.parquet --target y_label \
  --mode auto --max_rounds 5 \
  --output_dir ./outputs/seg

User rule-based segmentation

python scripts/run_segment.py \
  --data_path ./data.parquet --target y_label \
  --mode manual \
  --segment_rules '{"年轻": "age < 30", "中年": "age >= 30 and age < 50", "高龄": "age >= 50"}' \
  --output_dir ./outputs/seg

Automatic clustering segmentation

python scripts/run_segment.py \
  --data_path ./data.parquet --target y_label \
  --mode manual --n_clusters 4 \
  --output_dir ./outputs/seg

Decision tree segmentation

python scripts/run_segment.py \
  --data_path ./data.parquet --target y_label \
  --mode manual \
  --tree_depth 3 --tree_features "age,income,credit_score" \
  --output_dir ./outputs/seg

---

Output Content

Real-time progress (streaming output)

━━━ Round 1/5: 基线（不分群）━━━
单一模型 AUC: 0.742

━━━ Round 2/5: 用户规则分群 ━━━
规则: age < 30 | 30-50 | > 50
分群样本: [12,340 | 18,560 | 14,288]
子模型 AUC: [0.71 | 0.75 | 0.78]
汇总 AUC: 0.758 (+2.2%)
决策: ✅ KEEP

━━━ Round 3/5: 决策树分群 (depth=2) ━━━
自动分割: income < 5000 → ...
汇总 AUC: 0.772 (+1.8%)
决策: ✅ KEEP (新最佳!)

Final report

• Details of the optimal segmentation scheme
• Comparison table of each strategy
• List of sub-models and metrics
• Improvement over baseline
• Segmentation stability analysis (PSI)

---

Evaluation Criteria

Metric	Description	Threshold
Overall AUC	Effect after aggregating the segmented models	Higher is better
vs Baseline	Improvement compared with no segmentation	> 0
Segmentation Stability	Change in OOT segmentation proportions	PSI < 0.1
Minimum Coverage	Minimum group proportion	> 5%

---

Relationship with Other Skills

Skill	Responsibility	Relationship
xgb-modeling	Single-model training	Reused training sub-models
auto-experiment	Feature exploration	Each group can be optimized independently after segmentation
feature-analysis	Feature analysis	Assists in selecting segmentation features

---

Notes

1. Number of segments: 2-5 segments are recommended; too many easily leads to overfitting
2. Minimum sample size: each segment is recommended to be > 5% of the total sample
3. Stability: pay attention to whether the OOT segmentation proportions are stable
4. Business interpretability: decision tree segmentation rules are easier to explain
5. Combined use: you can first segment and then perform feature exploration for each segment