Source code for kaxanuk.attribution_analysis.market_data_pipeline.field_definitions

"""
Market data field definitions and constants.

This module provides standardized field name constants and enums to ensure
type safety and prevent magic strings throughout the codebase.
"""
from enum import StrEnum
from typing import Final




class CalculatedMetric(StrEnum):
    """
    Calculated metrics that are derived from base fields.

    These metrics are computed by the system and added to the dataset
    after the initial data load.
    """
    RETURNS = "c_returns"
    LOG_RETURNS = "c_log_returns"
    VOLATILITY = "c_volatility"





class DataPipelineKeys:
    """
    Keys used in data pipeline result dictionaries.

    Centralise string constants so callers never rely on magic strings
    when accessing :class:`DataPipelineResult` fields.

    Attributes
    ----------
    PORTFOLIO_ENTITY : str
        Key for the portfolio entity object.
    PORTFOLIO_DF : str
        Key for the portfolio DataFrame.
    START_DATE_BACKTEST : str
        Key for the backtest start date.
    MARKET_DATA_BUNDLE : str
        Key for the market data bundle.
    DATA_DICT : str
        Key for the data dictionary.
    BENCHMARK : str
        Key for the benchmark table.
    PORTFOLIO_DICT : str
        Key for the portfolio weights dictionary.
    EQUIVALENCE_DICT : str
        Key for the field equivalence mapping.
    """
    PORTFOLIO_ENTITY = "portfolio_entity"
    PORTFOLIO_DF = "portfolio_df"
    START_DATE_BACKTEST = "start_date_backtest"
    MARKET_DATA_BUNDLE = "market_data_bundle"
    DATA_DICT = "data_dict"
    BENCHMARK = "benchmark"
    PORTFOLIO_DICT = "portfolio_dict"
    EQUIVALENCE_DICT = "equivalence_dict"





class RegisterKeys:
    """
    Keys used in register dictionaries.

    Centralise string constants for accessing register-related results
    produced by the engine.

    Attributes
    ----------
    REGISTER_DF : str
        Key for the main register DataFrame.
    COMMISSION_DF : str
        Key for the commissions DataFrame.
    SHARES_DF : str
        Key for the shares DataFrame.
    DAILY_WEIGHTS : str
        Key for the daily weights table.
    ORDERS_DF : str
        Key for the orders DataFrame.
    FINAL_TOTAL_PORTFOLIO_VALUE : str
        Key for the final portfolio value.
    TOTAL_COMMISSIONS : str
        Key for total commissions paid.
    YEARS : str
        Key for the number of years in the backtest.
    PORTFOLIO_STATS : str
        Key for portfolio statistics.
    BENCHMARK_STATS : str
        Key for benchmark statistics.
    """
    REGISTER_DF = "Register_df"
    COMMISSION_DF = "Commission_df"
    SHARES_DF = "Shares_df"
    DAILY_WEIGHTS = "Daily_Weights"
    ORDERS_DF = "orders_df"
    FINAL_TOTAL_PORTFOLIO_VALUE = "final_total_portfolio_value"
    TOTAL_COMMISSIONS = "Total_commissions"
    YEARS = "years"
    PORTFOLIO_STATS = "portfolio_stats"
    BENCHMARK_STATS = "benchmark_stats"





class StandardField(StrEnum):
    """
    Standard field names used internally by the engine.

    These are the canonical field names that the system uses for all operations.
    All input data is mapped to these standard field names.

    Attributes
    ----------
    PRICE
        Price column used for asset valuation and return calculation.
    DATE
        Column containing the trading dates.
    """
    PRICE = "price_column"
    DATE = "date_column"



    @classmethod
    def get_numeric_fields(cls) -> list['StandardField']:
        """Return all numeric standard fields (exclude date)."""
        return [cls.PRICE]




    @classmethod
    def get_all_fields(cls) -> list['StandardField']:
        """Return all required standard fields including date."""
        return [cls.PRICE, cls.DATE]




    @classmethod
    def values(cls) -> list[str]:
        """Return all field enum values as plain strings."""
        return [field.value for field in cls]




REQUIRED_FIELDS: Final[set[str]] = {
    StandardField.PRICE.value,
    StandardField.DATE.value,
}

STANDARD_FIELDS_ORDER: Final[tuple[str, ...]] = (
    StandardField.PRICE.value,
    StandardField.DATE.value,
)

PORTFOLIO_TICKER_COLUMN: Final[str] = "Ticker"