This class represents the basic structure of a CF data variable, the object that provides access to an array of data.
The CF data variable instance provides access to all the details that have
been associated with the data variable, such as axis information, grid
mapping parameters, etc. The actual data array can be accessed through the
data() and subset() methods of this class.
ncdfCF::CFObject -> ncdfCF::CFVariableBase -> CFVariable
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_wkt2(read-only) Retrieve the coordinate reference system description of the variable as a WKT2 string.
Inherited methods
ncdfCF::CFObject$add_coordinates()ncdfCF::CFObject$append_attribute()ncdfCF::CFObject$attribute()ncdfCF::CFObject$delete_attribute()ncdfCF::CFObject$print_attributes()ncdfCF::CFObject$set_attribute()ncdfCF::CFObject$write_attributes()ncdfCF::CFVariableBase$profile()ncdfCF::CFVariableBase$summarise()ncdfCF::CFVariableBase$time()
new()Create an instance of this class.
CFVariable$new(nc_var, axes)nc_varThe netCDF variable that defines this CF variable.
axesList of CFAxis instances that describe the dimensions.
An instance of this class.
...Arguments passed on to other functions. Of particular interest
is width = to indicate a maximum width of attribute columns.
brief()Some details of the data variable.
CFVariable$brief()A 1-row data.frame with some details of the data variable.
shard()The information returned by this method is very concise and most useful when combined with similar information from other variables.
CFVariable$shard()Character string with very basic variable information.
peek()Retrieve interesting details of the data variable.
CFVariable$peek(with_groups = TRUE)with_groupsShould group information be included? The save option
is TRUE (default) when the netCDF resource has groups because names may
be duplicated among objects in different groups.
A 1-row data.frame with details of the data variable.
A CFArray instance with all data from this variable.
subset()This method extracts a subset of values from the array of the variable, with the range along each axis to extract expressed in coordinate values of the domain of each axis.
CFVariable$subset(..., .aoi = NULL, rightmost.closed = FALSE)...One or more arguments of the form axis = range. The
"axis" part should be the name of an axis or its orientation X, Y,
Z or T. The "range" part is a vector of values representing
coordinates along the axis where to extract data. 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. You must
use the argument name when specifying this, like .aoi = my_aoi, to
avoid the argument being treated as an axis name.
rightmost.closedSingle logical value to indicate if the upper
boundary of range in each axis should be included. You must use the
argument name when specifying this, like rightmost.closed = TRUE, to
avoid the argument being treated as an axis name.
The range of values along each axis to be subset is expressed in
coordinates of the domain of the axis. Any axes for which no
selection is made in the ... argument are extracted in
whole. Coordinates 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 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 coordinate values for an axis in argument ...
extend the valid range of the axis in x, the extracted data 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 coordinate values for
any axis are all either smaller or larger than the valid range of the
axis 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 ... does not reorder the axes in the result; use the
CFArray$array() method for this.
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(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 ... 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 coordinates 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 ... 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 for both
X and Y. Note that if you want to extract the data in the
original grid, you should use the horizontal axis names in argument
....
A CFArray instance, having an array with its axes and
attributes of the variable, or NULL if one or more of the selectors
in the ... argument fall 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.