source: trunk/SRC/Interpolation/file_interp.pro @ 367

;+
;
; @hidden
;
;-
FUNCTION call_interp2d, data, inlon, inlat, inmask, outlon, outlat $
                      , INIRR=inirr, METHOD=method, SMOOTH=smooth $
                      , WEIG=weig, ADDR=addr, MISSING_VALUE=missing_value, _EXTRA=ex
;
  compile_opt idl2, strictarrsubs
;
; for byte, short and long, convert to double before extrapolation and interpolation
  intype = size(data, /type)
  if intype LE 3 THEN data = double(temporary(data))
;
; take care of NaN values
  nanmsk = finite(data)
  IF total(nanmsk) NE n_elements(nanmsk) THEN BEGIN
    data[where(nanmsk EQ 0b)] = 1.e20 ; put large value to be sure they are removed during the interpolation
    mask = inmask * temporary(nanmsk)
  ENDIF ELSE mask = inmask
;
  tpmiss = size(missing_value, /type)
  IF tpmiss NE 0 AND tpmiss NE 7 THEN BEGIN
    CASE 1 OF
      missing_value GT 1.e6:mask = temporary(mask) * (data LT (missing_value-10.))
      missing_value LT -1.e6:mask = temporary(mask) * (data GT (missing_value+10.))
      abs(missing_value) LT 1.e-6:mask = temporary(mask) * (abs(data) GT 1.e-6)
      ELSE:mask = temporary(mask) * (data NE missing_value)
    ENDCASE
  ENDIF
; extrapolation
    IF keyword_set(smooth) THEN data = extrapsmooth(temporary(data), mask, /x_periodic, _extra = ex) $
    ELSE data = extrapolate(temporary(data), mask, /x_periodic, _extra = ex)
; interpolation
  IF NOT keyword_set(inirr) THEN BEGIN
    data = fromreg(method, temporary(data), inlon, inlat, outlon, outlat, WEIG = weig, ADDR = addr, _extra = ex)
  ENDIF ELSE BEGIN
    data = fromirr(method, temporary(data), inlon, inlat, -1, outlon, outlat, -1, WEIG = weig, ADDR = addr)
  ENDELSE

  if intype LE 3 THEN data = round(temporary(data))

  RETURN, data
