pastas.stats.core.acf#

pastas.stats.core.acf(x: pandas.Series, lags: pastas.typing.ArrayLike = 365, bin_method: str = 'regular', bin_width: float = 0.5, max_gap: float = inf, min_obs: int = 50, full_output: bool = False, alpha: float = 0.05, fallback_bin_method: str = 'gaussian') → pandas.Series | pandas.DataFrame#

Calculate the autocorrelation function for irregular time steps.

Parameters:

  • x (pandas.Series) – Pandas Series containing the values to calculate the cross-correlation on. The index has to be a Pandas.DatetimeIndex.

  • lags (array_like, optional) – numpy array containing the lags in days for which the cross-correlation if calculated. Defaults is all lags from 1 to 365 days.

  • bin_method (str, optional) – method to determine the type of bin. Options are “regular” for regular data (default), and “gaussian” and “rectangle” for irregular data.

  • bin_width (float, optional) – number of days used as the width for the bin to calculate the correlation.

  • max_gap (float, optional) – Maximum time step gap in the data. All time steps above this gap value are not used for calculating the average time step. This can be helpful when there is a large gap in the data that influences the average time step.

  • min_obs (int, optional) – Minimum number of observations in a bin to determine the correlation.

  • full_output (bool, optional) – If True, also estimated uncertainties are returned. Default is False.

  • alpha (float, optional) – alpha level to compute the confidence interval (e.g., 1-alpha).

Returns:

result – If full_output=True, a DataFrame with columns “acf”, “conf”, and “n”, containing the autocorrelation function, confidence intervals (depends on alpha), and the number of samples n used to compute these, respectively. If full_output=False, only the ACF is returned.

Return type:

pandas.Series or pandas.DataFrame

Notes

The ACF method primarily tries to estimate the autocorrelation using common techniques if the time step between the measurements is regular. If the time step is irregular, the method falls back to an alternative method to calculate the autocorrelation function for irregular timesteps based on the slotting technique Rehfeld et al. [2011]. Different methods (kernels) to bin the data are available.

Estimating the autocorrelation for irregular time steps can be challenging. Depending on the data and the binning method and settings used, the correlation can be above 1 or below -1. If this occurs, a warning is raised.

Examples

For example, to estimate the autocorrelation for every second lag up to lags of one year:

>>> acf = ps.stats.acf(x, lags=np.arange(1.0, 366.0, 2.0))

See also

pastas.stats.ccf, statsmodels.api.tsa.acf