;+
;
; @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 rseries_getname and read_ncdf
;
; @returns
; Structure readable by litchamp or an array if NOSTRUCT is
; activated.
;
; @uses
; cm_4cal
; cm_4data
; jul2date
; date2jul
; report
; rseries_getname
; read_ncdf
;
; @restrictions
; see rseries_getname and read_ncdf
;
; @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