Skip to content

Welcome to OrdBoost

ordboost is a Python library for non-parametric discrete ordinal gradient boosting and continuous regression.

By reframing continuous targets as discrete ordinal binning problems, ordboost models complex, skewed, or multimodal target distributions without forcing restrictive parametric assumptions.

Key Features

  • Scikit-Learn API Compatibility: Fits seamlessly into standard ML workflows using fit, predict, and predict_dist.
  • Non-Parametric Probabilistic Output: Obtains complete predictive distribution objects capable of extracting probability mass functions (PMF), cumulative distribution functions (CDF), percentiles (ppf), and dynamic prediction intervals.
  • Flexible Continuous Target Mapping: Maps continuous values to discrete target spaces using configurable binning strategies (QuantileBinMapper, UniformBinMapper, EmpiricalMeanBinMapper, EmpiricalMedianBinMapper, ContinuousBinMapper).
  • Monotonic Ordinal Constraints: Supports constrained ordinal boosting (e.g., isotonic constraints) across sequential boundaries.
  • Probabilistic Evaluation: Evaluates probabilistic predictions directly using CRPS (crps_score), quantile loss (pinball_loss), and their skill scores.
  • Prediction Intervals Measures: Measures the prediction interval coverage (interval_coverage_rate), sharpness (sharpness), and Winkler score (winkler_score).
  • Calibration Diagnostics: Computes marginal calibration (marginal_calibration_curve) and probabilistic calibration (pit_diagnostics).

Quickstart example

Get started with continuous probabilistic regression in just a few lines of code:

OrdBoost regression example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
import numpy as np

from ordboost import OrdBoostRegressor

# --- Generate data
# 1. Generate synthetic continuous regression data with non-linear skew
rng = np.random.default_rng(42)
X_train = rng.standard_normal((300, 3))
y_train = np.exp(X_train[:, 0] * 0.6) + rng.normal(0.0, 0.5, size=300)

X_test = rng.standard_normal((1, 3))

# --- Fit model
# 2. Instantiate and fit OrdBoostRegressor
reg = OrdBoostRegressor(
    bin_edges=[-0.5, 1.5, 3.0, 5.5],
    mapper="mean",
    learning_rate=0.05,
    max_iter=50,
    random_state=42,
)
reg.fit(X_train, y_train)

# --- Predict
# 3. Generate continuous point predictions
y_pred_mean = reg.predict(X_test)
y_pred_median = reg.predict(X_test, method="median")

# 80% prediction intervals
dist = reg.predict_dist(X_test)
lower_80, upper_80 = dist.interval(alpha=0.20)
prob_under_3 = dist.cdf(3.0)

# Display predictions for test sample
print(
    f"Predicted mean: {y_pred_mean[0]:.2f} "
    f"[80% PI: {lower_80[0]:.2f}, {upper_80[0]:.2f}]"
)
print(
    f"Predicted median: {y_pred_median[0]:.2f} "
    f"[80% PI: {lower_80[0]:.2f}, {upper_80[0]:.2f}]"
)
print(f"P(Y <= 3.0): {prob_under_3[0]:.2%}")

Installation

Standard Installation

Install the published package directly from PyPI:

pip install ordboost

Installing from source (Developer setup)

To set up a local development environment and contribute to ordboost:

  1. Clone the GitHub repository:
git clone [https://github.com/Surgical-Recovery-and-Safety-Lab/ordboost.git](https://github.com/Surgical-Recovery-and-Safety-Lab/ordboost.git)
cd ordboost
  1. Install the package in editable mode with development dependencies: 
    pip install -e ".[dev]"

Explore examples

For step-by-step code walkthroughs and diagnostic workflows, visit the Example pages:

  • Quickstart examples: Basic discrete ordinal ranking and continuous prediction interval workflows.
  • Evaluating model quality: Model calibration diagnostics using PIT histograms, interval coverage, and Winkler scores.
  • Advanced examples: Creating custom target mappers by extending BaseBinMapper and learning how to use floor_atom and lower_bound.

Contributing

We welcome contributions from the community! Whether you are fixing bugs, improving documentation, or proposing new features:

  1. Feel free to open an issue or start a discussion on our GitHub Repository.

  2. Submit Pull Requests targeting the main branch.

  3. Ensure all unit tests pass before submitting (pytest).

License

This project is licensed under the Apache-2.0 License. Developed and maintained by the Surgical Recovery and Safety Lab.