segmtree 0.3.0__tar.gz

segmtree-0.3.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.idea/
+.vscode/

segmtree-0.3.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+## 0.3.0 — 2026-08-25
+
+- **Encoding-invariant categorical impurity**: declared categorical features
+  now contribute *Gini impurity relative to the root Gini* to node
+  heterogeneity (continuous/binary keep normalized variance). Results no
+  longer depend on how categories happen to be integer-coded; any relabeling
+  yields an equivalent partition. Children Gini for every candidate split is
+  evaluated exactly via per-column contingency tables.
+- **Exact categorical codes under any dtype**: category columns are stored as
+  int64/float64 internally, so codes like `16_777_216` vs `16_777_217` stay
+  distinct even with `dtype=numpy.float32`.
+- **`handle_unknown` parameter** (`"complement"` default, `"error"`): control
+  whether unseen category codes at prediction time route deterministically to
+  the complement side or raise `ValueError` naming the feature and values.
+  New learned attribute ``categories_`` records the training-time code set of
+  every categorical column.
+- **`profile_leaves` categorical profiles**: categorical columns are excluded
+  from z-scored ``top_features`` and instead reported through
+  ``category_enrichment``: the most enriched ``(feature, code, leaf_share,
+  lift)`` pairs per segment.
+- Test suite hardening: package-style imports (`tests/__init__.py`),
+  recoding-invariance tests across multiple permutations, float32 large-code
+  regression, unknown-category policy tests and categorical profile tests.
+
+## 0.2.0 — 2026-08-25
+
+- **Native categorical features**: pass integer-coded columns via
+  `categorical_features`; splits are category-subset memberships
+  (`color in {1, 2}`), enumerated exhaustively and scored with the same
+  normalized-heterogeneity criterion (`max_categories` guards the 2^(k-1)
+  enumeration).
+- Candidate thresholds for numeric splits are now computed and located in the
+  original feature space, guaranteeing that the evaluated partition is exactly
+  the committed one (fixes a rare boundary-point flip when a quantile knot
+  coincided with a data point).
+- `Condition` / `Cut` gained set-membership semantics (`op="in"`, `categories`);
+  rule replay, `predict` on unseen codes (deterministic right branch) and
+  profiling all support categorical columns.
+
+## 0.1.0 — 2026-08-25
+
+Initial release.
+
+- `SegTree`: best-first unsupervised decision tree (clustering tree) with
+  normalized mixed-type heterogeneity criterion, quantile candidate splits,
+  automatic binary-feature detection, sklearn-compatible API and float32/64
+  internal precision.
+- `extract_rules` / `replay_labels` / `replay_check`: rule extraction with
+  independent replay verification.
+- `profile_leaves`: per-segment z-score feature profiles.
+- `bootstrap_stability`: bootstrap ARI stability assessment.
+- `adjusted_rand_score`: pure-numpy ARI matching scikit-learn numerics.

segmtree-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The segmtree authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

