Metadata-Version: 2.4
Name: trust-free
Version: 2.1.4
Summary: TRUST - Decision Trees with Lasso Leaves and Random Forest accuracy
Home-page: https://adc-trust-ai.github.io/trust/
Author: Albert Dorador Chalar
Maintainer: TRUST Team
Maintainer-email: trustalgorithm.dev@gmail.com
License: Proprietary - Permissive Binary Only
Project-URL: Repository, https://github.com/adc-trust-ai/trust-free
Project-URL: Documentation, https://github.com/adc-trust-ai/trust-free/blob/main/MANUAL.md
Project-URL: Issue Tracker, https://github.com/adc-trust-ai/trust-free/issues
Keywords: machine learning,linear models,decision trees,random forest,regression,interpretable ml,explainable ai,ai safety,compliance
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Education
Classifier: Natural Language :: English
Requires-Python: >=3.11,<3.13
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: ipython>=9.4.0
Requires-Dist: joblib>=1.5.1
Requires-Dist: matplotlib>=3.10.5
Requires-Dist: numpy<2.0.0,>=1.26.4
Requires-Dist: pandas>=2.3.2
Requires-Dist: plotly>=6.3.1
Requires-Dist: PyALE>=1.2.0
Requires-Dist: pydot>=4.0.1
Requires-Dist: scikit-learn>=1.7.1
Requires-Dist: scipy>=1.16.1
Requires-Dist: shap>=0.48.0
Requires-Dist: statsmodels>=0.14.5
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# trust-free <a href="https://adc-trust-ai.github.io/trust"><img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/TRUST_logo_500x500.png" align="right" height="128" alt="TRUST logo"/></a>

