Computes the (Pearson) sample linear cross-correlations at lag 0 only.
function escorc ( x : numeric, y : numeric ) return_val : numeric
An array of any numeric type or size. The rightmost dimension is usually time.y
An array of any numeric type or size. The rightmost dimension is usually time. The size of the rightmost dimension must be the same as x.
Computes sample linear cross-correlations (Pearson) at lag 0 only. If a lagged correlations is required, use esccr. Missing values are allowed. This function can also be used to determine a "one-point-correlation-map" where one point is used to cross-correlate with all other points (see example 4 below).
cor = SUM [(X(t)-Xave)*(Y(t)-Yave)}]/(Xstd*Ystd)The dimension sizes(s) of c are a function of the dimension sizes of the x and y arrays. Type double is returned if x or y are double, and float otherwise. The following illustrates dimensioning:
x(N), y(N) c x(N), y(K,M,N) c(K,M) x(I,N), y(K,M,N) c(I,K,M) x(J,I,N), y(L,K,M,N) c(J,I,L,K,M)Special case when dimensions of all x and y are identical:
x(J,I,N), y(J,I,N) c(J,I)
The Pearson linear correlation coefficient (r) for n pairs of independent observations can be tested against the null hypothesis (ie.: no correlation) using the statistic
t = r*sqrt[ (n-2)/(1-r^2) ]This statistic has a Student-t distribution with n-2 degrees of freedom. See Example 1.
The confidence interval for r may also be estimated. However, since the sampling distribution of Pearson's r is not normally distributed, the Pearson r is converted to Fisher's z-statistic and the confidence interval is computed using Fisher's z. An inverse transform is used to return to r space (-1 to +1). This approach is also demonstrated in Example 1.
Specifically, the confidence interval for the Pearson correlation may be obtained via use of:
- the Fischer z-transformation: z = 0.5*log((1+r)/(1-r))
- the standard error of the z-transformation: z_se = sqrt(1.0/(N-3))
- The inverse of the Fischer transform: ri = (exp(2*z)-1)/(exp(2*z)+1))
Use escorc_n if the dimension to do the calculation on is not the rightmost dimension and reordering is not desired. This function can be significantly faster than escorc.
The following will calculate the cross-correlation for a two one-dimensional arrays x(N) and y(N).
r = escorc(x,y) ; ccr is a scalarThe following is an example that illustrates calculating the cross-correlation(s) and associated confidence limits.
;; http://www.unt.edu/UNT/departments/CC/Benchmarks/sprsum97/resamp.htm: x = (/ 0.20, 1.88, -0.76, 0.42, 0.32, -0.56, 1.55, -1.21, -0.66, -0.96, -0.21 /) y = (/ 0.18, 0.54, -0.49, 0.92, 0.22, 0.75, 0.66, -2.65, -0.51, 0.47, -0.09 /) r = escorc(x,y) ; Pearson correlation ; r=0.559956 ;---Compute correlation confidence interval n = dimsizes(x) ; n=11 df = n-2 ; Fischer z-transformation z = 0.5*log((1+r)/(1-r)) ; z-statistic se = 1.0/sqrt(n-3) ; standard error of z-statistic ; low and hi z values zlow = z - 1.96*se ; 95% (2.58 for 99%) zhi = z + 1.96*se ; inverse z-transform; return to r space (-1 to +1) rlow = (exp(2*zlow)-1)/(exp(2*zlow)+1) rhi = (exp(2*zhi )-1)/(exp(2*zhi )+1) print("r="+r) ; r=0.559956 print("z="+z+" se="+se) ; z=0.63277 se=0.353553 print("zlow="+zlow+" zhi="+zhi) ; zlow=-0.0601951 zhi=1.32573 print("rlow="+rlow+" rhi="+rhi) ; rlow=-0.0601225 rhi=0.868203Since the r confidence interval includes 0.0, the calculated r is not significant.
An alternative for testing significance is:
t = r*sqrt((n-2)/(1-r^2)) p = student_t(t, df) psig = 0.05 ; test significance level print("t="+t+" p="+p) ; t=2.02755 p=0.0732238 if (p.le.psig) then print("r="+r+" is significant at the 95% level")) else print("r="+r+" is NOT significant at the 95% level")) end if
The following will calculate the cross-correlation for one two-dimensional array y(lat,lon,time) and one one-dimensional array x(time). Both significance and confidence intervals may be estimated using the approach outlined in Example 1.
ccr = escorc(x,y) ; ccr(lat,lon)Example 3
Consider x(neval,time) and y(lat,lon,time)
ccr = escorc(x,y) ; ccr(neval,lat,lon)Example 4
Consider y(nl,ml,time) where nl and ml are specified by the user and y(lat,lon,time). The result is a "one-point correlation pattern". Basically, a specific point is correlated with all other points. Both significance and confidence intervals may be estimated using the approach outlined in Example 1.
nl = 32 ; for example ml = 64 ccr = escorc(y(nl,ml,:),y) ===> ccr(lat,lon)Example 5
Consider w(time,lat,lon) and q(time,lat,lon) where 'time', 'lat' and 'lon' are named dimensions: Compute the temporal correlation at each latitude and longitude. Dimension reordering must be used to make 'time' the rightmost dimension.
ccr = escorc(w(lat|:,lon|:,time|:),q(lat|:,lon|:,time|:)) ===> ccr(lat,lon)Note: with NCL V6.2.1 or later, you can use escorc_n to avoid having to reorder the array first:
ccr = escorc_n(w,q,0,0) ===> ccr(lat,lon)