augment_drawdown

augment_drawdown(
    data,
    date_column,
    close_column,
    reduce_memory=False,
    engine='pandas',
)

The augment_drawdown function calculates the drawdown metrics for a financial time series using either pandas or polars engine, and returns the augmented DataFrame with peak value, drawdown, and drawdown percentage columns.

Parameters

Name Type Description Default
data Union[pd.DataFrame, pd.core.groupby.generic.DataFrameGroupBy] The input data can be either a pandas DataFrame or a pandas DataFrameGroupBy object containing the time series data for drawdown calculation. required
date_column str The name of the column containing dates or timestamps. required
close_column str The column containing the values (e.g., price) to calculate drawdowns from. required
reduce_memory bool If True, reduces memory usage of the DataFrame before calculation. Default is False. False
engine str The computation engine to use: β€˜pandas’ or β€˜polars’. Default is β€˜pandas’. 'pandas'

Returns

Name Type Description
pd.DataFrame A pandas DataFrame augmented with three columns: - {close_column}_peak: Running maximum value up to each point - {close_column}_drawdown: Absolute difference from peak to current value - {close_column}_drawdown_pct: Percentage decline from peak to current value

Notes

Drawdown is a measure of peak-to-trough decline in a time series, typically used to assess the risk of a financial instrument:

  • Peak Value: The highest value observed up to each point in time
  • Drawdown: The absolute difference between the peak and current value
  • Drawdown Percentage: The percentage decline from the peak value

Examples

import pandas as pd
import pytimetk as tk

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

# Single stock drawdown
dd_df = (
    df.query("symbol == 'AAPL'")
    .augment_drawdown(
        date_column='date',
        close_column='close',
    )
)
dd_df.head()
symbol date open high low close volume adjusted close_peak close_drawdown close_drawdown_pct
5398 AAPL 2013-01-02 19.779285 19.821428 19.343929 19.608213 560518000 16.791180 19.608213 0.000000 0.000000
5399 AAPL 2013-01-03 19.567142 19.631071 19.321428 19.360714 352965200 16.579241 19.608213 -0.247499 -0.012622
5400 AAPL 2013-01-04 19.177500 19.236786 18.779642 18.821428 594333600 16.117437 19.608213 -0.786785 -0.040125
5401 AAPL 2013-01-07 18.642857 18.903570 18.400000 18.710714 484156400 16.022623 19.608213 -0.897499 -0.045772
5402 AAPL 2013-01-08 18.900356 18.996071 18.616072 18.761070 458707200 16.065746 19.608213 -0.847143 -0.043203 
dd_df.groupby('symbol').plot_timeseries('date', 'close_drawdown_pct')
# Multiple stocks with groupby
dd_df = (
    df.groupby('symbol')
    .augment_drawdown(
        date_column='date',
        close_column='close',
        engine='polars'
    )
)
dd_df.head()
symbol date open high low close volume adjusted close_peak close_drawdown close_drawdown_pct
0 META 2013-01-02 27.440001 28.180000 27.420000 28.000000 69846400 28.000000 28.00 0.000000 0.000000
1 META 2013-01-03 27.879999 28.469999 27.590000 27.770000 63140600 27.770000 28.00 -0.230000 -0.008214
2 META 2013-01-04 28.010000 28.930000 27.830000 28.760000 72715400 28.760000 28.76 0.000000 0.000000
3 META 2013-01-07 28.690001 29.790001 28.650000 29.420000 83781800 29.420000 29.42 0.000000 0.000000
4 META 2013-01-08 29.510000 29.600000 28.860001 29.059999 45871300 29.059999 29.42 -0.360001 -0.012237 
dd_df.groupby('symbol').plot_timeseries('date', 'close_drawdown_pct')