How InsideForest Works

InsideForest searches for geometric regions whose target distribution is useful. It is supervised clustering, not an alternative class predictor.

1. Generate candidate leaves

A fitted RandomForestClassifier partitions feature space. InsideForest extracts bounds, support, and target distributions from its physical leaves. The fitted generator is available as forest_; its feature importance is diagnostic metadata.

2. Score and select regions

InsideForestClassRegionClusterer evaluates purity, lift, and coverage for every class, then associates each physical leaf only with the class that maximizes the objective. Support, percentile, and per-class limits remove weak candidates. The default branch_aggregation="none" keeps this one-leaf/one-region geometry explicit.

3. Assign cluster IDs

For every observation, all matching regions are collected. The winning region has the highest score; ties use lower entropy, greater support, then lower cluster ID. If no region matches, the result is -1. The forest's class prediction is never used as a fallback.

model.fit(X_train, y_train)
cluster_ids = model.predict(X_test)
details = model.assign_regions(X_test)
memberships = model.transform(X_test)

4. Evaluate regions as clustering

region_quality_report reports coverage, unmatched rate, purity, lift, entropy, AMI, NMI, ARI, homogeneity, completeness, and class-level diagnostics. score(X, y) is AMI including -1; forest accuracy is outside the clusterer contract.

Choose a clusterer

Inspect the result

regions = model.explain_regions(top_n=20)
quality = model.region_quality_report(X_test, y_test)
print(model.labels_)         # training cluster IDs
print(model.region_metrics_) # region-level metrics

The lower-level Trees, Regions, and Labels modules remain available for custom pipelines, but their intermediate tables are not the canonical high-level output.