This class represents a CF data variable, the object that provides access to an array of data.
ncdfCF::CFObject -> CFVariable
groupThe NCGroup that this variable is defined in.
axesList of instances of classes descending from CFAxis that are the axes of the variable.
grid_mappingThe CFGridMapping of this variable. If this field
is NULL, the horizontal component of the axes are in decimal degrees of
longitude and latitude.
friendlyClassName(read-only) A nice description of the class.
gridLongLatThe grid of longitude and latitude values of every grid cell when the main variable grid has a different coordinate system.
crs(read-only) Retrieve the coordinate reference system description of the variable as a WKT2 string.
Inherited methods
new()Create an instance of this class.
CFVariable$new(grp, nc_var, axes)grpThe group that this CF variable lives in.
nc_varThe netCDF variable that defines this CF variable.
axesList of CFAxis instances that describe the dimensions.
An instance of this class.
brief()Some details of the data variable
CFVariable$brief()A 1-row data.frame with some details of the data variable.
shard()Very concise information on the variable
The information returned by this function is very concise and most useful when combined with similar information from other variables.
CFVariable$shard()Character string with very basic variable information.
data()Retrieve all data of the variable. Scalar variables are not present in the result.
CFVariable$data()A CFData instance with all data from this variable.
subset()Extract data from the variable
CFVariable$subset(subset, aoi = NULL, rightmost.closed = FALSE, ...)subsetA list with the range to extract from each axis. The
list should have elements for the axes to extract a subset from - if an
axis is not present in the list the entire axis will be extracted
from the array. List element names should be the axis designator X, Y,
Z or T, or the name of the axis - axes without an axis designator
and any additional axes beyond the four standard ones can only
be specified by name. Axis designators and names are case-sensitive and
can be specified in any order. If values for the range per axis fall
outside of the extent of the axis, the range is clipped to the extent of
the axis.
aoiOptional, an area-of-interest instance of class AOI created
with the aoi() function to indicate the horizontal area that should be
extracted. The longitude and latitude coordinates must be included; the X
and Y resolution will be calculated if not given. When provided, this
argument will take precedence over the corresponding axis information for
the X and Y axes in the subset argument.
rightmost.closedSingle logical value to indicate if the upper boundary of range in each axis should be included.
...Ignored. Included to avoid "unused argument" errors on
argument rightmost.closed.
The subset() method extracts a subset of values from the array of the
variable, with the range along each axis to extract expressed in values
of the domain of each axis.
The range of values along each axis to be subset is expressed in values
of the domain of the axis. Any axes for which no information is
provided in the subset argument are extracted in whole. Values can be
specified in a variety of ways that are specific to the nature of the
axis. For numeric axes it should (resolve to) be a vector of real
values. A range (e.g. 100:200), a long vector (c(23, 46, 3, 45, 17),
a sequence (seq(from = 78, to = 100, by = 2), all work. Note, however,
that only a single range is generated from the vector so these examples
resolve to 100:200, 3:46, and 78:100, respectively. For time axes a
vector of character timestamps, POSIXct or Date values must be
specified. As with numeric values, only the two extreme values in the
vector will be used.
If the range of values for an axis in argument subset extend the valid
range of the axis in x, the extracted slab will start at the beginning
for smaller values and extend to the end for larger values. If the
values envelope the valid range the entire axis will be extracted in
the result. If the range of subset values for any axis are all either
smaller or larger than the valid range of the axis in x then nothing
is extracted and NULL is returned.
The extracted data has the same dimensional structure as the data in the
variable, with degenerate dimensions dropped. The order of the axes in
argument subset does not reorder the axes in the result.
As an example, to extract values of a variable for Australia for the year
2020, where the first axis in x is the longitude, the second
axis is the latitude, both in degrees, and the
third (and final) axis is time, the values are extracted by
x$subset(list(X = c(112, 154), Y = c(-9, -44), T = c("2020-01-01", "2021-01-01"))).
You could take the longitude-latitude values from sf::st_bbox() or
terra::ext() if you have specific spatial geometries for whom you want to
extract data. Note that this works equally well for projected coordinate
reference systems - the key is that the specification in argument subset
uses the same domain of values as the respective axes in x use.
A special case exists for variables where the horizontal dimensions (X
and Y) are not in longitude and latitude values but in some other
coordinate system. In this case the netCDF resource may have so-called
auxiliary coordinate variables for longitude and latitude that are two
grids with the same dimension as the horizontal axes of the data variable
where each pixel gives the corresponding value for the longitude and
latitude. If the variable has such auxiliary coordinate variables then
they will be used automatically if, and only if, the axes are labeled in
argument subset as X and Y. The resolution of the grid that is
produced by this method is automatically calculated. If you want to
subset those axes then specify values in decimal degrees; if you want to
extract the full extent, specify NA. Note that if
you want to extract the data in the original grid, you should use the
horizontal axis names in argument subset.
An CFData instance, having an array with its axes and
attributes of the variable, or NULL if one or more of the elements in
the subset argument falls entirely outside of the range of the axis.
Note that degenerate dimensions (having length(.) == 1) are dropped
from the array but the corresponding axis is maintained in the result as
a scalar axis.
clone()The objects of this class are cloneable with this method.
CFVariable$clone(deep = FALSE)deepWhether to make a deep clone.
The CF data variable instance provides access to the data array from the netCDF resource, as well as all the details that have been associated with the data variable, such as axis information, grid mapping parameters, etc.