merton.core.firm

The Firm input container.

A Firm carries everything a single-firm Merton calibration needs: equity value, debt structure, risk-free rate, horizon, and the choice of default-point formula. It is intentionally a tiny frozen dataclass — pydantic is reserved for the merton._config settings layer, not for hot-path objects.

Classes

Firm	A single-firm Merton model input.

Module Contents

class merton.core.firm.Firm

A single-firm Merton model input.

Parameters:

• equity – Market value of equity (scalar or 1-D time series).

• debt_short – Short-term (≤ 1y) debt balance.

• debt_long – Long-term (> 1y) debt balance.

• equity_vol – Annualised equity volatility σ_E (decimal). Optional — many calibrators estimate it from the equity time series.

• rf – Risk-free rate r. Defaults to 4 %.

• dividend_yield – Continuous dividend yield q. Defaults to 0.

• horizon – Time-to-debt-maturity T in years. Default 1.0 (1-year DD/PD).

• default_point – One of "kmv" (default), "total", "short_only", or "custom".

• custom_default_point – Required when default_point == "custom".

• ticker – Optional metadata for traceability in reports / panels.

• asof – Optional metadata for traceability in reports / panels.

Examples

>>> firm = Firm(equity=100, debt_short=20, debt_long=30, equity_vol=0.30)
>>> firm.default_point_value()
35.0
>>> firm.total_debt
50.0

equity: merton._typing.ArrayLike

debt_short: merton._typing.ArrayLike

debt_long: merton._typing.ArrayLike

equity_vol: merton._typing.ArrayLike | None = None

rf: merton._typing.ArrayLike = 0.04

dividend_yield: merton._typing.ArrayLike = 0.0

horizon: float = 1.0

default_point: merton.core.default_point.DefaultPointLike

custom_default_point: collections.abc.Callable[[merton._typing.ArrayLike, merton._typing.ArrayLike], merton._typing.FloatArray] | None = None

ticker: str | None = None

asof: Any | None = None

property total_debt: float

Sum of short- and long-term debt as a scalar (or array if vectorized).

default_point_value() → merton._typing.FloatArray

Resolve the default threshold L per the chosen formula.

classmethod from_dict(mapping: dict[str, Any]) → Firm

Build a Firm from a plain dict (e.g. a JSON record).

classmethod from_panel(df: pandas.DataFrame, *, mapping: dict[str, str] | None = None) → Firm

Build a vectorized Firm from a pandas DataFrame.

The DataFrame is expected to have one row per (firm, date) or per date, with columns matching the dataclass field names. Use mapping to rename source columns to canonical names, e.g. {"mkt_cap": "equity", "st_debt": "debt_short"}.

classmethod from_yfinance(ticker: str, *, lookback: str = '2y', rf: float = 0.04, debt_point: merton.core.default_point.DefaultPointLike = DefaultPoint.KMV) → Firm

Quick-start helper: pull equity and balance-sheet data via yfinance.

Requires the [data] extra (pip install "merton[data]").

replace(**kwargs: Any) → Firm

Return a copy with some fields replaced. (Dataclasses are frozen.)