source: trunk/SRC/ReadWrite/rseries_ncdf.pro @ 463

;+
;
; @file_comments
;
; @categories
;
; @param VAR_NAME {in}{required}{type=string}
; name of the variable to be read.
;
; @param date1 {in}{required}{type=scalar, long interger or double precision}
; date given in the yyyymmdd format. data will be read from date1
;
; @param date2 {in}{required}{type=scalar, long interger or double precision}
; date given in the yyyymmdd format. data will be read until date1
;
; @param prefix {in}{required}{type=string}
; a string defining the prefix used to identify the file.
;
; @param suffix {in}{required}{type=string}
; a string defining the suffix used to identify the file.
; note that *.nc is added to suffix is it is not finishing with ".nc'
;
; @keyword DATEFMT {default='i8_i8'}{type=scalar string}
; a string defining the date format used in the file name. the
; possible coices are:
;   - 'i8_i8': yyyymmdd_yyyymmdd (for ex. 20110401_20110431)
;   - 'i6_i6': yyyymm_yyyymm (for ex. 201104_201104). we assume date1(date2) = beginning(end) of the month
;   - 'i4_i4': yyyy_yyyy (for ex. 2011_2011). we assume date1(date2) = beginning(end) of the year
;   - 'i8': yyyymmdd (for ex. 20110401) we assume date2 = date1
;   - 'i6': yyyymm (for ex. 201104) we assume date1(date2) = beginning(end) of the month
;   - 'i4': yyyymm (for ex. 2011) we assume date1(date2) = beginning(end) of the year
;   - 'yi4mi2di2_yi4mi2di2': yxxxxmxxdxx_yxxxxmxxdxx (for ex. y2011m04d01_y2011m04d31)
;   - 'yi4mi2_yi4mi2': yxxxxmxx_yxxxxmxx (for ex. y2011m04_y2011m04) we assume date1(date2) = beginning(end) of the month
;   - 'yi4_yi4': yxxxx_yxxxx (for ex. y2011_y2011) we assume date1(date2) = beginning(end) of the year
;   - 'yi4mi2di2': yxxxxmxxdxx (for ex. y2011m04d01) we assume date2 = date1
;   - 'yi4mi2': yxxxxmxx (for ex. y2011m04) we assume date1(date2) = beginning(end) of the month
;   - 'yi4': yxxxx (for ex. y2011) we assume date1(date2) = beginning(end) of the year
;
; @keyword NOSTRUCT {default=0}{type=scalar: 0 or 1}
; We activate it if we do not want that read_ncdf send back a structure
; but only the array referring to the field.
;
; @keyword _EXTRA
; Used to pass keywords to <pro>rseries_getname</pro> and <pro>read_ncdf</pro>
;
; @returns
; Structure readable by <pro>litchamp</pro> or an array if NOSTRUCT is 
; activated.
;
; @uses
;   <pro>cm_4cal</pro>
;   <pro>cm_4data</pro>
;   <pro>jul2date</pro>
;   <pro>date2jul</pro>
;   <pro>report</pro>
;   <pro>rseries_getname</pro>
;   <pro>read_ncdf</pro>
;
; @restrictions
; see <pro>rseries_getname</pro> and <pro>read_ncdf</pro>
;
; @examples
;  IDL> a = rseries_ncdf('zos', 100101,121231,'tr33beta','1Y_grid_')
;  IDL> a = rseries_ncdf('zos', 100101,121231,'tr33beta','1Y_grid_',direc='xy',/nostruct)
;
; @history
; 2011-04: Creation. Sebastien Masson (smasson\@locean-ipsl.upmc.fr) 
;
; @version
; $Id$
;
;-
FUNCTION rseries_ncdf, var_name, date1, date2, prefix, suffix, NOSTRUCT = nostruct, DATEFMT = datefmt, FILESLIST = fileslist $
                       , WITHSSH = withssh, SSHPREFIX = sshprefix, SSHSUFFIX = sshsuffix, FIRSTONLY = firstonly, _extra = ex

  compile_opt idl2, strictarrsubs

@cm_4cal
@cm_4data
  
  IF n_params() NE 5 THEN return, report('rseries_ncdf needs 5 parameters')
  IF n_elements(sshprefix) EQ 0 THEN sshprefix = prefix
  IF n_elements(sshsuffix) EQ 0 THEN sshsuffix = suffix