segmtree-0.3.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: segmtree
+Version: 0.3.0
+Summary: Interpretable unsupervised decision tree for customer segmentation and rule-based clustering.
+Project-URL: Homepage, https://github.com/Unknownxu1/segmtree
+Project-URL: Repository, https://github.com/Unknownxu1/segmtree
+Project-URL: Issues, https://github.com/Unknownxu1/segmtree/issues
+Author-email: Unknownxu1 <Unknownxu1@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: clustering,clustering-tree,customer-segmentation,decision-tree,interpretable-ml,unsupervised-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Provides-Extra: dev
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: scikit-learn>=1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# segmtree
+
+Interpretable unsupervised decision trees for segmentation — clusters rows of a
+tabular dataset into segments, where every segment is described by a short,
+human-readable rule chain. No target variable required.
+
+`segmtree` implements a **clustering tree**: instead of predicting labels, it
+recursively splits the data so that within-segment heterogeneity drops as much
+as possible at every cut, growing best-first (highest-gain node expanded
+first). Think of it as "a decision tree grown without `y`" — you get both the
+partition *and* the rules that define it, which plain k-means or GMM cannot
+give you.
+
+## Why segmtree?
+
+| | k-means / GMM | segmtree |
+|---|---|---|
+| Segment definition | centroid coordinates | `income > 50k AND is_active = 0` style rules |
+| New-row assignment | nearest centroid | evaluate ≤ 6 threshold tests |
+| Mixed binary + continuous features | needs scaling tricks | one normalized criterion for both |
+| Built-in self-checks | none | gain additivity + rule replay verification |
+| Stability assessment | ad hoc | one-call bootstrap ARI |
+
+Typical uses: customer segmentation with behavioral flags, patient phenotyping,
+survey respondent typing — any "many 0/1 tags + a few counts" table.
+
+## Installation
+
+```bash
+pip install segmtree
+```
+
+Requires Python ≥ 3.9 and numpy only.
+
+## Quickstart
+
+```python
+import numpy as np
+from segmtree import SegTree, extract_rules, profile_leaves, replay_check, bootstrap_stability
+
+rng = np.random.default_rng(0)
+# 4 continuous features + 3 binary flags, three latent groups
+X = np.vstack([
+    np.hstack([rng.normal([0, -1, 2, .5], .5, (250, 4)), (rng.random((250, 3)) < .1)]),
+    np.hstack([rng.normal([4, 3, -2, .5], .5, (200, 4)), (rng.random((200, 3)) < .5)]),
+    np.hstack([rng.normal([-4, 2, 0, 8], .5, (150, 4)), (rng.random((150, 3)) < .9)]),
+])
+
+tree = SegTree(min_gain=0.02, min_leaf_frac=0.05, min_leaf_abs=10)
+tree.fit(X)
+
+print(f"{tree.n_leaves_} segments, heterogeneity reduced {tree.reduction_:.0%}")
+
+for rule in extract_rules(tree):
+    print(rule)                      # #0: x1 <= -1.24 AND x0 <= 1.83 ...
+
+profile_leaves(tree, X, top_k=3)     # most distinctive features per segment
+replay_check(tree, X)                # True: stored rules reproduce the partition exactly
+bootstrap_stability(tree, X, n_replicates=12, random_state=0).mean   # e.g. 0.98
+```
+
+Binary columns (all values in `{0, 1}`) are detected automatically and split
+with a single test; pandas DataFrames are accepted and column names flow into
+the rules.
+
+## Categorical features
+
+Columns holding integer category codes (e.g. `0..k-1` from a nominal
+encoding) can be declared with `categorical_features`. They are split by the
+best **subset** of categories rather than by a threshold, and the rules read
+as membership tests:
+
+```python
+tree = SegTree(categorical_features=["color"], max_categories=12).fit(df)
+# rule example:  #3: color in {1, 2} AND income > 42 ...
+```
+
+Impurity contribution: categorical columns use **Gini impurity relative to
+the root Gini**, while continuous/binary columns keep normalized variance.
+Gini depends only on the category *distribution*, so any one-to-one recoding
+of the codes yields an equivalent partition — results are encoding-invariant.
+
+Notes:
+
+- Codes must be integral; non-numeric labels should be factorized first
+  (`pd.factorize`, `df["color"].astype("category").cat.codes`).
+- Codes are handled exactly at any magnitude (int64/float64 internally), even
+  with `dtype=np.float32` for the continuous columns.
+- All `2^(k-1)-1` category partitions of a node are evaluated exactly, so
+  keep `k <= max_categories` (rare levels can be grouped beforehand); for
+  high-cardinality columns prefer one-hot encoding.
+- Unseen codes at prediction time follow `handle_unknown`: `"complement"`
+  (default) routes them deterministically to the complement side and
+  `replay_check` stays exact; `"error"` raises `ValueError` naming the
+  feature and unknown values. The training-time code sets are exposed via
+  the ``categories_`` attribute.
+- ``profile_leaves`` reports categorical structure through
+  ``category_enrichment`` — ``(feature, code, leaf_share, lift)`` pairs —
+  and keeps z-scores for continuous/binary features only.
+
+## How it works
+
+Node heterogeneity averages per-feature variance relative to the root:
+
+```
+H(S) = (1/m) · Σ_j Var_j(S) / Var_j(root)          H(root) = 1
+```
+
+Because Bernoulli variance p(1−p) fits the same formula, binary and continuous
+features share one comparable criterion. A split into L/R earns:
+
+```
+Gain = H(S) − [ n_L/n_S · H(L) + n_R/n_S · H(R) ]
+```
+
+Candidates are the in-node quantiles of each feature (`quantiles=8` → the 5%
+… 95% quantiles; binary features get one candidate at 0.5). All candidates are
+evaluated per feature via sort + prefix sums in O(n log n), and the globally
+best leaf is always split next (best-first).
+
+Splitting stops when no cut gains at least `min_gain`, a node is too small
+(`max(min_leaf_abs, min_leaf_frac·n)` per child), or `max_depth` is reached.
+
+Two properties make results trustworthy out of the box:
+
+- **Gain additivity** — `total_gain_ == h_root_ − h_avg_` up to float error;
+  it accounts for exactly how much heterogeneity was explained.
+- **Rule replay** — `replay_check()` re-evaluates every leaf's rule chain from
+  scratch and must reproduce `predict()` bit-for-bit.
+
+The test suite additionally verifies exact agreement against an independent
+naive reference implementation.
+
+## API overview
+
+```python
+SegTree(min_gain=0.01, min_leaf_frac=0.01, min_leaf_abs=50, max_depth=None,
+        quantiles=8, binary_features="auto", categorical_features=None,
+        max_categories=12, handle_unknown="complement", feature_names=None,
+        dtype=np.float64)
+```
+
+| Member | Purpose |
+|---|---|
+| `.fit(X)` / `.fit_predict(X)` / `.predict(X)` | sklearn-style fit & assignment |
+| `.labels_`, `.n_leaves_`, `.leaves_`, `.cuts_` | fitted structure |
+| `.reduction_`, `.h_avg_`, `.total_gain_`, `.summary()` | quality statistics |
+| `extract_rules(tree)` | list of `Rule` objects (`str(rule)` → readable chain) |
+| `replay_labels(tree, X)` / `replay_check(tree, X)` | rule-replay validation |
+| `profile_leaves(tree, X, top_k=3)` | z-score profiles per segment |
+| `bootstrap_stability(tree, X, n_replicates, random_state)` | mean/std of bootstrap ARI |
+| `adjusted_rand_score(a, b)` | pure-numpy ARI |
+
+Tuning tips:
+
+- Fewer, larger segments → raise `min_gain` (e.g. `0.02–0.05`) or lower
+  `quantiles`; cap `max_depth` (e.g. 4–6) to keep rules short and stable.
+- Small datasets (< 5000 rows) → lower `min_leaf_abs` (it defaults to 50).
+- Unstable segments (low bootstrap ARI) → fewer quantiles, higher `min_gain`,
+  or a depth cap usually stabilize the structure.
+
+## Comparison with related tools
+
+- **scikit-learn DecisionTree on k-means labels** ("surrogate tree"): two-step,
+  rules may contradict the clustering; `segmtree` optimizes split quality and
+  rule fidelity simultaneously.
+- **forest-clustering / URF**: forest-proximity clustering — accurate but the
+  segments themselves are not directly interpretable.
+- **CUBT (R)**: closest academic relative; `segmtree` adds best-first growth,
+  mixed-type normalization, additivity checks and bootstrap stability in a
+  numpy-only package.
+
+## Development
+
+```bash
+git clone <your-fork-url> && cd segmtree
+pip install -e .[dev]
+pytest            # run the test suite
+ruff check src tests
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+[中文文档](README.zh-CN.md)

segmtree-0.3.0/README.md

@@ -0,0 +1,186 @@
+# segmtree
+
+Interpretable unsupervised decision trees for segmentation — clusters rows of a
+tabular dataset into segments, where every segment is described by a short,
+human-readable rule chain. No target variable required.
+
+`segmtree` implements a **clustering tree**: instead of predicting labels, it
+recursively splits the data so that within-segment heterogeneity drops as much
+as possible at every cut, growing best-first (highest-gain node expanded
+first). Think of it as "a decision tree grown without `y`" — you get both the
+partition *and* the rules that define it, which plain k-means or GMM cannot
+give you.
+
+## Why segmtree?
+
+| | k-means / GMM | segmtree |
+|---|---|---|
+| Segment definition | centroid coordinates | `income > 50k AND is_active = 0` style rules |
+| New-row assignment | nearest centroid | evaluate ≤ 6 threshold tests |
+| Mixed binary + continuous features | needs scaling tricks | one normalized criterion for both |
+| Built-in self-checks | none | gain additivity + rule replay verification |
+| Stability assessment | ad hoc | one-call bootstrap ARI |
+
+Typical uses: customer segmentation with behavioral flags, patient phenotyping,
+survey respondent typing — any "many 0/1 tags + a few counts" table.
+
+## Installation
+
+```bash
+pip install segmtree
+```
+
+Requires Python ≥ 3.9 and numpy only.
+
+## Quickstart
+
+```python
+import numpy as np
+from segmtree import SegTree, extract_rules, profile_leaves, replay_check, bootstrap_stability
+
+rng = np.random.default_rng(0)
+# 4 continuous features + 3 binary flags, three latent groups
+X = np.vstack([
+    np.hstack([rng.normal([0, -1, 2, .5], .5, (250, 4)), (rng.random((250, 3)) < .1)]),
+    np.hstack([rng.normal([4, 3, -2, .5], .5, (200, 4)), (rng.random((200, 3)) < .5)]),
+    np.hstack([rng.normal([-4, 2, 0, 8], .5, (150, 4)), (rng.random((150, 3)) < .9)]),
+])
+
+tree = SegTree(min_gain=0.02, min_leaf_frac=0.05, min_leaf_abs=10)
+tree.fit(X)
+
+print(f"{tree.n_leaves_} segments, heterogeneity reduced {tree.reduction_:.0%}")
+
+for rule in extract_rules(tree):
+    print(rule)                      # #0: x1 <= -1.24 AND x0 <= 1.83 ...
+
+profile_leaves(tree, X, top_k=3)     # most distinctive features per segment
+replay_check(tree, X)                # True: stored rules reproduce the partition exactly
+bootstrap_stability(tree, X, n_replicates=12, random_state=0).mean   # e.g. 0.98
+```
+
+Binary columns (all values in `{0, 1}`) are detected automatically and split
+with a single test; pandas DataFrames are accepted and column names flow into
+the rules.
+
+## Categorical features
+
+Columns holding integer category codes (e.g. `0..k-1` from a nominal
+encoding) can be declared with `categorical_features`. They are split by the
+best **subset** of categories rather than by a threshold, and the rules read
+as membership tests:
+
+```python
+tree = SegTree(categorical_features=["color"], max_categories=12).fit(df)
+# rule example:  #3: color in {1, 2} AND income > 42 ...
+```
+
+Impurity contribution: categorical columns use **Gini impurity relative to
+the root Gini**, while continuous/binary columns keep normalized variance.
+Gini depends only on the category *distribution*, so any one-to-one recoding
+of the codes yields an equivalent partition — results are encoding-invariant.
+
+Notes:
+
+- Codes must be integral; non-numeric labels should be factorized first
+  (`pd.factorize`, `df["color"].astype("category").cat.codes`).
+- Codes are handled exactly at any magnitude (int64/float64 internally), even
+  with `dtype=np.float32` for the continuous columns.
+- All `2^(k-1)-1` category partitions of a node are evaluated exactly, so
+  keep `k <= max_categories` (rare levels can be grouped beforehand); for
+  high-cardinality columns prefer one-hot encoding.
+- Unseen codes at prediction time follow `handle_unknown`: `"complement"`
+  (default) routes them deterministically to the complement side and
+  `replay_check` stays exact; `"error"` raises `ValueError` naming the
+  feature and unknown values. The training-time code sets are exposed via
+  the ``categories_`` attribute.
+- ``profile_leaves`` reports categorical structure through
+  ``category_enrichment`` — ``(feature, code, leaf_share, lift)`` pairs —
+  and keeps z-scores for continuous/binary features only.
+
+## How it works
+
+Node heterogeneity averages per-feature variance relative to the root:
+
+```
+H(S) = (1/m) · Σ_j Var_j(S) / Var_j(root)          H(root) = 1
+```
+
+Because Bernoulli variance p(1−p) fits the same formula, binary and continuous
+features share one comparable criterion. A split into L/R earns:
+
+```
+Gain = H(S) − [ n_L/n_S · H(L) + n_R/n_S · H(R) ]
+```
+
+Candidates are the in-node quantiles of each feature (`quantiles=8` → the 5%
+… 95% quantiles; binary features get one candidate at 0.5). All candidates are
+evaluated per feature via sort + prefix sums in O(n log n), and the globally
+best leaf is always split next (best-first).
+
+Splitting stops when no cut gains at least `min_gain`, a node is too small
+(`max(min_leaf_abs, min_leaf_frac·n)` per child), or `max_depth` is reached.
+
+Two properties make results trustworthy out of the box:
+
+- **Gain additivity** — `total_gain_ == h_root_ − h_avg_` up to float error;
+  it accounts for exactly how much heterogeneity was explained.
+- **Rule replay** — `replay_check()` re-evaluates every leaf's rule chain from
+  scratch and must reproduce `predict()` bit-for-bit.
+
+The test suite additionally verifies exact agreement against an independent
+naive reference implementation.
+
+## API overview
+
+```python
+SegTree(min_gain=0.01, min_leaf_frac=0.01, min_leaf_abs=50, max_depth=None,
+        quantiles=8, binary_features="auto", categorical_features=None,
+        max_categories=12, handle_unknown="complement", feature_names=None,
+        dtype=np.float64)
+```
+
+| Member | Purpose |
+|---|---|
+| `.fit(X)` / `.fit_predict(X)` / `.predict(X)` | sklearn-style fit & assignment |
+| `.labels_`, `.n_leaves_`, `.leaves_`, `.cuts_` | fitted structure |
+| `.reduction_`, `.h_avg_`, `.total_gain_`, `.summary()` | quality statistics |
+| `extract_rules(tree)` | list of `Rule` objects (`str(rule)` → readable chain) |
+| `replay_labels(tree, X)` / `replay_check(tree, X)` | rule-replay validation |
+| `profile_leaves(tree, X, top_k=3)` | z-score profiles per segment |
+| `bootstrap_stability(tree, X, n_replicates, random_state)` | mean/std of bootstrap ARI |
+| `adjusted_rand_score(a, b)` | pure-numpy ARI |
+
+Tuning tips:
+
+- Fewer, larger segments → raise `min_gain` (e.g. `0.02–0.05`) or lower
+  `quantiles`; cap `max_depth` (e.g. 4–6) to keep rules short and stable.
+- Small datasets (< 5000 rows) → lower `min_leaf_abs` (it defaults to 50).
+- Unstable segments (low bootstrap ARI) → fewer quantiles, higher `min_gain`,
+  or a depth cap usually stabilize the structure.
+
+## Comparison with related tools
+
+- **scikit-learn DecisionTree on k-means labels** ("surrogate tree"): two-step,
+  rules may contradict the clustering; `segmtree` optimizes split quality and
+  rule fidelity simultaneously.
+- **forest-clustering / URF**: forest-proximity clustering — accurate but the
+  segments themselves are not directly interpretable.
+- **CUBT (R)**: closest academic relative; `segmtree` adds best-first growth,
+  mixed-type normalization, additivity checks and bootstrap stability in a
+  numpy-only package.
+
+## Development
+
+```bash
+git clone <your-fork-url> && cd segmtree
+pip install -e .[dev]
+pytest            # run the test suite
+ruff check src tests
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+[中文文档](README.zh-CN.md)

