Empulse: Cost-Sensitive Learning in Python

Not every mistake costs the same.

Accuracy, F1 and AUC treat a false positive and a false negative as equally bad. Your business does not. Flagging a loyal customer as a churner wastes a discount; missing a real churner loses their entire lifetime value. A model tuned for accuracy quietly optimises the wrong thing.

Empulse is a Python package for cost-sensitive classification and value-driven (profit-driven) machine learning. It lets you write down what each outcome is actually worth, then use that same definition to evaluate models, train them, and set their decision threshold — all as ordinary scikit-learn estimators.

Installation

Empulse requires Python 3.11 or higher.

pip install empulse

To pull in every optional dependency at once:

pip install empulse[optional]

A model that makes money

On a real telecom churn dataset, an ordinary logistic regression reaches 0.93 ROC AUC and 89% accuracy — and earns 2.28 per customer once the retention campaign is priced in. Training the same data against the cost matrix turns that into a profit of 3.29 per customer.

import pandas as pd
from empulse.datasets import fetch_iranian_churn
from empulse.metrics import Cost, Metric
from empulse.models import CSLogitClassifier

dataset = fetch_iranian_churn(backend=pd)
X, y = dataset.data, dataset.target
clv = dataset.instance_costs['clv']  # each customer's lifetime value

# The dataset ships a cost matrix; turn it into a metric
expected_cost = Metric(dataset.cost_matrix, Cost())

# Train a model that optimises it directly
model = CSLogitClassifier(loss=expected_cost)
model.fit(X, y, clv=clv)

print(expected_cost(y, model.predict_proba(X)[:, 1], clv=clv))

Define your own cost matrix just as easily:

from empulse.metrics import Cost, CostMatrix, Metric

# A spam filter: a legitimate email marked as spam is 5x worse than spam getting through
cost_matrix = (
    CostMatrix().add_fp_cost('missed_email').add_fn_cost('wasted_time').set_default(missed_email=5, wasted_time=1)
)
expected_cost = Metric(cost_matrix, Cost())

Read the 5-minute quickstart or the full tutorial.

Features

Profit-driven metrics	Ready-made metrics for churn, acquisition and credit scoring, or build your own from a symbolic cost matrix.
Cost-sensitive models	Logistic regression, gradient boosting, trees, forests, bagging, minimax probability machines and evolutionary trees — all trained on your cost matrix.
Threshold tuning	Pick the cut-off that maximises profit instead of defaulting to 0.5, or classify the top-k% by score.
Instance-dependent costs	Costs that differ per row are routed through pipelines and cross-validation automatically via scikit-learn metadata routing.
Robustness	RobustCSClassifier detects and imputes outliers in noisy instance-dependent costs.
Samplers	Cost-proportionate resampling and bias mitigation to make any estimator cost-sensitive.
Optimizers	L-BFGS-B, SGD/Adam/RMSProp with learning-rate schedules, and genetic/memetic algorithms for non-smooth objectives.
Datasets	Cost-sensitive datasets, each shipping its own cost matrix.

Works with scikit-learn

Every estimator follows scikit-learn conventions, so it drops into Pipeline, GridSearchCV and cross_val_score unchanged, and every metric can be wrapped with make_scorer.

from sklearn.model_selection import GridSearchCV
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from empulse.models import CSLogitClassifier

pipeline = Pipeline([
    ('scaler', StandardScaler()),
    ('model', CSLogitClassifier()),
])
search = GridSearchCV(pipeline, {'model__C': [0.1, 1, 10]})
search.fit(X, y, model__fp_cost=10, model__fn_cost=1)

Documentation

Full documentation at empulse.readthedocs.io:

• Getting Started — install, quickstart, and which tool you need
• Tutorial — a complete worked churn example
• User Guide — in-depth guides per component
• API Reference — every class and function

Citing

If you use Empulse in your research, please cite it via its Zenodo DOI.

License

AGPLv3 — see LICENSE.