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`.
-   **Trading Strategies**: Implemented in `cycles/Analysis/strategies.py`.

## Class: `RSI`

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

Calculates the Relative Strength Index.
### Mathematical Model  
1. **Average Gain (AvgU)** and **Average Loss (AvgD)** over 14 periods:  
   $$
   \text{AvgU} = \frac{\sum \text{Upward Price Changes}}{14}, \quad \text{AvgD} = \frac{\sum \text{Downward Price Changes}}{14}
   $$  
2. **Relative Strength (RS)**:  
   $$
   RS = \frac{\text{AvgU}}{\text{AvgD}}
   $$  
3. **RSI**:  
   $$
   RSI = 100 - \frac{100}{1 + RS}
   $$  

### `__init__(self, period: int = 14)`

-   **Description**: Initializes the RSI calculator.
-   **Parameters**:
    -   `period` (int, optional): The period for RSI calculation. Defaults to 14. Must be a positive integer.

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

-   **Description**: Calculates the RSI and adds it as an 'RSI' column to the input DataFrame. Handles cases where data length is less than the period by returning the original DataFrame with a warning.
-   **Parameters**:
    -   `data_df` (pd.DataFrame): DataFrame with historical price data. Must contain the `price_column`.
    -   `price_column` (str, optional): The name of the column containing price data. Defaults to 'close'.
-   **Returns**: `pd.DataFrame` - The input DataFrame with an added 'RSI' column (containing `np.nan` for initial periods where RSI cannot be calculated). Returns a copy of the original DataFrame if the period is larger than the number of data points.

## Class: `BollingerBands`

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

## **Bollinger Bands**  
### Mathematical Model  
1. **Middle Band**: 20-day Simple Moving Average (SMA)  
   $$
   \text{Middle Band} = \frac{1}{20} \sum_{i=1}^{20} \text{Close}_{t-i}
   $$  
2. **Upper Band**: Middle Band + 2 × 20-day Standard Deviation (σ)  
   $$
   \text{Upper Band} = \text{Middle Band} + 2 \times \sigma_{20}
   $$  
3. **Lower Band**: Middle Band − 2 × 20-day Standard Deviation (σ)  
   $$
   \text{Lower Band} = \text{Middle Band} - 2 \times \sigma_{20}
   $$  


### `__init__(self, period: int = 20, std_dev_multiplier: float = 2.0)`

-   **Description**: Initializes the BollingerBands calculator.
-   **Parameters**:
    -   `period` (int, optional): The period for the moving average and standard deviation. Defaults to 20. Must be a positive integer.
    -   `std_dev_multiplier` (float, optional): The number of standard deviations for the upper and lower bands. Defaults to 2.0. Must be positive.

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

-   **Description**: Calculates Bollinger Bands and adds 'SMA' (Simple Moving Average), 'UpperBand', and 'LowerBand' columns to the DataFrame.
-   **Parameters**:
    -   `data_df` (pd.DataFrame): DataFrame with price data. Must include the `price_column`.
    -   `price_column` (str, optional): The name of the column containing the price data (e.g., 'close'). Defaults to 'close'.
-   **Returns**: `pd.DataFrame` - The original DataFrame with added columns: 'SMA', 'UpperBand', 'LowerBand'.

## Class: `Strategy`

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

Implements various trading strategies using technical indicators.

### `__init__(self, config = None, logging = None)`

-   **Description**: Initializes the Strategy class with configuration and logging.
-   **Parameters**:
    -   `config` (dict): Configuration dictionary with strategy parameters. Must be provided.
    -   `logging` (logging object, optional): Logger for output messages. Defaults to None.

### `run(self, data, strategy_name)`

-   **Description**: Executes a specified strategy on the provided data.
-   **Parameters**:
    -   `data` (pd.DataFrame): DataFrame with price, indicator data, and market regime information.
    -   `strategy_name` (str): Name of the strategy to run. Currently supports "MarketRegimeStrategy".
-   **Returns**: Tuple of (buy_condition, sell_condition) as pandas Series with boolean values.

### `no_strategy(self, data)`

-   **Description**: Returns empty buy/sell conditions (all False).
-   **Parameters**:
    -   `data` (pd.DataFrame): Input data DataFrame.
-   **Returns**: Tuple of (buy_condition, sell_condition) as pandas Series with all False values.

### `rsi_bollinger_confirmation(self, rsi, window=14, std_mult=1.5)`

-   **Description**: Calculates Bollinger Bands on RSI values for signal confirmation.
-   **Parameters**:
    -   `rsi` (pd.Series): Series containing RSI values.
    -   `window` (int, optional): The period for the moving average. Defaults to 14.
    -   `std_mult` (float, optional): Standard deviation multiplier for bands. Defaults to 1.5.
-   **Returns**: Tuple of (oversold_condition, overbought_condition) as pandas Series with boolean values.

### `MarketRegimeStrategy(self, data)`

-   **Description**: Advanced strategy combining Bollinger Bands, RSI, volume analysis, and market regime detection.
-   **Parameters**:
    -   `data` (pd.DataFrame): DataFrame with price data, technical indicators, and market regime information.
-   **Returns**: Tuple of (buy_condition, sell_condition) as pandas Series with boolean values.

#### Strategy Logic

This strategy adapts to different market conditions:

**Trending Market (Breakout Mode):**
- Buy: Price < Lower Band ∧ RSI < 50 ∧ Volume Spike (≥1.5× 20D Avg)
- Sell: Price > Upper Band ∧ RSI > 50 ∧ Volume Spike

**Sideways Market (Mean Reversion):**
- Buy: Price ≤ Lower Band ∧ RSI ≤ 40
- Sell: Price ≥ Upper Band ∧ RSI ≥ 60

When `SqueezeStrategy` is enabled, additional confirmation using RSI Bollinger Bands is required:
- For buy signals: RSI must be below its lower Bollinger Band
- For sell signals: RSI must be above its upper Bollinger Band

For sideways markets, volume contraction (< 0.7× 30D Avg) is also checked to avoid false signals.