augment_hurst_exponent

augment_hurst_exponent(
    data,
    date_column,
    close_column,
    window=100,
    reduce_memory=False,
    engine='pandas',
)

Calculate the Hurst Exponent on a rolling window for a financial time series. Used for detecting trends and mean-reversion.

Parameters

Name Type Description Default
data Union[pd.DataFrame, pd.core.groupby.generic.DataFrameGroupBy] Input pandas DataFrame or GroupBy object with time series data. required
date_column str Column name containing dates or timestamps. required
close_column str Column name with closing prices to calculate the Hurst Exponent. required
window Union[int, Tuple[int, int], List[int]] Size of the rolling window for Hurst Exponent calculation. Accepts int, tuple (start, end), or list. Default is 100. 100
reduce_memory bool If True, reduces memory usage before calculation. Default is False. False
engine str Computation engine: β€˜pandas’ or β€˜polars’. Default is β€˜pandas’. 'pandas'

Returns

Name Type Description
pd.DataFrame DataFrame with added columns: - {close_column}hurst{window}: Hurst Exponent for each window size

Notes

The Hurst Exponent measures the long-term memory of a time series:

  • H < 0.5: Mean-reverting behavior
  • H β‰ˆ 0.5: Random walk (no persistence)
  • H > 0.5: Trending or persistent behavior Computed using a simplified R/S analysis over rolling windows.

References:

  • https://en.wikipedia.org/wiki/Hurst_exponent

Examples:

import pandas as pd
import pytimetk as tk

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

# Example 1 - Single stock Hurst Exponent with pandas engine
hurst_df = (
    df.query("symbol == 'AAPL'")
    .augment_hurst_exponent(
        date_column='date',
        close_column='close',
        window=[100, 200]
    )
)
hurst_df.glimpse()
<class 'pandas.core.frame.DataFrame'>: 2699 rows of 10 columns
symbol:           object            ['AAPL', 'AAPL', 'AAPL', 'AAPL', 'AA ...
date:             datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), T ...
open:             float64           [19.779285430908203, 19.567142486572 ...
high:             float64           [19.821428298950195, 19.631071090698 ...
low:              float64           [19.343929290771484, 19.321428298950 ...
close:            float64           [19.608213424682617, 19.360713958740 ...
volume:           int64             [560518000, 352965200, 594333600, 48 ...
adjusted:         float64           [16.791179656982422, 16.579240798950 ...
close_hurst_100:  float64           [nan, nan, nan, nan, nan, nan, nan,  ...
close_hurst_200:  float64           [nan, nan, nan, nan, nan, nan, nan,  ...
# Example 2 - Multiple stocks with groupby using pandas engine
hurst_df = (
    df.groupby('symbol')
    .augment_hurst_exponent(
        date_column='date',
        close_column='close',
        window=100
    )
)
hurst_df.glimpse()
<class 'pandas.core.frame.DataFrame'>: 16194 rows of 9 columns
symbol:           object            ['META', 'META', 'META', 'META', 'ME ...
date:             datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), T ...
open:             float64           [27.440000534057617, 27.879999160766 ...
high:             float64           [28.18000030517578, 28.4699993133544 ...
low:              float64           [27.420000076293945, 27.590000152587 ...
close:            float64           [28.0, 27.770000457763672, 28.760000 ...
volume:           int64             [69846400, 63140600, 72715400, 83781 ...
adjusted:         float64           [28.0, 27.770000457763672, 28.760000 ...
close_hurst_100:  float64           [nan, nan, nan, nan, nan, nan, nan,  ...
# Example 3 - Single stock Hurst Exponent with polars engine
hurst_df = (
    df.query("symbol == 'AAPL'")
    .augment_hurst_exponent(
        date_column='date',
        close_column='close',
        window=[100, 200],
        engine='polars'
    )
)
hurst_df.glimpse()
<class 'pandas.core.frame.DataFrame'>: 2699 rows of 10 columns
symbol:           object            ['AAPL', 'AAPL', 'AAPL', 'AAPL', 'AA ...
date:             datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), T ...
open:             float64           [19.779285430908203, 19.567142486572 ...
high:             float64           [19.821428298950195, 19.631071090698 ...
low:              float64           [19.343929290771484, 19.321428298950 ...
close:            float64           [19.608213424682617, 19.360713958740 ...
volume:           int64             [560518000, 352965200, 594333600, 48 ...
adjusted:         float64           [16.791179656982422, 16.579240798950 ...
close_hurst_100:  float64           [nan, nan, nan, nan, nan, nan, nan,  ...
close_hurst_200:  float64           [nan, nan, nan, nan, nan, nan, nan,  ...
# Example 4 - Multiple stocks with groupby using polars engine
hurst_df = (
    df.groupby('symbol')
    .augment_hurst_exponent(
        date_column='date',
        close_column='close',
        window=100,
        engine='polars'
    )
)
hurst_df.glimpse()
<class 'pandas.core.frame.DataFrame'>: 16194 rows of 9 columns
symbol:           object            ['META', 'META', 'META', 'META', 'ME ...
date:             datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), T ...
open:             float64           [27.440000534057617, 27.879999160766 ...
high:             float64           [28.18000030517578, 28.4699993133544 ...
low:              float64           [27.420000076293945, 27.590000152587 ...
close:            float64           [28.0, 27.770000457763672, 28.760000 ...
volume:           int64             [69846400, 63140600, 72715400, 83781 ...
adjusted:         float64           [28.0, 27.770000457763672, 28.760000 ...
close_hurst_100:  float64           [nan, nan, nan, nan, nan, nan, nan,  ...