source: trunk/STATISTICS/a_timecorrelate.pro @ 2

;+
; NAME:
;       A_TIMECORRELATE
;
; PURPOSE:
;       Same function as A_CORRELATE but accept array (until 4
;       dimension) for input and do the autocorrelation or the
;       autocovariance along the time dimension which must be the last
;       one of the input array.
;
;       This function computes the autocorrelation Px(L) or autocovariance
;       Rx(L) of a sample population X as a function of the lag (L).
;
; CATEGORY:
;       Statistics.
;
; CALLING SEQUENCE:
;       Result = a_timecorrelate(X, Lag)
;
; INPUTS:
;       X:    an Array which last dimension is the time dimension os
;       size n.
;
;     LAG:    A scalar or n-element vector, in the interval [-(n-2), (n-2)],
;             of type integer that specifies the absolute distance(s) between 
;             indexed elements of X.
;
; KEYWORD PARAMETERS:
;       COVARIANCE:    If set to a non-zero value, the sample autocovariance
;                      is computed.
;
;       DOUBLE:        If set to a non-zero value, computations are done in
;                      double precision arithmetic.
;
; EXAMPLE
;       Define an n-element sample population.
;         x = [3.73, 3.67, 3.77, 3.83, 4.67, 5.87, 6.70, 6.97, 6.40, 5.57]
;
;       Compute the autocorrelation of X for LAG = -3, 0, 1, 3, 4, 8
;         lag = [-3, 0, 1, 3, 4, 8]
;         result = a_correlate(x, lag)
;
;       The result should be:
;         [0.0146185, 1.00000, 0.810879, 0.0146185, -0.325279, -0.151684]
;
; PROCEDURE:
;
;
;                         n-L-1 
;                         sigma  (X[k]-Xmean)(X[k+L]-Xmean)
;                          k=0
;   correlation(X,L)=----------------------------------------
;                            n-1                   
;                           sigma  (X[k]-Xmean)^2
;                            k=0                   
;
;
;
;                        n-L-1 
;                        sigma  (X[k]-Xmean)(X[k+L]-Xmean)
;                         k=0
;   covariance(X,L)=-------------------------------------------
;                                     n
;
;   Where Xmean is the Time mean of the sample population
;   x=(x[t=0],x[t=1],...,x[t=n-1])
;
;
; REFERENCE:
;       INTRODUCTION TO STATISTICAL TIME SERIES
;       Wayne A. Fuller
;       ISBN 0-471-28715-6
;
; MODIFICATION HISTORY:
;       24/2/2000 Sebastien Masson (smasson@lodyc.jussieu.fr)
;       Based on the A_CORRELATE procedure of IDL
;-

FUNCTION TimeAuto_Cov, X, M, nT, Double = Double, zero2nan = zero2nan
;Sample autocovariance function
   TimeDim = size(X, /n_dimensions)
   Xmean = TOTAL(X, TimeDim, Double = Double) / nT
   if double then one = 1.0d ELSE one = 1.0
   Xmean = Xmean[*]#replicate(one, nT - M)
;
;
   case TimeDim of
      1:res = TOTAL((X[0:nT - M - 1L] - Xmean) * (X[M:nT - 1L] - Xmean), $
                    TimeDim, Double = Double)
      2:res = TOTAL((X[*, 0:nT - M - 1L] - Xmean) * $
                    (X[*, M:nT - 1L] - Xmean) $
                    , TimeDim, Double = Double)
      3:res = TOTAL((X[*, *, 0:nT - M - 1L] - Xmean) * $
                    (X[*, *, M:nT - 1L] - Xmean) $
                    , TimeDim, Double = Double)
      4:res = TOTAL((X[*, *, *, 0:nT - M - 1L] - Xmean) * $
                    (X[*, *, *, M:nT - 1L] - Xmean) $
                    , TimeDim, Double = Double)
   ENDCASE
   if keyword_set(zero2nan) then begin
      zero = where(res EQ 0)
      if zero[0] NE -1 then res[zero] = !values.f_nan
   endif
   RETURN, res

END

FUNCTION A_TimeCorrelate, X, Lag, COVARIANCE = Covariance, DOUBLE = Double

;Compute the sample-autocorrelation or autocovariance of (Xt, Xt+l)
;as a function of the lag (l).

   ON_ERROR, 2

   XDim = SIZE(X, /dimensions)
   XNDim = SIZE(X, /n_dimensions)
   nT = XDim[XNDim-1]
                                ;Check length.
   if nT lt 2 then $
    MESSAGE, "Time axis of X array must contain 2 or more elements."
   
;If the DOUBLE keyword is not set then the internal precision and
;result are identical to the type of input.
   if N_ELEMENTS(Double) eq 0 then $
    Double = (SIZE(X, /type) eq 5)

   
   if n_elements(lag) EQ 0 then lag = 0
   nLag = N_ELEMENTS(Lag)

   if nLag eq 1 then Lag = [Lag] ;Create a 1-element vector.

   case XNDim of
      1:if Double eq 0 then Auto = FLTARR(nLag) else Auto = DBLARR(nLag)
      2:if Double eq 0 then Auto = FLTARR(XDim[0], nLag) else Auto = DBLARR(XDim[0], nLag)
      3:if Double eq 0 then Auto = FLTARR(XDim[0], XDim[1], nLag) $
      else Auto = DBLARR(XDim[0], XDim[1], nLag)
      4:if Double eq 0 then Auto = FLTARR(XDim[0], XDim[1], XDim[2], nLag) $
      else Auto = DBLARR(XDim[0], XDim[1], XDim[2], nLag)
   endcase

   if KEYWORD_SET(Covariance) eq 0 then begin ;Compute Autocorrelation.
      for k = 0, nLag-1 do $
       case XNDim of
         1:Auto[k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = Double) / $
          TimeAuto_Cov(X, 0L, nT, Double = Double, /zero2nan)
         2:Auto[*, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = Double) / $
          TimeAuto_Cov(X, 0L, nT, Double = Double, /zero2nan)
         3:Auto[*, *, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = Double) / $
          TimeAuto_Cov(X, 0L, nT, Double = Double, /zero2nan)
         4:Auto[*, *, *, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = Double) / $
          TimeAuto_Cov(X, 0L, nT, Double = Double, /zero2nan)
      endcase
   endif else begin             ;Compute Autocovariance.
      for k = 0, nLag-1 do $ 
       case XNDim of
         1:Auto[k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = Double) / nT
         2:Auto[*, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = Double) / nT
         3:Auto[*, *, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = Double) / nT
         4:Auto[*, *, *, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = Double) / nT
      endcase
   endelse

   if Double eq 0 then RETURN, FLOAT(Auto) else $
    RETURN, Auto

END