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

ESMF_regrid_with_weights

Using the provided weight file, regrids data from one lat/lon grid to another.

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.

	function ESMF_regrid_with_weights (
		data        : numeric,  
		wgtFile [1] : string,   
		opt     [1] : logical   
	)

	return_val  :  float or double

Arguments

data

The data to regrid. This can be any dimensionality, but the rightmost dimensions must match what was originally indicated in the source grid file.

wgtFile

Name of the input NetCDF file that contains the weights.

opt

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

See below for a full list of attributes.

Description

ESMF_regrid_with_weights regrids data from a source grid to a destination grid, using weights stored in the wgtFile NetCDF file.

As of V6.1.0 (not V6.1.0-beta), this function will return type float if data is float, and double if data is double or the special "ReturnDouble" attribute is set to True (see below).

Important changes incorporated in the return variable after V6.1.0-beta was released:

If regridding to a rectilinear grid, coordinate variables will be attached by default. If regridding to a curvilinear grid, "lat2d" and "lon2d" attributes will be attached to the output array. If regridding to an unstructured grid, "lat1d" and "lon1d" attributes will be attached to the output array. You can set opt@CopyVarCoords to False if you don't want this behavior.
"long_name" attribute will not be modified
"remap" attribute added - Note: there's a "bug" if the "patch" method is used. The ESMF regridder returns "Bilinear remapping" as the mapping used.
"missing_value" attribute added
"_FillValue_original" attribute removed
"missing_value_original" attribute removed

ESMF_regrid_with_weights is part of a suite of regridding routines based on Earth System Modeling Framework (ESMF) software.

This function can be used on its own to regrid data from one grid to another, if you already have a weights file. Otherwise the regridding can be done via a multi-step process that includes this function.

If you don't already have a weights file, then the multi-step process involves:

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

The source and destination grids can be rectilinear, curvilinear, or unstructured.

The weight file is generated by ESMF_regrid_gen_weights.

The attributes that can be attached to opt include:

CopyVarAtts (default = True)
The attributes of the variable being regridded will be copied to the regridded variable, unless this is set to False. Attributes that will not be copied include "lat2d", "lon2d", "lat1d", "lon1d", and "coordinates".
CopyVarCoords (default = True in V6.1.0 and later)
This function will attempt to copy over any coordinate arrays, unless this attribute is set to False. It gets the coordinate information from the weights file.
If the destination grid is rectilinear, then the coordinates will be copied as 1D coordinate arrays. If the destination grid is curvilinear, then the coordinates will be attached as special attributes called "lat2d" and "lon2d". If the destination grid is unstructured, then the coordinates will be attached as special attributes called "lat1d" and "lon1d".
ReturnDouble (added in V6.1.0)
If set to True, then the return value from this function will be double, regardless of the type of the input data.
RemapIndexes (default = False)
If set to True, then this indicates that the weights in this file apply to a 1D grid is a subset of a larger nD grid. This means the values have to be remapped onto the original destination grid using index values indicated by Indexes, and the dimension sizes indicated by IndexesDims.
Indexes (no default)
See the description for RemapIndexes.
IndexesDims (no default)
See the description for RemapIndexes.
PrintTimings (default = False)
Print the CPU time spent in this routine.
Debug (default = False) Turn on debug print statements.

This function is part of a suite of regridding routines based on the Earth System Modeling Framework (ESMF) software.

The four basic steps for regridding data using the ESMF tools include:

Writing the description of the source grid to a SCRIP or ESMF description file, using one of latlon_to_SCRIP, rectilinear_to_SCRIP, curvilinear_to_SCRIP, or unstructured_to_ESMF.
Writing the description of the destination grid to a SCRIP or ESMF description file, using one of latlon_to_SCRIP, rectilinear_to_SCRIP, curvilinear_to_SCRIP, or unstructured_to_ESMF.
Generating the weights using ESMF_regrid_gen_weights.
Regridding the data using 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

    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)
. . .

ESMF_regrid_with_weights

Prototype

Arguments

Description

See Also

Examples