cranalytics 0.2.0__py3-none-any.whl

cranalytics/README.md

@@ -0,0 +1,42 @@
+# Source Layout Guide
+
+This package is organized around workflow boundaries rather than one deep class
+hierarchy. Use this file when you know the business workflow and need to find
+the right implementation file quickly.
+
+## Start here first
+
+- `__init__.py`: top-level re-export surface for common user-facing imports
+- `cli.py`: CLI command registration and command-specific flow
+- `validation.py`: shared reusable validation rules across workflows
+- `governance_models.py`: internal Pydantic models for non-DataFrame governance artifacts and workflow metadata
+- `docs/reference/module_map.md`: source-to-test-to-doc map by workflow
+
+## Workflow boundaries
+
+- Vintage: `vintage.py` facade over `vintage_fitting.py`, `vintage_smoothing.py`, `vintage_validation.py`, `vintage_transforms.py`, `vintage_session.py`, `vintage_wide.py`; prefer `run_vintage_analysis_session()` for multi-step comparison and validation
+- Lifetime Loss Forecasting: `loss_forecasting.py`, with related cashflow logic in `simulation.py`
+- Loan snapshot normalization: `loan_snapshot.py`, `loan_snapshot_contract.py`
+- Loan history normalization: `loan_history.py`, `loan_history_contract.py`
+- Transition estimation: `transition/estimator.py`
+- FICO / portfolio diagnostics: `portfolio.py`, `metrics.py`
+- Feature analytics: `early_performance.py`, `model_development.py`, `score_monitoring.py`
+- Predictive modeling: `predictive_targets.py`, `predictive_modeling.py`, `predictive_backtest.py`, `predictive_session.py`, `forecasting_bridge.py`; prefer `run_predictive_modeling_session()` for the end-to-end modeling path
+- Rollforward workflow: `rollforward_workflow.py`, `rollforward_readiness.py`, `rollforward_backtest.py`, `rollforward_contract.py`, `rollforward_evaluation.py`, plus internal `_rollforward_*` coordination and reporting modules
+- Survival: `survival.py`, `survival_flows.py`
+- Skills bundle: `skills/`
+- Packaged demos: `examples/`
+
+## Naming conventions
+
+- `*_contract.py`: workflow-specific reusable validation seam
+- `*_workflow.py`: top-level orchestration entrypoint
+- `*_session.py`: workflow-aligned coordination boundaries; some are public and return typed session result objects
+- `*_report*.py`: artifact rendering or summary outputs
+- underscore-prefixed modules: internal only
+
+## Editing guidance
+
+- Start at the public workflow seam before editing internal helpers.
+- If a change affects accepted inputs, inspect the relevant `*_contract.py` file before broadening logic elsewhere.
+- If a change affects docs, onboarding, or first-run discovery, edit both the command surface and the workflow routing docs in the same pass.

cranalytics/__init__.py

