CFDataset: CF data set
In ncdfCF: Easy Access to NetCDF Files with CF Metadata Conventions
CFDataset R Documentation
CF data set
Description
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
Public 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)
Arguments
resourceAn instance of NCResource that links to the netCDF
resource, or a character string with the name of a new data set.
formatCharacter string with the format of the netCDF resource as
reported by the call opening the resource. Ignored when argument
resource is a character string.
Method print()
Summary of the data set printed to the console.
Usage
CFDataset$print(...)
Arguments
...Arguments passed on to other functions. Of particular interest
is width = to indicate a maximum width of attribute columns.
Method hierarchy()
Print the group hierarchy to the console.
Usage
CFDataset$hierarchy()
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.
Usage
CFDataset$objects_by_standard_name(standard_name)
Arguments
standard_nameOptional, a character string to search for a
specific "standard_name" value in variables and axes.
Returns
If argument standard_name is provided, a character vector of
variable or axis names. If argument standard_name is missing or an
empty string, a named list with all "standard_name" attribute values in
the the netCDF resource; each list item is named for the variable or
axis.
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.
Usage
CFDataset$has_subgroups()
Returns
Logical to indicate that the netCDF resource uses 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.
Usage
CFDataset$find_by_name(name)
Arguments
nameThe name of a CF data variable or axis, with an optional
absolute group path.
Returns
The object with the provided name. If the object is not found,
returns NULL.
Method variables()
This method lists the CF data variables located in this
netCDF resource, including those in subgroups.
Usage
CFDataset$variables()
Returns
A list of CFVariable instances.
Method axes()
This method lists the axes located in this netCDF resource,
including axes in subgroups.
Usage
CFDataset$axes()
Returns
A list of CFAxis descendants.
Method attributes()
List all the attributes of a group. This method returns a
data.frame containing all the attributes of the indicated group.
Usage
CFDataset$attributes(group)
Arguments
groupThe name of the group whose attributes to return. If the
argument is missing, the global attributes will be returned.
Returns
A data.frame of attributes.
Method attribute()
Retrieve global attributes of the data set.
Usage
CFDataset$attribute(att, field = "value")
Arguments
attVector of character strings of attributes to return.
fieldThe field of the attribute to return values from. This must
be "value" (default) or "type".
Returns
If the field argument is "type", a character string. If field
is "value", a single value of the type of the attribute, or a vector
when the attribute has multiple values. If no attribute is named with a
value of argument att NA is returned.
Method set_attribute()
Add an attribute to the global attributes. If an attribute
name already exists, it will be overwritten.
Usage
CFDataset$set_attribute(name, type, 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.
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.
Returns
Self, invisibly.
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.
Usage
CFDataset$append_attribute(name, value, sep = "; ", prepend = FALSE)
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 value should be placed
before the existing value. Default is FALSE.
Returns
Self, invisibly.
Method delete_attribute()
Delete attributes. If an attribute name is not present
this method simply returns.
Usage
CFDataset$delete_attribute(name)
Arguments
nameVector of names of the attributes to delete.
Returns
Self, invisibly.
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 CFVariable or 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 list whose named elements correspond to
the names of objects associated with the data variable in argument
var. 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 of group, then specify locations = list(lon = "..", lat = ".."). Locations can use absolute paths or
relative paths from the group. Associated objects that are not in the
list will be stored in group. If the argument locations is not
provided, all associated objects will be stored in group.
Returns
Argument var, invisibly.
Method save()
Save the data set to file, including its subordinate objects
such as attributes, data variables, axes, CRS, etc.
Usage
CFDataset$save(fn, pack = FALSE)
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.
Returns
Self, invisibly.
Method clone()
The objects of this class are cloneable with this method.
Usage
CFDataset$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
ncdfCF documentation built on Jan. 24, 2026, 1: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.
| CFDataset | R Documentation |
CF data set
Description
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
Public 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)
Arguments
resourceAn instance of
NCResourcethat links to the netCDF resource, or a character string with the name of a new data set.formatCharacter string with the format of the netCDF resource as reported by the call opening the resource. Ignored when argument
resourceis a character string.
Method print()
Summary of the data set printed to the console.
Usage
CFDataset$print(...)
Arguments
...Arguments passed on to other functions. Of particular interest is
width = to indicate a maximum width of attribute columns.
Method hierarchy()
Print the group hierarchy to the console.
Usage
CFDataset$hierarchy()
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.
Usage
CFDataset$objects_by_standard_name(standard_name)
Arguments
standard_nameOptional, a character string to search for a specific "standard_name" value in variables and axes.
Returns
If argument standard_name is provided, a character vector of
variable or axis names. If argument standard_name is missing or an
empty string, a named list with all "standard_name" attribute values in
the the netCDF resource; each list item is named for the variable or
axis.
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.
Usage
CFDataset$has_subgroups()
Returns
Logical to indicate that the netCDF resource uses 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.
Usage
CFDataset$find_by_name(name)
Arguments
nameThe name of a CF data variable or axis, with an optional absolute group path.
Returns
The object with the provided name. If the object is not found,
returns NULL.
Method variables()
This method lists the CF data variables located in this netCDF resource, including those in subgroups.
Usage
CFDataset$variables()
Returns
A list of CFVariable instances.
Method axes()
This method lists the axes located in this netCDF resource, including axes in subgroups.
Usage
CFDataset$axes()
Returns
A list of CFAxis descendants.
Method attributes()
List all the attributes of a group. This method returns a
data.frame containing all the attributes of the indicated group.
Usage
CFDataset$attributes(group)
Arguments
groupThe name of the group whose attributes to return. If the argument is missing, the global attributes will be returned.
Returns
A data.frame of attributes.
Method attribute()
Retrieve global attributes of the data set.
Usage
CFDataset$attribute(att, field = "value")
Arguments
attVector of character strings of attributes to return.
fieldThe field of the attribute to return values from. This must be "value" (default) or "type".
Returns
If the field argument is "type", a character string. If field
is "value", a single value of the type of the attribute, or a vector
when the attribute has multiple values. If no attribute is named with a
value of argument att NA is returned.
Method set_attribute()
Add an attribute to the global attributes. If an attribute
name already exists, it will be overwritten.
Usage
CFDataset$set_attribute(name, type, 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.
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.
Returns
Self, invisibly.
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.
Usage
CFDataset$append_attribute(name, value, sep = "; ", prepend = FALSE)
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.
Returns
Self, invisibly.
Method delete_attribute()
Delete attributes. If an attribute name is not present
this method simply returns.
Usage
CFDataset$delete_attribute(name)
Arguments
nameVector of names of the attributes to delete.
Returns
Self, invisibly.
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.
Returns
Argument var, invisibly.
Method save()
Save the data set to file, including its subordinate objects such as attributes, data variables, axes, CRS, etc.
Usage
CFDataset$save(fn, pack = FALSE)
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.
Returns
Self, invisibly.
Method clone()
The objects of this class are cloneable with this method.
Usage
CFDataset$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.