.. _data_formats:

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.

.. code-block:: text

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

.. list-table::
   :header-rows: 1
   :widths: 20 30 50

   * - 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``):

.. code-block:: text

   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):

.. code-block:: text

   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.

.. code-block:: text

   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).