merton.core.panel

Arrow-backed columnar container for many (firm, date) records.

FirmPanel wraps a pyarrow.Table and gives users an ergonomic interface for assembling panels from pandas/polars/CSV/Parquet/dict, slicing, iterating row-by-row as Firm objects, and exporting back to common formats. The Arrow representation is the source of truth so callers don’t pay unnecessary copies when round-tripping between dataframe libraries.

Examples

>>> import pandas as pd
>>> from merton import FirmPanel
>>> df = pd.DataFrame(
...     {
...         "firm_id": ["A", "B"],
...         "equity": [100.0, 200.0],
...         "debt_short": [20.0, 50.0],
...         "debt_long": [30.0, 70.0],
...         "equity_vol": [0.30, 0.25],
...     }
... )
>>> panel = FirmPanel.from_pandas(df)
>>> len(panel)
2
>>> firms = list(panel.firms())
>>> firms[0].equity, firms[0].total_debt
(100.0, 50.0)

Classes

FirmPanel

An Arrow-backed table of single-firm Merton inputs.

Module Contents

class merton.core.panel.FirmPanel(table: pyarrow.Table)

An Arrow-backed table of single-firm Merton inputs.

The class is intentionally thin: any heavy operation is implemented in terms of Arrow / pandas / polars compute kernels, and the public API mostly exposes classmethod constructors plus the iteration / conversion helpers practitioners need.

classmethod from_arrow(table: pyarrow.Table) → FirmPanel

Wrap an existing pyarrow.Table.

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

Build from a pandas DataFrame, optionally renaming columns.

classmethod from_polars(df: Any, *, mapping: dict[str, str] | None = None) → FirmPanel

Build from a polars DataFrame (requires polars installed).

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

Build from a column-oriented dict.

classmethod from_csv(path: str | pathlib.Path) → FirmPanel

Read a CSV file into a panel.

classmethod from_parquet(path: str | pathlib.Path) → FirmPanel

Read a Parquet file into a panel.

property table: pyarrow.Table

The underlying pyarrow.Table (read-only; do not mutate).

property columns: list[str]

property equity: numpy.ndarray

property debt_short: numpy.ndarray

property debt_long: numpy.ndarray

property equity_vol: numpy.ndarray | None

property rf: numpy.ndarray | None

head(n: int = 5) → FirmPanel

firms() → collections.abc.Iterator[merton.core.firm.Firm]

Yield Firm instances one row at a time.

to_pandas() → pandas.DataFrame

to_polars() → Any

to_arrow() → pyarrow.Table

to_csv(path: str | pathlib.Path) → None

to_parquet(path: str | pathlib.Path) → None