Quick API

InsideForest 0.4.3 exposes three canonical supervised region clusterers. All follow fit/predict, and predict returns region-cluster IDs rather than target classes or numeric values.

General supervised regions

from sklearn.datasets import load_iris
from InsideForest import InsideForestRegionClusterer

X, y = load_iris(return_X_y=True)
model = InsideForestRegionClusterer(
    rf_params={"n_estimators": 40, "random_state": 21}
)
labels = model.fit_predict(X, y)
assignments = model.assign_regions(X)
regions = model.explain_regions(top_n=10)
quality = model.region_quality_report(X, y)

labels and model.labels_ are cluster IDs. score(X, y) returns AMI, and rows outside every selected region receive -1.

Class-enriched regions

from InsideForest import InsideForestClassRegionClusterer

class_regions = InsideForestClassRegionClusterer(
    leaf_percentile=95,
    min_support=2,
    branch_aggregation="none",
    random_state=21,
)
cluster_ids = class_regions.fit_predict(X, y)
setosa_regions = class_regions.regions_for_class(0, top_n=5)
ambiguous = class_regions.ambiguous_regions(top_n=10)
coverage = class_regions.class_coverage_report()

Each selected physical leaf has one region_target_class and retains its complete class_distribution. classes_ is region metadata, not the output space of predict.

Assignment schema

assign_regions(X) reports cluster_id, target-class metadata, membership score, class distribution, lift, entropy, margin, all matching region IDs, and a source limited to region or unmatched. There is no RandomForest fallback and no predict_proba.

Persistence

model.save("region-clusterer.joblib")
loaded = InsideForestRegionClusterer.load("region-clusterer.joblib")
assert (loaded.predict(X) == model.predict(X)).all()

Persistence retains the forest generator, regions, distributions, metrics, and training assignments. Legacy serialized models can be migrated, but labels_ must be recalculated when it previously stored a metrics table.

Regression

from InsideForest import InsideForestContinuousRegionClusterer

continuous = InsideForestContinuousRegionClusterer(
    leaf_percentile=90,
    min_support=3,
    branch_aggregation="none",
)
region_ids = continuous.fit_predict(X, y_continuous)
eta_squared = continuous.score(X, y_continuous)
details = continuous.assign_regions(X)

predict returns region IDs and score is η², including -1. InsideForestRegressor is deprecated and retains forest R² only for migration.