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

curvilinear_to_SCRIP

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

Available in version 6.1.0 and later.

Prototype

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 curvilinear_to_SCRIP (
		SCRIP_filename [1] : string,   
		lat         [*][*] : numeric,  
		lon         [*][*] : numeric,  
		opt            [1] : logical   
	)

Arguments

SCRIP_filename

Name of SCRIP NetCDF file to write.

lat
lon

The two-dimensional lat/lon arrays representing the curvilinear grid. The ordering of these arrays must be nlat x nlon.

opt

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.

Description

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

curvilinear_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 (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")

    Set this option to "netcdf4" to force a NetCDF-4 file to be written for the weights file. This will be necessary if your curvilinear grid requires more than 2 GB of memory to store it in the NetCDF file.

    Available in version 6.2.1 and later.

  • LargeFile (default = True) This causes the NetCDF file to be written with "large file support" turned on. This creates a "64-bit offset" NetCDF file under the hood and allows you to write variables > 2 GB but less than 4 GB.

    If you are working with large data files that require more than 4 GB, you may need to set one or more of the NetCDFType options to "netcdf4". This will force a NetCDF4 file to be written under the hood and will allow you to write variables that are > 4 GB.

  • 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

Examples

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.

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.

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

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"

begin
;---Input file
    srcFileName = "sst.nc"

;---Output (and input) files
    srcGridName = "src_SCRIP.nc"
    dstGridName = "dst_SCRIP.nc"
    wgtFileName = "NCEP_2_Rect.nc"

;----------------------------------------------------------------------
; 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"

    rectilinear_to_SCRIP(srcGridName,temp&LAT,temp&LON,Opt)

;---Clean up
    delete(Opt)

;----------------------------------------------------------------------
; 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

    latlon_to_SCRIP(dstGridName,"5x5",Opt)

;---Clean up
    delete(Opt)

;----------------------------------------------------------------------
; 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

    ESMF_regrid_gen_weights(srcGridName,dstGridName,wgtFileName,Opt)

    delete(Opt)

;----------------------------------------------------------------------
; 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)
    printVarSummary(temp_regrid)

;----------------------------------------------------------------------
; Plot the original and regridded data on a panel plot
;----------------------------------------------------------------------
    wks = gsn_open_wks("ps","ESMF")             ; ESMF.ps
    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

    gsn_panel(wks,(/plot_orig,plot_regrid/),(/2,1/),pres)
end

Example 2

This example assumes the "NCEP_2_Rect.nc" weight file from the previous example has already been generated. It uses this weight file to regrid a new variable from the same "sst.nc" 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("sst.nc","r")
    P  = sfile->P(0,0,:,:)

    P_regrid = ESMF_regrid_with_weights(P,"NCEP_2_Rect.nc",False)
    printVarSummary(P_regrid)
. . .