Returns#

Return time-series entities shared by both attribution methodologies.

class PortfolioReturns(portfolio_returns: pandas.DataFrame)[source]#

Bases: object

portfolio_returns: DataFrame#

Immutable entity for asset return time-series stored as PyArrow tables.

This module provides ReturnsTable, a frozen dataclass that wraps a pa.Table of periodic asset returns and validates its schema on construction. It is used for both investable-asset returns (computed from prices) and benchmark returns loaded from files.

class ReturnsTable(table: Table)[source]#

Bases: object

Immutable wrapper around a PyArrow table of asset returns.

The expected schema is:

[date: timestamp(ns), ASSET1: float64, ASSET2: float64, ...]

Return values may be negative and the first row may contain nulls (a natural consequence of percentage-change computation).

Validation is performed automatically on construction via __post_init__ and includes:

  • The table must contain at least one row.

  • A "date" column of type timestamp(ns) must be present.

  • Every non-date column must be float64.

Parameters:

table (pa.Table) – PyArrow table whose first column is a timestamp(ns) date column named "date" and whose remaining columns hold per-asset periodic returns as float64.

Raises:

  • DataValidationError – If the table is empty.

  • MissingColumnError – If the "date" column is absent.

  • EntityTypeError – If the "date" column is not a timestamp or any asset column is not float64.

Examples

>>> import pyarrow as pa
>>> tbl = pa.table({
...     "date": pa.array(["2024-01-02", "2024-01-03"]).cast(pa.timestamp("ns")),
...     "AAPL": pa.array([0.012, -0.005], type=pa.float64()),
...     "MSFT": pa.array([0.008,  0.003], type=pa.float64()),
... })
>>> rt = ReturnsTable(table=tbl)
>>> rt.asset_names
['AAPL', 'MSFT']
property asset_names: list[str]#

Return the list of asset column names (excludes "date").

Returns:

Ordered list of asset ticker names present in the table.

Return type:

list[str]

table: Table#