Data Formats#

Market data (Input/Data/)#

One file per ticker (e.g. AAPL.csv, MSFT.parquet). Each file needs a date column and a price column; their names are configurable (user_column_date, user_column_price). Returns are computed internally from the price series. Extra columns are ignored.

m_date,m_close_split_adjusted
2020-01-02,73.87
2020-01-03,73.07
2020-01-06,73.75

Format

File naming

Notes

CSV

{TICKER}.csv

Headers required, dates as YYYY-MM-DD

Parquet

{TICKER}.parquet

Efficient for large datasets

Portfolio & benchmark weights (Input/Portfolios/, Input/Benchmark_Portfolios/)#

Weight files define allocations at each rebalancing date. The loader auto-detects orientation.

Horizontal (first column must be Ticker):

Ticker | 2020-01-02 | 2022-01-03 | 2024-01-02
AAPL   | 0.40       | 0.35       | 0.30
MSFT   | 0.35       | 0.35       | 0.40
GOOGL  | 0.25       | 0.30       | 0.30

Vertical (first column must be a date header):

date       | AAPL | MSFT | GOOGL
2020-01-02 | 0.40 | 0.35 | 0.25

Rules: weights are decimals, no null values, supported formats .csv / .xlsx.

Benchmark returns (Input/Benchmark_Portfolios/)#

The daily benchmark returns file uses the same weight-file format (a Ticker row with one column per date), read through the portfolio loader. It is used for date-range alignment.

Factor returns (Input/Factor_Models/)#

One file per factor (e.g. f_momentum.csv). First column is the date, followed by one column per asset, holding that factor’s per-asset return. Only assets present in the portfolio are read.

date,AAPL,MSFT,GOOGL
2020-01-02,0.010,-0.004,0.006
2020-01-03,0.008,0.002,-0.003

Every factor column must correspond to a ticker present in the portfolio.

Pre-Execution Checklist#

Before running, verify:

  • Portfolio and benchmark weight files are in their directories with the correct format (no nulls).

  • A market data file exists in Input/Data/ for every ticker in the portfolio.

  • Factor files in Input/Factor_Models/ only reference tickers present in the portfolio.

  • All input date ranges overlap (otherwise the common-range alignment yields no data).

  • user_column_date / user_column_price match the actual headers in your market-data files.

  • Config/attribution_analysis_parameters.xlsx parameters_format_version matches the package (run kaxanuk.attribution_analysis update excel if it asks you to).