@@ -0,0 +1,151 @@
+"""
+cranalytics - Credit risk analytics library for vintage forecasting,
+FICO segmentation, and portfolio modeling.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+__version__ = "0.2.0"
+
+_PREFERRED_EXPORTS = {
+    "CurveFitter": "cranalytics.vintage",
+    "DynamicTransitionModel": "cranalytics.simulation",
+    "StaticMatrixTransitionModel": "cranalytics.simulation",
+    "calculate_classification_metrics": "cranalytics.metrics",
+    "calculate_fico_mix": "cranalytics.portfolio",
+    "calculate_gini": "cranalytics.metrics",
+    "calculate_ks": "cranalytics.metrics",
+    "calculate_lgd": "cranalytics.portfolio",
+    "calculate_wal": "cranalytics.metrics",
+    "create_vintage_triangle": "cranalytics.vintage",
+    "detect_incomplete_vintages": "cranalytics.vintage",
+    "estimate_recovery": "cranalytics.portfolio",
+    "forecast_lifetime_loss": "cranalytics.loss_forecasting",
+    "forecast_portfolio_states": "cranalytics.loss_forecasting",
+    "load_sample_transition_matrix": "cranalytics.datasets",
+    "make_mock_performance_data": "cranalytics.datasets",
+    "make_mock_portfolio": "cranalytics.datasets",
+    "normalize_vintage_data": "cranalytics.vintage",
+    "segment_fico": "cranalytics.portfolio",
+    "simulate_portfolio_cashflows": "cranalytics.simulation",
+    "smooth_curve": "cranalytics.vintage",
+    "summarize_lifetime_loss": "cranalytics.loss_forecasting",
+}
+
+_COMPAT_EXPORTS = {
+    "ReadinessConfig": "cranalytics.rollforward_readiness",
+    "Rollforward": "cranalytics.rollforward",
+    "RollforwardResult": "cranalytics.rollforward",
+    "aggregate_by_dollar_weights": "cranalytics.vintage",
+    "assemble_modeling_frame": "cranalytics.predictive_targets",
+    "build_targets": "cranalytics.predictive_targets",
+    "compute_woe_iv": "cranalytics.early_performance",
+    "engineer_loan_features": "cranalytics.model_development",
+    "fit_woe_binning": "cranalytics.model_development",
+    "forecast_calendar_chargeoff_from_predictions": "cranalytics.forecasting_bridge",
+    "generate_rollforward_readiness_report": "cranalytics.rollforward_readiness",
+    "get_best_method": "cranalytics.vintage",
+    "lift_gain_table": "cranalytics.model_development",
+    "make_mock_fpf_data": "cranalytics.datasets",
+    "make_performance_flag_schema": "cranalytics.validation",
+    "project_incomplete_vintage_tails": "cranalytics.vintage",
+    "rank_smoothing_methods": "cranalytics.vintage",
+    "run_predictive_backtest": "cranalytics.predictive_backtest",
+    "run_predictive_modeling_session": "cranalytics.predictive_session",
+    "run_rollforward": "cranalytics.rollforward",
+    "run_rollforward_workflow": "cranalytics.rollforward_workflow",
+    "run_validation_suite": "cranalytics.vintage",
+    "run_vintage_analysis_session": "cranalytics.vintage",
+    "score_model": "cranalytics.predictive_modeling",
+    "smooth_vintage": "cranalytics.vintage",
+    "summarize_predictive_backtest": "cranalytics.predictive_backtest",
+    "train_binary_model": "cranalytics.predictive_modeling",
+    "train_regression_model": "cranalytics.predictive_modeling",
+    "validate_rollforward_input_contract": "cranalytics.rollforward_contract",
+}
+
+# Tombstones for top-level aliases removed in 0.2.0. Accessing one raises an
+# AttributeError that names the module to import from instead.
+_DEPRECATED_TOP_LEVEL_EXPORT_GROUPS = {
+    "cranalytics.early_performance": (
+        "calculate_early_performance_rates",
+        "compute_conditional_loss_table",
+        "compute_marginal_impact",
+        "compute_segment_rates",
+        "estimate_vintage_lifetime_profit",
+        "rank_features_by_separation",
+        "validate_performance_flags",
+    ),
+    "cranalytics.fpf_workflow": (
+        "FPFWorkflowReport",
+        "print_fpf_report",
+        "run_fpf_workflow",
+        "train_fpf_challenger",
+    ),
+    "cranalytics.method_selection": (
+        "ModelSweepSpec",
+        "build_curve_fitter_sweep_spec",
+        "run_backtest_sweeps",
+        "select_champion_and_challengers",
+        "summarize_variant_performance",
+    ),
+    "cranalytics.rollforward_backtest": (
+        "run_rollforward_backtest_sweeps",
+        "select_rollforward_champion_and_challengers",
+        "summarize_rollforward_variant_performance",
+    ),
+    "cranalytics.score_monitoring": (
+        "calibrate_score_to_event_rate",
+        "compute_actual_vs_expected",
+        "compute_psi",
+        "score_performance_monitoring_report",
+        "simulate_policy_cutoff",
+    ),
+    "cranalytics.survival_flows": (
+        "compare_known_actuals_to_curves",
+        "fit_flow_hazard_curves",
+        "forecast_balance_flows",
+        "validate_flow_data",
+    ),
+    "cranalytics.vintage_wide": (
+        "compute_cgco_curve_wide",
+        "compute_final_cgco_wide",
+        "load_wide_vintage_data",
+    ),
+}
+
+_REMOVED_TOP_LEVEL_EXPORTS = {
+    name: module_name
+    for module_name, names in _DEPRECATED_TOP_LEVEL_EXPORT_GROUPS.items()
+    for name in names
+}
+
+# Keep the top-level namespace compatibility-friendly, but treat `_PREFERRED_EXPORTS`
+# as the small stable promise and `_COMPAT_EXPORTS` as a wider discovery surface.
+_EXPORTS = {**_PREFERRED_EXPORTS, **_COMPAT_EXPORTS}
+_PREFERRED_TOP_LEVEL_NAMES = tuple(sorted(_PREFERRED_EXPORTS))
+
+__all__ = tuple(sorted(_EXPORTS))
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _EXPORTS.get(name)
+    if module_name is None:
+        removed_module_name = _REMOVED_TOP_LEVEL_EXPORTS.get(name)
+        if removed_module_name is not None:
+            raise AttributeError(
+                f"Top-level import {name!r} was removed in cranalytics 0.2.0; "
+                f"use 'from {removed_module_name} import {name}' instead."
+            )
+        raise AttributeError(f"module 'cranalytics' has no attribute {name!r}")
+
+    value = getattr(import_module(module_name), name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted([*globals(), *__all__])

cranalytics/__main__.py

@@ -0,0 +1,6 @@
+"""Package entry point for ``python -m cranalytics``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cranalytics/_contract_helpers.py

