generic_features
================

.. py:module:: generic_features


Classes
-------

.. autoapisummary::

   generic_features.FeatureType
   generic_features.FillStrategy
   generic_features.OperationType
   generic_features.Feature
   generic_features.Candle
   generic_features.MovingWindow
   generic_features.ATR
   generic_features.RSI
   generic_features.MACD
   generic_features.BollingerBands
   generic_features.MSTD
   generic_features.OBV
   generic_features.Stochastic
   generic_features.Turbulence


Module Contents
---------------

.. py:class:: FeatureType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Enum for feature types.


   .. py:attribute:: CANDLE
      :value: 'candle'



   .. py:attribute:: MOVING_WINDOW
      :value: 'moving_window'



   .. py:attribute:: RSI
      :value: 'rsi'



   .. py:attribute:: MACD
      :value: 'macd'



   .. py:attribute:: BOLLINGER_BANDS
      :value: 'bollinger_bands'



   .. py:attribute:: STOCHASTIC
      :value: 'stochastic'



   .. py:attribute:: PIOTROSKI
      :value: 'piotroski'



   .. py:attribute:: TURBULENCE
      :value: 'turbulence'



   .. py:attribute:: ATR
      :value: 'atr'



   .. py:attribute:: MSTD
      :value: 'mstd'



   .. py:attribute:: OBV
      :value: 'obv'



.. py:class:: FillStrategy

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Enum for fill strategies used in Feature cleaning.


   .. py:attribute:: INTERPOLATE
      :value: 'interpolate'



   .. py:attribute:: ZERO
      :value: 'zero'



   .. py:attribute:: DROP
      :value: 'drop'



   .. py:attribute:: BACKWARD_FILL
      :value: 'bfill'



.. py:class:: OperationType

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Enum for rolling operations.


   .. py:attribute:: MEAN
      :value: 'mean'



   .. py:attribute:: STD
      :value: 'std'



   .. py:method:: __call__(df, column, window)

      Apply the rolling operation to a DataFrame column.

      :param df: Input DataFrame.
      :type df: pd.DataFrame
      :param column: Name of the column to operate on.
      :type column: str
      :param window: Rolling window size.
      :type window: int

      :returns: Result of the rolling operation.
      :rtype: pd.Series



.. py:class:: Feature(**data)

   Bases: :py:obj:`pydantic.BaseModel`


   Represents a single feature with its name and value.
   This is an abstract base class for all features.
   Subclasses should implement the `to_df` method to convert feature data into a DataFrame.
   It also provides methods for cleaning columns, getting feature names, and a factory method
   to create instances based on a dictionary input.
   The `Feature` class is not meant to be instantiated directly; instead, it serves as a base class
   for specific feature implementations like `Candle`, `MovingWindow`, `RSI`, etc.
   Subclasses must define the `TYPE` class variable to specify their feature type.
   Subclasses can also define additional fields specific to their feature type.


   .. py:attribute:: type
      :type:  FeatureType


   .. py:attribute:: name
      :type:  str
      :value: None



   .. py:attribute:: enabled
      :type:  bool
      :value: None



   .. py:attribute:: source
      :type:  str | None
      :value: None



   .. py:attribute:: fill_strategy
      :type:  FillStrategy
      :value: None



   .. py:attribute:: _registry
      :type:  ClassVar[Dict[FeatureType, Type[Feature]]]


   .. py:method:: shape(data)

      Shape the data to ensure all symbols have the same timestamps.
      Missing timestamps for symbols are filled with NaNs.

      :param data: Input DataFrame with MultiIndex (timestamp, symbol).
      :type data: pd.DataFrame

      :returns: Shaped DataFrame where all symbols have identical timestamps.
      :rtype: pd.DataFrame



   .. py:method:: clean_columns(cols, df)

      Clean the DataFrame by filling NaN values in specified columns with given strategy.
      Filling is applied per symbol to avoid cross-contamination between symbols.
      :param cols: List of column names to clean.
      :type cols: List[str]
      :param df: DataFrame to clean.
      :type df: pd.DataFrame

      :returns: Cleaned DataFrame with NaN values handled according to the fill strategy.
      :rtype: pd.DataFrame



   .. py:method:: get_feature_names()

      Get the names of the features provided by this instance.
      :returns: List of feature names.
      :rtype: List[str]



   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



   .. py:method:: __init_subclass__(**kwargs)
      :classmethod:


      Register subclasses of Feature in the _registry dictionary.



   .. py:method:: factory(data, fill_strategy)
      :classmethod:


      Factory method to create a Feature instance from a dictionary.
      :param data: Dictionary containing feature data, must include 'type'.
      :type data: dict

      :returns: An instance of a subclass of Feature based on the 'type' field.
      :rtype: Feature

      :raises ValueError: If 'type' is missing or if the type is unknown.



   .. py:method:: _zscore(s)
      :staticmethod:



   .. py:method:: _robust_zscore(s)
      :staticmethod:



   .. py:method:: _minmax(s)
      :staticmethod:



   .. py:method:: _sigmoid_pct_change(s)
      :staticmethod:



.. py:class:: Candle(**data)

   Bases: :py:obj:`Feature`


   Represents a candle feature with OHLCV data.


   .. py:method:: get_feature_names()

      Get the names of the features provided by this instance.
      :returns: List of feature names.
      :rtype: List[str]



   .. py:method:: get_raw_feature_names()


   .. py:method:: normalize(df)


   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


