Merge pull request #40 from UBC-MDS/update-docs

add example for each function

src/traders_copilot_mzza_25/data.py

@@ -3,18 +3,25 @@
 from datetime import datetime
 
 def generate_synthetic_data(start_date, end_date, num_records=252, seed=40):
-    """
-    Generate synthetic stock data.
+    """Generate synthetic stock data.
 
-    Args:
+    Parameters
+    ----------
         start_date (str): Start date in YYYY-MM-DD format.
         end_date (str): End date in YYYY-MM-DD format.
         num_records (int): Number of records to generate 
                           (default is 252 trading days in a year in major stock markets).
         seed (int): Random seed for reproducibility.
 
-    Returns:
-        pandas.DataFrame
+    Returns
+    -------
+        pd.DataFrame: A DataFrame containing the generated stock data with 'Date', 'Open', 'High', 'Low', 
+                      'Close', 'Adj Close', and 'Volume' columns.
+
+    Examples
+    --------
+    >>> data = generate_synthetic_data("2021-01-01", "2021-12-31", num_records=252, seed=40)
+    >>> print(data.head())
     """
 
     try:

src/traders_copilot_mzza_25/generate_signals.py

@@ -1,14 +1,27 @@
 import pandas as pd
 
 def generate_signals(data):
-    """
-    Generate buy/sell signals based on SMA and RSI.
+    """Generate buy/sell signals based on Simple Moving Averages (SMA) and Relative Strength Index (RSI).
+
+    Parameters
+    ----------
+    data : pandas.DataFrame
+        DataFrame containing 'SMA_50', 'SMA_200', and 'RSI' columns.
 
-    Parameters:
-    - data (pd.DataFrame): DataFrame that includes 'SMA_50', 'SMA_200', and 'RSI' columns.
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame with an additional 'Signal' column indicating 'BUY', 'SELL', or 'HOLD' signals.
 
-    Returns:
-    - pd.DataFrame: DataFrame with a new 'Signal' column (Buy, Sell, Hold).
+    Examples
+    --------
+    >>> data = pd.DataFrame({
+    >>>     'SMA_50': [100, 102, 104, 106, 108],
+    >>>     'SMA_200': [98, 99, 100, 101, 102],
+    >>>     'RSI': [25, 30, 35, 40, 45]
+    >>> })
+    >>> result = generate_signals(data)
+    >>> print(result['Signal'])
     """
 
     if not isinstance(data, pd.DataFrame):

src/traders_copilot_mzza_25/indicators.py

@@ -3,16 +3,27 @@
 
 #SMA
 def calculate_sma(data, window=50, fillna=False):
-    """
-    Calculate the Simple Moving Average (SMA) for the given data.
+    """Calculate the Simple Moving Average (SMA) for the given data.
+
+    Parameters
+    ----------
+    data : pandas.DataFrame
+        DataFrame containing stock price data with a 'Close' column.
+    window : int, optional
+        The number of periods to calculate the SMA (default is 50).
+    fillna : bool, optional
+        Whether to fill NaN values (default is False).
 
-    Args:
-        data (pd.DataFrame): DataFrame containing stock price data with a 'Close' column.
-        window (int): The number of periods to calculate the SMA (default is 50).
-        fillna (bool): Whether to fill NaN values (default is False).
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame with an additional column for the SMA.
 
-    Returns:
-        pd.DataFrame: DataFrame with an additional column for the SMA.
+    Examples
+    --------
+    >>> data = pd.DataFrame({'Close': [100, 102, 104, 106, 108]})
+    >>> result = calculate_sma(data, window=3)
+    >>> print(result['SMA_3'])
     """
     if not isinstance(data, pd.DataFrame):
         raise TypeError("The input data must be a pandas DataFrame.")
@@ -33,17 +44,29 @@ def calculate_sma(data, window=50, fillna=False):
 
 #RSI 
 def calculate_rsi(data, window=14, fillna=False):
-    """
-    Calculate the Relative Strength Index (RSI) measuring the speed and change of price movements.
+    """Calculate the Relative Strength Index (RSI) measuring the speed and change of price movements.
 
-    Args:
-        data (pd.DataFrame): DataFrame containing stock price data with a 'Close' column.
-        window (int): Number of periods for RSI calculation (default is 14).
-        fillna (bool): Whether to fill NaN values (default is False).
+    Parameters
+    ----------
+    data : pandas.DataFrame
+        DataFrame containing stock price data with a 'Close' column.
+    window : int, optional
+        Number of periods for RSI calculation (default is 14).
+    fillna : bool, optional
+        Whether to fill NaN values (default is False).
 
-    Returns:
-        pd.DataFrame: DataFrame with an additional column for RSI.
+    Returns
+    -------
+    pandas.DataFrame
+        DataFrame with an additional column for RSI.
+    
+    Examples
+    --------
+    >>> data = pd.DataFrame({'Close': [100, 102, 104, 106, 108]})
+    >>> result = calculate_rsi(data, window=3)
+    >>> print(result['RSI'])
     """
+
     if not isinstance(data, pd.DataFrame):
         raise TypeError("The input data must be a pandas DataFrame.")
 

src/traders_copilot_mzza_25/plot_signals.py

@@ -40,8 +40,7 @@ def generate_plot(price, time):
     return fig
 
 def plot_signals(data, price_col="Close", time_col="Date"):
-    """
-    Plot a time series depicting the price at specific timestamps from a DataFrame.
+    """Plot a time series depicting the price at specific timestamps from a DataFrame.
     
     Parameters
     ----------
@@ -68,12 +67,13 @@ def plot_signals(data, price_col="Close", time_col="Date"):
     Examples
     --------
     >>> data = pd.DataFrame({"Date": ["2023-01-01", "2023-01-02", "2023-01-03"], 
-    ...                      "Close": [100, 102, 104]})
+    >>>                      "Close": [100, 102, 104]})
     >>> fig = plot_signals(data)
     >>> fig.show()
     """
     validate_columns(data, price_col, time_col)
     validate_lengths(data, price_col, time_col)
     validate_non_empty(data, price_col, time_col)
     validate_dates(data, time_col)
+
     return generate_plot(data[price_col], data[time_col])