Apply the Hilbert transform to specified columns of a DataFrame or DataFrameGroupBy object.
Signal Processing: The Hilbert transform is used in various signal processing techniques, including phase and amplitude modulation and demodulation, and in the analysis of signals with time-varying amplitude and frequency.
Parameters
Name
Type
Description
Default
data
pd.DataFrame or pd.core.groupby.generic.DataFrameGroupBy
Input DataFrame or DataFrameGroupBy object with one or more columns of real-valued signals.
required
value_column
str or list
List of column names in ‘data’ to which the Hilbert transform will be applied.
required
reduce_memory
bool
The reduce_memory parameter is used to specify whether to reduce the memory usage of the DataFrame by converting int, float to smaller bytes and str to categorical data. This reduces memory for large data but may impact resolution of float and will change str to categorical. Default is True.
True
engine
(auto, pandas, polars)
Specifies the backend to use for the computation. When “auto” (default) the backend is inferred from the input data. Use “pandas” or “polars” to force a specific backend.
"auto"
Returns
Name
Type
Description
df_hilbert
DataFrame
A new DataFrame with the 2 Hilbert-transformed columns added, 1 for the real and 1 for imaginary (original columns are preserved). Matches the backend of the input data.
Notes
The Hilbert transform is used in time series analysis primarily for:
Creating Analytic Signals: Forms a complex-valued signal whose properties (magnitude and phase) provide valuable insights into the original signal’s structure.
Determining Instantaneous Phase/Frequency: Offers real-time signal characteristics, crucial for non-stationary signals whose properties change over time.
Extracting Amplitude Envelope: Helps in identifying signal’s amplitude variations, useful in various analysis tasks.
Enhancing Signal Analysis: Assists in tasks like demodulation, trend analysis, feature extraction for machine learning, and improving signal-to-noise ratio, providing a deeper understanding of underlying patterns and trends.
Examples
# Example 1: Using Pandas Engine on a pandas groupby objectimport pytimetk as tkimport pandas as pddf = tk.load_dataset('walmart_sales_weekly', parse_dates=['Date'])df_hilbert = ( df .groupby('id') .augment_hilbert( date_column ='Date', value_column = ['Weekly_Sales'], engine ='pandas' ))df_hilbert.head()
id
Store
Dept
Date
Weekly_Sales
IsHoliday
Type
Size
Temperature
Fuel_Price
MarkDown1
MarkDown2
MarkDown3
MarkDown4
MarkDown5
CPI
Unemployment
Weekly_Sales_hilbert_real
Weekly_Sales_hilbert_imag
0
1_1
1
1
2010-02-05
24924.500000
0
A
151315
42.310001
2.572
NaN
NaN
NaN
NaN
NaN
211.096359
8.106
24924.498047
-12764.086914
1
1_1
1
1
2010-02-12
46039.488281
1
A
151315
38.509998
2.548
NaN
NaN
NaN
NaN
NaN
211.242172
8.106
46039.488281
-13469.210938
2
1_1
1
1
2010-02-19
41595.550781
0
A
151315
39.930000
2.514
NaN
NaN
NaN
NaN
NaN
211.289139
8.106
41595.550781
16686.888672
3
1_1
1
1
2010-02-26
19403.539062
0
A
151315
46.630001
2.561
NaN
NaN
NaN
NaN
NaN
211.319641
8.106
19403.535156
9378.224609
4
1_1
1
1
2010-03-05
21827.900391
0
A
151315
46.500000
2.625
NaN
NaN
NaN
NaN
NaN
211.350143
8.106
21827.898438
2552.131836
# Example 2: Using the polars accessor on a grouped tableimport pytimetk as tkimport polars as pldf = tk.load_dataset('walmart_sales_weekly', parse_dates=['Date'])df_hilbert = ( pl.from_pandas(df) .group_by('id') .tk.augment_hilbert( date_column ='Date', value_column = ['Weekly_Sales'], ))df_hilbert.head()
shape: (5, 19)
id
Store
Dept
Date
Weekly_Sales
IsHoliday
Type
Size
Temperature
Fuel_Price
MarkDown1
MarkDown2
MarkDown3
MarkDown4
MarkDown5
CPI
Unemployment
Weekly_Sales_hilbert_real
Weekly_Sales_hilbert_imag
str
i64
i64
datetime[ns]
f64
bool
str
i64
f64
f64
f64
f64
f64
f64
f64
f64
f64
f64
f64
"1_1"
1
1
2010-02-05 00:00:00
24924.5
false
"A"
151315
42.31
2.572
null
null
null
null
null
211.096358
8.106
24924.5
-12764.088716
"1_1"
1
1
2010-02-12 00:00:00
46039.49
true
"A"
151315
38.51
2.548
null
null
null
null
null
211.24217
8.106
46039.49
-13469.209506
"1_1"
1
1
2010-02-19 00:00:00
41595.55
false
"A"
151315
39.93
2.514
null
null
null
null
null
211.289143
8.106
41595.55
16686.889086
"1_1"
1
1
2010-02-26 00:00:00
19403.54
false
"A"
151315
46.63
2.561
null
null
null
null
null
211.319643
8.106
19403.54
9378.223595
"1_1"
1
1
2010-03-05 00:00:00
21827.9
false
"A"
151315
46.5
2.625
null
null
null
null
null
211.350143
8.106
21827.9
2552.133165
# Example 3: Using the polars accessor on a DataFrameimport pytimetk as tkimport polars as pldf = tk.load_dataset('taylor_30_min', parse_dates=['date'])df_hilbert = ( pl.from_pandas(df) .tk.augment_hilbert( date_column ='date', value_column = ['value'], ))df_hilbert.head()