fusionlab.utils.ts_utils.trend_analysis¶

fusionlab.utils.ts_utils.trend_analysis(df, value_col, dt_col=None, view=False, check_stationarity=True, trend_type='both', strategy='adf', stationnay_color='green', linestyle='--', fig_size=(10, 6), trend_color='red', show_grid=True, error='raise', verbose=0, **kw)[source]¶

Perform trend analysis on a given time series, combining a stationarity test and a linear trend detection. The function checks whether the series is stationary via the specified test (ADF or KPSS) and, if non-stationary, fits a simple linear regression model to infer the direction of trend.

Mathematically, the trend detection relies on fitting:

\[y_t = \beta_0 + \beta_1 \cdot t + \epsilon_t,\]

where \(y_t\) is the value at time \(t\). The slope \(\beta_1\) determines whether the trend is upward (\(\beta_1 > 0\)), downward (\(\beta_1 < 0\)), or stationary (\(\beta_1 \approx 0\)).

Parameters:

df (pandas.DataFrame) – The input DataFrame containing time series data.
value_col (str or array-like) – The name (or direct series) of the target variable to analyze.
dt_col (str, optional) – The column name representing datetime information. If None, attempts to detect or convert the index to datetime.
view (bool, optional) – If True, displays a plot showing the original time series along with the fitted trend line (if applicable).
check_stationarity (bool, optional) – If True, performs a stationarity test (ADF or KPSS) before trend detection. If the data is found stationary and trend_type is not ‘both’, the function may not fit a trend line.
trend_type ({'both', 'upward', 'downward'}, optional) – Type of trend to detect. If 'both', considers all possibilities. If 'upward', checks only for a positive slope. If 'downward', checks only for a negative slope.
strategy ({'adf', 'kpss'}, optional) –
Stationarity test to use:
- 'adf': Augmented Dickey-Fuller test.
- 'kpss': Kwiatkowski–Phillips–Schmidt–Shin test.
stationnay_color (str, optional) – Color for the mean line if the series is found to be stationary.
linestyle (str, optional) – The line style for the stationary mean line.
fig_size (tuple of (int, int), optional) – The width and height of the plot in inches.
trend_color (str, optional) – Color for the fitted trend line.
show_grid (bool, optional) – Whether to display grid lines on the plot.
error ({'raise', 'warn', 'ignore'}, optional) –
Behavior to adopt when encountering errors:
- 'raise': Raises a ValueError.
- 'warn': Issues a warning message.
- 'ignore': Silently ignores errors.
verbose (int, optional) –
Verbosity level controlling console output:
- 0: No messages.
- 1: Basic information.
- 2: More detailed status updates.
**kw (dict, optional) – Additional keyword arguments passed to matplotlib’s plotting function (e.g., marker styles, alpha).

Returns:

trend (str) – Detected trend type:
- 'upward': If the slope is strictly positive.
- 'downward': If the slope is strictly negative.
- 'stationary': If no clear slope or series is identified as stationary.
p_value (float or None) – p-value from the stationarity test. If check_stationarity=False, returns None.

Examples

>>> import pandas as pd
>>> from fusionlab.utils.ts_utils import trend_analysis
>>> data = {
...     'Date': [
...         '2020-01-01', '2020-01-02', '2020-01-03',
...         '2020-01-04', '2020-01-05'
...     ],
...     'Value': [10, 12, 15, 13, 14]
... }
>>> df = pd.DataFrame(data)
>>> trend, p_val = trend_analysis(
...     df, value_col='Value',
...     dt_col='Date', view=True,
...     check_stationarity=True, strategy='adf'
... )
>>> trend
'non-stationary'  # or 'upward', 'downward', or 'stationary'

Notes

Identifying trends is a central component of time series analysis. Non-stationary behavior can lead to misleading statistical results if not handled properly [1] [2]. This function thus helps detect both stationarity and monotonic tendencies in the data.