Cycles/docs/analysis.md

# Analysis Module

This document provides an overview of the `Analysis` module and its components, which are typically used for technical analysis of financial market data.

## Modules

The `Analysis` module includes classes for calculating common technical indicators:

-   **Relative Strength Index (RSI)**: Implemented in `cycles/Analysis/rsi.py`.
-   **Bollinger Bands**: Implemented in `cycles/Analysis/boillinger_band.py`.
-   Note: Trading strategies are detailed in `strategies.md`.

## Class: `RSI`

Found in `cycles/Analysis/rsi.py`.

Calculates the Relative Strength Index.
### Mathematical Model  
The standard RSI calculation typically involves Wilder's smoothing for average gains and losses.
1. **Price Change (Delta)**: Difference between consecutive closing prices.
2. **Gain and Loss**: Separate positive (gain) and negative (loss, expressed as positive) price changes.
3. **Average Gain (AvgU)** and **Average Loss (AvgD)**: Smoothed averages of gains and losses over the RSI period. Wilder's smoothing is a specific type of exponential moving average (EMA):
   - Initial AvgU/AvgD: Simple Moving Average (SMA) over the first `period` values.
   - Subsequent AvgU: `(Previous AvgU * (period - 1) + Current Gain) / period`
   - Subsequent AvgD: `(Previous AvgD * (period - 1) + Current Loss) / period`
4. **Relative Strength (RS)**:
   $$
   RS = \\frac{\\text{AvgU}}{\\text{AvgD}}
   $$  
5. **RSI**:  
   $$
   RSI = 100 - \\frac{100}{1 + RS}
   $$
   Special conditions:
   - If AvgD is 0: RSI is 100 if AvgU > 0, or 50 if AvgU is also 0 (neutral).

### `__init__(self, config: dict)`

-   **Description**: Initializes the RSI calculator.
-   **Parameters**:\n    -   `config` (dict): Configuration dictionary. Must contain an `'rsi_period'` key with a positive integer value (e.g., `{'rsi_period': 14}`).

### `calculate(self, data_df: pd.DataFrame, price_column: str = 'close') -> pd.DataFrame`

-   **Description**: Calculates the RSI (using Wilder's smoothing by default) and adds it as an 'RSI' column to the input DataFrame. This method utilizes `calculate_custom_rsi` internally with `smoothing='EMA'`.
-   **Parameters**:\n    -   `data_df` (pd.DataFrame): DataFrame with historical price data. Must contain the `price_column`.\n    -   `price_column` (str, optional): The name of the column containing price data. Defaults to 'close'.
-   **Returns**: `pd.DataFrame` - A copy of the input DataFrame with an added 'RSI' column. If data length is insufficient for the period, the 'RSI' column will contain `np.nan`.

### `calculate_custom_rsi(price_series: pd.Series, window: int = 14, smoothing: str = 'SMA') -> pd.Series` (Static Method)

-   **Description**: Calculates RSI with a specified window and smoothing method (SMA or EMA). This is the core calculation engine.
-   **Parameters**:
    -   `price_series` (pd.Series): Series of prices.
    -   `window` (int, optional): The period for RSI calculation. Defaults to 14. Must be a positive integer.
    -   `smoothing` (str, optional): Smoothing method, can be 'SMA' (Simple Moving Average) or 'EMA' (Exponential Moving Average, specifically Wilder's smoothing when `alpha = 1/window`). Defaults to 'SMA'.
-   **Returns**: `pd.Series` - Series containing the RSI values. Returns a series of NaNs if data length is insufficient.

## Class: `BollingerBands`

Found in `cycles/Analysis/boillinger_band.py`.

Calculates Bollinger Bands.
### Mathematical Model  
1. **Middle Band**: Simple Moving Average (SMA) over `period`.
   $$
   \\text{Middle Band} = \\text{SMA}(\\text{price}, \\text{period})
   $$  
2. **Standard Deviation (σ)**: Standard deviation of price over `period`.
3. **Upper Band**: Middle Band + `num_std` × σ
   $$
   \\text{Upper Band} = \\text{Middle Band} + \\text{num_std} \\times \\sigma_{\\text{period}}
   $$  
4. **Lower Band**: Middle Band − `num_std` × σ
   $$
   \\text{Lower Band} = \\text{Middle Band} - \\text{num_std} \\times \\sigma_{\\text{period}}
   $$  
For the adaptive calculation in the `calculate` method (when `squeeze=False`):
-   **BBWidth**: `(Reference Upper Band - Reference Lower Band) / SMA`, where reference bands are typically calculated using a 2.0 standard deviation multiplier.
-   **MarketRegime**: Determined by comparing `BBWidth` to a threshold from the configuration. `1` for sideways, `0` for trending.
-   The `num_std` used for the final Upper and Lower Bands then varies based on this `MarketRegime` and the `bb_std_dev_multiplier` values for "trending" and "sideways" markets from the configuration, applied row-wise.

### `__init__(self, config: dict)`

-   **Description**: Initializes the BollingerBands calculator.
-   **Parameters**:\n    -   `config` (dict): Configuration dictionary. It must contain:
        -   `'bb_period'` (int): Positive integer for the moving average and standard deviation period.
        -   `'trending'` (dict): Containing `'bb_std_dev_multiplier'` (float, positive) for trending markets.
        -   `'sideways'` (dict): Containing `'bb_std_dev_multiplier'` (float, positive) for sideways markets.
        -   `'bb_width'` (float): Positive float threshold for determining market regime.

### `calculate(self, data_df: pd.DataFrame, price_column: str = 'close', squeeze: bool = False) -> pd.DataFrame`

-   **Description**: Calculates Bollinger Bands and adds relevant columns to the DataFrame.
    -   If `squeeze` is `False` (default): Calculates adaptive Bollinger Bands. It determines the market regime (trending/sideways) based on `BBWidth` and applies different standard deviation multipliers (from the `config`) on a row-by-row basis. Adds 'SMA', 'UpperBand', 'LowerBand', 'BBWidth', and 'MarketRegime' columns.
    -   If `squeeze` is `True`: Calculates simpler Bollinger Bands with a fixed window of 14 and a standard deviation multiplier of 1.5 by calling `calculate_custom_bands`. Adds 'SMA', 'UpperBand', 'LowerBand' columns; 'BBWidth' and 'MarketRegime' will be `NaN`.
-   **Parameters**:\n    -   `data_df` (pd.DataFrame): DataFrame with price data. Must include the `price_column`.\n    -   `price_column` (str, optional): The name of the column containing the price data. Defaults to 'close'.\n    -   `squeeze` (bool, optional): If `True`, calculates bands with fixed parameters (window 14, std 1.5). Defaults to `False`.
-   **Returns**: `pd.DataFrame` - A copy of the original DataFrame with added Bollinger Band related columns.

### `calculate_custom_bands(price_series: pd.Series, window: int = 20, num_std: float = 2.0, min_periods: int = None) -> tuple[pd.Series, pd.Series, pd.Series]` (Static Method)

-   **Description**: Calculates Bollinger Bands with a specified window, standard deviation multiplier, and minimum periods.
-   **Parameters**:
    -   `price_series` (pd.Series): Series of prices.
    -   `window` (int, optional): The period for the moving average and standard deviation. Defaults to 20.
    -   `num_std` (float, optional): The number of standard deviations for the upper and lower bands. Defaults to 2.0.
    -   `min_periods` (int, optional): Minimum number of observations in window required to have a value. Defaults to `window` if `None`.
-   **Returns**: `tuple[pd.Series, pd.Series, pd.Series]` - A tuple containing the Upper band, SMA, and Lower band series.