NCL Home > Documentation > Functions > General applied math

esacr

Computes sample auto-correlations.

Prototype

	function esacr (
		x         : numeric,  
		mxlag [1] : integer   
	)

	return_val  :  numeric

Arguments

An array of any numeric type or size. The rightmost dimension is usually time.

mxlag

A scalar integer. It is recommended that 0 <= mxlag <= N/4. This is because the correlation algorithm(s) use N rather than (N-k) values in the denominator (Chatfield Chapter 4).

Return value

An array of the same size as x except that the rightmost dimension has been replaced by mxlag+1. Double values are returned if x is double, and float otherwise.

Description

Computes sample auto-correlations using the equations found in Chatfield [The Analysis of Time Series, 1982, Chapman and Hall].

If it is desired to do this calculation across a dimension other than the rightmost dimension, then see esacr_n. This function will require less memory and potentially be faster, because it doesn't require you to reorder the data first.

Missing values are allowed.

Algorithm: Here, q(t) and q(t+k) refer to the rightmost dimension. k runs from 0 to mxlag.

  c(k) = SUM [(q(t)-qAve)*(q(t+k)-qAve)}]/qVar

The dimension shape of c is a function of the dimension shape of the x arrays. The following illustrates dimensioning:


        x(N)          c(mxlag)
        x(M,N),       c(M,mxlag)
        x(K,M,N)      c(K,M,mxlag)
        x(L,K,M,N)    c(L,K,M,mxlag)

When calculating lag auto-correlations, Chatfield (pp. 60-62, p. 173) recommends using the entire series (i.e. all non-missing values) to estimate mean and standard deviation rather than (N-k) values. The reason is better mean-square error properties.

There are trade-offs to be made. For example, it is possible that correlation coefficients calculated using qAve and qStd based on the entire series can lead to correlation coefficients that are > 1. or < -1. This is because the subset (N-k) points might be a series with slightly different statistical characteristics.

Examples

Example 1

The following will calculate the auto-correlation for a one dimensional array x(N) at 11 lags (0->10). The result is a one-dimensional array of length 11.

    acr = esacr(x,10)   ; acr(0:10)

Example 2

The following will calculate the auto-correlation for a three-dimensional array x(nlat,nlon,ntim) at mxlag + 1 lags (0->mxlag).

    mxlag = 10
    acr   = esacr(x,mxlag) ; acr(nlat,nlon,mxlag+1)

Example 3

Similar to example 2, but assume that time is the rightmost dimension. In this case, assuming x has named dimensions, we need to reorder the array first:

    mxlag = 10
    acr   = esacr(x(lat|:, lon|:, time|:),mxlag) ; acr(nlat,nlon,mxlag+1)

In NCL V6.5.0 and later, you can use esacr_n to avoid having to reorder the array: