Metadata-Version: 2.4
Name: fgclustering
Version: 3.0.0
Summary: Forest-Guided Clustering: Explainability method for Random Forest models.
Author: Dominik Thalmeier
Author-email: Lisa Barros de Andrade e Sousa <lisa.barros.andrade.sousa@gmail.com>, Helena Pelin <helena.pelin@helmholtz-muenchen.de>, Marie Piraud <marie.piraud@helmholtz-muenchen.de>
Maintainer-email: Lisa Barros de Andrade e Sousa <lisa.barros.andrade.sousa@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Helmholtz AI
        
        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.
        
Project-URL: documentation, https://forest-guided-clustering.readthedocs.io/en/latest/
Project-URL: repository, https://github.com/HelmholtzAI-Consultants-Munich/fg-clustering
Keywords: random forest,xai,explainable ai,forest-guided clustering
Classifier: Programming Language :: Python :: 3
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: matplotlib>=3.6
Requires-Dist: seaborn>=0.12
Requires-Dist: scikit-learn>=1.2
Requires-Dist: scipy>=1.9
Requires-Dist: numba>=0.57
Requires-Dist: tqdm>=4.65
Requires-Dist: kmedoids>=0.4
Requires-Dist: statsmodels>=0.13.5
Requires-Dist: numexpr>=2.8.4
Requires-Dist: imbalanced-learn>=0.11
Requires-Dist: plotly>=5.15
Requires-Dist: nbformat>=5.7
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="https://raw.githubusercontent.com/HelmholtzAI-Consultants-Munich/fg-clustering/main/docs/source/_figures/FGC_Logo.png" width="200">
	

# *Forest-Guided Clustering* - Shedding light into the Random Forest Black Box 