segmtree-0.3.0/README.zh-CN.md

@@ -0,0 +1,166 @@
+# segmtree
+
+可解释的无监督决策树分群库 —— 把一张"客户标签"表自动划分成若干人群，每个人群都由一条
+简短、人类可读的规则链定义，全程不需要任何标签 y。
+
+`segmtree` 实现的是**聚类决策树**（clustering tree）：不预测类别，而是自顶向下递归二分，
+每一刀选择使"组内异质性下降最多"的单特征阈值规则，并按 Best-First（全局收益最大的叶子
+先切）生长。可以理解为"没有 y 也能长的决策树"——同时给你划分结果和划分规则，这是
+k-means / GMM 做不到的。
+
+## 为什么选 segmtree？
+
+| | k-means / GMM | segmtree |
+|---|---|---|
+| 人群定义 | 质心坐标 | `income > 50k AND is_active = 0` 式规则 |
+| 新样本归类 | 最近质心 | 至多几条阈值判断即可回放 |
+| 二值 + 连续混合特征 | 需要各种缩放技巧 | 归一化后同口径比较 |
+| 内置自检 | 无 | 收益可加性 + 规则回放一致性校验 |
+| 稳定性评估 | 自己想办法 | 一行调用的 Bootstrap ARI |
+
+典型场景：带行为标签的客户分群、患者表型归类、问卷人群画像——一切"大量 0/1 标签 +
+少量计数/金额列"的表。
+
+## 安装
+
+```bash
+pip install segmtree
+```
+
+仅要求 Python ≥ 3.9 与 numpy。
+
+## 快速上手
+
+```python
+import numpy as np
+from segmtree import SegTree, extract_rules, profile_leaves, replay_check, bootstrap_stability
+
+rng = np.random.default_rng(0)
+X = np.vstack([
+    np.hstack([rng.normal([0, -1, 2, .5], .5, (250, 4)), (rng.random((250, 3)) < .1)]),
+    np.hstack([rng.normal([4, 3, -2, .5], .5, (200, 4)), (rng.random((200, 3)) < .5)]),
+    np.hstack([rng.normal([-4, 2, 0, 8], .5, (150, 4)), (rng.random((150, 3)) < .9)]),
+])
+
+tree = SegTree(min_gain=0.02, min_leaf_frac=0.05, min_leaf_abs=10)
+tree.fit(X)
+
+print(f"{tree.n_leaves_} 类人群，异质性降低 {tree.reduction_:.0%}")
+
+for rule in extract_rules(tree):
+    print(rule)                      # #0: x1 <= -1.24 AND x0 <= 1.83 ...
+
+profile_leaves(tree, X, top_k=3)     # 每类与全体差异最大的特征（z 分数）
+replay_check(tree, X)                # True：规则回放与 predict 完全一致
+bootstrap_stability(tree, X, n_replicates=12, random_state=0).mean   # 例如 0.98
+```
+
+取值只有 {0, 1} 的列会被自动识别为二值特征（只做一次"是/否"切分）；直接传 pandas
+DataFrame 也可以，列名会自动带入规则文本。
+
+## 类别特征
+
+整数编码的类别列（如名义变量的 0..k-1 码）可通过 `categorical_features` 声明。
+它们不按阈值切分，而是按**类别子集**划分，规则呈现为成员判断：
+
+```python
+tree = SegTree(categorical_features=["color"], max_categories=12).fit(df)
+# 规则示例： #3: color in {1, 2} AND income > 42 ...
+```
+
+异质性贡献：类别列使用 **Gini 杂度相对根 Gini 的比值**，连续/二值列保持归一化
+方差。Gini 只取决于类别*分布*，因此对编码做任何一一重映射都会得到等价的划分——
+结果与编码方式无关。
+
+注意：
+
+- 编码必须为整数值；非数值标签请先因子化
+  （`pd.factorize` 或 `df["color"].astype("category").cat.codes`）；
+- 任意大小的编码都会被精确处理（内部 int64/float64），即使连续列选择
+  `dtype=np.float32` 也不会合并；
+- 节点内会精确评估全部 `2^(k-1)-1` 种类别划分，请保持
+  `k <= max_categories`（稀有水平建议先归并）；高基数列更适合 one-hot；
+- 预测时未见过的编码由 `handle_unknown` 控制：`"complement"`（默认）确定性地
+  落入补集一侧且 `replay_check` 依然严格一致；`"error"` 抛出带特征名与未知值
+  的 `ValueError`。训练期类别集合通过 ``categories_`` 属性暴露；
+- ``profile_leaves`` 通过 ``category_enrichment``（`(特征, 编码, 叶内占比,
+  lift)`）报告类别结构，z 分数仅用于连续/二值特征。
+
+## 方法原理
+
+节点异质性 = 各特征组内方差除以根方差后的平均：
+
+```
+H(S) = (1/m) · Σ_j Var_j(S) / Var_j(root)          H(root) = 1
+```
+
+二值特征的伯努利方差 p(1−p) 天然适用同一公式，因此两类特征可在同一口径下比较。
+一刀切成 L/R 两块的收益：
+
+```
+Gain = H(S) − [ n_L/n_S · H(L) + n_R/n_S · H(R) ]
+```
+
+候选阈值取各特征在节点内的分位数（`quantiles=8` 即 5%~95% 共 8 个；二值特征仅 0.5
+一刀）。每个特征用排序 + 前缀和 O(n log n) 批量评估全部候选，堆维护全局最优叶子，
+Best-First 生长。满足任一条件即停止：最优刀收益低于 `min_gain`、子节点过小
+（`max(min_leaf_abs, min_leaf_frac·n)`）、达到 `max_depth`。
+
+两个开箱即用的可信度保证：
+
+- **收益可加性** —— `total_gain_ == h_root_ − h_avg_`（浮点误差量级），精确核算这棵树
+  解释掉了多少总异质性；
+- **规则回放** —— `replay_check()` 从零重新求值每条叶子规则链，必须与 `predict()`
+  逐行一致。
+
+测试套件还包含与一个独立朴素参考实现逐位一致性的对照测试。
+
+## API 一览
+
+```python
+SegTree(min_gain=0.01, min_leaf_frac=0.01, min_leaf_abs=50, max_depth=None,
+        quantiles=8, binary_features="auto", categorical_features=None,
+        max_categories=12, handle_unknown="complement", feature_names=None,
+        dtype=np.float64)
+```
+
+| 成员 | 用途 |
+|---|---|
+| `.fit(X)` / `.fit_predict(X)` / `.predict(X)` | sklearn 风格训练与归类 |
+| `.labels_`, `.n_leaves_`, `.leaves_`, `.cuts_` | 拟合结构 |
+| `.reduction_`, `.h_avg_`, `.total_gain_`, `.summary()` | 质量统计 |
+| `extract_rules(tree)` | 返回 `Rule` 列表（`str(rule)` 即规则链文本） |
+| `replay_labels(tree, X)` / `replay_check(tree, X)` | 规则回放校验 |
+| `profile_leaves(tree, X, top_k=3)` | 每类 z 分数画像 |
+| `bootstrap_stability(tree, X, ...)` | Bootstrap ARI（mean/std） |
+| `adjusted_rand_score(a, b)` | 纯 numpy 实现的 ARI |
+
+调参建议：
+
+- 想要更少、更大的人群 → 提高 `min_gain`（如 0.02~0.05）或减少 `quantiles`；
+- 规则想更短、结果想更稳 → 设 `max_depth`（4~6）；
+- 小数据集（< 5000 行）→ 降低 `min_leaf_abs`（默认 50 是为大数据设的下限）；
+- Bootstrap ARI 偏低 → 通常减少分位数、提高 `min_gain` 或限深即可稳定结构。
+
+## 与相关工具的比较
+
+- **先 k-means 再用 sklearn 决策树拟合**（代理树）：两步走，规则可能与聚类结果矛盾；
+  segmtree 把切分质量与规则一致性放进同一个目标。
+- **forest-clustering / URF**：基于森林邻近度的聚类，精度好但人群本身不可直接解释。
+- **CUBT（R 包）**：学术上最接近的方法；segmtree 在纯 numpy 包内补齐了 Best-First
+  生长、混合类型归一化、可加性自检与 Bootstrap 稳定性。
+
+## 开发
+
+```bash
+git clone <your-fork-url> && cd segmtree
+pip install -e .[dev]
+pytest            # 运行测试
+ruff check src tests
+```
+
+## 许可证
+
+MIT — 见 [LICENSE](LICENSE)。
+
+[English](README.md)