abaquant.credit.fundamentals

Import path: abaquant.credit.fundamentals

Domain: Credit-risk analytics and fundamentals-derived credit proxies.

Purpose

Grouped financial-statement inputs and transparent credit-proxy metrics.

When to use it

Use this package for transition matrices, spread-based valuation, CDS/CDO building blocks, copula simulation, tail risk, and accounting-based credit diagnostics.

Public objects

  • class: ReportedValue — One reported financial value with statement provenance.

  • class: BalanceSheetInputs — Balance-sheet values for one reporting date in a consistent currency.

  • class: IncomeStatementInputs — Income-statement values for one reporting period in a consistent currency.

  • class: CashFlowInputs — Cash-flow values for one reporting period in a consistent currency.

  • class: PriorPeriodInputs — Comparable values from the immediately preceding reporting period.

  • class: MarketEquityObservation — Market-capitalization observation with its observation date.

  • class: CreditHistoricalSeries — Comparable historical earnings and leverage observations, oldest first.

  • class: CreditAnalysisInputs — Grouped, immutable inputs for fundamental credit-proxy calculations. * CreditAnalysisInputs.total_debt — Return current total debt from the balance-sheet input group. * CreditAnalysisInputs.total_equity — Return current total equity from the balance-sheet input group. * CreditAnalysisInputs.current_assets — Return current assets from the balance-sheet input group. * CreditAnalysisInputs.inventory — Return inventory from the balance-sheet input group. * CreditAnalysisInputs.current_liabilities — Return current liabilities from the balance-sheet input group. * CreditAnalysisInputs.cash_and_cash_equivalents — Return cash and cash equivalents from the balance-sheet input group. * CreditAnalysisInputs.total_assets — Return current total assets from the balance-sheet input group. * CreditAnalysisInputs.total_liabilities — Return current total liabilities from the balance-sheet input group. * CreditAnalysisInputs.retained_earnings — Return retained earnings from the balance-sheet input group. * CreditAnalysisInputs.long_term_debt — Return long-term debt from the balance-sheet input group. * CreditAnalysisInputs.shares_outstanding — Return current shares outstanding from the balance-sheet input group. * CreditAnalysisInputs.ebit — Return EBIT from the income-statement input group. * CreditAnalysisInputs.ebitda — Return EBITDA from the income-statement input group. * CreditAnalysisInputs.interest_expense — Return interest expense from the income-statement input group. * CreditAnalysisInputs.revenue — Return current revenue from the income-statement input group. * CreditAnalysisInputs.net_income — Return current net income from the income-statement input group. * CreditAnalysisInputs.gross_profit — Return current gross profit from the income-statement input group. * CreditAnalysisInputs.operating_cash_flow — Return operating cash flow from the cash-flow input group. * CreditAnalysisInputs.market_value_equity — Return observed market equity, or ‘’None’’ when it was not supplied. * CreditAnalysisInputs.earnings_history — Return the normalized historical earnings sequence. * CreditAnalysisInputs.leverage_history — Return the normalized historical leverage sequence. * CreditAnalysisInputs.previous_total_assets — Return prior-period total assets, or ‘’None’’ when unavailable. * CreditAnalysisInputs.previous_net_income — Return prior-period net income, or ‘’None’’ when unavailable. * CreditAnalysisInputs.previous_long_term_debt — Return prior-period long-term debt, or ‘’None’’ when unavailable. * CreditAnalysisInputs.previous_current_assets — Return prior-period current assets, or ‘’None’’ when unavailable. * CreditAnalysisInputs.previous_current_liabilities — Return prior-period current liabilities, or ‘’None’’ when unavailable. * CreditAnalysisInputs.previous_shares_outstanding — Return prior-period shares outstanding, or ‘’None’’ when unavailable. * CreditAnalysisInputs.previous_gross_profit — Return prior-period gross profit, or ‘’None’’ when unavailable. * CreditAnalysisInputs.previous_revenue — Return prior-period revenue, or ‘’None’’ when unavailable.

  • class: CreditScenarioAnalysis — Multiplier scenario grid for a fundamental credit-proxy assessment. * CreditScenarioAnalysis.as_dict — Return a serialization-friendly credit scenario mapping. * CreditScenarioAnalysis.report — Return an exportable report for this credit-proxy assessment. * CreditScenarioAnalysis.visualize — Return a figure for this credit multiplier scenario grid.

  • class: CreditProxyAssessment — Transparent result of fundamental credit-proxy calculations. * CreditProxyAssessment.scenario_analysis — Recalculate credit-proxy metrics over statement-input multipliers. * CreditProxyAssessment.as_dict — Return a flat, serialization-friendly mapping of assessment outputs. * CreditProxyAssessment.report — Return an exportable report for this credit-proxy assessment. * CreditProxyAssessment.visualize — Return a figure for this credit-proxy assessment.

  • function: calculate_credit_proxy_metrics — Calculate manual fundamental credit-proxy metrics.

