Skip to content

Choose Your Path

Start with the question you need to answer, not the whole package.

Canonical first step

After install, the default first command is:

cranalytics quickstart

Use this page when you already know roughly what kind of risk question or data shape you are working with.

For full column constraints, accepted values, and alias tables, use Input Data Contracts. This page stays intentionally lighter and focuses on routing.

Fast Picks

If you need to... Start here First run First win Next doc
Forecast cumulative loss by cohort Vintage curve fitting cranalytics quickstart -> choose Vintage Curve Fitting Ranked smoothing comparison and projected tail output Vintage Analysis Tutorial
Forecast portfolio lifetime loss from transition assumptions or loan history Lifetime loss forecasting cranalytics quickstart -> choose Lifetime Loss Forecasting Reserve estimate on a mock portfolio Lifetime Loss Forecasting Tutorial
Bucket a portfolio by score bands and estimate mix/LGD FICO segmentation and portfolio diagnostics cranalytics quickstart -> choose FICO Segmentation FICO-band table and mix diagnostics FICO Segmentation Tutorial
Decide which variables are worth modeling Credit risk feature analytics cranalytics quickstart -> choose Feature Analytics Ranked feature table Feature Analytics Tutorial
Build loan-level predictive models and backtest them over time ML modeling cranalytics quickstart -> choose ML Modeling Session result with fold-level backtest, diagnostics, and scored data ML Modeling Tutorial
Analyze time-to-default or prepayment curves Survival analysis (advanced) python -m cranalytics.examples.core_survival Survival/hazard view by cohort Survival Analysis Tutorial
Generate charts for vintage or survival outputs Visualization (advanced) Start from the vintage plotting snippet below Reusable analyst-facing chart Vintage Analysis Tutorial

If you already know the right workflow, each section below also lists the direct demo command. The table above keeps the first-run path consistent for a new user.

Start from the data you already have

Data you already have Best starting point
Loan-level portfolio snapshot Lifetime Loss Forecasting or FICO Segmentation
Loan history panel by observation date Lifetime Loss Forecasting or ML Modeling
Loan-level booked-loan data plus a known flag Feature Analytics
Loan-month panel with performance history ML Modeling
Monthly aggregated flows by segment and MOB Rollforward Workflow
Cohort/vintage loss observations Vintage Curve Fitting
Time-to-event records Survival Analysis

Core Workflows

Vintage Curve Fitting

Use this when: you have cohort-level performance over months on book and want to fit or smooth cumulative loss curves.

  • Minimum input columns: vintage_date, months_on_book, cumulative_loss_rate (or pass custom column names such as vintage_name and mob)
  • First run: cranalytics quickstart -> choose Vintage Curve Fitting
  • Direct demo: python -m cranalytics.examples.core_vintage
  • First win: ranked smoothing comparison and optional projected tail
  • Next doc: Vintage Analysis Tutorial
  • Do not start here if you already have transition assumptions or loan history and want a reserve estimate
  • Instead go to: Lifetime Loss Forecasting

Lifetime Loss Forecasting

Use this when: you already have a transition matrix, transition ledger, or loan history panel and want a portfolio-level lifetime loss estimate.

  • Minimum portfolio columns: loan_id, principal, annual_rate, term_months, start_date, status
  • Also required: transition input in one of three shapes:
  • a square transition matrix whose rows and columns share the same states and include Charged Off (or legacy Default)
  • a transition ledger with loan_id, period, and status
  • a loan history panel with loan_id, fund_date, and as_of_date
  • First run: cranalytics quickstart -> choose Lifetime Loss Forecasting
  • Direct demo: python -m cranalytics.examples.core_lifetime_loss
  • First win: reserve estimate on a mock portfolio
  • Next doc: Lifetime Loss Forecasting Tutorial
  • Full contract: Input Data Contracts
  • Do not start here if your real source data is monthly aggregated flows
  • Instead go to: Special Case: Monthly Rollforward Data

FICO Segmentation & Portfolio Diagnostics

Use this when: you want fast portfolio segmentation before deeper modeling work.

  • Minimum input columns: fico_score
  • Often useful extras: principal, collateral_value, collateral_type
  • First run: cranalytics quickstart -> choose FICO Segmentation
  • Direct demo: python -m cranalytics.examples.core_segmentation
  • First win: FICO-band table and mix diagnostics
  • Next doc: FICO Segmentation Tutorial
  • Full contract: Input Data Contracts
  • Do not start here if you need temporal backtesting or model training
  • Instead go to: ML Modeling