; take care ofd the precision of the calendar parameters... 
  CASE size(date1, /type)  OF
    1:date1 = long(date1)
    2:date1 = long(date1)
    3:
    4:date1 = double(date1)
    5:
  ENDCASE
  CASE size(date2, /type)  OF
    1:date2 = long(date2)
    2:date2 = long(date2)
    3:
    4:date2 = double(date2)
    5:
  ENDCASE
  date2p1 = jul2date(date2jul(date2)+1)
  res = -1
  tseries = -1
  ndims = -1
  flist = ''

  date = date1
  WHILE date LE date2 DO BEGIN

    filename = rseries_getname(prefix, suffix, date, dd1, dd2, datefmt = datefmt)
    IF filename EQ '' THEN return, -1
    time = ncdf_gettime(filename)
    IF jpt EQ 1 AND time[0] LT 0 THEN return, -1
    jdate = date2jul(date) ; do it after ncdf_gettime to be sure to use the proper calendar...
    dummy = where(time GE jdate, cnt)
    IF cnt NE 0 THEN BEGIN
print, file_basename(filename)
      IF keyword_set(fileslist) THEN BEGIN 
        vlist = ncdf_listvars(filename)
        IF (where(vlist EQ var_name))[0] NE -1 THEN flist = [flist, filename] ELSE BEGIN 
          print, var_name + 'not found in the file ' + filename
          return, ''
        ENDELSE 
      ENDIF ELSE BEGIN 
        IF keyword_set(withssh) THEN BEGIN
          sshfilename = rseries_getname(sshprefix, sshsuffix, date, datefmt = datefmt)
          IF sshfilename EQ '' THEN return, -1
print, file_basename(sshfilename)
          IF keyword_set(firstonly) THEN ssh = read_ncdf(withssh, filename = sshfilename, /nostruct) $
          ELSE ssh = read_ncdf(withssh, date, date2, filename = sshfilename, /nostruct)
        ENDIF
        IF keyword_set(firstonly) THEN tmp = read_ncdf(var_name, filename = filename, /nostruct, ssh = ssh, _extra = ex) $
        ELSE tmp = read_ncdf(var_name, date, date2, filename = filename, /nostruct, ssh = ssh, _extra = ex)
        IF n_elements(tmp) EQ 1 AND tmp[0] EQ -1 THEN return, -1
; store the shape of the data    
        sz = size(tmp)
        IF sz[0] GT ndims THEN BEGIN
          ndims = sz[0]
          IF ndims EQ 0 THEN shape = [-1] ELSE BEGIN 
            IF jpt EQ 1 THEN shape = [sz[1:ndims], 1] ELSE shape = sz[1:ndims]
          ENDELSE 
        ENDIF
; concatenate the arrays (as vectors)  
        res = [temporary(res), (temporary(tmp))[*]]
        tseries = [temporary(tseries), time]
      ENDELSE 
    ENDIF
      
    date = jul2date(date2jul(dd2)+1)

  ENDWHILE
;
  IF keyword_set(fileslist) THEN BEGIN 
    IF n_elements(flist) EQ 1 THEN return, '' ELSE return, flist[1:*]
  ENDIF
  IF n_elements(res) EQ 1 THEN return, -1
;
  res = (temporary(res))[1:*]
  time = tseries[1:*]
  jpt = n_elements(time)
  IF jpt EQ 1 THEN BEGIN 
    IF n_elements(shape) NE 1 THEN shape = shape[0:n_elements(shape)-2]
  ENDIF ELSE shape[n_elements(shape)-1] = jpt
  IF shape[0] EQ -1 THEN res = res[0] ELSE res = reform(res, shape, /overwrite)
;
  IF keyword_set(nostruct) THEN return, res
  IF keyword_set(key_forgetold) THEN BEGIN
    return, {arr:temporary(res), grid:vargrid, unit:varunit, experiment:varexp, name:varname}
  ENDIF ELSE BEGIN
    return, {tab:temporary(res), grille:vargrid, unite:varunit, experience:varexp, nom:varname}
  ENDELSE

  RETURN, res
END