DisTreebution

🌳 Branching Out: The New Rust Implementation

We have turned a new leaf! DisTreebution now features a high-performance backend rewritten from the ground up in Rust, powered by PyO3 and Rayon.

This new implementation roots out Python's CPU bottlenecks, bringing massive parallel processing capabilities directly to your workflows while keeping the exact same user-friendly Python API.

🚀 Key Improvements

• 10–100× Wall-Clock Speedup: Tree fitting is massively accelerated.
• GIL-Free Parallelism: Powered by Rayon to scale feature searches across all available CPU cores.
• Cache-Optimized Storage: Features are stored column-major to ensure per-feature scans stay in CPU cache.
• Seamless Integration: Built with PyO3 for zero-overhead type conversion.
• Identical Math: Maintains the exact same (O(N \log N)) Fenwick tree (CRPS-RF) and min-max heap (PMQRF) algorithms.

⚡ Integration & Usage

You can start using the Rust engine without installing any compiler. Prebuilt wheels are fully available.

Head over to the distreebution-rs repository to get the installation commands and see how to use it as a drop-in replacement for your existing Python code.

Documentation

For detailed documentation and tutorials, visit: Documentation

DisTreebution fits distributional regression trees and forests to generate calibrated probabilistic forecasts.

It optimizes trees using:

• A sum of Pinball losses for multiple-quantile regression
• CRPS (Continuous Ranked Probability Score) for full distributional regression

The package also includes implementations of split conformal prediction methods built upon these forests of distributional trees. Two main conformal approaches are provided:

• Conformalized Quantile Regression, where nested sets are of the form $$\left( [q_{\beta}-t , q_{1-\beta} +t] \right)_t$$ for some nominal level $\beta$.

• Distributional Conformal Prediction, where nested sets are of the form $$\left( [q_{t} , q_{1-t}] \right)_t$$.

Paper: https://arxiv.org/abs/2502.05157

Installation

You can install DisTreebution in three ways. We recommend using the VS Code Dev Container for the easiest and most reproducible workflow.

---

Option 1 — Use VS Code Dev Container (recommended)

The easiest way to use DisTreebution is via a VS Code Dev Container:

1. Make sure you have:

   • Visual Studio Code
   • Docker running
   • VS Code Dev Containers extension installed
   • Cloned this repository

2. Open the project folder (the folder containing .devcontainer/ and notebooks/) in VS Code.

3. Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) → search Dev Containers: Reopen in Container → press Enter.

4. VS Code will:

   • Pull the quentinduchemin/distreebution Docker image if necessary
   • Mount your project folder into the container at /workspace
   • Open a fully configured environment with Python, Jupyter, and all dependencies ready

5. You can now open notebooks in notebooks/ directly inside VS Code and run DisTreebution without additional setup.

Option 2 — Install from source

git clone https://github.com/quentin-duchemin/DisTreebution
cd DisTreebution
pip install -e .

Option 3 — Use Docker without VSCode

A pre-built Docker image are available on Docker Hub:

• quentinduchemin/distreebution

Pull the images:

docker pull quentinduchemin/distreebution

Run the image:

docker run --rm -it \
  -v $(pwd):/workspace \
  -w /workspace \
  quentinduchemin/distreebution

---

Tutorial

For tutorial and examples: Tutorial Notebook

---

Citation

If you use DisTreebution in your research, please cite:

@article{distreebution2026,
  title={Efficient distributional regression trees learning algorithms for calibrated non-parametric probabilistic forecasts},
  author={Quentin Duchemin and Guillaume Obozinski},
  year={2026}
}

---

License

This project is licensed under the BSD 3-Clause License.
See the LICENSE file for details.