NCL Home> Application examples> Data Analysis || Data files for some examples

Example pages containing: tips | resources | functions/procedures

Regridding using NCL with Earth System Modeling Framework (ESMF) software

Quick note: if the examples on this page are not helpful, then you can visit NCL templates page for a list of generic ESMF regridding template scripts.

This page shows how you can use ESMF regridding functions to regrid data on rectilinear, curvilinear, and unstructured "source" grids, to "destination" grids of any of these types. ESMF regridding creates a weights file that you can use to regrid other variables on the same grid. See the special note below about weights and missing values.

This software is only available in NCL version 6.1.0 and later.

The Earth System Modeling Framework (ESMF) is "software for building and coupling weather, climate, and related models". The ESMF "ESMF_RegridWeightGen" tool has been incorporated into NCL for generating weights for interpolating (regridding) data from a one grid to another.

Many thanks go to Robert Oehmke of NOAA---one of the developers of ESMF---for his consulting and patience in helping us learn and incorporate this software. Many thanks also go to Mohammad Abouali, who developed the original version of these NCL functions as part of a CISL SIParCS summer internship program.

The basic steps of NCL/ESMF regridding involve:

Reading or generating the "source" grid.
Reading or generating the "destination" grid.
Creating special NetCDF files that describe these two grids.
*Generating a NetCDF file that contains the weights.
Applying the weights to data on the source grid, to interpolate the data to the destination grid.
Copying over any metadata to the newly regridded data.

*This is the most important step. Once you have a weights file, you can skip steps #1-4 if you are interpolating data on the same grids.

ESMF regridding in NCL can be done one of three ways; each method has its advantages:

Via a single call to the function ESMF_regrid - this method does most of all of the above steps for you, but can be redundant if you are generating the same weights file over and over.
Via a call to the function ESMF_regrid_with_weights - this method is straight-forward and faster; it requires that you already have the weights file. You can use the weights file generated from an initial call to ESMF_regrid, or from the third method described below.
Via a multi-step process - this method is the most complicated, but allows for individual control over all the regridding steps. This method is not really recommended, unless you understand the multi-step regridding process well. See the detailed description below.

Several of the examples below include more than one script showing you the various methods:

Method 1: ESMF_regrid_n.ncl
Method 2: ESMF_wgts_regrid_n.ncl
Method 3: ESMF_all_n.ncl

More detailed description of ESMF regridding

For the special NetCDF files that are generated to describe the source and destination grids: SCRIP (Spherical Coordinate Remapping and Interpolation Package) is used to describe the rectilinear and curvilinear grids, and an internal ESMF format is used to describe the unstructured grids.

When the weights file is generated, there are three types of interpolation methods supported by ESMF software:

"bilinear" - the algorithm used by this application to generate the bilinear weights is the standard one found in many textbooks. Each destination point is mapped to a location in the source mesh, the position of the destination point relative to the source points surrounding it is used to calculate the interpolation weights.
"patch" - this method is the ESMF version of a technique called "patch recovery" commonly used in finite element modeling. It typically results in better approximations to values and derivatives when compared to bilinear interpolation.
"conserve" - this method will typically have a larger interpolation error than the previous two methods, but will do a much better job of preserving the value of the integral of data between the source and destination grid.
The "conserve" method requires that the corners of the lat/lon grid be input. NCL will try to provide a guess at the corners if you don't provide them, but this could likely result in failure.

You can (and are highly recommended to) provide your own grid corners via the special Src/Dst/GridCornerLat/Lon resources. They 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".

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 the lat/lon grid that you are regridding from and to are exactly the same, and, if you use the special SrcMask2D/DstMask2D/Mask2D options, that your masks are exactly the same. The masks are 2D 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.

