;----------------------------------------------------------------------------
; $Id: climvar_data.pro,v 1.5 2003/04/04 03:59:36 wblin Exp wblin $
;+
; NAME:
;   CLIMVAR_DATA
;
; PURPOSE:
;   Using CCM3 output, for each point in X-Y space, compute the variance 
;   of the time series of the grid, using spline fit climatology as the 
;   "mean" of the time series.
;
; CATEGORY:
;   CCM3 Tools, Statistics.
;
; CALLING SEQUENCE:
;   Result = CLIMVAR_DATA(in_time, in_date, in_data)
;
; INPUTS:
;   in_time:      Vector of time at each timestep.  Must be same size as
;                 the last dimension of in_data, monotonically increasing,
;                 and sampled at equal intervals.  Assumed to be in days.
;
;   in_date:      Vector of integer values of the date at each in_time
;                 element in format yyyymmdd (with leading zeros absent).
;                 Must be same size as the last dimension of in_data and
;                 monotonically increasing in time.
;
;   in_data:      Hyperslab array of data (usually dimensioned [lon, lat,
;                 time]. As code is dimensioned [NX,NY,NT].  Returned 
;                 unchanged.
;   
; KEYWORD PARAMETERS:
;   BASE_DATE:    The date (in same format as in_date) that in_time=0
;                 occurs at.  Integer.
;
;   BASE_SEC:     The number of seconds on the date specified by Base_Date
;                 that in_time=0 occurs at.  Floating.
;
;   CCM3_MOLY_MEANS:  If keyword set true, input data in_data consists of
;                     monthly means generated by CCM3.  The unique quirk
;                     of this data is that in_date is written the day after
;                     the month the mean applies to (i.e. a Sep 00 mean has
;                     date 1001), which is compensated for by this function.
;
; OUTPUTS:
;   out_var:  Variance of dataset at each spatial point [NX,NY].  Double 
;             floating.  Created.
;
; FILE DEVICE I/O:
;   None.
;
; COMMON BLOCKS:
;   None.
;
; EXAMPLE:
;   Date and time are follow the format from a 1000 day CCM3 run with
;   daily output interval, starting at a base date of 1 Sep 0000 (and
;   a 365 day year):
;       date = [901, 902, 903, ... , 30525, 30526, 30527, 30528]
;       time = FINDGEN(1000)
;   Use random values as data:
;       seed = 43
;       data = RANDOMN(seed, 5,4,1000)
;   Calculate:
;       Result = CLIMVAR_DATA(time, date, data)
;       PRINT, Result, Format='(5f13.9)'
;   IDL prints:
;       0.004832354  0.014783781  0.015257162  0.011002604  0.008352358
;       0.009616258  0.008112190  0.005974326  0.004747618  0.014388766
;       0.013178529  0.006666478  0.014563084  0.013048176  0.016142340
;       0.010715461  0.005044437  0.007670232  0.008139987  0.005280071
;
; MODIFICATION HISTORY:
; - 4 Sep 2001:  Orig. ver. Johnny Lin, CIRES/University of Colorado.
;   Email:  air_jlin@yahoo.com.  Partly based on climvar_data.pro,v 1.1 
;   2000/01/19 01:47:31 in ~/qtcm/tools-v2.1/idl at the UCLA Suns.  Passed
;   passably reasonable tests.
;
; NOTES:
; - Written for IDL 5.3.
; - Variance formula from IDL MOMENT procedure help screen.
; - All keyword parameters are optional unless otherwise stated.
; - No procedures called with _Extra keyword invoked.
; - User-written procedures called:  CALCANOM.
;-
; Copyright (c) 2001 Johnny Lin.  For licensing and contact information
; see http://www.johnny-lin.com/lib.html.
;----------------------------------------------------------------------------

FUNCTION CLIMVAR_DATA, in_time, in_date, in_data  $
                     , BASE_DATE       = in_base_date  $
                     , BASE_SEC        = in_base_sec  $
                     , CCM3_MOLY_MEANS = ccm3_moly_means  $
                     , _EXTRA = extra



; -------------------- Error Check and Parameter Setting --------------------

ON_ERROR, 0

time = in_time         ;- protect input parameters (we protect in_data 
date = in_date         ;  even though it's memory consuming since it will 
data = in_data         ;  be changed in CALCANOM)

sd_data = SIZE(data)                          ;- set dimensions and derived 
if (sd_data[0] ne 3L) then  $                 ;  constants
   MESSAGE, 'error--bad dimensions'
NX    = sd_data[1]
NY    = sd_data[2]
NT    = sd_data[3]
DNT_1 = DOUBLE(NT-1L)

if (N_ELEMENTS(in_base_date) eq 1) then  $    ;- set base date and sec
   base_date = in_base_date             
if (N_ELEMENTS(in_base_sec) eq 1) then  $
   base_sec  = FLOAT(in_base_sec)



; -------------------------- Calculate Anomalies ----------------------------

CALCANOM, time, date, data  $                ;- compute anomal. as deviation
        , BASE_DATE       = base_date  $     ;  from spline fit climatol.
        , BASE_SEC        = base_sec  $
        , CCM3_MOLY_MEANS = ccm3_moly_means



; --------------------------- Calculate Variance ----------------------------

PRINT, 'CLIMVAR_DATA:  Calc. variance with spline fit climatol. as mean'

data = TRANSPOSE(TEMPORARY(data), [2,0,1])  ;- transpose for better memory
var  = DBLARR(NX,NY)                        ;  mngmnt. & est. working array

for j=0L,NY-1L do begin
  for i=0L,NX-1L do begin
     temp     = REFORM(data[*,i,j])
     temp     = TEMPORARY(temp)^2
     var[i,j] = TOTAL(temp)/DNT_1
  endfor
endfor

data = 0      ;- deallocate data



; ----------------------------- Prepare Output ------------------------------

out_var = TEMPORARY(var)

RETURN, out_var



END     ;=== end of function ===
 
 
; ========== end file ==========