Which tool do I need?#

Empulse has a lot of surface area. This page maps problems to the component that solves them, so you can skip straight to the right guide.

Everything rests on one idea: write down what each classification outcome is worth, then reuse that definition everywhere. That definition is a CostMatrix, and pairing it with a strategy makes it a Metric you can score with, train on, and threshold by.

Start from your situation#

I want to…

Use

Score a model I already have, in money rather than accuracy

A prebuilt metric (churn, acquisition, credit scoring) or your own Metric

Train a model that optimises business value directly

CSLogitClassifier, CSBoostClassifier, CSTreeClassifier and ensembles

Keep my existing model and only fix the decision threshold

CSThresholdClassifier / CSRateClassifier

Keep my existing model and change the training data instead

CostSensitiveSampler

Handle costs that differ for every row

Instance-dependent costs and metadata routing

Handle cost estimates that are noisy or contain outliers

RobustCSClassifier

Make predictions independent of a sensitive attribute

Bias mitigation

Benchmark on realistic data

Bundled datasets

Choosing a metric strategy#

A cost matrix on its own is not a number. A strategy decides how it becomes one, and the right choice depends on what you have and what you want.

Strategy

Direction

Expects

Use when

Cost

Lower is better

Calibrated probabilities

You want the expected cost per instance, in currency.

Savings

Higher is better

Calibrated probabilities

You want that same cost relative to a naive baseline, as a 0-1 ratio that is comparable across datasets.

MaxProfit

Higher is better

Ranking scores

The threshold is not fixed yet and you want the profit at the best possible cut-off — optionally averaging over uncertain business parameters.

Warning

Cost and Savings assume y_score holds calibrated probabilities; MaxProfit only needs a ranking. Passing the wrong kind does not raise an error, it just returns a misleading number. See Choosing the right metric for the details.

Not every model supports every strategy — Use your custom metric inside a model has the compatibility table.

Choosing a model#

Model

Best when

CSLogitClassifier

You want a linear, interpretable model with coefficients you can explain.

CSBoostClassifier

You want the strongest predictive performance and have XGBoost, LightGBM or CatBoost installed. Usually the best default.

CSTreeClassifier

You want a single interpretable tree split on a cost-sensitive criterion.

CSForestClassifier / CSBaggingClassifier

You want the robustness of an ensemble of cost-sensitive trees.

ProfLogitClassifier / ProfTreeClassifier

Your objective is non-smooth (typically MaxProfit) and needs a gradient-free optimizer.

B2BoostClassifier

You have a B2B churn problem and want the cost matrix pre-wired.

RobustCSClassifier

Your instance-dependent costs are estimates that may contain outliers.

Two ways to specify costs#

Every cost-sensitive model accepts costs in either of two forms.

Plain costs — quickest, when your costs are just four numbers or four arrays:

from empulse.models import CSBoostClassifier
from sklearn.datasets import make_classification

X, y = make_classification(n_samples=200, random_state=42)

model = CSBoostClassifier()
model.fit(X, y, fp_cost=5, fn_cost=100)

A Metric — when costs are built from business parameters, or you want the same definition used for scoring and training:

from empulse.metrics import Cost, CostMatrix, Metric

cost_matrix = (
    CostMatrix()
    .add_fp_cost('discount')
    .add_fn_cost('lost_value')
    .set_default(discount=5, lost_value=100)
)
model = CSBoostClassifier(loss=Metric(cost_matrix, Cost()))
model.fit(X, y)

Prefer the second when a parameter varies per instance, when you want to tune a business parameter by cross-validation, or when the cost formula is more than a single number per outcome.

Where next#