[![PyPI version](https://img.shields.io/pypi/v/trust-free.svg)](https://pypi.org/project/trust-free/)
[![Python](https://img.shields.io/pypi/pyversions/trust-free.svg)](https://pypi.org/project/trust-free/)
[![Downloads](https://static.pepy.tech/badge/trust-free)](https://pepy.tech/project/trust-free)
[![License](https://img.shields.io/badge/license-Proprietary-lightgrey.svg)](LICENSE.txt)
[![User Manual](https://img.shields.io/badge/docs-User_Manual-blue)](https://github.com/adc-trust-ai/trust-free/blob/main/MANUAL.md)


### Model. Explain. TRUST. All in one package.

## Overview

**trust-free** is a Python package for fitting interpretable regression models using Transparent, Robust, and Ultra-Sparse Trees (TRUST™) — a new generation of Linear Model Trees (LMTs) with Random-Forest (RF) accuracy and intuitive explanations. The core methods are based on the [PRICAI 2025 paper](https://arxiv.org/abs/2506.15791) that introduced the TRUST algorithm, forthcoming in **Springer Nature (Lecture Notes in Artificial Intelligence)**.

It includes a **state-of-the-art explainability suite**, providing comprehensive, automatically-generated explanation reports. To see it in action, here are two 15-second demos showcasing the explain() and compare() methods applied to the famous [Medical Insurance Charges](https://www.kaggle.com/datasets/mirichoi0218/insurance) dataset from Kaggle:

<div align="center">
  <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain_demo_compressed.gif"
       alt="explain() method"
       width="96%" />
  <br><br>
  <strong>TRUST™’s <code>explain()</code> method</strong> — Straightforward prediction explanations
</div>

<br>

<div align="center">
  <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_compare_demo_compressed.gif"
       alt="compare() method"
       width="96%" />
  <br><br>
  <strong>TRUST™’s <code>compare()</code> method</strong> — Comprehensive head-to-head profile comparisons
</div>


### Proven Performance: Accuracy + Full Interpretability (60 Datasets)

| Model                   | **Test R² ↑** | **Interpretable?** |
|-------------------------|---------------|--------------------|
| **TRUST™**              | **0.67**      | ✅ Yes             |
| Random Forest (RF)      | 0.62          | ❌ No              |
| Lasso                   | 0.57          | ✅ Yes             |
| CART                    | 0.49          | ✅ Yes             |
| Node Harvest (NH)       | 0.47          | ✅ Yes             |
| M5' (Linear Model Tree) | 0.36          | ⚠️ Partially*      |

> In the table above, **TRUST™ is the only fully interpretable model statistically above 0.6 test R²** across varied benchmark datasets — and **6× sparser** than M5' (*17 vs 109 coefficients* on average).  
> *Source: PRICAI 2025 (Springer LNAI)*

See full benchmarks in the [PRICAI 2025 paper](https://arxiv.org/abs/2506.15791)

---

The package currently supports standard regression and experimental time-series regression tasks. Future releases will also tackle other tasks such as classification.

## Key Advantages: RF Accuracy ⟡ Tree Transparency ⟡ Linear Interpretability

- **Hybrid power**: Trees to capture non-linearity & interactions + sparse linear (Relaxed Lasso) models in leaves
- **Superior accuracy**: RF-level accuracy, proven on 60 benchmark datasets
- **Full transparency**: Every prediction is auditable via tree path + leaf equation
- **Inclusive**: Explanation reports written in natural language accessible to all audiences
- **Compliant by design**: 100% Compliant with the EU AI Act and the OECD AI Principles — ideal for high-stakes domains like finance and healthcare

### Media
- [Data Elixir](https://news.dataelixir.com/t/t-69C03215CCA6CFF02540EF23F30FEDED)
- [Data Science Weekly](https://datascienceweekly.substack.com/p/data-science-weekly-issue-616)

### About this edition
- ℹ️ Free-tier dataset limits: ≤ 5,000 rows and ≤ 20 columns (intended for proof-of-concept, R&D and teaching)
- ✅ All core features are fully functional within these bounds
- ✅ Unlimited scale and [additional features](https://github.com/adc-trust-ai/trust-free/blob/main/trust-pro.md) in the forthcoming **trust-pro** edition

**Want early access to trust-pro?**  
- Join the [waitlist](https://forms.gle/Gsti4kZ7yG5ZTNqu7) (completely anonymous & GDPR-compliant)
- Star ⭐ the project's [GitHub repository](https://github.com/adc-trust-ai/trust-free) to stay updated!


## Installation

You can install this package using pip:

```bash
pip install trust-free
```
> 📦 **Note:** The package name on PyPI is `trust-free`, but the module you import in Python is `trust`: `from trust import TRUST`.

### What's new in version 2.1.4? First version with **expanded platform compatibility**, plus minor improvements in many areas.

Check [CHANGELOG.md](https://github.com/adc-trust-ai/trust-free/blob/main/CHANGELOG.md) on the project's GitHub to see this and all past release notes.

ℹ️ Currently, `trust-free` includes a precompiled binary for:
- ✅ macOS11+ ARM64 
- ✅ macOS11+ Intel
- ✅ Both **Python 3.11** and **3.12** are supported. Support for Python 3.13+ will be added as soon as all trust-free dependencies support it.

Compatibility for Linux and Windows is **coming soon** for this release, projected for early December 2025:
- ⏳ Linux Intel (e.g. for Google Colab compatibility)
- ⏳ Linux ARM64
- ⏳ Windows Intel

🚀 Stay tuned!

For a fully reproducible development environment with all dependencies, see [SETUP.md](https://github.com/adc-trust-ai/trust-free/blob/main/SETUP.md).


## Usage

Here are two basic examples of how to use the TRUST™ algorithm:

```python
from trust import TRUST # note the import name is trust, not trust-free
from sklearn.datasets import make_regression
from sklearn.model_selection import train_test_split
from sklearn.metrics import r2_score, mean_squared_error
```

### 🧪 Example 1: Sparse Synthetic Regression (n=5000, p=20)
```python
X, y, coefs = make_regression(n_samples=5000, n_features=20, n_informative=10, coef=True, noise=0.1, random_state=123)
print(coefs)

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=123)
# Instantiate and fit your model
model = TRUST()
model.fit(X_train, y_train)
# Predict and print results
y_pred = model.predict(X_test)
print("Predictions:", y_pred[:5])
print("True y values:", y_test[:5])
print("test R\u00B2:", r2_score(y_test, y_pred))
```

```python
# Obtain (conditional) variable importance by Ghost method (based on Delicado and Pena, 2023)
model.varImp(X_test, y_test, corAnalysis=True, filename="Synthetic")
# Unconditional variable importance by permutation (with added debiasing and uncertainty quantification steps)
model.varImpPerm(X_test, y_test, R=20, B=20, U=10, filename="Synthetic")
```
<div align="center">
    <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/varImpScores_plot_Synthetic.png" alt="varImp" width="49.88%" />
    <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/varImpPermScores_plot_Synthetic.png" alt="varImpPerm" width="47%" />
</div>

```python
# Obtain prediction explanation for first observation
model.explain(X_test[0,:], mode="detailed", actual=y_test[0], filename="Synthetic") 
```
<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain1.png" alt="Explain1" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Pie_chart_Synthetic.png" alt="PieChart" width="50%" style="display: block; margin: auto;" />
</div>


### 🩺 Example 2: Diabetes Dataset (n=442, p=10)
```python
import pandas as pd
from sklearn import datasets
from sklearn.preprocessing import LabelEncoder

Diabetes = pd.DataFrame(datasets.load_diabetes().data)
Diabetes.columns = datasets.load_diabetes().feature_names
diab_target = datasets.load_diabetes().target
Diabetes.insert(len(Diabetes.columns), "Disease_marker", diab_target)
Diabetes_X = Diabetes.iloc[:,:-1]
# Binary encoding (0/1) for 'sex'
le = LabelEncoder()
Diabetes_X.loc[:, 'sex'] = le.fit_transform(Diabetes_X['sex']).astype(str)
Diabetes_y = Diabetes.iloc[:,-1]
RLT_Diabetes = TRUST(max_depth=1)
RLT_Diabetes.fit(Diabetes_X,Diabetes_y)
y_pred_TRUST = RLT_Diabetes.predict(Diabetes_X)
```
```python
# Tree plotting requires Graphviz to be installed in your system path
# You can use e.g. Homebrew: brew install graphviz or Conda: conda install -c conda-forge graphviz
RLT_Diabetes.plot_tree("Diabetes") #will save "tree_plot_Diabetes.png" in your working directory
```
<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/tree_plot_Diabetes.png" alt="tree" width="50%" style="display: block; margin: auto;" />
</div>


```python
# Obtain variable importance with 2 different methods: Ghost and permutation
RLT_Diabetes.varImp(Diabetes_X, Diabetes_y, corAnalysis=True, filename="Diabetes") #Ghost method
RLT_Diabetes.varImpPerm(Diabetes_X, Diabetes_y, filename="Diabetes") #Permutation method
```
<div align="center">
    <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/varImpScores_plot_Diabetes.png" alt="varImp2" width="49%" />
    <img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/varImpPermScores_plot_Diabetes.png" alt="varImp3" width="48.25%" />
</div>


```python
# Obtain prediction explanation for second observation
RLT_Diabetes.explain(Diabetes_X.iloc[1,:], aim="decrease", actual=Diabetes_y[1], filename="Diabetes")
```
<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain2.png" alt="Explain2" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain3.png" alt="Explain3" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_explain4.png" alt="Explain4" width="97%" style="display: block; margin: auto;" />
</div>


```python
# Compare the second and fourth observations head-to-head
RLT_Diabetes.compare(Diabetes_X.iloc[1,:], Diabetes_X.iloc[3,:], filename="Diabetes")
```
<div align="center">
<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_compare1.png" alt="Compare1" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Radar_chart_Diabetes.png" alt="Radar" width="50%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/trust-free_compare2.png" alt="Compare2" width="97%" style="display: block; margin: auto;" />

<img src="https://raw.githubusercontent.com/adc-trust-ai/trust-free/main/assets/Pie_charts_Diabetes.png" alt="Pies" width="97%" style="display: block; margin: auto;" />
</div>


### More Examples on Kaggle Datasets
- [Medical Insurance Charges (1.82M views, 360K downloads)](https://www.kaggle.com/datasets/mirichoi0218/insurance)
- [Life Satisfaction in the EU (own contribution)](https://www.kaggle.com/datasets/albertdorador/eu-life-satisfaction-eurostat-un-oecd)


## License

This software is provided under a Proprietary - Permissive Binary Only license.
For detailed terms, please refer to the [LICENSE.txt](https://github.com/adc-trust-ai/trust-free/blob/main/LICENSE.txt) file, which is also included with the distribution.

## More Information

For more details, documentation, and information about the full upcoming 'pro' version of the TRUST™ algorithm, visit:

https://github.com/adc-trust-ai/trust-free

Further details about the TRUST™ algorithm can be found in our preprint on arXiv:

https://www.arxiv.org/abs/2506.15791

Copyright © 2025 Albert Dorador Chalar. All rights reserved. TRUST™ is a trademark of Albert Dorador Chalar.