END
;+
;
; @file_comments
; interpolate a NetCDF file from a grid to another (both regular or not)
;
; @categories
; Interpolation, NetCDF
;
; @param filein {in}{type=scalar string}
; input file name (must exist)
;
; @param fileout {in}{type=scalar string}
; output file name (will be overwritten if already exist)
;
; @param gridout {in}{type=scalar string}
; output grid file name (must exist and must contain the
; longitude and latitude axis as 1D or 2D arrays)
;
; @keyword GRIDIN {type=scalar string}{default=set to filein}
; define the input grid file name. It must exist and must contain the
; longitude and latitude axis as 1D or 2D arrays. Useful if
; filein file doesn't contain longitude and latitude axis
;
; @keyword MASKIN {type=scalar string}{default=set to gridin}
; define the input mask file name. It must exist. The mask will be
; determined through <pro>ncdf_getmask</pro> according to the keywords
; inmaskname, ininvmask, inuseasmask, inmissing_value, inaddscl_before
; (see below)
;
; @keyword MASKOUT {type=scalar string}{default=set to gridout}
; define the output mask file name. It must exist. The mask will be
; determined through <pro>ncdf_getmask</pro> according to the keywords
; outmaskname, outinvmask, outuseasmask, outmissing_value,
; outaddscl_before (see below).
;
; @keyword KEEP {type=string array}{default=all variables}
; array defining the name of the variables that must be kept in the
; output file
;
; @keyword REMOVE {type=string array}{default=empty}
; array defining the name of the variables that will be removed in the
; output file
;
; @keyword METHOD {type=scalar string}{default='bilinear'}
; interpolation method: can be only 'bilinear' (or 'imoms3' if the input grid
; is a "regular" grid). A "regular/rectangular grid" is defined as a
; grid for which each longitude lines have the same latitude and each
; latitude columns have the same longitude.
;
; @keyword SMOOTH {type=scalar 0 or 1}{default=0}
; activate to use <pro>extrapsmooth</pro> instead of
; <pro>extrapolate</pro> when extrapolating input data over masked
; points.
;
; @keyword SET_XDIMNAME {type=scalar string}{default=not used}
; used to defined the name of x dimension in filein input file when
; gridin keyword is used and when the x dimension name is not the same
; in filein and gridin files. By default, we assume both file have the
; same x dimension name.
;
; @keyword SET_YDIMNAME {type=scalar string}{default=not used}
; same as set_xdimname but for y dimension
;
; @keyword SET_XAXISNAME {type=scalar string}{default=not used}
; used to defined the name of the variable containing the x axis in
; filein input file when gridin keyword is used and when its variable
; containing the x axis name is not the same. By default, we assume
; both file have the same x axis name. Not that if filein includes x
; axis there is no point to use gridin
;
; @keyword SET_YAXISNAME {type=scalar string}{default=not used}
; same as set_xaxisname but for y dimension
;
; @keyword INMASKNAME {type=scalar string}{default=not used}
; A string giving the name of the variable in the file maskin that
; contains the land/sea mask
;
; @keyword OUTMASKNAME {type=scalar string}{default=not used}
; same as inmaskname but for output mask file maskout
;
; @keyword ININVMASK {default=0}{type=scalar: 0 or 1}
; Inverse the land/sea mask of the input mask file maskin (that should
; have 0/1 values for land/sea)
;
; @keyword OUTINVMASK {default=0}{type=scalar: 0 or 1}
; same as ininvmask but for output mask file maskout
;
; @keyword INUSEASMASK {type=scalar string}
; A string giving the name of the variable in the input mask file
; that will be used to build the input land/sea mask. In this case the
; mask is based on the first record (if record dimension
; exists). The input mask is build according to operator defined by INTESTOP
; keyword (default NE) and the testing values defined as 
;   1) the second word of TESTOP if existing
;   2) MISSING_VALUE keyword
;   3) attribute missing_value or _fillvalue of the variable USEASMASK
;   4) !Values.f_nan (can be used only with NE and EQ operators)
;
; @keyword OUTUSEASMASK {type=scalar string}
; same as inuseasmask but for output mask file maskout
;
; @keyword INMISSING_VALUE {type=scalar}
; To define (or redefine if the attribute is already existing) the
; missing values used with INUSEASMASK keyword to build the input mask.
; Note that this value is not used if INTESTOP keyword is given and
; contains 2 words.
; Note: do not mismatch with MISSING_VALUE used to detect missing
; values at reach record.   
;
; @keyword OUTMISSING_VALUE {type=scalar}
; same as inmissing_value but for output mask file maskout
;
; @keyword INTESTOP {default='NE'} {type=scalar string, for example 'GT 0.5'}
; a string describing the type of test that will be done to define the
; input mask. The test is performed on the variable specified by INUSEASMASK
; keyword.
; INTESTOP can contain 1 or 2 words. The first word is the operator
; definition: "EQ" "NE" "GE" "GT" "LE" "LT" (default is NE). The
; second word define the testing value. If INTESTOP contains only 1
; word, then the test value is denifed by
;   1) INMISSING_VALUE keyword
;   2) attribute missing_value or _fillvalue of the variable INUSEASMASK
;   3) !Values.f_nan (can be used only with NE and EQ operators)
;
; @keyword OUTTESTOP {default='NE'} {type=scalar string, for example 'GT 0.5'}
; same as INTESTOP but for output mask file maskout
;
; @keyword INADDSCL_BEFORE {default=0}{type=scalar: 0 or 1}
; put 1 to apply add_offset and scale factor on data before looking for
; missing values when using INUSEASMASK keyword
;
; @keyword OUTADDSCL_BEFORE {default=0}{type=scalar: 0 or 1}
; same as inaddscl_before but for output mask file maskout
;
; @keyword MISSING_VALUE {type=scalar}{default=defined by attribute missing_value or _fillvalue}
; (Re)define the missing value in input data (missing values are treated
; like masked values and will be filled with extrapolation before
; interpolation). 
; Note: do not mismatch with (IN/OUT)MISSING_VALUE which are missing value
; used (in association with (IN/OUT)USEASMASK) to built the mask (that
; does not change from one record to another).
; Note: this value will be apply to all interpolated variables
;
; @keyword ADDR {type=2d array or variable name}
; 1) at the first call of file_interp:
;   This keyword can be set to a named variable (undefined or equal to
;   0) into which the addresses used to perform the interpolation will
;   be copied when the current routine exits.
; 2) Next, once this keyword is set to a defined 2d array, it is used
;   to bypass the computation of the weights and addresses used to
;   perform the interpolation. In this case, interpolation is much
;   faster
;
; @keyword WEIG {type=2d array or variable name}
; (see ADDR)
;
; @keyword INXAXISNAME {default='x', 'longitude', 'nav_lon', 'lon', 'lon_rho' or 'NbLongitudes'}{type=scalar string}
; A string giving the name of the variable containing the x axis in
; the input grid file gridin
;
; @keyword INYAXISNAME {default='y', 'latitude', 'nav_lat','lat', 'lat_rho' or 'NbLatitudes'}{type=scalar string}
; same as inxaxisname but for the y axis in the input grid file gridin
;
; @keyword OUTXAXISNAME {default='x', 'longitude', 'nav_lon', 'lon', 'lon_rho' or 'NbLongitudes'}{type=scalar string}
; same as inxaxisname but for output grid file gridout
;
; @keyword OUTYAXISNAME {default='y', 'latitude', 'nav_lat','lat', 'lat_rho' or 'NbLatitudes'}{type=scalar string}
; same as inyaxisname but for output grid file gridout
;
; @keyword  _EXTRA
; to use <pro>extrapolate</pro>, <pro>extrapsmooth</pro> and <pro>fromreg</pro> keywords
;
; @uses
; <pro>extrapsmooth</pro>, <pro>extrapolate</pro>, <pro>fromreg</pro> and <pro>fromirr</pro>
;
; @restrictions
;
; - perform only horizontal interpolations on scalar fields
; - all masked and missing values are filled before interpolation
;   -> output data are not masked and have values everywhere.
; - attributes (like valid_min...) are not updated
; - see restrictions of <pro>fromreg</pro> and <pro>fromirr</pro>
; - output mask is not used but, if the input file contains the mask
;   in a variable (defined by inmaskname), this variable will contain
;   the output mask in the ouput file
;
; @examples
;
; IDL> file_interp, filein, fileout, gridout, inxaxisname = 'lo', inyaxisname = 'la', keep = ['lo', 'la', 'cond_sed']
;
; IDL> file_interp, in, out, gdout, inuseasmask = 'sst', inmissing_value = -1.00000e+30, missing_value = -1000.00
;
; @history
;  September 2007: Sebastien Masson (smasson\@locean-ipsl.upmc.fr)
;
; @version
; $Id$
;
;-
PRO file_interp, filein, fileout, gridout, GRIDIN=gridin, MASKIN=maskin, MASKOUT=maskout $
               , KEEP=keep, REMOVE=remove, METHOD=method, SMOOTH=smooth $
               , SET_XDIMNAME=set_xdimname, SET_YDIMNAME=set_ydimname $
               , SET_XAXISNAME=set_xaxisname, SET_YAXISNAME=set_yaxisname $
               , INMASKNAME=inmaskname, ININVMASK=ininvmask $
               , INUSEASMASK=inuseasmask, INMISSING_VALUE=inmissing_value $
               , INADDSCL_BEFORE=inaddscl_before, INTESTOP = intestop $
               , OUTMASKNAME=outmaskname, OUTINVMASK=outinvmask $
               , OUTUSEASMASK=outuseasmask, OUTMISSING_VALUE=outmissing_value $
               , OUTADDSCL_BEFORE=outaddscl_before, OUTTESTOP = outtestop $
               , MISSING_VALUE=MISSING_VALUE, WEIG=weig, ADDR=addr $
               , INXAXISNAME=inxaxisname, INYAXISNAME=inyaxisname $
               , OUTXAXISNAME=outxaxisname, OUTYAXISNAME=outyaxisname $
               , _EXTRA=ex
