This class represents a CF data set, the object that
encapsulates a netCDF resource. You should never instantiate this class
directly; instead, call open_ncdf() which will return an instance that
has all properties read from the netCDF resource, or create_ncdf() for a
new, empty instance. Class methods can then be called, or the base R
functions called with this instance.
The CF data set instance provides access to all the objects in the netCDF resource, organized in groups.
Public fields
nameThe name of the netCDF resource. This is extracted from the URI (file name or URL).
rootRoot of the group hierarchy through which all elements of the netCDF resource are accessed. It is strongly discouraged to manipulate the objects in the group hierarchy directly. Use the provided access methods instead.
file_typeThe type of data in the netCDF resource, if identifiable. In terms of the CF Metadata Conventions, this includes discrete sampling geometries (DSG). Other file types that can be identified include L3b files used by NASA and NOAA for satellite imagery (these data sets need special processing), and CMIP5, CMIP6 and CORDEX climate projection data.
Active bindings
friendlyClassName(read-only) A nice description of the class.
resource(read-only) The connection details of the netCDF resource. This is for internal use only.
uri(read-only) The connection string to the netCDF resource.
conventions(read-only) Returns the conventions that this netCDF resource conforms to.
var_names(read-only) Vector of names of variables in this data set.
axis_names(read-only) Vector of names of axes in this data set.
Methods
Method new()
Create an instance of this class. Do not instantiate this
class directly; instead, call open_ncdf() which will return an
instance that has all properties read from the netCDF resource, or
create_ncdf() for a new, empty instance.
Usage
CFDataset$new(resource, format)Method print()
Summary of the data set printed to the console.
Method objects_by_standard_name()
Get objects by standard_name. Several conventions define standard vocabularies for physical properties. The standard names from those vocabularies are usually stored as the "standard_name" attribute with variables or axes. This method retrieves all variables or axes that list the specified "standard_name" in its attributes.
Method has_subgroups()
Does the netCDF resource have subgroups? Newer versions of
the netcdf library, specifically netcdf4, can organize dimensions
and variables in groups. This method will report if the data set is
indeed organized with subgroups.
Method find_by_name()
Find an object by its name. Given the name of a CF data variable or axis, possibly preceded by an absolute group path, return the object to the caller.
Method variables()
This method lists the CF data variables located in this netCDF resource, including those in subgroups.
Method axes()
This method lists the axes located in this netCDF resource, including axes in subgroups.
Method attributes()
List all the attributes of a group. This method returns a
data.frame containing all the attributes of the indicated group.
Method attribute()
Retrieve global attributes of the data set.
Method set_attribute()
Add an attribute to the global attributes. If an attribute
name already exists, it will be overwritten.
Arguments
nameThe name of the attribute. The name must begin with a letter and be composed of letters, digits, and underscores, with a maximum length of 255 characters. UTF-8 characters are not supported in attribute names.
typeThe type of the attribute, as a string value of a netCDF data type.
valueThe value of the attribute. This can be of any supported type, including a vector or list of values. Matrices, arrays and like compound data structures should be stored as a data variable, not as an attribute and they are thus not allowed. In general, an attribute should be a character value, a numeric value, a logical value, or a short vector or list of any of these. Values passed in a list will be coerced to their common mode.
Method append_attribute()
Append the text value of a global attribute. If an attribute
name already exists, the value will be appended to the existing
value of the attribute. If the attribute name does not exist it will
be created. The attribute must be of "NC_CHAR" or "NC_STRING" type; in
the latter case having only a single string value.
Arguments
nameThe name of the attribute. The name must begin with a letter and be composed of letters, digits, and underscores, with a maximum length of 255 characters. UTF-8 characters are not supported in attribute names.
valueThe character value of the attribute to append. This must be a character string.
sepThe separator to use. Default is
"; ".prependLogical to flag if the supplied
valueshould be placed before the existing value. Default isFALSE.
Method delete_attribute()
Delete attributes. If an attribute name is not present
this method simply returns.
Method add_variable()
Add a CFVariable object to the data set. If there is another object with the same name in the group where the data variable should be placed an error is thrown. For objects associated with the data variable (such as axes, CRS, boundary variables, etc), if another object with the same name is otherwise identical to the associated object then that object will be linked from the variable, otherwise an error is thrown.
Usage
CFDataset$add_variable(var, group, locations = list())Arguments
varAn instance of
CFVariableor any of its descendants.groupOptional. An instance of CFGroup where the data variable should be located. If omitted, the data variable will be stored in the root group.
locationsOptional. A
listwhose named elements correspond to the names of objects associated with the data variable in argumentvar. Each list element has a single character string indicating the group in the hierarchy where the object should be stored. As an example, if the data variable has axes "lon" and "lat" and they should be stored in the parent group ofgroup, then specifylocations = list(lon = "..", lat = ".."). Locations can use absolute paths or relative paths from thegroup. Associated objects that are not in the list will be stored ingroup. If the argumentlocationsis not provided, all associated objects will be stored ingroup.
Method save()
Save the data set to file, including its subordinate objects such as attributes, data variables, axes, CRS, etc.
Arguments
fnFully-qualified file name indicating where to save the data set to. This argument must be provided if the data set is virtual. If the argument is provided on a data set that was read from a netCDF file, a new netCDF file will be written to the indicated location. If the argument is missing, the existing netCDF file will be updated.
packOptional. Logical to indicate if the data should be packed; default is
FALSE. Packing is only useful for numeric data; packing is not performed on integer values. Packing is always to the "NC_SHORT" data type, i.e. 16-bits per value.