Detailed reference

Grouped financial-statement inputs and transparent credit-proxy metrics.

class abaquant.credit.fundamentals.CreditAnalysisInputs(balance_sheet, income_statement, cash_flow_statement, prior_period=None, market_equity=None, historical_series=None, reporting_currency=None, reporting_period=None, provenance=None)

Bases: object

Grouped, immutable inputs for fundamental credit-proxy calculations.

The current, prior-period, market-equity, and historical values are kept in separate groups to make reporting-period provenance explicit.

Parameters:

  • balance_sheet (BalanceSheetInputs)

  • income_statement (IncomeStatementInputs)

  • cash_flow_statement (CashFlowInputs)

  • prior_period (PriorPeriodInputs | None)

  • market_equity (MarketEquityObservation | None)

  • historical_series (CreditHistoricalSeries | None)

  • reporting_currency (str | None)

  • reporting_period (str | None)

  • provenance (DataProvenance | None)

property total_debt

Return current total debt from the balance-sheet input group.

property total_equity

Return current total equity from the balance-sheet input group.

property current_assets

Return current assets from the balance-sheet input group.

property inventory

Return inventory from the balance-sheet input group.

property current_liabilities

Return current liabilities from the balance-sheet input group.

property cash_and_cash_equivalents

Return cash and cash equivalents from the balance-sheet input group.

property total_assets

Return current total assets from the balance-sheet input group.

property total_liabilities

Return current total liabilities from the balance-sheet input group.

property retained_earnings

Return retained earnings from the balance-sheet input group.

property long_term_debt

Return long-term debt from the balance-sheet input group.

property shares_outstanding

Return current shares outstanding from the balance-sheet input group.

property ebit

Return EBIT from the income-statement input group.

property ebitda

Return EBITDA from the income-statement input group.

property interest_expense

Return interest expense from the income-statement input group.

property revenue

Return current revenue from the income-statement input group.

property net_income

Return current net income from the income-statement input group.

property gross_profit

Return current gross profit from the income-statement input group.

property operating_cash_flow

Return operating cash flow from the cash-flow input group.

property market_value_equity

Return observed market equity, or None when it was not supplied.

property earnings_history

Return the normalized historical earnings sequence.

property leverage_history

Return the normalized historical leverage sequence.

property previous_total_assets

Return prior-period total assets, or None when unavailable.

property previous_net_income

Return prior-period net income, or None when unavailable.

property previous_long_term_debt

Return prior-period long-term debt, or None when unavailable.

property previous_current_assets

Return prior-period current assets, or None when unavailable.

property previous_current_liabilities

Return prior-period current liabilities, or None when unavailable.

property previous_shares_outstanding

Return prior-period shares outstanding, or None when unavailable.

property previous_gross_profit

Return prior-period gross profit, or None when unavailable.

property previous_revenue

Return prior-period revenue, or None when unavailable.

class abaquant.credit.fundamentals.CreditProxyAssessment(metrics, piotroski_signals, synthetic_credit_proxy_score, synthetic_credit_proxy_band, available_score_weight, disclosures, inputs=None, provenance=None)

Bases: object

Transparent result of fundamental credit-proxy calculations.

Parameters:

  • metrics (Mapping[str, float | int | str | None])

  • piotroski_signals (Mapping[str, int | None])

  • synthetic_credit_proxy_score (float | None)

  • synthetic_credit_proxy_band (str)

  • available_score_weight (float)

  • disclosures (tuple[str, ...])

  • inputs (CreditAnalysisInputs | None)

  • provenance (DataProvenance | None)

metrics

Ratio, score, trend, and diagnostic values. Missing inputs produce None for affected metrics rather than estimated substitute values.

Type:

Mapping[str, MetricValue]

piotroski_signals

Nine individually documented F-score binary signals. None indicates an unavailable signal because its required inputs were not supplied.

Type:

Mapping[str, int | None]

synthetic_credit_proxy_score

Completeness-normalized heuristic score on a 0–100 scale. It is not a credit rating or probability of default.

Type:

float | None

synthetic_credit_proxy_band

Plain-language proxy band derived from the score, or "unavailable".