.. py:class:: MovingWindow(**data)

   Bases: :py:obj:`Feature`


   Represents a moving average feature by Days.
   Note: This feature is readily available in vectorbt, but this implementation
   allows for custom operations and fields.


   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: period
      :type:  int
      :value: None



   .. py:attribute:: field
      :type:  str
      :value: None



   .. py:attribute:: operation
      :type:  OperationType
      :value: None



.. py:class:: ATR(**data)

   Bases: :py:obj:`Feature`


   Average True Range (ATR) feature.


   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: period
      :type:  int
      :value: None



   .. py:attribute:: field_high
      :type:  str
      :value: None



   .. py:attribute:: field_low
      :type:  str
      :value: None



   .. py:attribute:: field_close
      :type:  str
      :value: None



   .. py:method:: get_feature_names()

      Get the names of the features provided by this instance.
      :returns: List of feature names.
      :rtype: List[str]



   .. py:method:: get_raw_feature_names()


   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



.. py:class:: RSI(**data)

   Bases: :py:obj:`Feature`


   Relative Strength Index (RSI) feature.


   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: period
      :type:  int
      :value: None



   .. py:attribute:: field
      :type:  str
      :value: None



   .. py:attribute:: ewm
      :type:  bool
      :value: None



   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



.. py:class:: MACD(**data)

   Bases: :py:obj:`Feature`


   Moving Average Convergence Divergence (MACD) feature.


   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: fast_period
      :type:  int
      :value: None



   .. py:attribute:: slow_period
      :type:  int
      :value: None



   .. py:attribute:: signal_period
      :type:  int
      :value: None



   .. py:attribute:: field
      :type:  str
      :value: None



   .. py:attribute:: ewm
      :type:  bool
      :value: None



   .. py:attribute:: signal_ewm
      :type:  bool
      :value: None



   .. py:method:: get_feature_names()

      Get the names of the features provided by this instance.
      :returns: List of feature names.
      :rtype: List[str]



   .. py:method:: get_raw_feature_names()


   .. py:method:: normalize(df)


   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



.. py:class:: BollingerBands(**data)

   Bases: :py:obj:`Feature`


   Bollinger Bands feature.


   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: period
      :type:  int
      :value: None



   .. py:attribute:: field
      :type:  str
      :value: None



   .. py:attribute:: ewm
      :type:  bool
      :value: None



   .. py:attribute:: alpha
      :type:  float
      :value: None



   .. py:method:: get_feature_names()

      Get the names of the features provided by this instance.
      :returns: List of feature names.
      :rtype: List[str]



   .. py:method:: get_raw_feature_names()


   .. py:method:: normalize(df)


   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



.. py:class:: MSTD(**data)

   Bases: :py:obj:`Feature`


   Moving Standard Deviation feature.


   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: field
      :type:  str
      :value: None



   .. py:attribute:: window
      :type:  int
      :value: None



   .. py:attribute:: ewm
      :type:  bool
      :value: None



   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



.. py:class:: OBV(**data)

   Bases: :py:obj:`Feature`


   On-Balance Volume (OBV) feature.


   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: field_close
      :type:  str
      :value: None



   .. py:attribute:: field_volume
      :type:  str
      :value: None



   .. py:method:: get_feature_names()

      Get the names of the features provided by this instance.
      :returns: List of feature names.
      :rtype: List[str]



   .. py:method:: get_raw_feature_names()


   .. py:method:: normalize(df)


   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



.. py:class:: Stochastic(**data)

   Bases: :py:obj:`Feature`


   Stochastic Oscillator feature.


   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: period
      :type:  int
      :value: None



   .. py:attribute:: field_high
      :type:  str
      :value: None



   .. py:attribute:: field_low
      :type:  str
      :value: None



   .. py:attribute:: field_close
      :type:  str
      :value: None



   .. py:attribute:: k_window
      :type:  int
      :value: None



   .. py:attribute:: d_window
      :type:  int
      :value: None



   .. py:attribute:: ewm
      :type:  bool
      :value: None



   .. py:method:: get_feature_names()

      Get the names of the features provided by this instance.
      :returns: List of feature names.
      :rtype: List[str]



   .. py:method:: to_df(df, data)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.



.. py:class:: Turbulence(**data)

   Bases: :py:obj:`Feature`


   Computes a market turbulence index using multiple return periods and proper covariance calculation.
   This measures how unusual current market conditions are compared to historical patterns.
   ! TODO pretty sure turbulence is broken


   .. py:attribute:: TYPE
      :type:  ClassVar[FeatureType]


   .. py:attribute:: lookback
      :type:  int
      :value: None



   .. py:attribute:: field
      :type:  str
      :value: None



   .. py:attribute:: return_periods
      :type:  List[int]
      :value: None



   .. py:method:: to_df(df, data = None)

      Convert the feature data to a DataFrame.
      :param df: DataFrame to which the feature will be added.
      :type df: pd.DataFrame
      :param data: Data to convert into a DataFrame.
      :type data: Any

      :returns: DataFrame with the feature data added.
      :rtype: pd.DataFrame

      :raises NotImplementedError: If the method is not implemented in the subclass.