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

;+
;
; @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 NAN
;
; @keyword DOUBLE
; If set to a non-zero value, computations are done in
; double precision arithmetic.
;
; @hidden
;
; @version
; $Id$
;
;-
FUNCTION timeauto_cov, x, m, nt, DOUBLE=double, ZERO2NAN=zero2nan, NAN =  nan
;Sample autocovariance function
;
  compile_opt idl2, strictarrsubs
;
  IF NAN AND M GE 1 THEN $
   STOP, 'Warning : lagged autocorrelation is not possible at the moment for time-series with NaN !!!'

  TimeDim = size(X, /n_dimensions)
  Xmean = NAN ? TOTAL(X, TimeDim, Double = Double,  NAN =  nan) / TOTAL(FINITE(X), TimeDim) : $
   TOTAL(X, TimeDim, Double = Double) / nT                                                                                
  one = double ? 1.0d : 1.0
  Xmean = Xmean[*]#replicate(one, nT - M)

; Time-series with NaN : only for Lag = 0
  case TimeDim of
     1:res = TOTAL((X[0:nT - M - 1L] - Xmean) * (X[M:nT - 1L] - Xmean), $
                   TimeDim, Double = Double, NAN =  nan)
     2:res = TOTAL((X[*, 0:nT - M - 1L] - Xmean) * $
                   (X[*, M:nT - 1L] - Xmean[*]) $
                   , TimeDim, Double = Double, NAN =  nan)
     3:res = TOTAL((X[*, *, 0:nT - M - 1L] - Xmean[*, *]) * $
                   (X[*, *, M:nT - 1L] - Xmean) $
                   , TimeDim, Double = Double, NAN =  nan)
     4:res = TOTAL((X[*, *, *, 0:nT - M - 1L] - Xmean) * $
                   (X[*, *, *, M:nT - 1L] - Xmean) $
                   , TimeDim, Double = Double,  NAN =  nan)
  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 <proidl>A_CORRELATE</proidl> 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 NVAL
; A named variable that, on exit, contains the number of valid
; observations (not NAN)
;
; @keyword DOUBLE
; If set to a non-zero value, computations are done in
; double precision arithmetic.
;
; @examples
; Define an n-element sample population.
; IDL> 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
; IDL> lag = [-3, 0, 1, 3, 4, 8]
; IDL> 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, NVAL =  nval
;
  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]

; Keyword NAN activated if needed for TimeAuto_Cov function
; Keyword NVAL not compulsory.

   NAN = ( (WHERE(FINITE(X) EQ 0 ))[0] NE -1 ) ? 1 : 0
;We can retrieve the matrix of real lenghts of time-series   
   nTreal = ( (WHERE(FINITE(X) EQ 0 ))[0] NE -1 ) ?  TOTAL(FINITE(X),  XNDim) : nT 

   IF ARG_PRESENT(NVAL) THEN nval = nTreal

;Check length.
   IF (WHERE(nTreal LE 1))[0] NE -1 THEN $
    MESSAGE,  "Matrix of length of time-series 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.
   type = SIZE(X, /TYPE)
   useDouble = (N_ELEMENTS(Double) eq 1) ? KEYWORD_SET(Double) : (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.

; Type of outputs according to the type of data input

   case XNDim of
      1: Auto = useDouble ? DBLARR(nLag) : FLTARR(nLag)
      2: Auto = useDouble ? DBLARR(XDim[0], nLag) : FLTARR(XDim[0], nLag)
      3: Auto = useDouble ? DBLARR(XDim[0], XDim[1], nLag) : FLTARR(XDim[0], XDim[1], nLag)
      4: Auto = useDouble ? DBLARR(XDim[0], XDim[1], XDim[2], nLag) : FLTARR(XDim[0], XDim[1], XDim[2], nLag)
   endcase

; Compute lagged autocorrelation or autocovariance (no NaN)
   FOR k = 0, nLag-1 DO BEGIN
      case XNDim of
         1: BEGIN
            Auto[k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = useDouble, NAN = nan) / $
             ( KEYWORD_SET(Covariance) ?  nTreal : TimeAuto_Cov(X, 0L, nT, Double = useDouble,  /zero2nan, NAN = nan) )
         END
         2: BEGIN
            Auto[*, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = useDouble, NAN = nan) / $
             ( KEYWORD_SET(Covariance) ?  nTreal : TimeAuto_Cov(X, 0L, nT, Double = useDouble, /zero2nan, NAN = nan) )   
         END
         3: BEGIN
            Auto[*, *, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = useDouble, NAN = nan) / $
             ( KEYWORD_SET(Covariance) ?  nTreal : TimeAuto_Cov(X, 0L, nT, Double = useDouble, /zero2nan, NAN = nan) )
         END
         4: BEGIN
            Auto[*, *, *, k] = TimeAuto_Cov(X, ABS(Lag[k]), nT, Double = useDouble, NAN = nan) / $
             ( KEYWORD_SET(Covariance) ?  nTreal : TimeAuto_Cov(X, 0L, nT, Double = useDouble, /zero2nan, NAN = nan) )
         END
      ENDCASE
   ENDFOR

   return, useDouble ? Auto : FLOAT(Auto)

END