[![Docs](https://img.shields.io/badge/docs-latest-blue?style=flat&logo=readthedocs)](https://forest-guided-clustering.readthedocs.io/en/latest/)
[![PyPI](https://img.shields.io/pypi/v/fgclustering.svg)](https://pypi.org/project/fgclustering)
[![PyPI Downloads](https://static.pepy.tech/badge/fgclustering)](https://pepy.tech/projects/fgclustering)
[![stars](https://img.shields.io/github/stars/HelmholtzAI-Consultants-Munich/forest_guided_clustering?logo=GitHub&color=yellow)](https://github.com/HelmholtzAI-Consultants-Munich/forest_guided_clustering/stargazers)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![arXiv](https://img.shields.io/badge/arXiv-2507.19455-b31b1b.svg)](https://doi.org/10.48550/arXiv.2507.19455)
[![test](https://github.com/HelmholtzAI-Consultants-Munich/fg-clustering/actions/workflows/test.yml/badge.svg)](https://github.com/HelmholtzAI-Consultants-Munich/fg-clustering/actions/workflows/test.yml)
	
</div>

## ✨ About this Package

<!-- LINK INTRODUCTION START -->

**Why Use Forest-Guided Clustering?**

Forest-Guided Clustering (FGC) is an explainability method for Random Forest models that addresses one of the key limitations of many standard XAI techniques: the inability to effectively handle correlated features and complex decision patterns. Traditional methods like permutation importance, SHAP, and LIME often assume feature independence and focus on individual feature contributions, which can lead to misleading or incomplete explanations. As machine learning models are increasingly deployed in sensitive domains like healthcare, finance, and HR, understanding why a model makes a decision is as important as the decision itself. This is not only a matter of trust and fairness, but also a legal requirement in many jurisdictions, such as the European Union's GDPR which mandates a “right to explanation” for automated decisions.

FGC offers a different approach: instead of approximating the model with simpler surrogates, it uses the internal structure of the Random Forest itself. By analyzing the tree traversal patterns of individual samples, FGC clusters data points that follow similar decision paths. This reveals how the forest segments the input space, enabling a human-interpretable view of the model's internal logic. FGC is particularly useful when features are highly correlated, as it does not rely on assumptions of feature independence. It bridges the gap between model accuracy and model transparency, offering a powerful tool for global, model-specific interpretation of Random Forests.

**📢 New! Forest-Guided Clustering is now on arXiv**

Please see our paper [Forest-Guided Clustering - Shedding Light into the Random Forest Black Box](https://doi.org/10.48550/arXiv.2507.19455) for a detailed description of the method, its theoretical foundations, and practical applications. Check it out to learn more about how FGC reveals structure in your Random Forest models!

**Prefer a visual walkthrough?**
Watch our short introduction video by clicking below:

<div align="center">

[![Video](http://i.vimeocdn.com/video/1501376117-3e402fde211d1a52080fb16b317efc3786a34d0be852a81cfe3a03aa89adc475-d_295x166)](https://vimeo.com/746443233/07ddf2290b)

</div>

**Curious how Forest-Guided Clustering compares to standard methods?**
See our notebook: [Introduction to FGC: Comparison of Forest-Guided Clustering and Feature Importance](https://github.com/HelmholtzAI-Consultants-Munich/fg-clustering/blob/main/tutorials/introduction_to_FGC_comparing_FGC_to_FI.ipynb).

<!-- LINK INTRODUCTION END -->

**Want to dive deeper?**
Visit our [full documentation](https://forest-guided-clustering.readthedocs.io/) for:

- Getting Started – Installation and quick start
- Tutorials – Use cases for classification, regression, and large datasets
- API Reference – Detailed descriptions of functions and classes

## 🛠️ Installation

<!-- LINK INSTALLATION START -->

**Requirements**

This package was tested for `Python 3.10 - 3.13` on ubuntu, macos and windows. It depends on the `kmedoids` python package. If you are using windows or macos, you may need to first install Rust/Cargo with:

    conda install -c conda-forge rust


If this does not work, please try to install Cargo from source:

    git clone https://github.com/rust-lang/cargo
    cd cargo
    cargo build --release


For further information on the kmedoids package, please visit [this page](https://pypi.org/project/kmedoids/).

All other required packages are automatically installed if installation is done via `pip`.


**Install Options**

The installation of the package is done via pip. Note: if you are using conda, first install pip with: `conda install pip`.

PyPI install:

    pip install fgclustering


Installation from source:

    git clone https://github.com/HelmholtzAI-Consultants-Munich/fg-clustering.git


- Installation as python package (run inside directory):

		pip install .   


<!-- LINK INSTALLATION END -->

## 💻 How to Use Forest-Guided Clustering

<!-- LINK BASIC USAGE START -->

**Basic Usage**

To apply Forest-Guided Clustering (FGC) for explaining a Random Forest model, you can follow the simple workflow consisting of three main steps: computing the forest-guided clusters, evaluating feature importance, and visualizing the results.

```python
# for classification tasks
clustering_distance_metric = DistanceRandomForestProximity()
# for regression tasks
clustering_distance_metric = DistanceRandomForestLCA()

# compute the forest-guided clusters
fgc = forest_guided_clustering(
    estimator=model, 
    X=X, 
    y=y, 
    clustering_distance_metric=clustering_distance_metric, 
    clustering_strategy=ClusteringKMedoids(),
)

# evaluate feature importance for best k
fgc_fi = forest_guided_feature_importance(
    X=X, 
    y=y, 
    y_pred=model.predict(X),
    cluster_labels=fgc.cluster_labels[fgc.best_k],
)

# visualize the results
plot_forest_guided_clustering(
    ks=fgc.ks, 
    scores=fgc.scores, 
    mean_ji=fgc.mean_ji, 
    cluster_jis=fgc.cluster_jis, 
    best_k=fgc.best_k, 
)

plot_forest_guided_feature_importance(
    feature_importance_local=fgc_fi.feature_importance_local,
    feature_importance_global=fgc_fi.feature_importance_global,
)

plot_forest_guided_decision_paths(
    data_clustering=fgc_fi.data_clustering,
    feature_importance_global=fgc_fi.feature_importance_global,
    feature_importance_local=fgc_fi.feature_importance_local,
    model_type=fgc.model_type,
)
```

where
- `estimator` is the trained Random Forest model
- `X` is the feature matrix
- `y` is the target variable
- `clustering_distance_metric` defines how similarity between samples is measured based on the Random Forest structure
- `clustering_strategy` determines how the distance-based clustering is performed 

For a detailed walkthrough, refer to the [Introduction to FGC: Simple Use Cases](https://github.com/HelmholtzAI-Consultants-Munich/fg-clustering/blob/main/tutorials/introduction_to_FGC_use_cases.ipynb) notebook.


**Using FGC on Large Datasets**

When working with datasets containing a large number of samples, Forest-Guided Clustering (FGC) provides several strategies to ensure efficient performance and scalability:

* *Parallelize Cluster Optimization*: Leverage multiple CPU cores by setting the `n_jobs` parameter to a value greater than 1 in the `forest_guided_clustering()` function. This will parallelize the bootstrapping process for evaluating cluster stability.

* *Use a Faster Clustering Algorithm*: Improve the efficiency of the K-Medoids clustering step by using the optimized `"fasterpam"` algorithm. Set the `method` parameter of your clustering strategy (e.g., `ClusteringKMedoids(method="fasterpam")`) to activate this faster implementation.

* *Enable Subsampling with CLARA*: For extremely large datasets, consider using the CLARA (Clustering Large Applications) variant by choosing `ClusteringClara()` as your clustering strategy. CLARA performs clustering on smaller random subsamples, making it suitable for high-volume data.

For a detailed example, please refer to the notebook [Special Case: FGC for Big Datasets](https://github.com/HelmholtzAI-Consultants-Munich/fg-clustering/blob/main/tutorials/special_case_big_data_with_FGC.ipynb).

<!-- LINK BASIC USAGE END -->

## 🤝 Contributing

<!-- LINK CONTRIBUTION START -->
 
We welcome contributions of all kinds—whether it’s improvements to the code, documentation, tutorials, or examples. Your input helps make Forest-Guided Clustering more robust and useful for the community.

To contribute:

1. Fork the repository.
2. Make your changes in a feature branch.
3. Submit a pull request to the main branch.

We’ll review your submission and work with you to get it merged.

If you have any questions or ideas you'd like to discuss before contributing, feel free to reach out to [Lisa Barros de Andrade e Sousa](mailto:lisa.barros@helmholtz-munich.de).

<!-- LINK CONTRIBUTION END -->

## 📝 How to cite

<!-- LINK CITE START -->

If you find Forest-Guided Clustering useful in your research or applications, please consider citing it:

```
@article{barros2025forest,
    title	= {Forest-Guided Clustering -- Shedding Light into the Random Forest Black Box},
    author	= {Lisa Barros de Andrade e Sousa,
		   Gregor Miller,
		   Ronan Le Gleut,
		   Dominik Thalmeier,
		   Helena Pelin,
		   Marie Piraud},
    journal	= {ArXiv},
    year	= {2025},
    url         = {https://doi.org/10.48550/arXiv.2507.19455}
}

```

<!-- LINK CITE END -->

## 🛡️ License

<!-- LINK LICENSE START -->

The `fgclustering` package is released under the MIT License. You are free to use, modify, and distribute it under the terms outlined in the [LICENSE](https://github.com/HelmholtzAI-Consultants-Munich/fg-clustering/blob/main/LICENSE) file.

<!-- LINK LICENSE END -->
