Documentation: DEFINE AXIS/MODULO
Closed this issue · 2 comments
A recent discussion with Ned Cokelet pointed out a lack of detail in the documentation about modulo axis definitions. I'd suggest some additions:
In this section https://ferret.pmel.noaa.gov/Ferret/documentation/users-guide/commands-reference/DEFINE there is the following:
DEFINE AXIS/MODULO[=len]
Specifies that the axis being defined be treated as modulo; that is, the first point will wrap around and follow the last point (e.g., a longitude axis).The optional modulo length is the length in axis units of the modulo repeat. If a length is specified, it may be longer than the axis span, so that the axis is treated as a subspan modulo axis, and if no length is specified then the default modulo length for the type of axis is used. See the sections on modulo axes and subspan modulo axes for more information.
In the last sentence there, "See the sections on modulo axes and subspan modulo axes" should link to this:
users-guide/Grids-Regions/REGIONS#_VPINDEXENTRY_723
After that paragraph, this should be added:
The modulo length of an axis is the span from the lower bound of the first grid cell to the upper bound of the last grid cell. So a global modulo longitude axis should not include coordinates at both 0 degrees and at 360 degrees, as the lower bound of the first cell is below 0 and the upper bound of the last cell is larger than 360. If an X axis has units of degrees or degrees_east, and if its length is 360 degrees or less, then it is automatically defined as a modulo axis with modulo length 360 degrees. If a T axis lies within the years 0000-0001 and its length is one year or less, it is automatically defined as a modulo (climatological) axis with length 1 year.
yes? define axis/x=5:360:5/units=degrees_east/modulo=360 x5deg
yes? define axis/x=0:359:1/units=degrees_east x1deg
yes? define axis/x=180W:178E:2/units=degrees_east x2deg
See also the examples defining climatological axes below, under "DEFINE AXIS/EDGES".
If we try to define an axis whose length exceeds the modulo length, the error message is issued:
yes? define axis/x=0:360:10/units=degrees/modulo=360 xaxis
**ERROR: improper grid or axis definition: Axis length exceeds modulo length
Some netCDF files may have longitude axes defined with coordinates ranging from 0 through 360 and an axis attribute modulo=360. On opening such a file, we will see a warning; The file is initialized but the axis is not defined as a modulo axis.
yes? use too_long.nc
*** NOTE: Ignored modulo length less than axis length: XLON_AX
This is done in the documentation update