Type:

str

available_score_weight

Maximum heuristic weight supported by the supplied inputs before score normalization. A low value indicates limited metric coverage.

Type:

float

disclosures

Mandatory limitations and model-use disclosures.

Type:

tuple[str, …]

scenario_analysis(*, debt_multiplier=(1.0,), ebitda_multiplier=(1.0,), ebit_multiplier=(1.0,), interest_expense_multiplier=(1.0,))

Recalculate credit-proxy metrics over statement-input multipliers.

Parameters:

  • debt_multiplier (Sequence[float], default=(1.0,)) – Multipliers applied to total debt and long-term debt.

  • ebitda_multiplier (Sequence[float], default=(1.0,)) – Multipliers applied to EBITDA.

  • ebit_multiplier (Sequence[float], default=(1.0,)) – Multipliers applied to EBIT.

  • interest_expense_multiplier (Sequence[float], default=(1.0,)) – Multipliers applied to interest expense.

Returns:

Long-form scenario grid containing selected recomputed metrics.

Return type:

CreditScenarioAnalysis

Raises:

ValueError – If this assessment was not built with retained input provenance.

as_dict()

Return a flat, serialization-friendly mapping of assessment outputs.

Returns:

Metric values plus the synthetic proxy score, band, coverage weight, and semicolon-separated disclosures.

Return type:

dict[str, MetricValue]

report()

Return an exportable report for this credit-proxy assessment.

Returns:

Report object with Markdown, HTML, and PDF export methods.

Return type:

ExportableReport

visualize(*, chart='metrics', backend=None, theme=None, save_path=None, filename=None)

Return a figure for this credit-proxy assessment.

Parameters:

  • chart ({"metrics", "score"}, default="metrics") – Numeric metric comparison or synthetic-score chart.

  • backend ({"matplotlib", "plotly"}, default="matplotlib") – Figure backend; the returned figure is not displayed automatically.

class abaquant.credit.fundamentals.CreditScenarioAnalysis(data, base_assessment, provenance=None)

Bases: object

Multiplier scenario grid for a fundamental credit-proxy assessment.

Parameters:

  • data (pandas.DataFrame) – Long-form scenario table containing the multipliers and selected credit metrics after each perturbed recalculation.

  • base_assessment (CreditProxyAssessment) – Assessment used as the base case for all multiplier shocks.

  • provenance (DataProvenance | None)

as_dict()

Return a serialization-friendly credit scenario mapping.

Return type:

dict[str, object]

report()

Return an exportable report for this credit-proxy assessment.

Returns:

Report object with Markdown, HTML, and PDF export methods.

Return type:

ExportableReport

visualize(*, metric='synthetic_credit_proxy_score', chart='heatmap', backend=None, theme=None, save_path=None, filename=None)

Return a figure for this credit multiplier scenario grid.

Parameters:

  • metric (str, default="synthetic_credit_proxy_score") – Numeric scenario metric to display.

  • chart ({"heatmap", "curves", "bar"}, default="heatmap") – Visual form for the scenario table.

  • backend ({"matplotlib", "plotly"}, optional) – Figure backend override.

  • theme (VisualizationTheme, optional) – Per-call style override.

  • save_path (str or pathlib.Path, optional) – Explicit export path.

  • filename (str, optional) – Filename relative to the active theme’s save directory.

abaquant.credit.fundamentals.calculate_credit_proxy_metrics(inputs)

Calculate manual fundamental credit-proxy metrics.

Parameters:

inputs (CreditAnalysisInputs) – Manual statement and market-value inputs measured consistently in one currency and reporting-period convention.

Returns:

Ratios, traditional Altman Z-score, Piotroski F-score and components, earnings volatility, leverage trend, and a clearly labeled synthetic proxy score.

Return type:

CreditProxyAssessment

Notes

Definitions include:

\[\mathrm{Debt\!\text{-}\!to\!\text{-}Equity} = D / E, \qquad \mathrm{Current\ Ratio} = CA / CL,\]
\[\mathrm{Interest\ Coverage} = EBIT / I, \qquad \mathrm{Net\ Debt}/EBITDA = (D - C) / EBITDA.\]

The traditional Altman formulation is

\[Z = 1.2X_1 + 1.4X_2 + 3.3X_3 + 0.6X_4 + 1.0X_5,\]

where the component definitions are reported in the returned metrics. The synthetic score normalizes only across components that can be computed from supplied inputs; it should therefore be compared only alongside available_score_weight and the disclosures.

References

Altman (1968); Piotroski (2000).