@@ -0,0 +1,53 @@
+"""Domain-agnostic helpers shared by all workflow contract modules.
+
+These are private utilities — not part of the public API.
+"""
+
+from __future__ import annotations
+
+import re
+
+import pandas as pd  # noqa: TC002
+
+from ._contract_issues import _append_issue
+
+
+def _norm(col: str) -> str:
+    """Lowercase, strip, and collapse non-alphanumeric runs to underscores."""
+    return re.sub(r"[^a-z0-9]+", "_", str(col).strip().lower()).strip("_")
+
+
+def resolve_alias_columns(
+    work: pd.DataFrame,
+    aliases: dict[str, tuple[str, ...]],
+    issues: list[dict[str, str]],
+) -> pd.DataFrame:
+    """Rename DataFrame columns from any known alias to the canonical name.
+
+    For each canonical column name in *aliases*, finds matching columns in
+    *work* and renames the first match to the canonical name.  If more than
+    one alias is present a ``MULTIPLE_ALIASES`` warning is appended to
+    *issues*.  Returns the renamed DataFrame.
+    """
+    rename_map: dict[str, str] = {}
+    for canonical, alias_tuple in aliases.items():
+        matches = [col for col in work.columns if col in alias_tuple]
+        if len(matches) > 1:
+            _append_issue(
+                issues,
+                severity="warning",
+                issue_code="MULTIPLE_ALIASES",
+                message=(
+                    f"Multiple aliases found for '{canonical}' ({matches}); "
+                    f"using '{matches[0]}'."
+                ),
+            )
+        if matches:
+            rename_map[matches[0]] = canonical
+    return work.rename(columns=rename_map)
+
+
+__all__ = [
+    "_norm",
+    "resolve_alias_columns",
+]

cranalytics/_contract_issues.py

