trust-free 2.1.3

TRUST - Decision Trees with Lasso Leaves and Random Forest accuracy

trust-free

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. It is based on this PRICAI 2025 paper, forthcoming in Springer Nature (Lecture Notes in Artificial Intelligence).

It includes a state-of-the-art explanation suite. Here are two 15-second demos showcasing the explain() and compare() methods, which generate automated explanation reports for the famous Medical Insurance Charges dataset from Kaggle:

TRUST™’s explain() method — Straightforward prediction explanations

TRUST™’s compare() method — Comprehensive head-to-head profile comparisons

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

---

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

ℹ️ Free-tier dataset limits (for proof-of-concept, R&D and teaching): ≤ 5,000 rows and ≤ 20 features ✅ All core features are fully functional within these bounds ✅ Unlimited scale and additional features in the forthcoming trust-pro edition

Want early access?

• Join the waitlist (completely anonymous & GDPR-compliant)
• Star ⭐ the repo to stay updated!

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

What's new in version 2.1.3?

TL;DR: First version with expanded platform compatibility, plus minor improvements in many areas.

Check CHANGELOG.md on the project's GitHub to see this and all past release notes.

Installation

You can install this package using pip:

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.

ℹ️ 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 late November 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.

Usage

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

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)

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))

# 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")

# Obtain prediction explanation for first observation
model.explain(X_test[0,:], mode="detailed", actual=y_test[0], filename="Synthetic") 

🩺 Example 2: Diabetes Dataset (n=442, p=10)

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)

# 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

# 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

# Obtain prediction explanation for second observation
RLT_Diabetes.explain(Diabetes_X.iloc[1,:], aim="decrease", actual=Diabetes_y[1], filename="Diabetes")

# Compare the second and fourth observations head-to-head
RLT_Diabetes.compare(Diabetes_X.iloc[1,:], Diabetes_X.iloc[3,:], filename="Diabetes")

More Examples on Kaggle Datasets

• Medical Insurance Charges (1.82M views, 360K downloads)
• Life Satisfaction in the EU (own contribution)

License

This software is provided under a Proprietary - Permissive Binary Only license. For detailed terms, please refer to the 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.