6. Datasets

Everything in the previous stages needs a cost matrix. Writing one for your own problem is the subject of The cost matrix; these five datasets come with theirs already written.

Empulse bundles five real-world cost-sensitive datasets for benchmarking and for the examples throughout this documentation. Each one ships not just features and a target, but a CostMatrix encoding the business problem it came from — which is what makes them useful for value-driven work, where a plain feature matrix is not enough. They are also the fastest way to see a realistic cost matrix that somebody else had to derive.

Every loader returns a Dataset and takes a required, keyword-only backend argument. Pass the dataframe library’s module itself, not a string — neither pandas nor polars is a hard dependency of Empulse, so the loader takes the one you already have.

pandas

import pandas as pd
from empulse.datasets import fetch_iranian_churn

dataset = fetch_iranian_churn(backend=pd)
X, y = dataset.data, dataset.target

polars

import polars as pl
from empulse.datasets import fetch_iranian_churn

polars_dataset = fetch_iranian_churn(backend=pl)
X_polars, y_polars = polars_dataset.data, polars_dataset.target

6.1. Choosing a dataset

Dataset	Samples	Features	Positives	Availability	Cost matrix
Iranian churn	3,150	12	15.7%	Downloaded	Symbolic, per-customer CLV
Churn TV subscriptions	9,379	46	4.79%	Bundled	Precomputed, all four terms
Bank telemarketing upsell	37,931	10	12.6%	Bundled	Symbolic, per-customer balance
Credit scoring PAKDD	38,938	25	19.9%	Bundled	Symbolic, per-applicant credit line
Give Me Some Credit	112,915	10	6.7%	Downloaded	Symbolic, per-applicant credit line

Bundled datasets ship inside the package and work offline. Downloaded datasets are fetched on first use and cached under ~/empulse_data (override with $EMPULSE_DATA_HOME or the data_home argument), so only the first call needs a network connection.

6.2. A note on cost matrices

The distinction in the last column matters more than it looks.

Most of these datasets carry a symbolic cost matrix: the business parameters stay named, with defaults, so you can override them at call time (accept_rate=0.5) and ask what-if questions without rebuilding anything. Only the genuinely per-row quantities — a customer’s lifetime value, an applicant’s credit line — arrive as arrays in instance_costs.

load_churn_tv_subscriptions is the exception: it ships precomputed costs, with all four outcome terms supplied directly as arrays. That makes it a natural fit for the models’ plain cost arguments, but its business parameters cannot be varied after the fact.

6.3. Where next

The Tutorial uses the Iranian churn dataset end to end, and is the best place to see one of these datasets put to work.