Nonlinear AR

timecave.data_generation.time_series_functions.nonlinear_ar_ts(number_samples, init_array, params, func_idxs)

Generate a time series array based on a nonlinear autoregressive (AR) model.

This function creates a time series array of a given length based on a nonlinear AR model with specified initial array, parameters, and function indices.

Parameters:

Name	Type	Description	Default
number_samples	int	The total number of samples in the time series array.	required
init_array	ndarray	The initial array for generating the time series. The lengths corresponds to the number of lags.	required
params	list	The parameters for the nonlinear AR model. The index representing the specific nonlinear transformation to apply: 0: Cosine function. 1: Sine function. 2: Hyperbolic tangent function. 3: Arctangent function. 4: Exponential decay function.	required
func_idxs	list	The indices of the nonlinear functions used in the model.	required

Returns:

Type	Description
ndarray	A time series array generated based on the specified nonlinear AR model parameters.

Warnings

The lengths of init_array, params and func_idxs must match.

Notes

This method of generating synthetic time series data was first proposed by Bergmeir et al. (2018). Please refer to [1] for more details on this method.

References

1

Christoph Bergmeir, Rob J Hyndman, and Bonsoo Koo. A note on the validity of cross-validation for evaluating autoregressive time series prediction. Computational Statistics & Data Analysis, 120:70–83, 2018.

Examples:

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from timecave.data_generation.time_series_functions import nonlinear_ar_ts
>>> ts = nonlinear_ar_ts(1000, init_array=np.zeros(2), params=[0.5, -0.3], func_idxs=[0, 1]);
>>> _ = plt.plot(np.arange(0, ts.shape[0]), ts);
>>> plt.show();

Functions other than sinusoids can be used as well:

>>> ts2 = nonlinear_ar_ts(1000, init_array=np.zeros(4), params=[0.2, 0.6, -0.1, -0.4], func_idxs=[2, 3, 4, 3]);
>>> _ = plt.plot(np.arange(0, ts.shape[0]), ts2);
>>> plt.show();

Source code in timecave/data_generation/time_series_functions.py

def nonlinear_ar_ts(
    number_samples: int, init_array: np.array, params: list, func_idxs: list
):
    """
    Generate a time series array based on a nonlinear autoregressive (AR) model.

    This function creates a time series array of a given length based on a nonlinear AR model
    with specified initial array, parameters, and function indices.

    Parameters
    ----------
    number_samples : int
        The total number of samples in the time series array.

    init_array : np.ndarray
        The initial array for generating the time series. The lengths corresponds to the number of lags.

    params : list
        The parameters for the nonlinear AR model. The index representing the specific nonlinear transformation to apply:
            0: Cosine function.
            1: Sine function.
            2: Hyperbolic tangent function.
            3: Arctangent function.
            4: Exponential decay function.

    func_idxs : list
        The indices of the nonlinear functions used in the model.

    Returns
    -------
    np.ndarray
        A time series array generated based on the specified nonlinear AR model parameters.

    Warnings
    --------
    The lengths of `init_array`, `params` and `func_idxs` must match.

    Notes
    -----
    This method of generating synthetic time series data was first proposed by Bergmeir et al. (2018). 
    Please refer to [[1]](#1) for more details on this method.

    References
    ----------
    ##1
    Christoph Bergmeir, Rob J Hyndman, and Bonsoo Koo. A note on the validity 
    of cross-validation for evaluating autoregressive time series prediction.
    Computational Statistics & Data Analysis, 120:70–83, 2018.

    Examples
    --------
    >>> import numpy as np
    >>> import matplotlib.pyplot as plt
    >>> from timecave.data_generation.time_series_functions import nonlinear_ar_ts
    >>> ts = nonlinear_ar_ts(1000, init_array=np.zeros(2), params=[0.5, -0.3], func_idxs=[0, 1]);
    >>> _ = plt.plot(np.arange(0, ts.shape[0]), ts);
    >>> plt.show();

    ![ARsin](../../../images/Nonlinear_AR_sin.png)

    Functions other than sinusoids can be used as well:

    >>> ts2 = nonlinear_ar_ts(1000, init_array=np.zeros(4), params=[0.2, 0.6, -0.1, -0.4], func_idxs=[2, 3, 4, 3]);
    >>> _ = plt.plot(np.arange(0, ts.shape[0]), ts2);
    >>> plt.show();

    ![ARother](../../../images/Nonlinear_AR_others.png)
    """
    _check_number_samples(number_samples)
    if len(params) != len(func_idxs):
        raise ValueError("'params' and 'func_idxs' must have the same length")

    init_len = len(init_array)

    x = np.empty(number_samples + init_len)
    x[0:init_len] = init_array

    for t in range(init_len, number_samples + init_len):
        x[t] = np.random.normal(scale=0.5)

        for j in range(1, init_len + 1):
            x[t] += params[j - 1] * _nonlin_func(func_idxs[j - 1], x[t - j])

    ts = x[init_len : (number_samples + init_len)]

    return ts