Getting started

Installation

pip install guide-rs

The distribution is named guide-rs; the package imports as guide. Wheels cover Python 3.10 and later on Linux (x86_64, aarch64), macOS (x86_64, arm64) and Windows (x64); elsewhere pip builds from the source distribution, which needs a Rust toolchain.

To work on the package itself, run uv sync in python/ of a clone of the repository (requires a Rust toolchain and uv).

Fitting a tree

from sklearn.datasets import load_iris
from guide import GuideClassifier

X, y = load_iris(return_X_y=True)
model = GuideClassifier().fit(X, y)
model.predict_proba(X[:5])

plot_tree needs matplotlib, available as the plot extra (pip install "guide-rs[plot]"):

from guide import plot_tree

plot_tree(model)

The estimators follow the scikit-learn API, so they work in pipelines, clone, grid search and cross-validation.

GuideClassifier(node_model="lda", min_samples_leaf=10) grows GUIDE’s linear discriminant trees instead: each node splits on a discriminant coordinate of its own selected features (categorical ones as level dummies) and classifies with an LDA leaf. Periodic features must be excluded with feature_roles. node_model="lda_splits" keeps these splits but chooses cuts by Gini impurity and predicts with constant leaves, GUIDE’s linear-split option.

Inputs

  • Categorical features are used natively. DataFrame columns with object, string, categorical or boolean dtypes are categorical; for arrays, name them with categorical_features.

  • Missing values (NaN or None) are allowed in features. Splits send them left or right, and missing_flags can record why a value is missing.

  • Feature roles (feature_roles) make a column split only, fit only (a regressor in linear leaves), both or excluded. periodic_features declares cyclic columns such as hour of day.

Pruning and parallelism

Single trees are pruned by 10-fold cross-validation by default. pruning also accepts cost complexity, a fixed leaf count, a validation sample passed to fit as validation_data, or none.

Like GUIDE, classifiers choose the tree size by held-out misclassification cost. pruning_loss="log_loss" or "brier" uses a proper scoring rule instead, which judges the predicted probabilities rather than only the predicted class; forests then report that loss as oob_loss_.

Cross-validation folds, forest trees and importance permutations run in parallel. n_jobs sets the number of threads; unlike most scikit-learn estimators, its default of None uses all cores. Results are the same for any thread count.

Boosting

GuideBoostingRegressor and GuideBoostingClassifier fit gradient-boosted trees. Boosting is experimental: a guide-rs extension, not part of GUIDE, whose variable selection and defaults may change between releases. Each split variable comes from chi-square tests of the gradients against each predictor’s bins (GUIDE’s tests on the gradient signs for squared error), and the split point from the second-order gain, so variables with many distinct values are not favored. Early stopping keeps the round with the lowest loss on a validation set:

from guide import GuideBoostingClassifier

model = GuideBoostingClassifier(n_estimators=500, early_stopping_rounds=20)
model.fit(X_train, y_train, validation_data=(X_valid, y_valid))
model.n_estimators_  # rounds kept

Importance scores

guide.importance() computes GUIDE’s bias-adjusted variable importance from shallow unpruned trees and permutations of the response:

from guide import importance

report = importance(GuideClassifier(), X, y)
for score in report["scores"]:
    print(score["feature"], score["adjusted_score"], score["group"])