Loss Forecasting API Reference

Loss Forecasting

cranalytics.loss_forecasting

Loss forecasting utilities based on transition matrices.

forecast_lifetime_loss(portfolio_df, migration_matrix, lgd=0.5, as_of_date=None, amortize=False, cpr=0.0, *, history_state_col='transition_state', history_strict=False)

Estimate total lifetime loss over remaining contractual term.

Formula: Loss = Exposure at Default (EAD) * Probability of Default (PD) * LGD.

.. warning:: Oversimplified Model for Baseline Testing Only This function uses a static transition matrix. You may pass that matrix directly, a transition ledger (loan_id, period, status), or a raw/ canonical loan-history panel (loan_id, fund_date, as_of_date) that is converted to a cohort matrix internally. The resulting forecast still assumes the matrix is static and the current principal balance does not amortize or prepay over the remaining term unless amortize=True is specified. Even with amortization, it applies fixed PDs scaled against decaying balances instead of true, time-dependent simulation. For robust, term-adjustable forecasting, please use cranalytics.simulation.simulate_portfolio_cashflows.

forecast_portfolio_states(migration_matrix, initial_states, n_periods)

Project future state distributions using a Markov chain.

.. warning:: Static Matrix Assumption This function assumes transition probabilities are static across time (the Markov Property) and identical for all loans regardless of age (Months on Book) or risk factors (FICO). It should be used as a high-level heuristic or baseline test, not as a primary state forecaster.

summarize_lifetime_loss(portfolio_df, migration_matrix, lgd=0.5, as_of_date=None, amortize=False, cpr=0.0, *, history_state_col='transition_state', history_strict=False)

Return a summary report for lifetime loss forecasting.