CFVariable: CF data variable
In ncdfCF: Easy Access to NetCDF Files with CF Metadata Conventions
CFVariable R Documentation
CF data variable
Description
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.
Super classes
ncdfCF::CFObject -> ncdfCF::CFVariableBase -> CFVariable
Active bindings
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.
Methods
Public methods
-
-
-
-
-
-
-
-
Inherited methods
Method new()
Create an instance of this class.
Usage
CFVariable$new(grp, nc_var, axes)
Arguments
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.
Returns
An instance of this class.
Method print()
Print a summary of the data variable to the console.
Usage
CFVariable$print(...)
Arguments
...Arguments passed on to other functions. Of particular interest
is width = to indicate a maximum width of attribute columns.
Method brief()
Some details of the data variable.
Usage
CFVariable$brief()
Returns
A 1-row data.frame with some details of the data variable.
Method shard()
The information returned by this method is very concise
and most useful when combined with similar information from other
variables.
Usage
CFVariable$shard()
Returns
Character string with very basic variable information.
Method peek()
Retrieve interesting details of the data variable.
Usage
CFVariable$peek(with_groups = TRUE)
Arguments
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.
Returns
A 1-row data.frame with details of the data variable.
Method data()
Retrieve all data of the variable.
Usage
CFVariable$data()
Returns
A CFArray instance with all data from this variable.
Method subset()
This 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.
Usage
CFVariable$subset(subset, aoi = NULL, rightmost.closed = FALSE, ...)
Arguments
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.
Details
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 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; 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(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.
Auxiliary coordinate variables
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 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 subset.
Returns
A CFArray 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.
Method clone()
The objects of this class are cloneable with this method.
Usage
CFVariable$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
ncdfCF documentation built on April 16, 2025, 9:08 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| CFVariable | R Documentation |
CF data variable
Description
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.
Super classes
ncdfCF::CFObject -> ncdfCF::CFVariableBase -> CFVariable
Active bindings
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.
Methods
Public methods
Inherited methods
Method new()
Create an instance of this class.
Usage
CFVariable$new(grp, nc_var, axes)
Arguments
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.
Returns
An instance of this class.
Method print()
Print a summary of the data variable to the console.
Usage
CFVariable$print(...)
Arguments
...Arguments passed on to other functions. Of particular interest is
width = to indicate a maximum width of attribute columns.
Method brief()
Some details of the data variable.
Usage
CFVariable$brief()
Returns
A 1-row data.frame with some details of the data variable.
Method shard()
The information returned by this method is very concise and most useful when combined with similar information from other variables.
Usage
CFVariable$shard()
Returns
Character string with very basic variable information.
Method peek()
Retrieve interesting details of the data variable.
Usage
CFVariable$peek(with_groups = TRUE)
Arguments
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.
Returns
A 1-row data.frame with details of the data variable.
Method data()
Retrieve all data of the variable.
Usage
CFVariable$data()
Returns
A CFArray instance with all data from this variable.
Method subset()
This 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.
Usage
CFVariable$subset(subset, aoi = NULL, rightmost.closed = FALSE, ...)
Arguments
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,ZorT, 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
AOIcreated with theaoi()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 thesubsetargument.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.
Details
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 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; 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(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.
Auxiliary coordinate variables
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 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 subset.
Returns
A CFArray 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.
Method clone()
The objects of this class are cloneable with this method.
Usage
CFVariable$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.