fetch_iranian_churn#

empulse.datasets.fetch_iranian_churn(*, backend, data_home=None, download_if_missing=True)[source]#

Fetch the Iranian Churn dataset from the UCI ML Repository (binary classification).

The goal is to predict whether a telecom customer will churn. The target variable is whether the customer churned, 1 = churned, 0 = active.

Uses the UCI ML Repository API (stdlib only — no extra dependencies).

For additional information about the dataset, consult the User Guide.

Classes

2

Churners

495

Non-churners

2755

Samples

3150

Features

12
Parameters:
backendmodule

Dataframe library to use for data and target. Pass the library module directly, e.g. backend=polars or backend=pandas.

data_homestr or Path, optional

Directory used for caching downloaded data. Defaults to ~/empulse_data (or $EMPULSE_DATA_HOME).

download_if_missingbool, default=True

If False, raise an OSError when the data is not cached locally.

Returns:
datasetDataset

instance_costs contains {'clv': array} — the customer lifetime value of each customer, extracted from the Customer Value column.

Notes

Cost matrix (deterministic, \(\gamma\) treated as a fixed scalar):

Actual positive \(y_i = 1\)

Actual negative \(y_i = 0\)

Predicted positive \(\hat{y}_i = 1\)

tp_benefit \(= \gamma (CLV_i - d \cdot CLV_i - f \cdot CLV_i) - (1-\gamma) f \cdot CLV_i\)

fp_cost \(= d \cdot CLV_i + f \cdot CLV_i\)

Predicted negative \(\hat{y}_i = 0\)

fn_cost \(= CLV_i\)

tn_cost \(= 0\)

The cost matrix uses symbolic parameters with the following defaults:

  • incentive_fraction (\(d\)) = 0.05

  • contact_fraction (\(f\)) = 0.01

  • accept_rate (\(\gamma\)) = 0.3

To override these defaults, pass the desired values when evaluating the metric:

metric(dataset.target, y_score, accept_rate=0.5, **dataset.instance_costs)

References

[1]

Jafari-Marandi, R., Denton, J., Idris, A., Smith, B. K., & Keramati, A. (2020). Optimum profit-driven churn decision making. Neural Computing and Applications, 32(18), 14929–14962.

Examples

import numpy as np
import pandas as pd
from empulse.datasets import fetch_iranian_churn
from empulse.metrics import Metric, Cost

dataset = fetch_iranian_churn(backend=pd)

# replace with your own model's predicted probabilities
y_score = np.random.default_rng(0).uniform(size=len(dataset.target))

metric = Metric(dataset.cost_matrix, Cost())
score = metric(dataset.target, y_score, **dataset.instance_costs)
On this page