Rollforward Workflow API Reference

Rollforward Workflow

Rollforward is the single object for all three rollforward surfaces: .run(mode="model") (in-memory), .run(mode="workflow", output_dir=...) (artifact-emitting), and .readiness(...). The module-level run(df) is a one-line convenience over model mode. Run readiness checks first when working with a new dataset. The result types (RollforwardRunSummary, operational_status, etc.) are the canonical cross-surface summary contract.

Each result also has .summary()/.plot() (RollforwardResult, RollforwardWorkflowResult) matching vintage/survival/predictive. ReadinessRunResult is a deliberate partial exception: it already has a field named summary (the readiness scoring dict), so result.summary — no call — already serves that role there; it still has .plot().

`cranalytics.rollforward`

Unified public front door for the rollforward workflow.

Rollforward is the single object for all three rollforward surfaces, hiding the multi-module session / evaluation / reporting / result-translation chain behind a small interface:

.run(mode="model") -> in-memory :class:RollforwardResult
.run(mode="workflow") -> artifact-emitting :class:RollforwardWorkflowResult
.readiness(...) -> readiness :class:ReadinessRunResult

model and workflow share the same session engine and differ only in whether artifacts are written, so they are two modes of one run. readiness uses a distinct session, config, and defaults, so it is a sibling method on the same object rather than a mode with half-ignored parameters. The module-level run (workflow-namespaced: cranalytics.rollforward.run) is a thin convenience over model mode.

No file I/O in model mode — fully in-memory.

This module carries the workflow's real entry-point logic (the Rollforward class), unlike the pure re-export facades used by other workflows — there is no separate flat module to preserve here.

`ReadinessRunResult` `dataclass`

No .summary() method here: summary is already a field (the readiness scoring dict), so result.summary already gives the compact summary other Phase 3 workflow results expose via a method call.

`plot(**kwargs: Any) -> Any`

Forecast-vs-actual chart already written to output_dir. Requires matplotlib.

`RollforwardResult` `dataclass`

`summary() -> pd.DataFrame`

Champion-vs-challenger backtest comparison, best-first by MAPE.

`plot(**kwargs: Any) -> Any`

Per-segment champion MAPE bar chart. Requires matplotlib.

`RollforwardWorkflowResult` `dataclass`

Workflow status and selected Rollforward model information.

`summary() -> pd.DataFrame`

One-row DataFrame of portfolio KPIs (total balance, champion, etc.).

`plot(**kwargs: Any) -> Any`

Forecast-vs-actual chart already written to output_dir. Requires matplotlib.

`Rollforward`

`is_ready_to_model() -> bool`

Quick pre-flight: no critical data issues and sufficient MOB history (>=18).

`run(*, mode: RollforwardRunMode = 'model', output_dir: Path | str | None = None, holdout_months: int = 6, min_train_months: int = 12, step_months: int = 1, variants: list[str] | None = None, monitor_thresholds: dict[str, float] | None = None, segment: str | None = None, strict: bool = False) -> RollforwardResult | RollforwardWorkflowResult`

run(*, mode: Literal['model'] = 'model', output_dir: Path | str | None = None, holdout_months: int = 6, min_train_months: int = 12, step_months: int = 1, variants: list[str] | None = None, monitor_thresholds: dict[str, float] | None = None, segment: str | None = None, strict: bool = False) -> RollforwardResult

run(*, mode: Literal['workflow'], output_dir: Path | str, holdout_months: int = 6, min_train_months: int = 12, step_months: int = 1, variants: list[str] | None = None, monitor_thresholds: dict[str, float] | None = None, segment: str | None = None, strict: bool = False) -> RollforwardWorkflowResult

Run the rollforward workflow in-memory (model) or with artifacts (workflow).

Parameters:

Name	Type	Description	Default
`mode`	`RollforwardRunMode`	`"model"` returns an in-memory result; `"workflow"` also writes committee-ready artifacts to `output_dir`.	`'model'`
`output_dir`	`Path \| str \| None`	Required when `mode="workflow"`; ignored otherwise.	`None`
`holdout_months`	`int`	Final months reserved for holdout evaluation.	`6`
`min_train_months`	`int`	Minimum historical months required for training.	`12`
`step_months`	`int`	Backtest step size.	`1`
`variants`	`list[str] \| None`	Optional candidate variant names.	`None`
`monitor_thresholds`	`dict[str, float] \| None`	Optional KPI threshold overrides.	`None`
`segment`	`str \| None`	Optional single segment to model.	`None`
`strict`	`bool`	Whether warnings should fail validation.	`False`

Returns:

Type	Description
`RollforwardResult \| RollforwardWorkflowResult`	class:`RollforwardResult` for `model` mode, or
`RollforwardResult \| RollforwardWorkflowResult`	class:`RollforwardWorkflowResult` for `workflow` mode.

Raises:

Type	Description
`ValueError`	If `mode` is not `"model"` or `"workflow"`, or if `mode="workflow"` is used without `output_dir`. For readiness reports use :meth:`readiness`.

`readiness(*, output_dir: Path | str, holdout_months: int = 6, min_train_months: int = 6, segment: str | None = None, strict: bool = False, scoring_config: ReadinessConfig | None = None, weights: Mapping[str, float] | None = None) -> ReadinessRunResult`

Generate a rollforward readiness report and emit its artifacts.

Readiness uses a distinct session and scoring configuration from :meth:run, including a lower default min_train_months. The input frame is copied, so the caller's DataFrame is never mutated.

`run(df: pd.DataFrame, **kwargs) -> RollforwardResult`

Convenience one-liner: initialize, run in-memory model mode, return result.

For artifact-emitting workflow runs or readiness reports, use the :class:Rollforward object directly (.run(mode="workflow", ...) / .readiness(...)) — those need an output_dir and have different defaults, so they are not folded into this convenience function.

Rollforward Contract

The contract module owns reusable validation for aggregated monthly flow data. Use it when integrating a new source or diagnosing alias resolution.

`cranalytics.rollforward._contract`

Public input-contract helpers for the Rollforward workflow.

`RollforwardContractResult` `dataclass`

Bases: IssueTableResultMixin

Normalized rollforward data plus collected contract issues.

`normalized_df(*, segment: str | None = None) -> pd.DataFrame`

Return normalized rollforward data, optionally filtered to one segment.

`amtloan_series(*, segment: str | None = None) -> pd.Series | None`

Return resolved denominator series, optionally filtered to one segment.

`amtloan_map(*, segment: str | None = None) -> dict[str, float]`

Return resolved denominators as a segment->value mapping.

`validate_rollforward_input_contract(df: pd.DataFrame, *, amtloan_col: str = 'amtloan', strict: bool = False) -> RollforwardContractResult`

Normalize columns, resolve aliases, and collect rollforward data issues.

Rollforward Backtest

Backtest helpers compare candidate Rollforward variants over historical holdouts. Use these lower-level functions when you need custom evaluation control beyond the workflow boundary.

`cranalytics.rollforward._backtest`

Backtesting helpers for Rollforward workflow variants.

`run_rollforward_backtest_sweeps(df: pd.DataFrame, *, variants: list[str] | None = None, holdout_horizons: tuple[int, ...] = (3, 6), min_train_months: int = 12, step_months: int = 1, amtloan_by_segment: pd.Series | None = None, amtloan_col: str = 'amtloan') -> pd.DataFrame`

Run rolling OOT backtests across configured rollforward variants.

`summarize_rollforward_variant_performance(results: pd.DataFrame) -> pd.DataFrame`

Aggregate split-level rollforward backtest results to one row per variant.

`select_rollforward_champion_and_challengers(summary: pd.DataFrame, *, benchmark_variant: str = 'baseline_flat_last_hazard', challenger_count: int = 2) -> dict[str, Any]`

Select a champion variant subject to baseline promotion rules.

Rollforward Workflow API Reference