ARMA

timecave.data_generation.time_series_functions.arma_ts(number_samples, lags, max_root, ar=True, ma=True, **kwargs)

Generate a time series array based on an Autoregressive Moving Average (ARMA) model.

This function creates a time series array of given length based on an ARMA model with specified parameters such as number of lags and maximum root. It generates samples using an ARMA process.

Parameters:

Name	Type	Description	Default
number_samples	int	The total number of samples in the time series array.	required
lags	int	The number of lags to consider in the ARMA model.	required
max_root	float	The maximum root for the ARMA model. This value has to be larger than 1.1.	required
ar	bool	Whether to include autoregressive (AR) component in the ARMA model.	True
ma	bool	Whether to include moving average (MA) component in the ARMA model.	True
**kwargs	dict	Additional keyword arguments to pass to the ARMA process generator. See ARMAProcess for more details.	{}

Returns:

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

Raises:

Type	Description
ValueError	If the maximum root is not larger than 1.1.

See also

nonlinear_ar_ts: Generate data from a nonlinear autoregressive process.

Notes

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

References

1

Christoph Bergmeir and José M Benítez. On the use of cross-validation for time series predictor evaluation. Information Sciences, 191:192–213, 2012.

Examples:

>>> import numpy as np
>>> import matplotlib.pyplot as plt
>>> from timecave.data_generation.time_series_functions import arma_ts
>>> ts = arma_ts(1000, 5, 2);
>>> _ = plt.plot(np.arange(0, ts.shape[0]), ts);
>>> plt.show();

Pure autoregressive processes can also be generated:

>>> ts2 = arma_ts(1000, 5, 2, ma=False);
>>> _ = plt.plot(np.arange(0, ts2.shape[0]), ts2);
>>> plt.show();

And so can pure moving average processes:

>>> ts3 = arma_ts(1000, 5, 2, ar=False);
>>> _ = plt.plot(np.arange(0, ts3.shape[0]), ts3);
>>> plt.show();

Source code in timecave/data_generation/time_series_functions.py

def arma_ts(
    number_samples: int,
    lags: int,
    max_root: float,
    ar: bool = True,
    ma: bool = True,
    **kwargs,
):
    """
    Generate a time series array based on an Autoregressive Moving Average (ARMA) model.

    This function creates a time series array of given length based on an ARMA model
    with specified parameters such as number of lags and maximum root. It generates
    samples using an ARMA process.

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

    lags : int
        The number of lags to consider in the ARMA model.

    max_root : float
        The maximum root for the ARMA model. This value has to be larger than 1.1.

    ar : bool, default=True
        Whether to include autoregressive (AR) component in the ARMA model.

    ma : bool, default=True
        Whether to include moving average (MA) component in the ARMA model.

    **kwargs : dict
        Additional keyword arguments to pass to the ARMA process generator. 
        See [ARMAProcess](https://www.statsmodels.org/stable/generated/statsmodels.tsa.arima_process.ArmaProcess.html) for more details.

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

    Raises
    -------
    ValueError
        If the maximum root is not larger than 1.1.

    See also
    --------
    [nonlinear_ar_ts](nonlinear_ar.md): Generate data from a nonlinear autoregressive process.

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

    References
    ----------
    ##1
    Christoph Bergmeir and José M Benítez. On the use of cross-validation for
    time series predictor evaluation. Information Sciences, 191:192–213, 2012.

    Examples
    --------
    >>> import numpy as np
    >>> import matplotlib.pyplot as plt
    >>> from timecave.data_generation.time_series_functions import arma_ts
    >>> ts = arma_ts(1000, 5, 2);
    >>> _ = plt.plot(np.arange(0, ts.shape[0]), ts);
    >>> plt.show();

    ![arma](../../../images/ARMA.png)

    Pure autoregressive processes can also be generated:

    >>> ts2 = arma_ts(1000, 5, 2, ma=False);
    >>> _ = plt.plot(np.arange(0, ts2.shape[0]), ts2);
    >>> plt.show();

    ![ar](../../../images/AR.png)

    And so can pure moving average processes:

    >>> ts3 = arma_ts(1000, 5, 2, ar=False);
    >>> _ = plt.plot(np.arange(0, ts3.shape[0]), ts3);
    >>> plt.show();

    ![ma](../../../images/MA.png)
    """
    _check_number_samples(number_samples)

    if ar == False and ma == False:
        raise ValueError("At least one of 'ar' or 'ma' must be set to True.")

    params_ar = _get_arma_parameters(lags, max_root)
    params_ma = _get_arma_parameters(lags, max_root)
    ar_coeff = np.r_[1, -params_ar]
    ma_coeff = np.r_[1, params_ma]

    if ar and not ma:
        ts = ArmaProcess(ma=ar_coeff).generate_sample(nsample=number_samples, **kwargs)
    elif not ar and ma:
        ts = ArmaProcess(ar=[1], ma=ma_coeff).generate_sample(
            nsample=number_samples, **kwargs
        )
    elif ar and ma:
        ts = ArmaProcess(ar=ar_coeff, ma=ma_coeff).generate_sample(
            nsample=number_samples, **kwargs
        )
    return ts