Skip to content

Getting Started

1. Install

pip install cranalytics
# or: uv add cranalytics

Visualization (matplotlib, plotly, seaborn) and survival analysis (lifelines) are included in the base install.

Optional modeling backends are extras:

pip install "cranalytics[ml]"        # optbinning: optimal WoE binning
pip install "cranalytics[xgboost]"   # xgboost model families
pip install "cranalytics[lightgbm]"  # lightgbm challenger workflows

Install troubleshooting

Official CPython 3.11 or 3.12 is the easiest path; Python 3.10+ is supported. If install fails on compiled dependencies (numpy, scipy, pyarrow):

  • Upgrade pip first (python -m pip install --upgrade pip) so binary wheels resolve.
  • Prefer official CPython over alternative interpreters.
  • On Windows, install or update the Microsoft Visual C++ Redistributable if pyarrow fails to import after install.
  • If you already use conda/mamba, conda-forge can be the simplest fallback for the scientific dependencies.

2. Run the canonical first command

cranalytics quickstart

This is the recommended first-run experience. It shows the package workflows, walks through synthetic examples, and tells you what real-world data shape you need next. Your goal is one first win and one clear next step, not a full tour of every command.

If you already know the workflow you want, use the same entry point without the interactive menu:

cranalytics quickstart --workflow vintage
cranalytics quickstart --workflow lifetime-loss --show-requirements
cranalytics quickstart --workflow vintage --write-template
cranalytics quickstart --workflow feature-analytics --write-template

3. Pick the right workflow

Use one of these pages next:

If you already know the right workflow, those pages also point to the stable direct demo command, such as:

cranalytics demo vintage

quickstart is still the default recommendation for a new user.

4. Validate or prepare your own data

If you are starting with a portfolio snapshot, see what columns the built-in portfolio validator expects first:

cranalytics check --show-schema

Then validate your portfolio file:

cranalytics check your_data.csv

check auto-detects portfolio, vintage, rollforward, and feature-analytics schemas. Use <slug> check to select a workflow explicitly. Rollforward data also has a dedicated pre-flight command:

cranalytics rollforward check your_rollforward_data.csv --output-dir rollforward_readiness_out

After the pre-flight check, run the monthly operating workflow:

cranalytics rollforward run your_rollforward_data.csv --output-dir rollforward_out

The CLI Reference lists the files it writes. The CLI reads CSV only. For Parquet or warehouse data, load a DataFrame and use the Python API:

from pathlib import Path
import pandas as pd
from cranalytics.rollforward import Rollforward

df = pd.read_parquet("your_rollforward_data.parquet")
result = Rollforward(df).run(mode="workflow", output_dir=Path("rollforward_out"))
print(result.status, result.champion)

For advanced ML modeling, survival, or other shapes without a CLI validator, use the workflow-specific references and tutorials, starting with Input Data Contracts.

Workflow Starter template Validation path
Lifetime loss forecasting Portfolio template cranalytics check your_data.csv
FICO segmentation Portfolio template cranalytics check your_data.csv
Portfolio simulation Portfolio template cranalytics check your_data.csv
Rollforward workflow Rollforward template cranalytics rollforward check your_rollforward_data.csv --output-dir rollforward_readiness_out
Vintage curve fitting Vintage template cranalytics vintage check your_data.csv
Feature analytics Feature analytics template cranalytics feature-analytics check your_data.csv
Advanced ML modeling, survival No starter template cranalytics <slug> check your_data.csv; see cranalytics <slug> run --help for required semantic mappings

5. Go deeper by workflow

Larger examples live in the repository's examples/ directory: an end-to-end pipeline on 35k LendingClub loans (lendingclub_full_pipeline.py) and an interactive Streamlit dashboard (streamlit-demos/).

6. Reference