NCL Home > Documentation > Functions > ESMF, Regridding, Interpolation


Writes the description of a rectilinear grid to a SCRIP file.

Available in version 6.1.0 and later.


load "$NCARG_ROOT/lib/ncarg/nclscripts/esmf/ESMF_regridding.ncl"  ; This library is automatically loaded 
                                                                  ; from NCL V6.5.0 onward.
                                                                  ; No need for user to explicitly load.

	procedure rectilinear_to_SCRIP (
		SCRIP_filename [1] : string,   
		lat            [*] : numeric,  
		lon            [*] : numeric,  
		opt            [1] : logical   



Name of SCRIP NetCDF file to write.


The one-dimensional lat/lon coordinate arrays.


An optional variable to set certain attributes for this procedure. If set to False, none of the attributes will have an effect.

See below for a full list of attributes.


This procedure writes the description of a rectilinear grid, given the 1D coordinate lat/lon arrays, to a NetCDF SCRIP file.

rectilinear_to_SCRIP is part of a suite of regridding routines based on Earth System Modeling Framework (ESMF) software. The regridding can be done via a multi-step process that includes this procedure, or via an "all-in-one" function called ESMF_regrid.

Both methods have their advantages. The multi-step process involves:

  1. Creating the description NetCDF file for the source grid.
  2. Creating the description NetCDF file for the destination grid.
  3. Calculating and writing the weights to a NetCDF file.
  4. Applying the weights to regrid the data from the source grid to the destination grid.
  5. Copying attributes and coordinates to the newly regridded variable.

The ESMF_regrid function performs all of the above steps.

The attributes that can be attached to opt include:

  • GridMask (added in V6.3.0; old name is Mask2D)(no default) A mask array of the same size as the desired lat/lon grid, that indicates which areas to mask out (that is, which values are missing). Set the masked (missing) areas to 0, and all the rest to 1.

    If these masks are different across multiple levels or timesteps, then you will need to generate a separate weights file for each level or timestep where it changes. See the special note below.

  • GridCornerLat / GridCornerLon (calculated internally if not provided)

    These arrays indicate the corner (edge) points of your source grid. If you don't set these attributes, then they will be calculated for you using a generic algorithm.

    It is better to use your own calculated values, especially for unusual grids like the HOMME grid. The values must be provided as an N x 4 array, where N represents the dimensionality of the center lat/lon grid. For example, if the center lat/lon grid is dimensioned 256 x 220, then the corner arrays must be 256 x 220 x 4. Sometimes the corner grids are provided on the file along with the center grids, with names like "lat_vertices"/"lon_vertices" or "lat_bounds"/"lon_bounds".

  • NetCDFType (default = "netcdf3")

    You can set this option to "netcdf4" to force a NetCDF-4 file to be written for the weights file. This may be necessary, for example, if your rectilinear grid is large, and requires more than 2 GB of memory to store it in the NetCDF file.

    Available in version 6.2.1 and later.

  • Overwrite (default = False) If set to True, then if the description NetCDF file exists (SCRIP_filename), you will be prompted for whether to remove it.

  • ForceOverwrite (default = False) If set to True, then the description NetCDF file (SCRIP_filename) will be overwritten no matter what.

  • Title (no default) An optional title to include in the NetCDF file.

  • PrintTimings (default = False) Print the CPU time spent in this routine.

  • Debug (default = False) Turn on debug prints.
Special note about weights files and missing values:

You can use the same weights file to regrid across other levels and timesteps of the same variable, or across other variables, as long as 1) the lat/lon grid that you are regridding from and to are exactly the same, and, 2) if you use the special GridMask (old name "Mask2D") option, that your masks are exactly the same. The masks are arrays filled with 0's and 1's that indicate where your data values and/or lat/lon values are missing. Here's a description from Robert Oehmke of ESMF about this:

What the mask does is remove the entity (cell or point depending on the type of regridding) from consideration by the regridder. If it's a source cell then no destination entities are mapped to it. If it's a destination entity, then it's not interpolated to. There is a little more in-depth discussion in the ESMF reference manual.

Right now, masking needs to be done before weight calculation so the regridding knows what it should ignore, so if the mask changes then you need to regenerate weights. We actually have a feature request ticket for handling this type of missing value situation more fluidly. The plan is to have the interpolation automatically not use missing values when they are encountered in a data field. Which would allow the same weights to be used for all the levels.