;
  compile_opt idl2, strictarrsubs
  revision = '$Id$'
;
  IF NOT keyword_set(method) THEN method = 'bilinear'
;
; input filenames checks...
;
  inid = ncdf_open(filein)
  ininq = ncdf_inquire(inid)

  outid = ncdf_create(fileout, /clobber)
  ncdf_control, outid, /nofill

  IF NOT keyword_set(gridin) THEN gridin = filein

  IF NOT keyword_set(maskin) THEN maskin = gridin
  IF NOT keyword_set(maskout) THEN maskout = gridout
;
; Copy global attributes
;
  FOR i = 0, ininq.ngatts-1 DO BEGIN
    name = ncdf_attname(inid, i, /global)
    dummy = ncdf_attcopy(inid, name, outid, /in_global, /out_global)
  ENDFOR
  ncdf_attput, outid, 'Created_by', revision, /GLOBAL
;
; x/y dim and x/yaxis informations
;
  ncdf_getaxis, gridin, indimidx, indimidy, inlon, inlat, xdimname = inxdimname, ydimname = inydimname $
                , xaxisname = inxaxisname, yaxisname = inyaxisname
  get_gridparams, inlon, inlat, jpiin, jpjin, 2
  IF keyword_set(set_xdimname) THEN inxdimname = set_xdimname
  IF keyword_set(set_ydimname) THEN inydimname = set_ydimname
  IF keyword_set(set_xaxisname) THEN inxaxisname = set_xaxisname
  IF keyword_set(set_yaxisname) THEN inyaxisname = set_yaxisname