Detailed description of the multi-step regridding process (method #3)

Write the description of the source grid to an intermediate SCRIP or ESMF file using one of the following functions:
Write the description of the destination grid to an intermediate SCRIP or ESMF file using the same functions as above.
Generate the weights file using ESMF_regrid_gen_weights.
[The weights are generated internally using the offline ESMF regridding tool called "ESMF_RegridWeightGen". This weight file can be reused for other variables with the same source and destination grids, enabling you to skip steps #1-3.]
Interpolate the data from the source grid to the destination grid using ESMF_regrid_with_weights.

Regrid and create netCDF files containing regridded variables

Most of the following examples show: (a) how to generate the weights needed to regrid variables; (b) apply the weights to a variable and (c) generate a plot showing the original and regridded variable.

Another approach is to regrid all or selected variables and then save the regridded data to a netCDF file for later use. In NCL, there are two methods that can be used to generate netCDF files. The following scripts, which operate on the CAM SE grid (See Example 25), illustrate how to save the regridded data via methods 1 and 2. The latter is considerably more complicated because it uses two steps to create the netCDF. However, the advantage is that it is the more efficient way to generate the netCDF file. The first step is to predefine the contents of the output file. No data values are written during this step. The second step is to regrid each variable and then write the regridded values into the predefined file structure.

             Method 1: se2fv_esmf.regrid2file.ncl
             Method 2: se2fv_esmf.regrid2file.ncl_predefine

ESMF_regrid_1.ncl / ESMF_wgts_1.ncl / ESMF_all_1.ncl:

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

The original data contains missing values, so it's important to set the special SrcMask2D option to indicate where the missing values are. For more information on weights files and masking, see the special note above.

The two scripts produce identical results; ESMF_all_1.ncl does the regridding in several steps, while ESMF_regrid_1.ncl does the regridding in a single call to ESMF_regrid.

This example was taken from the "regrid_1.ncl" example on the original regridding examples page, which uses the linint2 function to do the regridding.

ESMF_regrid_2.ncl / ESMF_wgts_2.ncl / ESMF_all_2.ncl:

This example shows how to regrid from a 1x1 degree global rectilinear grid (180 x 360) to lower resolution 2x3 degree (90 x 120) and 5x5 degree grid (36 x 72), using all three available interpolation methods: bilinear, patch, and conserve.

This example was taken from the "regrid_6.ncl" example on the original regridding examples page, which uses the area_conserve_remap_Wrap function to do the regridding.

ESMF_regrid_2.ncl does the regridding in a single call to ESMF_regrid.

ESMF_regrid_3.ncl / ESMF_wgts_3.ncl / ESMF_all_3.ncl:

This example shows how to regrid from a 0.25 degree global grid (400 x 1440) to a T42 (36 x 128) and T85 grid (72 x 256), using all three available interpolation methods: bilinear, patch, and conserve.

This example was taken from the "regrid_11.ncl" example on the original regridding examples page, which uses the area_conserve_remap_Wrap function to do the regridding.

ESMF_regrid_3.ncl does the regridding in a single call to ESMF_regrid.

ESMF_regrid_4.ncl / ESMF_wgts_4.ncl / ESMF_all_4.ncl:

This example shows how to regrid from a subset (511 x 1081) of a high-resolution rectilinear global elevation grid (5401 x 10801) to a low-resolution 0.5 degree regional grid (35 x 73), using the "conserve" interpolation method.

This example was taken from the "regrid_13.ncl" example on the original regridding examples page, which uses the area_conserve_remap_Wrap to do the regridding.

ESMF_regrid_5.ncl / ESMF_wgts_5.ncl / ESMF_all_5.ncl:

This example shows how to regrid two different datasets from a curvilinear WRF grid to a rectilinear grid of the same size (369 x 369), using the default "bilinear" interpolation method.

The weights are generated just once, and used to regrid two different variables on the file.

The variables plotted have 19 levels, but only the 19th level is plotted. If you want to interpolate and plot all 19 levels, set the LEVEL variable to -1.

ESMF_regrid_6.ncl / ESMF_wgts_6.ncl / ESMF_all_6.ncl:

This example shows how to regrid from a curvilinear CMIP5 global grid (220 x 256) to a 1x1 degree grid, using all three interpolation methods. Note that the grid corners are needed for the "conserve" method, and they are provided on the file as variables called "lat_vertices" and "lon_vertices". The special attributes "GridCornerLat" and "GridCornerLon" were set to these arrays before calling curvilinear_to_SCRIP.

ESMF_regrid_7.ncl / ESMF_wgts_7.ncl / ESMF_all_7.ncl:

This example shows how to regrid from a curvilinear ORCA global grid (292 x 362) to a 1x1 degree grid, using the default "bilinear" method.

ESMF_8.ncl / ESMF_wgts_8.ncl / ESMF_all_8.ncl:

This example shows how to regrid curvilinear regional swath data (265 x 185) to a rectilinear grid (238 x 250) read off a file. Three interpolation methods are compared here.

ESMF_regrid_9.ncl / ESMF_all_9.ncl:

This example hows how to regrid CCSM4 rectilinear data (192 x 288) to a curvilinear EASE grid (721 x 721), using the "patch" method.

This script took 148 CPU seconds on a MacBook Pro, using a single-threaded version of the ESMF_RegridWeightGen tool.

ESMF_regrid_10.ncl / ESMF_wgts_10.ncl / ESMF_all_10.ncl:

This example shows how to regrid unstructured MPAS data (163842 cells) to a 0.25 degree grid (719 x 440), using the default "bilinear" method.

ESMF_regrid_11.ncl / ESMF_wgts_11.ncl / ESMF_all_11.ncl:

This example uses the same unstructured MPAS data as the previous example, but regrids it to a curvilinear tripolar grid (300 x 360) read off a file. The "patch" interpolation method is used.

ESMF_regrid_12.ncl / ESMF_wgts_12.ncl / ESMF_all_12.ncl:

This example is the reverse of the previous example: it regrids data from a curvilinear tripolar grid (300 x 360) to an unstructured MPAS grid (163842 cells). The "patch" interpolation method is used again.

When you regrid to an unstructured grid, you MUST set Opt@DstGridType = "unstructured" so the ESMF regridding code knows you have an unstructured grid, and not a rectilinear grid that has the same length for its lat/lon arrays.

ESMF_regrid_13.ncl / ESMF_wgts_13.ncl / ESMF_all_13.ncl:

This example regrids data from an EASE grid (721 x 721) to a 0.25 degree global grid (359 x 1439). The "patch" interpolation method is used.

ESMF_regrid_14.ncl / ESMF_wgts_14.ncl / ESMF_all_14.ncl:

This example regrids unstructured data from the ICON model (20480 cells) to a 5 degree grid (37 x 73).

For more examples on plotting ICON data, see the "Visualizing ICON model data" examples page.

ESMF_regrid_15.ncl / ESMF_wgts_15.ncl / ESMF_all_15.ncl:

This example shows how to regrid curvilinear regional swath data (406 x 270) to a 0.25 degree regional grid (84 x 100) using all three interpolation methods.

ESMF_regrid_16.ncl:

This example shows how to regrid from a WRF curvilinear regional grid (546x480) to a much coarser MM5 curvilinear grid (34x19) using bilinear interpolation.

The variable regridded is "td2" (2m dewpoint temperature), but you can modify this script to do any 2D or 3D variable on the file. It should also work for more dimensions with slight modification.

ESMF_regrid_17.ncl / ESMF_wgts_17.ncl:

This example shows how to regrid from a CAM-SE unstructured grid with 48602 cells to a 96 x 144 finite volume (FV) rectilinear grid.

In this script, if you want to regrid to a subregion of the FV grid, then set SUBREGION to True, and set minlat/maxlat/minlon/maxlon to the desired region.

ESMF_regrid_18.ncl:

This example shows how to regrid two variables (PSL and T) on a HOMME unstructured finite volume grid (48602 cells) to a 96 x 144 finite volume (FV) rectilinear grid.

Once the first variable has been regridded using ESMF_regrid, you will have a NetCDF weights file. You can then use this weights file to regrid the second variable using ESMF_regrid_with_weights. This can be much faster than using ESMF_regrid again.

ESMF_regrid_19.ncl:

This example shows how to regrid data on a HOMME unstructured grid to POP curvilinear gx1v3 grid (384 x 320).

In this case, the POP grid was retrieved from an old weights file from a previous regridding that went from a 1x1 degree grid to a POP grid.

The destination lat/lon arrays on this weights file have corresponding names "yc_b" and "xc_b", and are one-dimensional. You have to reshape these 1D arrays to their original 2D structure using the "dst_grid_dims" variable on the file. The POP weights file also contains a mask grid called "mask_b" that you must apply via the special "DstMask2D" option.

ESMF_regrid_20.ncl:

This example shows how to regrid from a 27km WRF grid to a coarser 81km WRF grid using bilinear interpolation.

The color scheme used here is similar to the one used on the precipitation page of the WRF-ARW Online Tutorial. Set USE_WRF_COLORS to False if you want to "WhViBlGrYeOrRe" color table and a slightly different set of contour levels.

ESMF_regrid_21.ncl:

This example shows how to regrid from unstructured (random) data to a 0.1 degree grid.

Since this grid is not global, it is important to set the special "DstLLCorner" and "DstURCorner" resources to further zoom in on the 0.1 degree grid that the original data lies on. If you don't set these resources, then a global 0.1 degree grid will be created, causing the regridding to take a MUCH longer time.

ESMF_regrid_22.ncl:

This example shows how to regrid from data on a curvilinear grid that contains missing lat/lon values, to data on a curvilinear grid that covers a much smaller region.

Since the source grid contains missing values, it's important to set the SrcMask2D option:

  Opt@SrcMask2D         = where(ismissing(src_lat2d).or.\
                                ismissing(src_lon2d),0,1)

For plotting the data on the original grid, it is important to set:

  res@trGridType = "TriangularMesh"

so it handles these missing values correctly.

ESMF_regrid_23.ncl: This example was taken from the HDF examples page. It shows how to regrid data from a 9 km MODIS Aqua Level-3 HDF4 file to a 0.5 degree grid. The file attributes contain the geographical information, which is used to generate coordinate variables for the source grid.

The generation of the required files for regridding can be slow for this data, so once you have the "MODIST_to_0.5deg.nc" weights file, you can use ESMF_regrid_with_weights instead of ESMF_regrid to do the regridding. Look for HAVE_WGTS in the script for more information.

ESMF_regrid_24.ncl: This example shows how to regrid data from a POP curvilinear gx1v3 grid (384 x 320) to a 1.0 degree world grid. It plots sea water potential temperature on the new grid.

Note: Conservative interpolation will fail because grid vertex information needed by the ESMF software is not available.

ESMF_regrid_25.ncl: This example shows how to regrid CLM data on the 'ne30' to a finite volume grid.

Note_1: For some reason, in the CLM, grid locations over the oceans are set to _FillValue. This is not consistent with the treatment of land values in the POP model. The POP provides valid non-missing locations and sets the values to _FillValue.

Note_2: Conservative interpolation will fail because grid vertex information needed by the ESMF software is not available.