One trick you can do right now with missing values and a weight file is to do two interpolations to tell you where the missing values will spread in the destination field. First interpolate a field containing all 0's except for where the missing values are set the missing value locations to 1, the result of this interpolation tells you which destination locations (the ones whose values >0.0) will be affected by the missing values, so you can ignore them after interpolating the data. (You could also do something like this in one step during the data interpolation if you have a restricted range for your data and you use a value way outside that range for your missing value.) This, of course, will give you a coarser result than using the masking, but will probably be more efficient than recalculating the weights each time.

See Also

ESMF_regrid, latlon_to_SCRIP, rectilinear_to_SCRIP, curvilinear_to_SCRIP, unstructured_to_ESMF, ESMF_regrid_gen_weights, ESMF_regrid_with_weights


There's a suite of examples available on our ESMF applications page, and a set of basic ESMF template scripts to help you get started.

This example assumes the description and weight files have not been generated. If they have, then see example 2 below.

Example 1

This example regrids data from a global rectilinear NCEP grid (64 x 181) to a 5x5 degree lat/lon grid (25 x 72), using the default "bilinear" interpolation method.

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/esmf/ESMF_regridding.ncl"

;---Input file
    srcFileName = ""

;---Output (and input) files
    srcGridName = ""
    dstGridName = ""
    wgtFileName = ""

; Convert original source NCEP grid to a SCRIP convention file.
    src_file = addfile(srcFileName,"r")
    temp     = src_file->TEMP(0,0,:,:)

    Opt                = True
    Opt@GridMask       = where(.not.ismissing(temp),1,0)    ; use "Mask2D" in NCL V6.2.1 and earlier
    Opt@ForceOverwrite = True
    Opt@PrintTimings   = True
    Opt@Title          = "NCEP Grid"


;---Clean up

; Convert destination grid to a SCRIP convention file.
    Opt                = True
    Opt@LLCorner       = (/ -60.d,   0.d/)
    Opt@URCorner       = (/  60.d, 355.d/)
    Opt@ForceOverwrite = True
    Opt@PrintTimings   = True


;---Clean up

; Generate the weights that take you from the NCEP grid to a
; 5x5 degree grid.
    Opt                      = True
    Opt@InterpMethod         = "bilinear"     ; default
    Opt@ForceOverwrite       = True
    Opt@PrintTimings         = True



; Apply the weights to a given variable on the NCEP file.
    Opt                = True
    Opt@PrintTimings   = True

;---In V6.1.0, coordinates and attributes are copied automatically
    temp_regrid = ESMF_regrid_with_weights(temp,wgtFileName,Opt)

; Plot the original and regridded data on a panel plot
    wks = gsn_open_wks("ps","ESMF")             ;
    gsn_define_colormap(wks,"gui_default")      ; choose colormap

    res                     = True              ; Plot mods desired.
    res@gsnDraw             = False             ; We will panel later.
    res@gsnFrame            = False

    res@gsnMaximize         = True              ; Maximize plot
    res@mpMaxLatF           = 60                 ; choose map range
    res@mpMinLatF           = -60 

    res@cnFillOn            = True              ; color plot desired
    res@cnLinesOn           = False             ; turn off contour lines
    res@cnLineLabelsOn      = False             ; turn off contour lines

    res@cnLevelSelectionMode =  "ManualLevels"   ; manual levels
    res@cnMinLevelValF       = 4                 ; min level
    res@cnMaxLevelValF       = 32                ; max level
    res@cnLevelSpacingF      =  2                ; interval

    res@lbLabelBarOn        = False              ; Labelbar will be in panel

;---Plot data on original grid
    res@gsnAddCyclic = False

    dims = tostring(dimsizes(temp))
    res@tiMainString = "NCEP monthly means temp: original data (" + \
                       str_join(dims," x ") + ")"
    plot_orig = gsn_csm_contour_map(wks,temp,res)     

;---Plot data interpolated onto 5x5 degree grid
    res@gsnAddCyclic = True

    dims = tostring(dimsizes(temp_regrid))
    res@tiMainString = "NCEP monthly means temp: regridded to 5x5 grid (" +\
                       str_join(dims," x ") + ")"
    plot_regrid = gsn_csm_contour_map(wks,temp_regrid,res)     

;---Resources for paneling
    pres                  = True
    pres@gsnMaximize      = True
    pres@gsnPanelLabelBar = True


Example 2

This example assumes the "" weight file from the previous example has already been generated. It uses this weight file to regrid a new variable from the same "" input file.

The same weights file can only be used if the source and destination lat/lon grids are the same, and if the mask for the new variable is the same as the mask for the "temp" variable.

. . .
    sfile = addfile("","r")
    P  = sfile->P(0,0,:,:)

    P_regrid = ESMF_regrid_with_weights(P,"",False)
. . .