Portfolio Transformer#

Portfolio data transformation utilities.

This module provides functions for transforming portfolio data between different representations and formats.

Functions are organized by transformation type: - Format Detection: detect_portfolio_format - Table Operations: transpose_vertical_to_horizontal - Entity Conversion: entity_to_weights_dict

detect_portfolio_format(first_column_name: str, error_class: type[Exception]) → str#

Detect portfolio layout (horizontal vs vertical) based on the first column name.

Horizontal format starts with “Ticker”/”ticker”; vertical format starts with “Date”/”date”.

Parameters:

  • first_column_name (str) – Name of the first column in the portfolio file.

  • error_class (Type[Exception]) – Exception class to raise if format is invalid.

Returns:

“horizontal” or “vertical”.

Return type:

str

Raises:

error_class – If the first column is neither expected ticker nor date names.

entity_to_weights_dict(entity: PortfolioEntity) → dict[Timestamp, dict[str, Scalar]]#

Convert a PortfolioEntity into a time-indexed weights dictionary.

The result maps normalized timestamps (rebalancing dates) to “ticker -> weight” maps. Dates are parsed using supported formats and normalized to midnight.

Parameters:

entity (PortfolioEntity) – A validated portfolio entity containing asset weights organized by date columns.

Returns:

Mapping from rebalancing date to ticker weights.

Return type:

dict[pd.Timestamp, dict[str, pa.Scalar]]

Raises:

PortfolioEntityError – If date columns cannot be parsed using supported formats.

Notes

  • Only date columns with valid weights are kept.

  • Empty weight sets for specific dates are excluded.

transpose_vertical_to_horizontal(table: Table) → Table#

Transpose a vertical-format PyArrow table (dates as rows, tickers as columns) into a horizontal-format table (tickers as rows, dates as columns).

This transformation is commonly required when the portfolio is initially specified as:

  • One row per date.

  • One column per ticker.

But the internal engine requires:

  • One row per ticker.

  • One column per date.

Vertical format (input)#

Date | AAPL | MSFT | GOOG | … 2024-01-01 | 0.5 | 0.3 | 0.2 | … 2024-01-02 | 0.6 | 0.2 | 0.2 | … … (N dates)

Horizontal format (output)#

Ticker | 2024-01-01 | 2024-01-02 | … AAPL | 0.5 | 0.6 | … MSFT | 0.3 | 0.2 | … GOOG | 0.2 | 0.2 | …

param table:

A vertical-format table where: - The first column is date (string). - Subsequent columns are ticker symbols.

type table:

pa.Table

returns:

A horizontal-format table with: - Column 0 → “Ticker” - Columns 1..N → one column per date - One row per ticker.

rtype:

pa.Table

Notes

  • Date values remain as strings (not cast to timestamps).

  • Order of tickers and dates is preserved exactly as in the input.

  • This function does not normalize or validate portfolio weights.