This function constructs the area of interest of an analysis. It consists of an extent and a resolution of longitude and latitude, all in decimal degrees.
The AOI is used to define the subset of data to be extracted from a variable that has an auxiliary longitude-latitude grid (see the CFAuxiliaryLongLat class) at a specified resolution. The variable thus has a primary coordinate system where the horizontal components are not a geographic system of longitude and latitude coordinates.
aoi(lonMin, lonMax, latMin, latMax, resX, resY)The return value of the function is an R6 object which uses
reference semantics. Making changes to the returned object will be visible
in all copies made of the object.
The minimum and maximum values of the
longitude and latitude of the AOI, in decimal degrees. The longitude values
must agree with the range of the longitude in the variable to which this
AOI will be applied, e.g. [-180,180] or [0,360].
The separation between adjacent grid cell, in the longitude
and latitude directions respectively, in decimal degrees. The permitted
values lie within the range [0.01 ... 10]. If resY is missing it will
use the value of resX, yielding square grid cells.
Following the CF Metadata Conventions, axis coordinates represent
the center of grid cells. So when specifying aoi(20, 30, -10, 10, 1, 2),
the south-west grid cell coordinate is at (20.5, -9). If the axes of the
longitude-latitude grid have bounds, then the bounds will coincide with the
AOI and the CFVariable$subset() method that uses the AOI will attach
those bounds as attributes to the resulting array.
If no resolution is specified, it will be determined from the separation
between adjacent grid cells in both longitude and latitude directions in
the middle of the area of interest. If no extent is specified (meaning,
none of the values; if some but not all values are specified an error will
be thrown), then the whole extent of the variable is used, extended
outwards by the bounds if they are set or half the resolution otherwise.
Thus, to get the entire extent of the variable but in a longitude-latitude
grid and with a resolution comparable to the resolution at the original
Cartesian coordinate system of the variable, simply pass aoi() as an
argument to CFVariable$subset(). Note that any missing
arguments are calculated internally and stored in the returned object, but
only after the call to CFVariable$subset().
In data collections that are composed of multiple variables in a single
netCDF resource, a single auxiliary longitude-latitude grid may be
referenced by multiple variables, such as in ROMS
data which may have dozens of variables using a shared grid. When
subsetting with an AOI, the instance of this class is cached to improve
performance. The successive calls to CFVariable$subset() should use the
same object returned from a single call to this function for this caching
to work properly.
(aoi <- aoi(20, 60, -40, -20, 0.5))
Run the code above in your browser using DataLab