.. _configuration:

Configuration Reference
=======================

The configuration file is ``Config/backtest_engine_parameters.xlsx``, created by running ``kaxanuk.backtest_engine init excel``. Open it in any spreadsheet editor and edit **column B** only. Column A contains the parameter names (do not modify) and column C contains descriptions.

Backtest Settings
-----------------

.. list-table::
   :widths: 35 25 40
   :header-rows: 1

   * - Parameter
     - Example value
     - Description
   * - ``portfolio_name``
     - ``my_portfolio``
     - Filename of your portfolio without extension. Must exist in the portfolio directory.
   * - ``benchmark_file_name``
     - ``SPY``
     - Ticker used as benchmark. A market data file for this ticker must exist in the data directory.
   * - ``start_date``
     - ``2020-01-02``
     - Backtest start date (``YYYY-MM-DD``). Use ``auto`` to derive from the first date in the portfolio file.
   * - ``end_date``
     - ``2024-12-31``
     - Backtest end date (``YYYY-MM-DD``). Use ``auto`` to derive from the last date in the portfolio file.
   * - ``initial_capital``
     - ``1000000``
     - Starting capital in currency units.
   * - ``cash_reserve_percentage``
     - ``0.01``
     - Fraction of portfolio value reserved as cash on each rebalance. Range: 0.0–0.50.
   * - ``commission_cents``
     - ``0.05``
     - Per-share commission in dollars. Range: 0.0–0.10. Example: ``0.01`` means $0.01 per share.

File Paths and Formats
----------------------

.. list-table::
   :widths: 40 25 35
   :header-rows: 1

   * - Parameter
     - Example value
     - Description
   * - ``input_market_data_directory``
     - ``Input/Data``
     - Absolute or relative path to the directory containing market data files.
   * - ``input_portfolio_directory``
     - ``Input/Portfolios``
     - Absolute or relative path to the directory containing portfolio files.
   * - ``backtest_results_output_directory``
     - ``Output``
     - Path where backtest results and reports are saved.
   * - ``market_data_input_format``
     - ``csv``
     - Format of market data files: ``csv`` or ``parquet``.
   * - ``portfolio_input_format``
     - ``csv``
     - Format of portfolio files: ``csv`` or ``excel``.

Column Name Mappings
--------------------

These values must exactly match the column headers in your market data files.

.. list-table::
   :widths: 40 25 35
   :header-rows: 1

   * - Parameter
     - Example value
     - Purpose
   * - ``commission_price_column``
     - ``vwap``
     - Column used to calculate the share count for commission fees (typically unadjusted VWAP).
   * - ``trade_execution_price_column``
     - ``vwap_adjusted``
     - Column used as the trade execution price for buying/selling shares.
   * - ``mark_to_market_price_column``
     - ``close_adjusted``
     - Column used for daily portfolio valuation between rebalancing dates.
   * - ``date_column``
     - ``date``
     - Column containing trading dates.

System Settings
---------------

.. list-table::
   :widths: 35 25 40
   :header-rows: 1

   * - Parameter
     - Example value
     - Description
   * - ``logger_level``
     - ``error``
     - Logging verbosity. Valid values: ``debug``, ``info``, ``warning``, ``error``, ``critical``.

Complete Example
----------------

After editing, your Excel file (column A | column B) should look like this:

.. code-block:: text

   portfolio_name                     | my_portfolio
   benchmark_file_name                | SPY
   start_date                         | 2020-01-02
   end_date                           | 2024-12-31
   initial_capital                    | 100000
   cash_reserve_percentage            | 0.05
   commission_cents                   | 0.01
   input_market_data_directory        | Input/Data
   input_portfolio_directory          | Input/Portfolios
   backtest_results_output_directory  | Output
   market_data_input_format           | csv
   portfolio_input_format             | csv
   commission_price_column            | vwap
   trade_execution_price_column       | vwap_adjusted
   mark_to_market_price_column        | close_adjusted
   date_column                        | date
   logger_level                       | info

Programmatic Configuration
---------------------------

When using ``BatchConfigParser.parse_dict()`` the dict keys follow the same parameter names, with column mappings prefixed by ``user_column_``:

.. code-block:: python

   {
       "global_defaults": {
           "start_date": "2020-01-02",
           "end_date": "2024-12-31",
           "commission_cents": 0.01,
           "cash_reserve_percentage": 0.05,
           "user_column_commission_price": "vwap",
           "user_column_trade_execution_price": "vwap_adjusted",
           "user_column_mark_to_market_price": "close_adjusted",
           "user_column_date": "date",
           ...
       }
   }

API Reference
-------------

The following classes back the configuration system. Their docstrings are the authoritative reference for all parameters and validation rules.

.. autoclass:: kaxanuk.backtest_engine.entities.configuration.Configuration
   :members:
   :undoc-members:
   :show-inheritance:
   :noindex:

.. autoclass:: kaxanuk.backtest_engine.config_handlers.excel_configurator.ExcelConfigurator
   :members:
   :show-inheritance:
   :noindex:

.. autoclass:: kaxanuk.backtest_engine.config_handlers.multi_backtest_parser.BatchConfigParser
   :members:
   :show-inheritance:
   :noindex: