statsmodels.tsa.stattools.pccf#

statsmodels.tsa.stattools.pccf(x, y, *, nlags=None, method='ywm', alpha=None, result_object=None)[source]#

Partial Cross-Correlation Function

Computes the (1,2) element of the partial lag correlation matrix P(s) for the bivariate series (x, y) at lags 1, 2, …, nlags. At lag h, this is the correlation between x_t and y_{t+h} after removing the linear dependence on all intervening observations of both series.

Parameters:

x, yarray_like

The time series data to use in the calculation.

nlagsint, optional

Number of lags to return partial cross-correlations for. If not provided, uses min(10 * np.log10(nobs), nobs // 2 - 1).

methodstr, optional

Specifies which method for the calculations to use.

“ywm”, “ywmle” or “yw_mle” : Yule-Walker via the multivariate Levinson-Durbin recursion without sample-size adjustment in the autocovariance denominator. Default.
“yw”, “ywa”, “ywadjusted” or “yw_adjusted” : Yule-Walker via the multivariate Levinson-Durbin recursion with sample-size adjustment in the autocovariance denominator.
“ols” : OLS regression of x_t and y_{t+h} on all intervening observations.

alphafloat, optional

If a number is given, the confidence intervals for the given level are returned. For instance if alpha=.05, 95 % confidence intervals are returned where the standard deviation is 1/sqrt(n).

result_objectbool, optional

Flag controlling whether a PccfResult is returned. When alpha is not None a PccfResult is always returned; it holds the same two values as the legacy tuple it replaces. When alpha is None a bare array is returned unless result_object=True, which additionally yields a PccfResult with confint set to None.

Returns:

PccfResult or ndarray

When alpha is not None (or result_object=True), a result object with fields:

pccfndarray: The partial cross-correlation function for lags 1, 2, …, nlags.
confintndarray or None: Confidence intervals for the PCCF at lags 1, 2, …, nlags using the level given by alpha. Shape (nlags, 2). None when alpha is None.

See PccfResult.

When alpha is None a bare ndarray of partial cross-correlations is returned instead.

See also

statsmodels.tsa.stattools.ccf: Cross-correlation function.
statsmodels.tsa.stattools.acf: Autocorrelation function.
statsmodels.tsa.stattools.pacf: Partial autocorrelation function.
statsmodels.graphics.tsaplots.plot_pccf: Plot partial cross-correlations and confidence intervals.

Notes

The PCCF at lag h is the (1,2) element of the partial lag correlation matrix P(h) defined by Heyse and Wei (1985) [2].

pccf(x, y) is not symmetric: pccf(x, y) != pccf(y, x) in general. The (1,2) element measures the partial association from x to y, while pccf(y, x) measures the reverse direction.

The Yule-Walker methods use the multivariate Levinson-Durbin recursion on the bivariate autocovariance matrix sequence. For stationary series, this is asymptotically equivalent to OLS by the Frisch-Waugh-Lovell theorem [3], but is O(n * nlags) versus O(n * nlags^3) for OLS. The two methods may differ substantially on non-stationary (e.g., trending) data.

The “ols” method computes pccf(h) as the sample correlation between the backward residual (x_t regressed on the intervening observations) and the forward residual (y_{t+h} regressed on the same intervening observations). Both regressions include an intercept. For h=1, there are no intervening observations, so pccf(1) is the correlation between x[:-1] and y[1:].

For a bivariate VAR(p) process, P(h) = 0 for h > p, providing a useful identification tool.

If the series are perfectly collinear or constant, the sample autocovariance matrix is singular and the Yule-Walker methods return NaN for all lags.

The OLS method returns NaN for lags where either residual series has zero variance.

The confidence intervals use the asymptotic standard deviation 1/sqrt(n), following Wei (2006, Section 11.2) [1].

References

[1]

Wei, W. W. S. (2006). Time Series Analysis: Univariate and Multivariate Methods, 2nd edition. Pearson.

[2]

Heyse, J. F. and Wei, W. W. S. (1985). Inverse and partial lag autocorrelation for vector time series. American Statistical Association Proceedings of Business and Economic Statistics Section, pp. 233-237.

[3]

Frisch, R. and Waugh, F. V. (1933). Partial time regressions as compared with individual trends. Econometrica, 1(4), 387-401.

Examples

>>> import numpy as np
>>> from statsmodels.tsa.stattools import pccf
>>> rng = np.random.default_rng(12345)
>>> x = rng.standard_normal(100)
>>> y = 0.5 * x + rng.standard_normal(100)
>>> result = pccf(x, y, nlags=5)
>>> result_with_ci = pccf(x, y, nlags=5, alpha=0.05, result_object=True)
>>> result_with_ci.pccf.shape
(5,)
>>> result_with_ci.confint.shape
(5, 2)