nominal_resolution Usage Documentation

The purpose of the nominal_resolution python code is to calculate the “nominal resolution” of a horizontal grid. For CMIP6 the nominal resolution must be calculated the same way for all models. In the ESGF data archive of CMIP6 results, nominal resolution is one of the search criteria that can be useful in identifying datasets of interest.

The algorithm for defining nominal resolution is given in Appendix 2 of a data specifications document for CMIP6. For regular cartesian latitude by longitude global grids, it can be calculated (to a good approximation) using a formula given in Appendix 2, but for irregular grids, sub-global domains, and the like, it must be calculated with the python code available here (or its equivalent).

Note that the nominal resolution is defined for two different purposes:

• in each CMIP6-archived model output file, a global attribute named nominal_resolution is stored, which records the resolution of the grid on which data are reported
• in the CMIP6_source_id.json file the native_nominal_resolution is stored, which records the resolution of the native grid of each model.

There are two steps in calculating the nominal resolution (for allowed values, see CMIP6_nominal_resolution.json): first, the mean resolution is calculated using the mean_resolution function, and then that is passed to the nominal_resolution function, which returns nominal_resolution.

For the most common use case, the first step is to call the function mean_resolution, passing it an array (cellarea) containing grid-cell areas and arrays (latitude_bounds and longitude_bounds) containing the longitude and latitude coordinates of the vertices of each grid cell. The input arrays can either be simple arrays or numpy masked arrays dimensioned as follow:

     cellarea[ncells]
     latitude_bounds[ncells,nverts]
     longitude_bounds[ncells,nverts]

where ncells is the number of grid cells and nverts is the maximum number of vertices a grid cell might have.

Any sensible unit can be used in defining the cell areas (cellarea), including non-dimensional angular area measures. The longitudes and latitudes should be expressed either in radians or in degrees. If a grid includes some cells with fewer than nverts vertices, the longitudes_bounds and latitudes_bounds arrays should be defined as numpy masked arrays and any unneeded vertices should be masked.

Depending on the units, the latitude_bounds values should be in the range:

• for radians: -pi to pi
• for degrees: -90. to 90.

Depending on the units, the longitude_bounds values should:

• for radians: span a range no more than 3 pi.
• for degrees: span a range no more than 540 degrees.

The user must also set the parameter `convertdeg2rad, depending on the units of longitudes and latitudes:

• if units are degrees, set convertdeg2rad to True
• if units are radians, set convertdeg2rad to False

The mean_resolution is returned by the above function, and, optionally, by setting the function parameter returnMaxDistance to True, the function will also return an array containing the maximum dimension of each of the grid cells. This array of values could subsequently be used to more fully characterize the distribution of grid cell sizes (allowing the user, for example, to compute a standard deviation).

If there are grid cells that should be omitted from the calculation, then cellarea should be defined as a python masked array (and all omitted cells should be masked).

The second step is to obtain nominal_resolution by passing mean_resolution to the nominal_resolution function.

The above functions can be found at: https://github.com/PCMDI/nominal_resolution/blob/master/lib/api.py

Sample codes using nominal_resolution are available at: https://github.com/PCMDI/nominal_resolution/tree/master/tests