@@ -0,0 +1,112 @@
+"""Shared issue-table helpers for workflow contract modules."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+
+class IssueTableResultMixin:
+    """Mixin for contract results that expose an ``issue_table`` DataFrame."""
+
+    issue_table: pd.DataFrame
+
+    def has_severity(self, severity: str) -> bool:
+        return issue_table_has_severity(self.issue_table, severity)
+
+    def has_issue_code(self, issue_code: str) -> bool:
+        return issue_table_has_issue_code(self.issue_table, issue_code)
+
+    def failing_issue_table(
+        self,
+        *,
+        severities: Iterable[str],
+        ignored_issue_codes: Iterable[str] = (),
+    ) -> pd.DataFrame:
+        return select_issue_rows(
+            self.issue_table,
+            severities=severities,
+            ignored_issue_codes=ignored_issue_codes,
+        )
+
+
+def _issue_frame(issues: list[dict[str, str]]) -> pd.DataFrame:
+    frame = pd.DataFrame.from_records(issues)
+    return frame.reindex(columns=["severity", "issue_code", "message"])
+
+
+def issue_table_has_severity(issue_table: pd.DataFrame, severity: str) -> bool:
+    if issue_table.empty:
+        return False
+    return bool(issue_table["severity"].eq(str(severity)).any())
+
+
+def issue_table_has_issue_code(issue_table: pd.DataFrame, issue_code: str) -> bool:
+    if issue_table.empty:
+        return False
+    return bool(issue_table["issue_code"].eq(str(issue_code)).any())
+
+
+def select_issue_rows(
+    issue_table: pd.DataFrame,
+    *,
+    severities: Iterable[str],
+    ignored_issue_codes: Iterable[str] = (),
+) -> pd.DataFrame:
+    selected_severities = tuple(str(severity) for severity in severities)
+    if issue_table.empty or not selected_severities:
+        return issue_table.iloc[0:0].copy()
+
+    mask = issue_table["severity"].isin(selected_severities)
+    ignored_codes = tuple(str(code) for code in ignored_issue_codes)
+    if ignored_codes:
+        mask = mask & ~issue_table["issue_code"].isin(ignored_codes)
+    return issue_table.loc[mask].copy()
+
+
+def raise_on_issue_rows(
+    issue_table: pd.DataFrame,
+    *,
+    message_prefix: str,
+    severities: Iterable[str],
+    ignored_issue_codes: Iterable[str] = (),
+) -> None:
+    failing = select_issue_rows(
+        issue_table,
+        severities=severities,
+        ignored_issue_codes=ignored_issue_codes,
+    )
+    if failing.empty:
+        return
+    raise ValueError(f"{message_prefix} - " + "; ".join(failing["message"].tolist()))
+
+
+def _append_issue(
+    issues: list[dict[str, str]],
+    *,
+    severity: str,
+    issue_code: str,
+    message: str,
+) -> None:
+    issues.append(
+        {
+            "severity": severity,
+            "issue_code": issue_code,
+            "message": message,
+        }
+    )
+
+
+__all__ = [
+    "IssueTableResultMixin",
+    "_append_issue",
+    "_issue_frame",
+    "issue_table_has_issue_code",
+    "issue_table_has_severity",
+    "raise_on_issue_rows",
+    "select_issue_rows",
+]

cranalytics/_helpers.py

@@ -0,0 +1,140 @@
+"""Shared internal helpers for analytics modules.
+
+These are private utilities — not part of the public API.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING, cast
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def _check_maturity_coverage(
+    flag_series: pd.Series,
+    flag_col: str,
+    threshold: float = 0.10,
+) -> float:
+    """Compute mature fraction and warn if below threshold. Returns the fraction."""
+    n_total = len(flag_series)
+    if n_total == 0:
+        return 0.0
+    n_mature = int(flag_series.notna().sum())
+    fraction = n_mature / n_total
+    if fraction < threshold:
+        warnings.warn(
+            f"'{flag_col}' has only {fraction:.1%} mature observations "
+            f"({n_mature}/{n_total}). Results may be unreliable.",
+            UserWarning,
+            stacklevel=3,
+        )
+    return fraction
+
+
+def _require_columns(df: pd.DataFrame, columns: list[str]) -> None:
+    missing = [col for col in columns if col not in df.columns]
+    if missing:
+        raise ValueError(f"Missing required columns: {sorted(missing)}")
+
+
+def _validate_confidence(confidence: float) -> None:
+    if not 0 < confidence < 1:
+        raise ValueError("confidence must be between 0 and 1.")
+
+
+def _coerce_weights(
+    weight_series: pd.Series,
+    weight_col: str,
+) -> NDArray[np.float64]:
+    numeric_weights = cast("pd.Series", pd.to_numeric(weight_series, errors="coerce"))
+    weights = np.asarray(numeric_weights.to_numpy(dtype=np.float64), dtype=np.float64)
+    if np.isnan(weights).any():
+        raise ValueError(f"{weight_col} contains non-numeric values.")
+    if (weights < 0).any():
+        raise ValueError(f"{weight_col} must be non-negative.")
+    if weights.sum() <= 0:
+        raise ValueError(f"{weight_col} must have a positive total weight.")
+    return weights
+
+
+def _effective_sample_size(weights: NDArray[np.float64]) -> float:
+    sum_w = float(np.sum(weights))
+    sum_w2 = float(np.sum(np.square(weights)))
+    if sum_w <= 0 or sum_w2 <= 0:
+        return 0.0
+    return (sum_w**2) / sum_w2
+
+
+def _bin_series(series: pd.Series, n_bins: int) -> pd.Series:
+    """Quantile-bin a numeric series; returns object Series with pd.NA for nulls."""
+    if n_bins < 2:
+        raise ValueError("n_bins must be >= 2.")
+
+    out = pd.Series(pd.NA, index=series.index, dtype="object")
+    non_null = cast("pd.Series", series.dropna())
+    if non_null.empty:
+        return out
+
+    try:
+        binned = cast(
+            "pd.Series",
+            pd.Series(
+                pd.qcut(non_null, q=n_bins, duplicates="drop"), index=non_null.index
+            ),
+        )
+    except ValueError as exc:
+        raise ValueError(
+            f"Unable to create quantile bins for '{series.name}'. "
+            "Check cardinality and null coverage."
+        ) from exc
+
+    out.loc[non_null.index] = cast("pd.Series", binned.astype("object")).to_numpy()
+    return out
+
+
+def _months_elapsed(start_dates: pd.Series, as_of_date: pd.Timestamp) -> pd.Series:
+    """Whole-month elapsed time from start_date to as_of_date (floored at 0).
+
+    Applies a day-of-month correction: if the as_of_date day has not yet
+    reached the start-date day within the current month, the month is not
+    counted as complete.
+    """
+    elapsed = (as_of_date.year - start_dates.dt.year) * 12 + (
+        as_of_date.month - start_dates.dt.month
+    )
+    before_month_day = as_of_date.day < start_dates.dt.day
+    elapsed = elapsed - before_month_day.astype(int)
+    return elapsed.clip(lower=0).astype(int)
+
+
+def _series(value: object) -> pd.Series:
+    """Type-narrowing cast: raise TypeError if value is not a pandas Series."""
+    if not isinstance(value, pd.Series):
+        raise TypeError("Expected a pandas Series.")
+    return value
+
+
+def _frame(value: object) -> pd.DataFrame:
+    """Type-narrowing cast: raise TypeError if value is not a pandas DataFrame."""
+    if not isinstance(value, pd.DataFrame):
+        raise TypeError("Expected a pandas DataFrame.")
+    return value
+
+
+def _months_between(start_dates: pd.Series, end_dates: pd.Series) -> pd.Series:
+    """Whole-month elapsed time between two parallel date Series (floored at 0).
+
+    Element-wise variant of ``_months_elapsed`` for when both start and end
+    dates vary per row. Applies the same day-of-month correction.
+    """
+    elapsed = (end_dates.dt.year - start_dates.dt.year) * 12 + (
+        end_dates.dt.month - start_dates.dt.month
+    )
+    before_month_day = end_dates.dt.day < start_dates.dt.day
+    elapsed = elapsed - before_month_day.astype(int)
+    return elapsed.clip(lower=0).astype(int)