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.

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