The region in space and time where expressions are evaluated may be specified in 3 different ways:
1) with the command SET REGION
2) with qualifiers to the command name (slash-delimited)
3) with qualifiers to variable names (in square brackets, comma-delimited)
If SET REGION is used, Ferret remembers the region as the default context for future commands, whereas a qualifier to a command name specifies the region for that command only, and a qualifier to a variable name specifies the region for that variable and command only.
Regions may be manipulated using DEFINE REGION, SET REGION, @ notation, and CANCEL REGION. The Commands Reference section of this manual covers all of these topics.
Region information is normally specified in the following form:
QUAL=val or
QUAL=lo_val:hi_val or
QUAL=val@transform (as a variable qualifier only) or
QUAL=lo_val:hi_val@transform (as a variable qualifier only)
When the region for an axis is specified as a single value (instead of a range) Ferret, by default, selects the grid point of the grid box containing this value. The Ferret mode "interpolate" can control this behavior. See command SET MODE INTERPOLATE in Commands Reference.
Examples: Regions
Examples of valid region specifications.
1) Fully specify the region in an XY plane with the first vertical (Z) level and time 27739.
yes? SET REGION/X=140E:160W/Y=10S:20N/K=1/T=27739
2) Contour vertical heat advection within whatever region is the current default (previously set with SET REGION).
yes? CONTOUR qadz
3) Define, modify and set a named region and then modify with delta notation.
yes? DEFINE/REGION/Y=5S:5N YT !define region YT to be 5S:5N yes? DEFINE REGION/DY=-1:+1 YT !modify region YT to be 6S:6N yes? SET REGION/@YT !set current region to YT yes? SET REGION/DY=-1:+1 !modify current region to 7S:7N
4) List meridional currents calculated by averaging values between the surface and a depth of 50 m.
yes? LIST v[Z=0:50@AVE]
5) Equivalent to v[Z=10] - v[Z=0:100@AVE], the anomaly at z=10 between v and the 0 to 100 meter depth average of v.
yes? LIST/Z=10 v - v[Z=0:100@AVE]
For more about creating and using anomaly fields, see the FAQ, How do I calculate climatologies and climatological anomalies?
4.3.1 Latitude
Specify latitude or a latitude range with the qualifier Y or J. Specifications using J are integers between 1 and the number of points on the Y axis. Specifications using Y are in the units of the Y axis.
The units may be examined with SHOW GRID/Y. If the Y axis units are degrees of latitude then the Y positions may be specified as numbers followed by the letters "N" or "S".
Examples
yes? CONTOUR temp[Y=15S:10N] yes? LIST/J=50 u
4.3.2 Longitude
Specify longitude or a longitude range with the qualifier X or I. Specifications using I are integers between 1 and the number of points on the X axis. Specifications using X are in the units of the X axis.
The units may be examined with SHOW GRID/X. If the units are degrees, then X values may be given as numbers followed by "W" or "E" (e.g., 160E, 110.5W) or as values between 0 and 360 with Greenwich at 0 increasing eastward. Note: If the X axis is "modulo" then it is sometimes desirable to use X greater than 360.
Examples
yes? CONTOUR temp[Y=160E:140W] yes? LIST/I=100 u yes? SHADE/X=100:460 temp !360 degrees centered at 100W
See the chapter "Grids and Regins", section "Modulo Axes" , for help with globe-encircling axes.
4.3.3 Depth
Specify depth or a depth range with the qualifier Z or K. Specifications using K are integers between 1 and the number of points on the Z axis. Specifications using Z are in the units of the Z axis.
The units may be examined with SHOW GRID/Z.
Examples
yes? CONTOUR temp[Z=0:100] yes? LIST/K=3 u
Specify time or a time range with the qualifier T or L. Specifications using L are integers between 1 and the number of points on the T axis. Specifications using T may refer to calendar dates or to the time step units in which the time axis of the data set is defined.
Calendar date/time values are entered in the format dd-mmm-yyyy:hh:mm:ss, for example 14-FEB-1988:12:30:00. At a minimum the string must contain day, month, and year. If the string contains any colons it must be enclosed in quotation marks to differentiate from colons used to designate a range. If a time increment is specified with the repeat command given in calendar format (e.g., REPEAT/T="1-JAN-1982":"15-JAN-1982":6) it is interpreted as hours always. Calendar dates in the years 0000 and 0001 are regarded as year-independent dates (suitable for climatological data). Ferret cannot work with negative values for years, or years larger than year 9999.
SHOW GRID/T can be used to display time step values. (Units may vary between data sets.) The commands SET MODE CALENDAR and CANCEL MODE CALENDAR can be used to view date strings or time steps, respectively.
Examples
yes? LIST/T="1-JAN-1982:13:50":"15-FEB-1982" density yes? CONTOUR temp[T=27740:30000] yes? LIST/L=90 u
See the section in this chapter on "Modulo Axes" for help with climatological axes.
4.3.5 Delta
The notation q=lo:hi:delta (e.g., Y=20S:20N:5) specifies that the data in the requested range is regularly subsampled at interval "delta."
This notation is valid only for the REPEAT, SHOW GRID, and DEFINE AXIS commands, and the qualifiers /HLIMITS and /VLIMITS used in action commands with graphical output.
It can also be used in square brackets when specifying variable context:
yes? LIST temp[l=40:90:5]
(but this is NOT allowed: LIST/L=40:90:5 temp )
4.3.6 @ notation
Regions may be named and referred to using the syntax "@name". Some commonly used regions are predefined. See commands SET REGION and DEFINE REGION in the Commands Reference section for further information.
If a region is specified using a combination of "@" notation and explicit axis limits the explicit axis limits will be evaluated after the "@" specification, possibly superseding the "@" limits.
Note: It is not advised to use the @notation inside of variable definitions, as redefinitions of the named region can cause code errors that lead to wrong results.
Using the @ notation only sets/alters the axis limits specified in the named region. For example, suppose that region "XY" is defined for the X and Y axes, but not for the Z and T axes. Then
yes? SET REGION/@XY
modifies only X and Y limits. BUT,
yes? SET REGION XY
modifies all axes‚ X and Y to the limits specified by XY, and Z and T to unspecified (even if they were previously specified).
Examples
1) Contour the 25th time step of temperature data at depth 10 within region T, the "Tropical Pacific."
yes? CONTOUR/@T/Z=10/L=25 temp
2) Produce a contour plot over region W, the "Whole Pacific Ocean," in the XY plane (the variable to be contoured as well as the depth and time will be inferred from the current context).
yes? CONTOUR/@W var1
3) Set the default region to "T", the Tropical Pacific Ocean (latitude 23.5S to 23.5N).
yes? SET REGION/@T
4) Define a region and then supersede with an axis limit specification.
yes? DEFINE REGION/X=180:140W/Y=2S:2N/Z=5 BOX1 yes? SET REGION/@BOX1/Z=15 !replace Z
As a convenience in the analysis of the Tropical Pacific Ocean the following regions are pre-defined:
These may be redefined by the user for the duration of a Ferret session or until the definitions are canceled.
4.3.7 Modulo axes
Some axes are inherently "modulo," indicating that the axis wraps around‚ the first point immediately following the last.
To determine if an axis is modulo use SHOW AXIS or SHOW GRID. A letter "m" following the number of points in the axis indicates a modulo axis. The command SHOW GRID qualified by the appropriate axis limits can be used to examine any part of the axis‚ including points beyond the nominal length of the axis. The commands SET AXIS/MODULO and CANCEL AXIS/MODULO can be used to control this feature on an axis-by-axis basis. Starting with Ferret version5.5, longitude axes which span 360 degrees or less, and climatological time axes are always detected as modulo, unless Ferret is specifically directed that the axis is NOT modulo, e.g. by a CANCEL AXIS/MODULO command.
Example
yes? SET DATA coads_climatology yes? SHOW GRID/I=180:183 sst !range request beyond last point GRID COADS1 name axis # pts start end COADSX LONGITUDE 180mr 21E 19E(379) [text omitted] I X BOX_SIZ 180> 19E(379) 2 181> 21E(381) 2 182> 23E(383) 2 183> 25E(385) 2
The most common uses of modulo axes are:
1) As longitude axes for globe-encircling data sets. This allows any starting and any ending longitudes to be used, for example, X=140E:140E indicates the entire earth with data beginning and ending at 140E.
2) As time axes for climatological data. By this device the time axis appears to extend from 0 to infinity and the climatological data can be referred to at any point in time. This facilitates comparisons with data sets at fixed times.
4.3.7.1 Subspan Modulo Axes
Ferret V5.5 introduces the concept of a "sub-span modulo axis" -- an axis where the range is a sub-range of a fullmodulo cycle. As of V5.5, longitude axes and climatological time axes are always detected as modulo, or as sub-span modulo when appropriate, unless Ferret is specifically directed that the axis is NOT modulo, e.g. by a CANCEL AXIS/MODULO command. If the user does not specify the modulo length, it is set to 360 degrees for a longitude axis, or a year for a time axis. Time axes of length less than or equal to one year, and starting in year 0000 or 0001 are taken to be climatological axes.
The modulo length of an axis defined on the Ferret command line is set with an argument to the MODULO qualifier, or with an argument to the netCDF modulo attribute. The value specified is in world units, e.g. degrees, or hours, and must match the units of the coordinates on the axis. Here is an example showing an axis defined explicitly as a modulo axis, and another which is modulo by default.
yes? DEFINE AXIS/MODULO=100/x=41:55:1 xax_subspan yes? DEFINE AXIS/X=100:300:10/UNITS=degrees_longitude xax_lonspan
The output of SHOW AXIS includes the modulo length and span of the axis:
yes? show axis xax* name axis # pts start end XAX_SUBSPAN X 15mr 41 55 Axis span (to cell edges) = 15 (modulo length = 100) XAX_LONSPAN LONGITUDE 21mr 100E 60W Axis span (to cell edges) = 210 (modulo length = 360)
In netCDF output files you will now see the modulo attribute taking a value. Continuing the example above, we write some variables using the axes to a file and use ncdump to show the modulo attribute in these files.
yes? LET v1 = X[GX=xax_subspan] +10
yes? LET v2 = SIN(X[GX=xax_lonspan])
yes? SAVE/FILE=test_subspan_modulo.nc v1, v2
yes? SPAWN ncdump -c test_subspan_modulo.nc
netcdf test_subspan_modulo {
dimensions:
XAX_SUBSPAN = 15 ;
XAX_LONSPAN = 21 ;
variables:
double XAX_SUBSPAN(XAX_SUBSPAN) ;
XAX_SUBSPAN:modulo = 100. ;
XAX_SUBSPAN:AXIS = "X" ;
float V1(XAX_SUBSPAN) ;
V1:missing_value = -1.e+34f ;
V1:_FillValue = -1.e+34f ;
V1:long_name = "X[GX=XAX_SUBSPAN] + 10" ;
double XAX_LONSPAN(XAX_LONSPAN) ;
XAX_LONSPAN:units = "degrees_east" ;
XAX_LONSPAN:modulo = 360. ;
XAX_LONSPAN:AXIS = "X" ;
float V2(XAX_LONSPAN) ;
V2:missing_value = -1.e+34f ;
V2:_FillValue = -1.e+34f ;
V2:long_name = "SIN(X[GX=XAX_LONSPAN])" ;
// global attributes:
:history = "FERRET V5.50 15-Jan-03" ;
data:
XAX_SUBSPAN = 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55 ;
XAX_LONSPAN = 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200, 210,
220, 230, 240, 250, 260, 270, 280, 290, 300 ;
}The importance of the sub-span modulo axes is to take the first of two steps that will make it possible for users largely to ignore differences in encodings of longitude and climatological time -- e.g. the blending of data in plots and analyses where the data come from data sets that are encoded variously as -180:180, 0:360, etc. Thus, for example, in V5.5 you can refer to my_subspan_var[g=another_var] and get a meaningful answer as long as the grids occupy the same region on the globe, regardless of longitude encoding. (The second step, for a future release, will address the longitude encoding of scattered data.)
Example:
Suppose we have data on an axis that was defined as follows
yes? DEFINE AXIS/X=520:550:1/UNITS=degrees xax
and suppose we want to overlay it on a map showing the regional topography.
yes? USE etopo05 yes? SHOW GRID rose ! We will want the names of the axes GRID GOZ1 name axis # pts start end ETOPO05_X LONGITUDE 4320mr 0E 0.079987W ETOPO05_Y LATITUDE 2161 r 90S 90N normal Z normal T yes? SET REGION W yes? SHADE/PAL=land_sea rose[d=1] ! draw the shade plot yes? USE my_data.nc ! The dataset containing the x=520:550 data yes? SHOW AXIS xsub name axis # pts start end XSUB LONGITUDE 31mr 160E(520) 170W(550) Axis span (to cell edges) = 31 (modulo length = 360) ! Use /NOLABEL on the shade command to remove the automatic label yes? SHADE/OVER/NOLABEL/PAL=greyscale a[GX=etopo05_x,GY=etopo05_y] ! Use ANNOTATE to add a cusom label, here at the top of the plot. yes? ANNOTATE/NORM/X=-0.1/Y=1.1/HALIGN=-1/SIZE=0.12 "Overlay: My North-Atlantic Data"
There is an implied void point in a sub-span modulo axis that fills the gap between the end of the axis and the start of the next modulo cycle. The data value at this point will always be the missing value flag (except for pseudo-variables such as "X[g=my_subspan_axis]"). Transformations such as smoothers do not operate across the void point.
In netCDF files, the modulo attribute is specified as follows:
1) Specify the modulo length of the axis with the attribute modulo = <value>, e.g. var:modulo=100;
2) The modulo attribute from previous netCDF files remains unchanged: modulo = " ". To set a modulo axis of standard length (360 degrees or one year). The modulo length is 360 degrees for a longitude axis, or one year for a climatological time axis.
3) The attribute value modulo = "FALSE", modulo = "NO", modulo="OFF" tells Ferret that the axis is not to be treated as modulo
4.3.8 Region Conflicts
Conflicting region information can be given to Ferret in obvious ways such as
LIST/I=1:3 I[I=1:10]
in which it is not clear if the request is for 10 points or for 3, or in subtler, disguised ways such as
LET A = I[I=1:10] LIST/I=1:3 A
In both examples Ferret would resolve the conflict by listing just the three values I=1:3.
Internally, Ferret uses the region closest to the variable to perform the calculation. Thus, in both of the examples above Ferret will perform the calculation on I=1:10, since the "[I=1:10]" directly modifies the variable name. If Ferret sees conflicting regions it attempts to use the regions further from the variable to clip the calculation. Thus 10 points are clipped to 3 in the above examples.
Unresolvable conflicts such as
LIST/I=11:13 I[I=1:10]
will result in a warning message that invalid limits have been ignored.