# 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`.

## 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'.