Credit Risk Feature Analytics

Use this when: you want to engineer lending features and rank them before training a model.

  • Minimum input shape for a meaningful first pass: a loan-level DataFrame with fields like loan_id, principal, annual_rate, term_months, start_date, fico_score, plus a binary flag column such as fpf30_flag
  • Optional external backend: install optbinning if you want optimal WoE binning via fit_woe_binning()
  • First run: cranalytics quickstart -> choose Feature Analytics
  • Direct demo: python -m cranalytics.examples.core_feature_analytics
  • First win: ranked feature table ordered by separation strength
  • Next doc: Feature Analytics Tutorial
  • Full contract: Input Data Contracts
  • Do not start here if you already know your features and need out-of-time validation metrics
  • Instead go to: ML Modeling
import pandas as pd

from cranalytics import engineer_loan_features, rank_features_by_separation

ref_date = pd.Timestamp("2025-12-31")
train = engineer_loan_features(train_df, reference_date=ref_date)
ranking = rank_features_by_separation(
    train,
    feature_cols=feature_cols,
    flag_col="fpf30_flag",
)
print(ranking.head())

ML Modeling

Use this when: you need target construction, temporal backtesting, model training, scoring, and loan-level to calendar-month bridging.

  • Minimum panel columns in build_targets(..., mode="panel"): loan_id, mob, as_of_date, origination_date, original_principal, dpd, chargeoff_amount
  • Also required for backtesting/training: a modeling frame with feature_cols, a target column such as fpf30_flag, and a temporal split column such as origination_month
  • First run: cranalytics quickstart -> choose ML Modeling
  • Direct demo: python -m cranalytics.examples.core_ml_modeling
  • First win: fold-level backtest summary plus a trained baseline classifier
  • Next doc: ML Modeling Tutorial
  • Full contract: Input Data Contracts
  • Do not start here if you have not yet checked which variables carry signal
  • Instead go to: Credit Risk Feature Analytics
from cranalytics import run_predictive_modeling_session

session = run_predictive_modeling_session(
    modeling_df,
    feature_cols=feature_cols,
    target_col="fpf30_flag",
    split_col="origination_month",
    model_family="hgb_classifier",
)
print(session.backtest[["split", "auc", "gini", "ks"]])
print(session.training_diagnostics)

Advanced Modules

Survival Analysis

Use this when the problem is about time-to-default, time-to-prepayment, competing exits, or hazard timing instead of aggregate loss curves.

  • Minimum input fields for your own data: start date, end date or censoring date, and a status column that identifies default vs censored outcomes
  • First run: python -m cranalytics.examples.core_survival
  • First win: survival/hazard timing curves by cohort
  • Next doc: Survival Analysis Tutorial
  • Do not start here if your goal is a simple reserve estimate from a static transition matrix
  • Instead go to: Lifetime Loss Forecasting

Visualization

Use this when you already have vintage, smoothing, or survival outputs and need quick analyst-facing charts.

  • Viz deps (matplotlib, plotly, seaborn) are included in the base install — no extra needed.
  • Typical starting inputs: a vintage triangle or curve-comparison DataFrame
  • First win: a reusable chart you can drop into an analyst review or notebook
  • First example:
from cranalytics.viz import plot_vintage_triangle

fig = plot_vintage_triangle(triangle_df)
fig.show()

Special Case: Monthly Rollforward Data

If your real starting point is aggregated monthly rollforward data instead of loan-level records, use the onboarding diagnostics first.

  • Minimum input columns: segment_id, month_on_book, payments, chargeoffs, outstanding_balance
  • First run: cranalytics rollforward-readiness your_rollforward_data.csv --output-dir rollforward_readiness_out
  • First win: readiness report and data-quality diagnostics written to disk
  • Then run: cranalytics rollforward-workflow your_rollforward_data.csv --output-dir rollforward_out
  • Next doc: Rollforward Workflow API
  • Full contract: Input Data Contracts
  • Do not start here if your real data is already a loan-level portfolio snapshot or vintage panel
  • Instead go to: Start from the data you already have

Not sure about column names?

See the Input Data Contracts reference — every input shape, required column, type, and value constraint in one place.