source: trunk/SRC/ToBeReviewed/STATISTICS/a_timecorrelate.pro @ 241

;+
;
; @file_comments
; 
;
; @categories
; Statistics
;
; @param X {in}{required}{type=array}
; An Array which last dimension is the time dimension so
; size n.
;
; @param M
;
;
; @param NT
;
;
; @keyword ZERO2NAN
;
;
; @keyword DOUBLE
; If set to a non-zero value, computations are done in
; double precision arithmetic.
;
; @examples
;
;
; @history
;
;
; @version
; $Id$
;
;-
FUNCTION timeauto_cov, X, M, nT, Double = Double, zero2nan = zero2nan
;Sample autocovariance function
;
  compile_opt idl2, strictarrsubs
;
   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
;+
; @file_comments
; 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).
;
; @categories
; Statistics
;
; @param X {in}{required}{type=array}
; An Array which last dimension is the time dimension so
; size n.
;
; @param LAG {in}{required}{type=scalar or vector}
; 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 COVARIANCE
; If set to a non-zero value, the sample autocovariance
; is computed.
;
; @keyword DOUBLE
; If set to a non-zero value, computations are done in
; double precision arithmetic.
;
; @examples
;       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]
;
; @history
; 24/2/2000 Sebastien Masson (smasson\@lodyc.jussieu.fr)
;
; Based on the A_CORRELATE procedure of IDL
; INTRODUCTION TO STATISTICAL TIME SERIES
; Wayne A. Fuller
; ISBN 0-471-28715-6
;
; @version
; $Id$
;
;-

FUNCTION a_timecorrelate, X, Lag, COVARIANCE = Covariance, DOUBLE = Double
;
  compile_opt idl2, strictarrsubs
;

;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