Hierarchical Genetic Programming Library

A Python library for explainable rule-based classification. It evolves human-readable boolean rule trees via hierarchical genetic programming, with automatic binarization and parallel benchmarking.

Full documentation: https://fii-optim-lab.github.io/hgp-lib/

What it does

hgp_lib evolves boolean rules that classify tabular data. A rule is a tree of logical operators (And, Or) over literals, for example And(age < 50, Or(income >= 30k, employed)). Rules are readable, so a trained classifier can be inspected and explained.

The method is genetic programming. A population of candidate rules is scored against the data, the best rules are selected, and crossover and mutation produce the next generation. Over many epochs the population converges toward rules with high fitness. Hierarchical GP extends this with child populations that evolve on sampled subsets of features, then combine into larger rules.

Boolean GP operates on boolean data. Numeric and categorical columns are binarized first, so a numeric feature becomes a set of boolean bins. See Data Preparation for details.

The model is a single boolean rule, so it is readable on its own and needs no separate explanation. See Theory for how the search works and Interpretability for why this matters.

Installation

pip install hgp-lib
# or
pip install "hgp-lib[dev]"

Editable install:

git clone https://github.com/fii-optim-lab/hgp-lib.git
cd hgp-lib
# Create a python virtual environment first, and activate it
pip install -e ".[dev]"
# Now you are able to change the code and run the tests
python -m pytest

Quickstart

BooleanRuleClassifier is the fastest way to train an interpretable rule end to end. It binarizes the raw data for you, evolves a rule, and applies the same binarization when predicting. The example below is fully runnable on the scikit-learn breast_cancer dataset.

from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split

from hgp_lib import BooleanRuleClassifier
from hgp_lib.configs import BooleanGPConfig, TrainerConfig

X, y = load_breast_cancer(return_X_y=True, as_frame=True)
X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, stratify=y, random_state=0
)
X_train, X_val, y_train, y_val = train_test_split(
    X_train, y_train, test_size=0.25, stratify=y_train, random_state=0
)

config = TrainerConfig(
    gp_config=BooleanGPConfig(), num_epochs=1000, val_every=100
)
clf = BooleanRuleClassifier(config)  # StandardBinarizer by default; pass binarizer=... to customize
clf.fit(X_train, y_train, X_val, y_val)  # validation data is binarized internally too

predictions = clf.predict(X_test)  # raw data is binarized internally
print(clf.format_rule())           # the evolved rule as plain logic

Validation data is optional; when given, it is binarized with the same fitted binarizer and used to track a validation score during training. clf.format_rule() prints the rule with the binarized column names, so the model reads as plain logic. To binarize and train manually with GPTrainer, see Training; the Data Preparation guide shows how to avoid leaking data between splits.

Benchmarking

GPBenchmarker runs multiple independent experiments and aggregates the results. Each run takes a stratified train/test split, performs k-fold cross-validation on the training set, and evaluates the best rule on the held-out test set. Runs execute in parallel by default.

The benchmarker binarizes data internally, per fold, so you pass a raw pandas.DataFrame and skip manual binarization.

import numpy as np
from sklearn.datasets import load_breast_cancer
from hgp_lib.configs import BenchmarkerConfig, BooleanGPConfig, TrainerConfig
from hgp_lib.benchmarkers import GPBenchmarker

X, y = load_breast_cancer(return_X_y=True, as_frame=True)

gp_config = BooleanGPConfig()
trainer_config = TrainerConfig(gp_config=gp_config, num_epochs=1000, val_every=100)
config = BenchmarkerConfig(
    data=X,
    labels=y.to_numpy(),
    trainer_config=trainer_config,
    num_runs=30,
    n_folds=5,
    test_size=0.2,
    n_jobs=-1,
)
benchmarker = GPBenchmarker(config)
result = benchmarker.fit()

test_scores = result.test_scores
print(f"Test score: {np.mean(test_scores):.4f} ± {np.std(test_scores):.4f}")

# Human-readable best rule
print(result.best_rule.to_str(result.best_run.feature_names))

# sklearn-style predict on raw data (binarized internally with the best run's binarizer)
predictions = benchmarker.predict(X)

See Benchmarking for scorer optimization, custom binarizers, and the aggregated result fields.

Customizing the algorithm

The population, mutation, and crossover behavior is configured through factories passed to BooleanGPConfig. The default factories cover the common case. To use custom initialization strategies or mutations, subclass a factory and override its construction hook.

from hgp_lib.populations import PopulationGeneratorFactory

factory = PopulationGeneratorFactory(population_size=100)

The Configuring HGP guide covers the built-in factories and hierarchical GP. The Extending HGP guide covers custom strategies, mutations, and low-level use of BooleanGP directly.

Documentation

• Getting Started
• Theory
• Interpretability
• Data Preparation
• Training
• Benchmarking
• Configuring HGP
• Extending HGP
• Rule Trees
• Experiments
• API Reference

Contributing

See CONTRIBUTING.md.