fusionlab.datasets.make_trend_seasonal_data

fusionlab.datasets.make_trend_seasonal_data(n_timesteps=730, freq='D', trend_order=1, trend_coeffs=None, seasonal_periods=[7, 365.25], seasonal_amplitudes=[5, 15], noise_level=1.0, base_level=50.0, as_frame=False, seed=None)[source]

Generate synthetic time series with specified trend and seasonality.

Creates a univariate time series containing a configurable polynomial trend, multiple sinusoidal seasonal components, and Gaussian noise.

This is useful for testing decomposition methods or how well models capture specific trend and seasonal patterns.

Parameters:

  • n_timesteps (int, default 730) – Number of time steps (rows) to generate.

  • freq (str, default 'D') – Pandas frequency string for generating the datetime index.

  • trend_order (int, default 1) – Order of the polynomial trend (0=constant, 1=linear, 2=quadratic).

  • trend_coeffs (list of float, optional) – Coefficients for the polynomial trend, starting with the constant term. Length should be trend_order + 1. If None, default coefficients are used (e.g., [base_level, 0.1] for order 1). Default is None.

  • seasonal_periods (list of float, default [7, 365.25]) – List of periods for the sinusoidal seasonal components (in number of time steps).

  • seasonal_amplitudes (list of float, default [5, 15]) – List of amplitudes corresponding to each period in seasonal_periods. Length must match seasonal_periods.

  • noise_level (float, default 1.0) – Standard deviation of the Gaussian noise added to the signal.

  • base_level (float, default 50.0) – The constant term (offset) if trend_order is 0, or the intercept used in default trend coefficients.

  • as_frame (bool, default False) – Return type: False for Bunch, True for DataFrame.

  • seed (int, optional) – Seed for NumPy’s random number generator for reproducibility.

Returns:

data – If as_frame=False (default): A Bunch object with frame, data (values), target_names ([‘value’]), target (values array), dt_col (‘date’), and DESCR. If as_frame=True: The generated data as a pandas DataFrame with ‘date’ and ‘value’.

Return type:

Bunch or pandas.DataFrame

Raises:

ValueError – If lengths of seasonal_periods and seasonal_amplitudes mismatch, or if trend_coeffs length doesn’t match trend_order.

Examples

>>> from fusionlab.datasets import make_trend_seasonal_data
>>> # Generate data with linear trend and two seasonalities
>>> data_bunch = make_trend_seasonal_data(n_timesteps=100, freq='D', seed=1)
>>> print(data_bunch.frame.head())
>>> data_bunch.frame.plot(x='date', y='value', figsize=(10, 3)) # Quick plot