;
  ncdf_getaxis, gridout, outdimidx, outdimidy, outlon, outlat, xaxisname = outxaxisname, yaxisname = outyaxisname
  get_gridparams, outlon, outlat, jpiout, jpjout, 2
;
; masks
;
  inmask = ncdf_getmask(maskin, MASKNAME = inmaskname, INVMASK = ininvmask, USEASMASK = inuseasmask $
                       , MISSING_VALUE = inmissing_value, ADDSCL_BEFORE = inaddscl_before, TESTOP = intestop)
  inmasksz = size(inmask, /dimensions)
  IF size(inmask, /n_dimensions) EQ 2 THEN inmasksz = [inmasksz, 0]
  IF n_elements(inmaskname) EQ 0 THEN inmaskname = 'not defined' ; default definition
  outmask = ncdf_getmask(maskout, MASKNAME = outmaskname, INVMASK = outinvmask, USEASMASK = outuseasmask $
                        , MISSING_VALUE = outmissing_value, ADDSCL_BEFORE = outaddscl_before, TESTOP = outtestop)
;
; irregular grids?
;
  CASE 0 OF
    array_equal(inlon[*, 0], inlon[*, jpjin-1]):inirr = 1b
    array_equal(inlat[0, *], inlat[jpiin-1, *]):inirr = 1b
    array_equal(inlon, inlon[*, 0]#replicate(1, jpjin)):inirr = 1b
    array_equal(inlat, replicate(1, jpiin)#(inlat[0, *])[*]):inirr = 1b
    ELSE:inirr = 0b
  ENDCASE
  CASE 0 OF
    array_equal(outlon[*, 0], outlon[*, jpjout-1]):outirr = 1b
    array_equal(outlat[0, *], outlat[jpiout-1, *]):outirr = 1b
    array_equal(outlon, outlon[*, 0]#replicate(1, jpjout)):outirr = 1b
    array_equal(outlat, replicate(1, jpiout)#(outlat[0, *])[*]):outirr = 1b
    ELSE:outirr = 0b
  ENDCASE

  IF inirr AND method NE 'bilinear' THEN stop
;
; Dimensions
;
  indimsz = lonarr(ininq.ndims)
  outdimsz = lonarr(ininq.ndims)
  outdimid = lonarr(ininq.ndims)
  FOR i = 0, ininq.ndims-1 DO BEGIN
    ncdf_diminq, inid, i, name, size
    indimsz[i] = size
    outdimsz[i] = size
    CASE 1 OF
      strlowcase(name) EQ strlowcase(inxdimname): BEGIN
        outdimid[i] = ncdf_dimdef(outid, name, jpiout)
        outdimsz[i] = jpiout
        indimx = i
        outdimx = outdimid[i]
      END
      strlowcase(name) EQ strlowcase(inydimname): BEGIN
        outdimid[i] = ncdf_dimdef(outid, name, jpjout)
        outdimsz[i] = jpjout
        indimy = i
        outdimy = outdimid[i]
      END
      i EQ ininq.recdim: outdimid[i] = ncdf_dimdef(outid, name, /UNLIMITED)
      ELSE: outdimid[i] = ncdf_dimdef(outid, name, size)
    ENDCASE
  ENDFOR
;
; Variables
;
  outvarid = lonarr(ininq.nvars)
  FOR i = 0, ininq.nvars-1 DO BEGIN
    varinq = ncdf_varinq(inid, i)
    okvar = 1
    IF keyword_set(keep) THEN okvar = total(strlowcase(keep) EQ strlowcase(varinq.name)) EQ 1
    IF keyword_set(remove) THEN okvar = total(strlowcase(remove) EQ strlowcase(varinq.name)) EQ 0
    IF okvar THEN BEGIN
      IF varinq.ndims EQ 0 THEN BEGIN ; scalar variable
        outvarid[i] = ncdf_vardef(outid, varinq.name $
                                  , BYTE = varinq.datatype EQ 'BYTE', CHAR = varinq.datatype EQ 'CHAR' $
                                  , SHORT = varinq.datatype EQ 'INT' OR varinq.datatype EQ 'SHORT' $
                                  , LONG = varinq.datatype EQ 'LONG' $
                                  , FLOAT = varinq.datatype EQ 'FLOAT', DOUBLE = varinq.datatype EQ 'DOUBLE')
      ENDIF ELSE BEGIN          ; array
        CASE 1 OF
          strlowcase(varinq.name) EQ strlowcase(inxaxisname):BEGIN ; xaxis
            IF outirr THEN dimvar = [outdimx, outdimy] ELSE dimvar = [outdimx]
          END
          strlowcase(varinq.name) EQ strlowcase(inyaxisname):BEGIN ; yaxis
            IF outirr THEN dimvar = [outdimx, outdimy] ELSE dimvar = [outdimy]
          END
          strlowcase(varinq.name) EQ strlowcase(inmaskname):BEGIN ; mask
            IF outmask[0] NE -1 THEN dimvar = outdimid[varinq.dim] ELSE dimvar = -1
          END
          (total(varinq.dim EQ indimx) + total(varinq.dim EQ indimx)) EQ 1: dimvar = -1 ; strange variable...
          ELSE: dimvar = outdimid[varinq.dim]
        ENDCASE
        IF dimvar[0] NE -1 THEN BEGIN
          outvarid[i] = ncdf_vardef(outid, varinq.name, dimvar $
                                    , BYTE = varinq.datatype EQ 'BYTE', CHAR = varinq.datatype EQ 'CHAR' $
                                    , SHORT = varinq.datatype EQ 'INT' OR varinq.datatype EQ 'SHORT' $
                                    , LONG = varinq.datatype EQ 'LONG' $
                                    , FLOAT = varinq.datatype EQ 'FLOAT', DOUBLE = varinq.datatype EQ 'DOUBLE')
        ENDIF ELSE outvarid[i] = - 1
      ENDELSE
; Variables attributes
      IF outvarid[i] NE - 1 THEN BEGIN
        FOR j = 0, varinq.natts-1 DO BEGIN
          name = ncdf_attname(inid, i, j)
          dummy = ncdf_attcopy(inid, i, name, outid, outvarid[i])
        ENDFOR
      ENDIF
    ENDIF ELSE outvarid[i] = -1
  ENDFOR
;
  ncdf_control, outid, /endef
;
  FOR i = 0, ininq.nvars-1 DO BEGIN
    IF outvarid[i] NE -1 THEN BEGIN
      varinq = ncdf_varinq(inid, i)
      IF varinq.ndims GE 2 THEN BEGIN
        interp = varinq.dim[0] EQ indimx AND varinq.dim[1] EQ indimy
      ENDIF ELSE interp = 0b
      CASE 1 OF
        strlowcase(varinq.name) EQ strlowcase(inxaxisname):BEGIN ; x axis
          IF outirr THEN ncdf_varput, outid, outvarid[i], outlon $
          ELSE ncdf_varput, outid, outvarid[i], outlon[*, 0]
        END
        strlowcase(varinq.name) EQ strlowcase(inyaxisname):BEGIN ; y axis
          IF outirr THEN ncdf_varput, outid, outvarid[i], outlat $
          ELSE ncdf_varput, outid, outvarid[i], reform(outlat[0, *])
        END
        strlowcase(varinq.name) EQ strlowcase(inmaskname):BEGIN ; mask
          ncdf_varput, outid, outvarid[i], outmask
        END
        ELSE:BEGIN
          IF n_elements(missing_value) NE 0 THEN var_missing_value = MISSING_VALUE $
          ELSE ncdf_getatt, inid, i, MISSING_VALUE = var_missing_value
          CASE varinq.ndims OF
            0:BEGIN             ; salar
              ncdf_varget, inid, i, data
              ncdf_varput, outid, outvarid[i], temporary(data)
            END
            1:BEGIN             ; 1D
              ncdf_varget, inid, i, data
              ncdf_varput, outid, outvarid[i], temporary(data)
            END
            2:BEGIN             ; 2D
              ncdf_varget, inid, i, data
              IF interp THEN data = call_interp2d(temporary(data), inlon, inlat, inmask[*, *, 0], outlon, outlat $
                                                  , INIRR = inirr, METHOD = method, SMOOTH = smooth $
                                                  , WEIG = weig, ADDR = addr, MISSING_VALUE = var_missing_value, _extra = ex)
              ncdf_varput, outid, outvarid[i], temporary(data)
            END
            3:BEGIN             ; 3D
              FOR k = 0, indimsz[varinq.dim[2]]-1 DO BEGIN
                incnt = [indimsz[varinq.dim[0: 1]], 1]
                outcnt = [outdimsz[varinq.dim[0: 1]], 1]
                off = [0, 0, k]
                ncdf_varget, inid, i, data, offset = off, count = incnt
                IF n_elements(inmasksz) GE 3 THEN BEGIN
                  IF inmasksz[2] EQ indimsz[varinq.dim[2]] AND varinq.dim[2] NE ininq.recdim THEN tmpmsk = inmask[*, *, k] $
                  ELSE tmpmsk = inmask[*, *, 0]
                ENDIF ELSE tmpmsk = inmask[*, *, 0]
                IF interp THEN data = call_interp2d(temporary(data), inlon, inlat, temporary(tmpmsk), outlon, outlat $
                                                    , INIRR = inirr, METHOD = method, SMOOTH = smooth $
                                                    , WEIG = weig, ADDR = addr, MISSING_VALUE = var_missing_value, _extra = ex)
                ncdf_varput, outid, outvarid[i], temporary(data), offset = off, count = outcnt
              ENDFOR
            END
            4:BEGIN             ; 4D
              FOR t = 0, indimsz[varinq.dim[3]]-1 DO BEGIN
                FOR k = 0, indimsz[varinq.dim[2]]-1 DO BEGIN
                  incnt = [indimsz[varinq.dim[0: 1]], 1, 1]
                  outcnt = [outdimsz[varinq.dim[0: 1]], 1, 1]
                  off = [0, 0, k, t]
                  ncdf_varget, inid, i, data, offset = off, count = incnt
                  IF n_elements(inmasksz) GE 3 THEN BEGIN
                    IF inmasksz[2] EQ indimsz[varinq.dim[2]] THEN tmpmsk = inmask[*, *, k] ELSE tmpmsk = inmask
                  ENDIF ELSE tmpmsk = inmask[*, *, 0]
                  IF interp THEN data = call_interp2d(temporary(data), inlon, inlat, temporary(tmpmsk), outlon, outlat $
                                                      , INIRR = inirr, METHOD = method, SMOOTH = smooth $
                                                      , WEIG = weig, ADDR = addr, MISSING_VALUE = var_missing_value, _extra = ex)
                  ncdf_varput, outid, outvarid[i], temporary(data), offset = off, count = outcnt
                ENDFOR
              ENDFOR
            END
          ENDCASE
        END
      ENDCASE
    ENDIF
  ENDFOR

  ncdf_close, inid
  ncdf_close, outid

  return
END