augment_bbands

augment_bbands(data, date_column, close_column, periods=20, std_dev=2, reduce_memory=False, engine='pandas')

The augment_bbands function is used to calculate Bollinger Bands for a given dataset and return the augmented dataset.

Parameters

Name Type Description Default
data Union[pd.DataFrame, pd.core.groupby.generic.DataFrameGroupBy] The data parameter is the input data that can be either a pandas DataFrame or a pandas DataFrameGroupBy object. It contains the data on which the Bollinger Bands will be calculated. required
date_column str The date_column parameter is a string that specifies the name of the column in the data DataFrame that contains the dates. required
close_column str The close_column parameter is a string that specifies the name of the column in the data DataFrame that contains the closing prices of the asset. required
periods Union[int, Tuple[int, int], List[int]] The periods parameter in the augment_bbands function can be specified as an integer, a tuple, or a list. This parameter specifies the number of rolling periods to use when calculating the Bollinger Bands. 20
std_dev float The std_dev parameter is a float that represents the number of standard deviations to use when calculating the Bollinger Bands. Bollinger Bands are a technical analysis tool that consists of a middle band (usually a simple moving average) and an upper and lower band that are typically two standard deviations away from the middle band. The std_dev parameter specifies the number of standard deviations. std_dev can be a list of floats as well. 2
reduce_memory bool The reduce_memory parameter is a boolean flag that indicates whether or not to reduce the memory usage of the input data before performing the calculation. If set to True, the function will attempt to reduce the memory usage of the input data using techniques such as downcasting numeric columns and converting object columns False
engine str The engine parameter specifies the computation engine to use for calculating the Bollinger Bands. It can take two values: ‘pandas’ or ‘polars’. If ‘pandas’ is selected, the function will use the pandas library for computation. If ‘polars’ is selected, 'pandas'

Returns

Type Description
pd.DataFrame The function augment_bbands returns a pandas DataFrame.

Notes

Bollinger Bands are a technical analysis tool developed by John Bollinger in the 1980s. They are used to measure the ‘volatility’ of a stock price or other financial instrument. This indicator consists of three lines which are plotted in relation to an asset’s price:

  1. The Middle Band: This is typically a simple moving average (SMA) of the closing prices over a certain number of days (commonly 20 days).

  2. The Upper Band: This is set a specified number of standard deviations (usually two) above the middle band.

  3. The Lower Band: This is set the same number of standard deviations (again, usually two) below the middle band.

Volatility Indicator: The width of the bands is a measure of volatility. When the bands widen, it indicates increased volatility, and when they contract, it suggests decreased volatility.

Overbought and Oversold Conditions: Prices are considered overbought near the upper band and oversold near the lower band. However, these conditions do not necessarily signal a reversal; prices can remain overbought or oversold for extended periods during strong trends.

Examples

import pandas as pd
import pytimetk as tk

df = tk.load_dataset("stocks_daily", parse_dates = ['date'])

df
symbol date open high low close volume adjusted
0 META 2013-01-02 27.440001 28.180000 27.420000 28.000000 69846400 28.000000
1 META 2013-01-03 27.879999 28.469999 27.590000 27.770000 63140600 27.770000
2 META 2013-01-04 28.010000 28.930000 27.830000 28.760000 72715400 28.760000
3 META 2013-01-07 28.690001 29.790001 28.650000 29.420000 83781800 29.420000
4 META 2013-01-08 29.510000 29.600000 28.860001 29.059999 45871300 29.059999
... ... ... ... ... ... ... ... ...
16189 GOOG 2023-09-15 138.800003 139.360001 137.179993 138.300003 48947600 138.300003
16190 GOOG 2023-09-18 137.630005 139.929993 137.630005 138.960007 16233600 138.960007
16191 GOOG 2023-09-19 138.250000 139.175003 137.500000 138.830002 15479100 138.830002
16192 GOOG 2023-09-20 138.830002 138.839996 134.520004 134.589996 21473500 134.589996
16193 GOOG 2023-09-21 132.389999 133.190002 131.089996 131.360001 22042700 131.360001

16194 rows × 8 columns

# BBANDS pandas engine
df_bbands = (
    df
        .groupby('symbol')
        .augment_bbands(
            date_column = 'date', 
            close_column='close', 
            periods = [20, 40],
            std_dev = 2, 
            engine = "pandas"
        )
)

df_bbands.glimpse()
<class 'pandas.core.frame.DataFrame'>: 16194 rows of 14 columns
symbol:                     object            ['META', 'META', 'META', ' ...
date:                       datetime64[ns]    [Timestamp('2013-01-02 00: ...
open:                       float64           [27.440000534057617, 27.87 ...
high:                       float64           [28.18000030517578, 28.469 ...
low:                        float64           [27.420000076293945, 27.59 ...
close:                      float64           [28.0, 27.770000457763672, ...
volume:                     int64             [69846400, 63140600, 72715 ...
adjusted:                   float64           [28.0, 27.770000457763672, ...
close_bband_middle_20_2.0:  float64           [nan, nan, nan, nan, nan,  ...
close_bband_upper_20_2.0:   float64           [nan, nan, nan, nan, nan,  ...
close_bband_lower_20_2.0:   float64           [nan, nan, nan, nan, nan,  ...
close_bband_middle_40_2.0:  float64           [nan, nan, nan, nan, nan,  ...
close_bband_upper_40_2.0:   float64           [nan, nan, nan, nan, nan,  ...
close_bband_lower_40_2.0:   float64           [nan, nan, nan, nan, nan,  ...
# BBANDS polars engine
df_bbands = (
    df
        .groupby('symbol')
        .augment_bbands(
            date_column = 'date', 
            close_column='close', 
            periods = [20, 40],
            std_dev = 2, 
            engine = "polars"
        )
)

df_bbands.glimpse()
<class 'pandas.core.frame.DataFrame'>: 16194 rows of 14 columns
symbol:                     object            ['META', 'META', 'META', ' ...
date:                       datetime64[ns]    [Timestamp('2013-01-02 00: ...
open:                       float64           [27.440000534057617, 27.87 ...
high:                       float64           [28.18000030517578, 28.469 ...
low:                        float64           [27.420000076293945, 27.59 ...
close:                      float64           [28.0, 27.770000457763672, ...
volume:                     int64             [69846400, 63140600, 72715 ...
adjusted:                   float64           [28.0, 27.770000457763672, ...
close_bband_middle_20_2.0:  float64           [nan, nan, nan, nan, nan,  ...
close_bband_upper_20_2.0:   float64           [nan, nan, nan, nan, nan,  ...
close_bband_lower_20_2.0:   float64           [nan, nan, nan, nan, nan,  ...
close_bband_middle_40_2.0:  float64           [nan, nan, nan, nan, nan,  ...
close_bband_upper_40_2.0:   float64           [nan, nan, nan, nan, nan,  ...
close_bband_lower_40_2.0:   float64           [nan, nan, nan, nan, nan,  ...