;----------------------------------------------------------------------------
; $Id: calcclim.pro,v 1.7 2003/04/04 03:59:17 wblin Exp wblin $
;+
; Name:
;   CALCCLIM
;
; Purpose:
;   Calculate monthly climatology given a continuous x,y,t hyperslab of 
;   data (i.e. timeseries of x-y slabs).
;
; Category:
;   CCM3 Tools, Statistics.
;
; Calling Sequence:
;   Result = CALCCLIM(in_date, in_data)
;
; File I/O:
;   None.
;
; Entry and Exit States:
;   N/A.
;
; Input Parameters:
;   in_date       Vector of integer values of the date at each time point
;                 element in format yyyymmdd (with leading zeros absent).
;                 Must be same size as the last dimension of in_data.
;                 Unchanged.  See keyword Ccm3_Moly_Means for a quirk of
;                 in_date.
;
;   in_data       Hyperslab (dimensioned x,y,time) of data.  Unchanged.
;
; Output Parameter:
;   out_clim      Array of climatology, dimensioned (x,y,12), where
;                 each month's climatology is specified by the last
;                 dimension (i.e. Mar climatology is out_clim[*,*,2]).
;                 Type is FLOAT.  If not enough points exist to calculate 
;                 climatology for that month, out_clim returns NaN in that 
;                 element.  Array is created.
;
; Keywords (optional unless otherwise noted):
;   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.
;                    
; Revision History:
; - 24 Aug 2001:  Orig. ver. Johnny Lin, CIRES/University of Colorado.
;   Email:  air_jlin@yahoo.com.   Passed reasonable tests.
;
; Notes:
; - Written for IDL 5.2.1.
; - No procedures called with _Extra keyword invoked.
; - No user-written procedures called.
; - No common blocks are used in this program.
;-
; Copyright (c) 2001 Johnny Lin.  For licensing and contact information
; see http://www.johnny-lin.com/lib.html.
;----------------------------------------------------------------------------

FUNCTION CALCCLIM, in_date, in_data  $
                 , CCM3_MOLY_MEANS = ccm3_moly_means  $
                 , _EXTRA          = extra



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

ON_ERROR, 0
FORWARD_FUNCTION MEAN

if (N_PARAMS() ne 2) then MESSAGE, 'error--bad number of params'

date = in_date               ;- protect input

sd_data = SIZE(in_data)      ;- read array dimensions
NX = sd_data[1]
NY = sd_data[2]
NT = sd_data[3]

if (N_ELEMENTS(date) ne NT) then MESSAGE, 'error--bad date dim'



; ------------------- Extract Year and Month Information ------------------

yr = date/10000                  ;- vectors of the years and months
mo = (date-(yr*10000))/100       ;  of each elem. in date



; ------------------- Adjust for CCM3 Monthly Mean Case -------------------
;
; mo_num    Vector of the month numbers given in vector date that 
;           correspond to the month number given by the element number+1
;           of the last dimension of clim.  Thus, the value of mo_num[1]
;           is the month number value in vector date that a climatology
;           calculated for Feb will use.

if (KEYWORD_SET(ccm3_moly_means) eq 1) then begin  ;- Case:  moly mean input

   PRINT, 'CALCCLIM:  Input are CCM3 monthly means'

   check_mo = mo - SHIFT(mo,1)                     ;  + check that the month
   check_mo = check_mo[1:*]                        ;    values correspond to
   tmp = WHERE(check_mo eq 0, count)               ;    monthly mean data
   if (count gt 0) then  $
      MESSAGE, 'error--data not monthly'
   mo_num = SHIFT( INDGEN(12)+1, -1 )              ;  + set mo_num

endif else begin                                   ;- Case:  other input

   mo_num = INDGEN(12)+1                           ;  + set mo_num

endelse



; --------------------- Calculate Monthly Climatology ---------------------

PRINT, 'CALCCLIM:  Calculating climatology'

clim = FLTARR(NX,NY,12)       ;- climatology array

for j=0L,NY-1L do begin       ;- cycle through all spatial points (begin)
    for i=0L,NX-1L do begin

        dat_t = in_data[i,j,*]     ;+ timeseries at single spatial pt.

        for imo=0L,N_ELEMENTS(mo_num)-1L do begin      ;+ cycle each mo.
            imo_pts = WHERE(mo eq mo_num[imo], count)  ;  * pts. of this mo.
            if (count gt 0) then begin
               clim[i,j,imo] = MEAN(dat_t[imo_pts])    ;  * mean of mos.
            endif else begin
               clim[i,j,imo] = !VALUES.F_NAN           ;  * NaN to mo. w/
            endelse                                    ;    no pts.
        endfor

    endfor
endfor                       ;- cycle through all spatial points (end)



; ------------------------ Prepare Output and Return ----------------------

out_clim = TEMPORARY(clim)
RETURN, out_clim



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

; ========== end file ==========