InsideForest

Current release: 0.4.3

InsideForest discovers interpretable regions in tabular data through supervised clustering. A random forest is used only to generate candidate leaves; the public estimators select useful regions, describe them, and assign observations to region-cluster IDs.

The canonical estimators are:

InsideForestRegionClusterer for general categorical targets.
InsideForestClassRegionClusterer when each region must retain its complete class distribution and class-specific diagnostics.
InsideForestContinuousRegionClusterer for continuous targets.

predict(X) always returns cluster IDs. An observation outside every selected region receives -1; there is no fallback to RandomForest.predict or predict_proba.

Install

python -m pip install InsideForest==0.4.3

For development:

git clone https://github.com/jcval94/InsideForest.git
cd InsideForest
python -m pip install -e .
python -m pip install -r requirements-dev.txt

OPEN THE COMPLETE USE-CASE NOTEBOOK DIRECTLY IN COLAB

Class-guided regions

from sklearn.datasets import load_wine
from sklearn.model_selection import train_test_split
from InsideForest import InsideForestClassRegionClusterer

X, y = load_wine(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, stratify=y, random_state=42
)

model = InsideForestClassRegionClusterer(
    rf_params={"n_estimators": 50, "random_state": 42},
    min_support=2,
    leaf_percentile=90,
    branch_aggregation="none",
)
cluster_ids = model.fit_predict(X_train, y_train)
test_cluster_ids = model.predict(X_test)

assignments = model.assign_regions(X_test)
region_scores = model.transform(X_test)
regions = model.explain_regions(top_n=10)
quality = model.region_quality_report(X_test, y_test)
class_regions = model.regions_for_class(model.classes_[0], top_n=5)
ambiguous = model.ambiguous_regions(top_n=10)

Each physical leaf can produce at most one final region. Its region_target_class is the class that maximizes the configured purity-lift-coverage objective. Overlaps are resolved by region score, entropy, support, and stable cluster ID.

For categorical targets, score(X, y) is adjusted mutual information (AMI), including cluster -1. Quality reports also include coverage, unmatched rate, NMI, ARI, homogeneity, completeness, purity, lift, entropy, and class-level diagnostics.

Continuous-target regions

from sklearn.datasets import load_diabetes
from sklearn.model_selection import train_test_split
from InsideForest import InsideForestContinuousRegionClusterer

X, y = load_diabetes(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.3, random_state=42
)

model = InsideForestContinuousRegionClusterer(
    rf_params={"n_estimators": 50, "random_state": 42},
    min_support=3,
    leaf_percentile=90,
    branch_aggregation="none",
)
model.fit(X_train, y_train)

cluster_ids = model.predict(X_test)
assignments = model.assign_regions(X_test)
quality = model.region_quality_report(X_test, y_test)
eta_squared = model.score(X_test, y_test)

Continuous regions store support, coverage, mean, median, standard deviation, IQR, range, target shift, dispersion reduction, separation, and region score. The canonical score is η²: the fraction of target variance explained by all returned clusters, including -1. Numeric target prediction is intentionally outside the clusterer contract.

Shared API and fitted attributes

All canonical clusterers expose:

fit, fit_predict, predict, and transform.
assign_regions, explain_regions, and region_quality_report.
score, get_params, set_params, save, and load.
forest_, raw_regions_, regions_, region_metrics_, and training assignments in labels_.
feature_importances_ and plot_importances, which describe only the branch-generating forest.

InsideForestClassRegionClusterer additionally exposes regions_for_class, ambiguous_regions, class_coverage_report, and classes_ metadata.

Compatibility

InsideForestClassifier, InsideForestMulticlassClassifier, and InsideForestRegressor are deprecated migration aliases. They emit FutureWarning; the classifier/regressor aliases temporarily preserve their legacy forest-based score behavior. New code should use the canonical clusterers above. These compatibility names are scheduled for removal in 0.5.0.

Historical low-level helpers (Trees, Regions, Labels, metadata utilities, and description helpers) remain available, but they are not the canonical estimator contract.

Validation

The class-region benchmark evaluates coverage, unmatched rate, clustering agreement, regional quality, stability, runtime, and memory:

python experiments/validate_class_region_clusters.py --profile quick

The continuous benchmark evaluates η², coverage, dispersion reduction, assignment stability, geometric stability, and branch compression. Forest R²/RMSE are reported separately as generator diagnostics:

python experiments/validate_regression_regions.py --profile quick

Run the complete test suite with:

python -m pytest tests -q

See the documentation site, quick API, migration API pages, and v0.4.3 changelog for details.

License

InsideForest is distributed under the MIT License.

Metadata

Release files for InsideForest 0.4.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for InsideForest 0.4.3
File	Size	Uploaded
insideforest-0.4.3.tar.gz	149.5 kB	Jun 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for InsideForest 0.4.3
File	Interpreter	ABI	Platform	Reset
insideforest-0.4.3-py3-none-any.whl 123.4 kB Jun 30, 2026	Python 3	none	any	Details

Total release size: 273.0 kB

Release files / insideforest-0.4.3.tar.gz

Download URL	insideforest-0.4.3.tar.gz
Size	149.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`6ae4a981d2191699b0a5f87567cc1eed8c1276040fe4c723be99d4d4a27f447c`
BLAKE2b-256 checksum How to use checksums	`6719d8ebb95dfb550e671f2f9e236b7015177de41bf7aa81e1a78c7fd7944cd4`
Upload date	Jun 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.9`

Release files / insideforest-0.4.3-py3-none-any.whl

Download URL	insideforest-0.4.3-py3-none-any.whl
Size	123.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`c91f43a859ca8fa581631846a8c84773beba983ccb3c7b10e25f5f5e05d91496`
BLAKE2b-256 checksum How to use checksums	`62ded9e7424402e8d818ee471924534c56942f7352f0169d2c6fa4099370dafe`
Upload date	Jun 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.9`