churnlib

churnlib is a small Python toolkit that helps data scientists run end‑to‑end customer churn analyses with just a few lines of code.

Features

• Simple configuration via ChurnConfig
• Automatic train/test split (time‑based or random)
• Sensible preprocessing for numeric and categorical features
• Baseline model selection (logistic regression & gradient boosting)
• Standard ML metrics (AUC, PR‑AUC, F1, etc.)
• Churn‑specific business metrics and lift table
• Simple HTML report summarising configuration, performance, and top features

Installation (local / editable)

From the directory that contains pyproject.toml:

pip install -e .

This will install churnlib in editable mode so changes to the source are picked up immediately.

Quickstart

import pandas as pd
from churnlib import ChurnProject

df = pd.read_csv("your_customer_table.csv")

project = ChurnProject.from_dataframe(
    df,
    id_col="customer_id",
    label_col="churn",
    positive_label=1,   # or "Yes"
    date_col="snapshot_date",        # optional
    prediction_horizon_days=30,      # optional, for documentation
)

# Run the full workflow: split, preprocess, model selection, evaluation
results = project.auto_fit(df)

# Notebook‑friendly summary
print(project.summary())

# Generate a simple HTML report
project.report("churn_report.html")

# Score new customers
scoring_df = df.sample(100).copy()
scores = project.score(scoring_df)
print(scores.head())

Dependencies

Key dependencies (also listed in pyproject.toml):

• pandas
• scikit‑learn
• matplotlib (for optional plotting helpers)

Running tests

pip install -e ".[dev]"
pytest