ncdfCF: Easy Access to NetCDF Files and Interpreting with CF Metadata Conventions

Description

Support for accessing and interpreting netCDF datasets in a familiar R style. Built on top of the RNetCDF package, built and maintained by the developers of the netcdf library, package ncdfCF provides high-level access to netCDF resources. Resources are matched against the Climate and Forecast (CF) Metadata Conventions for climate and forecasting data, current version 1.12. The CF Metadata Conventions is widely used for distributing files with climate observations or projections, including the Coupled Model Intercomparison Project (CMIP) data used by climate change scientists and the Intergovernmental Panel on Climate Change (IPCC), as well as large collections of satellite imagery, including from Landsat and MODIS.

Details

This package currently supports group traversal with scoping rules, axis determination and interpretation, including auxiliary axes, time axis interpretation with all defined calendars, grid mapping, use of bounds data, manipulating and interpreting attributes of groups (including global attributes) and variables, search for and use of standard names. Some specific constructs in CF are also supported:

• Axes can be oriented to access the data in the familiar R arrangement (CF allows any data arrangement and most data sets indeed use an arrangement that is not immediately useful in R).

• The CFVariable::subset() function allows one to select subsets of data using coordinate values along the axes (such as latitude values, or points in time) rather than index values into the array.

• Use of auxiliary grids to warp data variables using a non-default grid to a regular latitude-longitude grid.

Properties of the netCDF resource objects are easily examined using common R commands. Access to the data in the variables can be had using similarly known patterns, and data can be exported to a variety of formats.

This package is intended to access data from netCDF resources in a format that is easily integrated with other R coding patterns and packages, with full support for the CF Metadata Conventions that define the data properties. This package does very little beyond that; specifically, there is no support for spatial analysis, mosaicing, changing the coordinate reference system (i.e. projection), or any significant form of data analysis at all. The user is directed to other packages for such functionality.

Global functions

• open_ncdf(): Open a netCDF resource, either in a local file system or on a THREDDS server, or through any other means supported by the RNetCDF package. The return value is a CFDataset. Note that resources are automatically closed.

• peek_ncdf(): Rapid inspection of objects in a netCDF resource, returning information on variables, axes and global attributes with which intelligent inferences can be made about a netCDF resource.

Data set

A CFDataset is the object that contains a netCDF resource. This is the main class that you need to access netCDF data.

• show(): Print information about the data set to the console. This will print some information on the resource, as well as all identified data variables, axes, and the global attributes.

• name: The name of the data set.

• conventions: The conventions that this data set complies with. There could be multiple conventions listed in a single character string. CF Metadata Conventions use a "CF-1.*" label.

• variables(), axes(), attributes(): Return a list or data.frame with all objects of the specific type found in the data set.

• find_by_name(): Find a named object in the data set. This can be a data variable, an axis, or a grid mapping object. A short-hand method to achieve the same is the [[ operator. This also supports scanning for objects in hierarchical groups in netcdf4 resources.

• objects_by_standard_name(): Find objects that use a specific value for the "standard_name" attribute, or return all objects that have such the "standard_name" attribute irrespective of its value.

• has_subgroups(): Indicates if the data set has subgroups below the root group.

• hierarchy(): Prints the group hierarchy in the data set to the console.

S3 methods for CFDataset

• names(): Vector of names of the data variables in the data set.

• dimnames(): Vector of names of the axes in the data set.

Data variable

A CFVariable contains a single data variable from a data set. It contains detailed information on the data variable and there are functions to access the data, with different selection methods.

Properties

• show(), brief(), and shard(): Print to the console or return to the caller (increasingly more compact) information on a data variable.

• name, id: Basic properties of the data variable.

• axes(): List of CFAxis objects representing the axes that the data variable uses.

• attributes: data.frame with the attributes of the data variable.

• attribute(): Retrieve the values of an attribute of the data variable.

• crs: The so-called grid-mapping object that contains information on the coordinate reference system (CRS) of the data variable.

• crs_wkt2: The CRS of the data variable, in WKT2 format. This is derived from the data in the grid-mapping object.

Data extraction

• data(): Extract all data from a data variable into a CFArray object.

• subset(): Select a subset of data from a variable by specifying extents in real-world coordinates for the axes into a CFArray object. This can also process "auxiliary coordinate variables", if present, to warp data from its native CRS to latitude-longitude.

• summarise(): Summarise the data in the data variable over the "time" axis, using a user-defined function, returning a CFArray object. The function can be built-in (such as min() and max()) or a user-developed function. The function may also return a vector with multiple values (such as range()) and then a list of CFArray objects is returned, one for each result of the function.

S3 methods for CFVariable

• dim(), dimnames(): Vector of the lengths and coordinate values of the axes of the data variable.

• ⁠[]⁠ (bracket_select): Select the entire data variable or a part thereof using index values, returning an array of data values.

Axis

The CFAxis class is the common ancestor of specialized classes that represent specific types of axes. These sub-classes are the ones that are actually returned when retrieving an axis. These classes are:

• CFAxisNumeric is a basic numeric axis, where the coordinate values represent some physical property. The CFAxisLongitude and CFAxisLatitude classes derive from the basic numeric class to manage the specifics of geodetic coordinate systems. Class CFAxisVertical also derives from the basic class to manage depth and height axes.

• CFAxisTime is a specialized class to deal with time axes. Under the CF Metadata Conventions multiple different calendars have been defined and this class deals with the complexities of all of these. Functionality is provided by the CFtime package.

• CFAxisCharacter is for axes that use character labels as categorical values.

• CFAxisDiscrete is for axes that don't have any intrinsic coordinate values, instead the ordinal values along the axis are used.

Any scalar axes that are found in a netCDF file are converted to one of the above axis classes, with a length of 1.

Any of the axis classes can have one or more coordinate sets associated with them. This is most useful for CFAxisDiscrete. Labels of the active coordinate set are used for display of axis properties, as well as for selection in e.g. CFVariable$subset().

Methods for CFAxis instances:

Properties

• show(), brief(), and shard(): Print to the console or return to the caller (increasingly more compact) information on an axis.

• name, id: Basic properties of the axis.

• coordinates: Get a vector of coordinate values of the axis.

Extraction

• indexOf(): Retrieve the sub-range of the axis that encompasses the physical values passed.

• subset: Create a new CFAxis instance that spans a sub-range of the axis.

• time(): Retrieve the CFTime instance of the axis.

Coordinates

• coordinate_names: Set or retrieve the names of the coordinate sets (not the coordinates themselves).

• active_coordinates: Set or retrieve the coordinate set that is currently active and used for display and selection.

• auxiliary: Set or retrieve the CF object that manages the active coordinate set, either an instance of CFLabel or an CFAxis descendant.

• coordinates: Retrieve the coordinates of the active coordinate set. This may be the coordinate values of the axis (say, longitude values) or a set of auxiliary coordinates associated with the axis.

S3 methods for CFAxis

• dim(), dimnames(): The length and coordinate values of the axis.

Data

The CFVariable::data() and CFVariable::subset() methods return a CFArray object to the caller. The CFArray object contains the data from the netCDF resource, as well as important metadata from the data variable: axes, CRS and attributes. The data is easily accessed as a raw array, or processed to some other format.

Properties

• show(): Print information about the data object to the console, including axes, the CRS and its attributes.

• axes(): List of CFAxis objects representing the axes that the data object uses.

• crs: A WKT2-formatted string of the CRS of the data object.

Data extraction

• raw(): The array of data values from the data object as read from the netCDF resource.

• array(): The array of data values from the data object, oriented in the standard R arrangement.

• summarise(): Summarise the data in the data array over the "time" axis, using a user-defined function, returning a new CFArray object. The function can be built-in (such as min() and max()) or a user-developed function. The function may also return a vector with multiple values (such as range()) and then a list of CFArray objects is returned, one for each result of the function.

• terra(): (requires the terra package) The data values from the data object as a terra::SpatRaster (2 or 3 dimensions) or terra::SpatRasterDataset (4 dimensions), with all relevant properties set.

• data.table(): (requires the data.table package) The data values from the data object as a data.table where every row consists of the permutation of the axis values and a final data value.

Author(s)

Maintainer: Patrick Van Laake patrick@vanlaake.net [copyright holder]

See Also

Useful links:

• https://github.com/R-CF/ncdfCF

• Report bugs at https://github.com/R-CF/ncdfCF/issues

Array data extracted from a CF data variable

Description

This class holds the data that is extracted from a CFVariable using the data(), subset() or profile() method. The instance of this class will additionally have the axes and other relevant information such as its attributes (as well as those of the axes) and the coordinate reference system.

Otherwise, a CFArray is detached from the data set where it was derived from. It is self-contained in the sense that all its constituent parts (axes, bounds, attributes, etc) are available and directly linked to the instance. For performance reasons, axes and their parts (e.g. bounds) are shared between instances of CFArray and CFVariable.

The class has a number of utility functions to extract the data in specific formats:

• raw(): The data without any further processing. The axes are as they are stored in the netCDF resource; there is thus no guarantee as to how the data is organized in the array. Dimnames will be set.

• array(): An array of the data which is organized as a standard R array with the axes of the data permuted to Y-X-others and Y-values in decreasing order. Dimnames will be set.

• terra(): The data is returned as a terra::SpatRaster (3D) or terra::SpatRasterDataset (4D) object, with all relevant structural metadata set. Package terra must be installed for this to work.

• data.table(): The data is returned as a data.table, with all data points on individual rows. Metadata is not maintained. Package data.table must be installed for this to work.

  The temporal axis of the data, if present, may be summarised using the summarise() method. The data is returned as a new CFArray instance.

  In general, the metadata from the netCDF resource will be lost when exporting to a different format insofar as those metadata are not recognized by the different format.

Super classes

ncdfCF::CFObject -> ncdfCF::CFVariableBase -> CFArray

Active bindings

Methods

Public methods

• CFArray$new()

• CFArray$print()

• CFArray$raw()

• CFArray$array()

• CFArray$append()

• CFArray$terra()

• CFArray$data.table()

• CFArray$save()

• CFArray$clone()

Method new()

Create an instance of this class.

Usage

CFArray$new(name, group, values, values_type, axes, crs, attributes)

Arguments

Returns

An instance of this class.

Method print()

Print a summary of the data object to the console.

Usage

CFArray$print(...)

Arguments

Method raw()

Retrieve the data in the object exactly as it was produced by the operation on CFVariable.

Usage

CFArray$raw()

Returns

The data in the object. This is usually an array with the contents along axes varying.

Method array()

Retrieve the data in the object in the form of an R array, with axis ordering Y-X-others and Y values going from the top down.

Usage

CFArray$array()

Returns

An array of data in R ordering.

Method append()

Append the data from another CFArray instance to the current instance, along one of the axes. The operation will only succeed if the axes other than the one to append along have the same coordinates and the coordinates of the axis to append along have to be monotonically increasing or decreasing after appending.

Usage

CFArray$append(from, along)

Arguments

Returns

self, invisibly, with the arrays from self and from appended.

Method terra()

Convert the data to a terra::SpatRaster (3D) or a terra::SpatRasterDataset (4D) object. The data will be oriented to North-up. The 3rd dimension in the data will become layers in the resulting SpatRaster, any 4th dimension the data sets. The terra package needs to be installed for this method to work.

Usage

CFArray$terra()

Returns

A terra::SpatRaster or terra::SpatRasterDataset instance.

Method data.table()

Retrieve the data in the object in the form of a data.table. The data.table package needs to be installed for this method to work.

Usage

CFArray$data.table(var_as_column = FALSE)

Arguments

Returns

A data.table with all data points in individual rows. All axes will become columns. Two attributes are added: name indicates the long name of this data variable, units indicates the physical unit of the data values.

Method save()

Save the data object to a netCDF file.

Usage

CFArray$save(fn, pack = FALSE)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFArray$clone(deep = FALSE)

Arguments

CF auxiliary longitude-latitude variable

Description

This class represents the longitude and latitude variables that compose auxiliary coordinate variable axes for X-Y grids that are not longitude-latitude.

The class provides access to the data arrays for longitude and latitude from the netCDF resource, as well as all the details that have been associated with both axes. Additionally, this class can generate the index to extract values on a long-lat grid of the associated X-Y grid data variable using a user-selectable extent and resolution.

Auxiliary longitude-latitude grids are only supported for reading from a netCDF resource. Creating an instance manually therefore has no practical purpose.

Super class

ncdfCF::CFObject -> CFAuxiliaryLongLat

Public fields

Active bindings

Methods

Public methods

• CFAuxiliaryLongLat$new()

• CFAuxiliaryLongLat$print()

• CFAuxiliaryLongLat$brief()

• CFAuxiliaryLongLat$sample_index()

• CFAuxiliaryLongLat$grid_index()

• CFAuxiliaryLongLat$clear_cache()

• CFAuxiliaryLongLat$clone()

Method new()

Creating a new instance. It should normally not be useful to create an instance of this class other than upon reading a netCDF resource.

Usage

CFAuxiliaryLongLat$new(varLong, varLat, boundsLong, boundsLat)

Arguments

Method print()

Summary of the auxiliary longitude-latitude variable printed to the console.

Usage

CFAuxiliaryLongLat$print()

Method brief()

Some details of the auxiliary longitude-latitude grid.

Usage

CFAuxiliaryLongLat$brief()

Returns

A 2-row data.frame with some details of the grid components.

Method sample_index()

Return the indexes into the X (longitude) and Y (latitude) axes of the original data grid of the points closest to the supplied longitudes and latitudes, up to a maximum distance.

Usage

CFAuxiliaryLongLat$sample_index(x, y, maxDist = NULL)

Arguments

Returns

A matrix with two columns X and Y and as many rows as arguments x and y. The X and Y columns give the index into the grid of the sampling points, or c(NA, NA) is no grid point is located within the maxDist distance from the sampling point.

Method grid_index()

Compute the indices for the AOI into the data grid.

Usage

CFAuxiliaryLongLat$grid_index()

Returns

An integer matrix with the dimensions of the AOI, where each grid cell gives the linear index value into the longitude and latitude grids.

Method clear_cache()

Clears the cache of pre-computed grid index values if an AOI has been set.

Usage

CFAuxiliaryLongLat$clear_cache(full = FALSE)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAuxiliaryLongLat$clone(deep = FALSE)

Arguments

CF axis object

Description

This class is a basic ancestor to all classes that represent CF axes. More useful classes use this class as ancestor.

This super-class does manage the "coordinates" of the axis, i.e. the values along the axis. This could be the values of the axis as stored on file, but it can also be the values from an auxiliary coordinate set, in the form of a CFLabel instance. The coordinate set to use in display, selection and processing is selectable through methods and fields in this class.

Super class

ncdfCF::CFObject -> CFAxis

Public fields

Active bindings

Methods

Public methods

• CFAxis$new()

• CFAxis$print()

• CFAxis$brief()

• CFAxis$shard()

• CFAxis$peek()

• CFAxis$time()

• CFAxis$identical()

• CFAxis$can_append()

• CFAxis$subset()

• CFAxis$indexOf()

• CFAxis$write()

• CFAxis$clone()

Method new()

Create a new CF axis instance from a dimension and a variable in a netCDF resource. This method is called upon opening a netCDF resource by the initialize() method of a descendant class suitable for the type of axis.

Creating a new axis is more easily done with the makeAxis() function.

Usage

CFAxis$new(nc_var, nc_dim, orientation)

Arguments

Returns

A basic CFAxis object.

Method print()

Prints a summary of the axis to the console. This method is typically called by the print() method of descendant classes.

Usage

CFAxis$print(...)

Arguments

Returns

self, invisibly.

Method brief()

Some details of the axis.

Usage

CFAxis$brief()

Returns

A 1-row data.frame with some details of the axis.

Method shard()

Very concise information on the axis. The information returned by this function is very concise and most useful when combined with similar information from other axes.

Usage

CFAxis$shard()

Returns

Character string with very basic axis information.

Method peek()

Retrieve interesting details of the axis.

Usage

CFAxis$peek(with_groups = TRUE)

Arguments

Returns

A 1-row data.frame with details of the axis.

Method time()

Return the CFTime instance that represents time. This method is only useful for CFAxisTime instances having time information. This stub is here to make the call to this method succeed with no result for the other descendant classes.

Usage

CFAxis$time()

Returns

NULL

Method identical()

Tests if the axis passed to this method is identical to self. This only tests for generic properties - class, length and name

• with further assessment done in sub-classes.

Usage

CFAxis$identical(axis)

Arguments

Returns

TRUE if the two axes are identical, FALSE if not.

Method can_append()

Tests if the axis passed to this method can be appended to self. This only tests for generic properties - class, mode of the values and name - with further assessment done in sub-classes.

Usage

CFAxis$can_append(axis)

Arguments

Returns

TRUE if the passed axis can be appended to self, FALSE if not.

Method subset()

Return an axis spanning a smaller coordinate range. This method is "virtual" in the sense that it does not do anything other than return NULL. This stub is here to make the call to this method succeed with no result for the CFAxis descendants that do not implement this method.

Usage

CFAxis$subset(group, rng = NULL)

Arguments

Returns

NULL

Method indexOf()

Find indices in the axis domain. Given a vector of numerical, timestamp or categorical coordinates x, find their indices in the coordinates of the axis.

This is a virtual method. For more detail, see the corresponding method in descendant classes.

Usage

CFAxis$indexOf(x, method = "constant", rightmost.closed = TRUE)

Arguments

Returns

Numeric vector of the same length as x.

Method write()

Write the axis to a netCDF file, including its attributes.

Usage

CFAxis$write(nc = NULL)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxis$clone(deep = FALSE)

Arguments

CF character axis object

Description

This class represent CF axes that use categorical character labels as coordinate values. Note that this is different from a CFLabel, which is associated with an axis but not an axis itself.

This is an extension to the CF Metadata Conventions. As per CF, axes are required to have numerical values, which is relaxed here.

Super classes

ncdfCF::CFObject -> ncdfCF::CFAxis -> CFAxisCharacter

Active bindings

Methods

Public methods

• CFAxisCharacter$new()

• CFAxisCharacter$brief()

• CFAxisCharacter$identical()

• CFAxisCharacter$append()

• CFAxisCharacter$indexOf()

• CFAxisCharacter$clone()

Method new()

Create a new instance of this class.

Creating a new character axis is more easily done with the makeAxis() function.

Usage

CFAxisCharacter$new(nc_var, nc_dim, orientation, values)

Arguments

Method brief()

Some details of the axis.

Usage

CFAxisCharacter$brief()

Returns

A 1-row data.frame with some details of the axis.

Method identical()

Tests if the axis passed to this method is identical to self.

Usage

CFAxisCharacter$identical(axis)

Arguments

Returns

TRUE if the two axes are identical, FALSE if not.

Method append()

Append a vector of values at the end of the current values of the axis.

Usage

CFAxisCharacter$append(from)

Arguments

Returns

A new CFAxisCharacter instance with values from self and the from axis appended.

Method indexOf()

Find indices in the axis domain. Given a vector of character strings x, find their indices in the coordinates of the axis.

Usage

CFAxisCharacter$indexOf(x, method = "constant", rightmost.closed = TRUE)

Arguments

Returns

Numeric vector of the same length as x. Values of x that are not equal to a coordinate of the axis are returned as NA.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisCharacter$clone(deep = FALSE)

Arguments

CF discrete axis object

Description

This class represent discrete CF axes, i.e. those axes whose coordinate values do not represent a physical property. The coordinate values are ordinal values equal to the index into the axis.

Super classes

ncdfCF::CFObject -> ncdfCF::CFAxis -> CFAxisDiscrete

Active bindings

Methods

Public methods

• CFAxisDiscrete$new()

• CFAxisDiscrete$print()

• CFAxisDiscrete$brief()

• CFAxisDiscrete$append()

• CFAxisDiscrete$indexOf()

• CFAxisDiscrete$subset()

• CFAxisDiscrete$write()

• CFAxisDiscrete$clone()

Method new()

Create a new instance of this class.

Creating a new discrete axis is more easily done with the makeDiscreteAxis() function.

Usage

CFAxisDiscrete$new(nc_var, nc_dim, orientation, dim_only = FALSE)

Arguments

Method print()

Summary of the axis printed to the console.

Usage

CFAxisDiscrete$print(...)

Arguments

Returns

self, invisibly.

Method brief()

Some details of the axis.

Usage

CFAxisDiscrete$brief()

Returns

A 1-row data.frame with some details of the axis.

Method append()

Append a vector of values at the end of the current values of the axis. In a discrete axis the values are always a simple sequence so the appended values extend the sequence, rather than using the values from axis from.

Usage

CFAxisDiscrete$append(from)

Arguments

Returns

A new CFAxisDiscrete with the combined length of self and the from axis.

Method indexOf()

Find indices in the axis domain. Given a vector of numerical values x, find their indices in the values of the axis. In effect, this returns index values into the axis, but outside values will be dropped.

Usage

CFAxisDiscrete$indexOf(x, method = "constant", rightmost.closed = TRUE)

Arguments

Returns

Numeric vector of the same length as x. Values of x outside of the range of the values in the axis are returned as NA.

Method subset()

Return an axis spanning a smaller coordinate range. This method returns an axis which spans the range of indices given by the rng argument.

Usage

CFAxisDiscrete$subset(group, rng = NULL)

Arguments

Returns

A CFAxisDiscrete instance covering the indicated range of indices. If the value of the argument is NULL, return the entire axis.

Method write()

Write the axis to a netCDF file, including its attributes, but only if it has an associated NC variable in the file.

Usage

CFAxisDiscrete$write(nc = NULL)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisDiscrete$clone(deep = FALSE)

Arguments

Latitude CF axis object

Description

This class represents a latitude axis. Its values are numeric. This class adds some logic that is specific to latitudes, such as their range, orientation and meaning.

Super classes

ncdfCF::CFObject -> ncdfCF::CFAxis -> ncdfCF::CFAxisNumeric -> CFAxisLatitude

Active bindings

Methods

Public methods

• CFAxisLatitude$new()

• CFAxisLatitude$subset()

• CFAxisLatitude$clone()

Method new()

Create a new instance of this class.

Creating a new latitude axis is more easily done with the makeLatitudeAxis() function.

Usage

CFAxisLatitude$new(nc_var, nc_dim, values)

Arguments

Method subset()

Return an axis spanning a smaller coordinate range. This method returns an axis which spans the range of indices given by the rng argument.

Usage

CFAxisLatitude$subset(group, rng = NULL)

Arguments

Returns

A CFAxisLatitude instance covering the indicated range of indices. If the value of the argument is NULL, return the entire axis.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisLatitude$clone(deep = FALSE)

Arguments

Longitude CF axis object

Description

This class represents a longitude axis. Its values are numeric. This class is used for axes that represent longitudes. This class adds some logic that is specific to longitudes, such as their range, orientation and their meaning. (In the near future, it will also support selecting data that crosses the 0-360 degree boundary.)

Super classes

ncdfCF::CFObject -> ncdfCF::CFAxis -> ncdfCF::CFAxisNumeric -> CFAxisLongitude

Active bindings

Methods

Public methods

• CFAxisLongitude$new()

• CFAxisLongitude$subset()

• CFAxisLongitude$clone()

Method new()

Create a new instance of this class.

Creating a new longitude axis is more easily done with the makeLongitudeAxis() function.

Usage

CFAxisLongitude$new(nc_var, nc_dim, values)

Arguments

Method subset()

Return an axis spanning a smaller coordinate range. This method returns an axis which spans the range of indices given by the rng argument.

Usage

CFAxisLongitude$subset(group, rng = NULL)

Arguments

Returns

A CFAxisLongitude instance covering the indicated range of indices. If the value of the argument is NULL, return the entire axis.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisLongitude$clone(deep = FALSE)

Arguments

Numeric CF axis object

Description

This class represents a numeric axis. Its values are numeric. This class is used for axes with numeric values but without further knowledge of their nature. More specific classes descend from this class.

Super classes

ncdfCF::CFObject -> ncdfCF::CFAxis -> CFAxisNumeric

Active bindings

Methods

Public methods

• CFAxisNumeric$new()

• CFAxisNumeric$print()

• CFAxisNumeric$brief()

• CFAxisNumeric$range()

• CFAxisNumeric$indexOf()

• CFAxisNumeric$identical()

• CFAxisNumeric$append()

• CFAxisNumeric$subset()

• CFAxisNumeric$clone()

Method new()

Create a new instance of this class.

Creating a new axis is more easily done with the makeAxis() function.

Usage

CFAxisNumeric$new(nc_var, nc_dim, orientation, values)

Arguments

Method print()

Summary of the axis printed to the console.

Usage

CFAxisNumeric$print(...)

Arguments

Returns

self, invisibly.

Method brief()

Some details of the axis.

Usage

CFAxisNumeric$brief()

Returns

A 1-row data.frame with some details of the axis.

Method range()

Retrieve the range of coordinate values in the axis.

Usage

CFAxisNumeric$range()

Returns

A numeric vector with two elements with the minimum and maximum values in the axis, respectively.

Method indexOf()

Retrieve the indices of supplied coordinates on the axis. If the axis has bounds then the supplied coordinates must fall within the bounds to be considered valid.

Usage

CFAxisNumeric$indexOf(x, method = "constant", rightmost.closed = TRUE)

Arguments

Returns

A vector giving the indices in x of valid coordinates provided. Values of x outside of the range of the coordinates in the axis are returned as NA.

Method identical()

Tests if the axis passed to this method is identical to self.

Usage

CFAxisNumeric$identical(axis)

Arguments

Returns

TRUE if the two axes are identical, FALSE if not.

Method append()

Append a vector of values at the end of the current values of the axis.

Usage

CFAxisNumeric$append(from)

Arguments

Returns

A new CFAxisNumeric or descendant instance with values from self and the from axis appended.

Method subset()

Return an axis spanning a smaller coordinate range. This method returns an axis which spans the range of indices given by the rng argument.

Usage

CFAxisNumeric$subset(group, rng = NULL)

Arguments

Returns

A CFAxisNumeric instance covering the indicated range of indices. If the value of the argument is NULL, return the entire axis.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisNumeric$clone(deep = FALSE)

Arguments

Time axis object

Description

This class represents a time axis. The functionality is provided by the CFTime class in the CFtime package.

Super classes

ncdfCF::CFObject -> ncdfCF::CFAxis -> CFAxisTime

Active bindings

Methods

Public methods

• CFAxisTime$new()

• CFAxisTime$print()

• CFAxisTime$brief()

• CFAxisTime$time()

• CFAxisTime$identical()

• CFAxisTime$append()

• CFAxisTime$indexOf()

• CFAxisTime$slice()

• CFAxisTime$subset()

• CFAxisTime$write()

• CFAxisTime$clone()

Method new()

Create a new instance of this class.

Creating a new time axis is more easily done with the makeTimeAxis() function.

Usage

CFAxisTime$new(nc_var, nc_dim, values)

Arguments

Method print()

Summary of the time axis printed to the console.

Usage

CFAxisTime$print(...)

Arguments

Returns

self, invisibly.

Method brief()

Some details of the axis.

Usage

CFAxisTime$brief()

Returns

A 1-row data.frame with some details of the axis.

Method time()

Retrieve the CFTime instance that manages the values of this axis.

Usage

CFAxisTime$time()

Returns

An instance of CFTime.

Method identical()

Tests if the axis passed to this method is identical to self.

Usage

CFAxisTime$identical(axis)

Arguments

Returns

TRUE if the two axes are identical, FALSE if not.

Method append()

Append a vector of time values at the end of the current values of the axis.

Usage

CFAxisTime$append(from)

Arguments

Returns

A new CFAxisTime instance with values from self and the from axis appended.

Method indexOf()

Retrieve the indices of supplied values on the time axis.

Usage

CFAxisTime$indexOf(x, method = "constant", rightmost.closed = FALSE)

Arguments

Returns

An integer vector giving the indices in the time axis of valid values in x, or NA if the value is not valid.

Method slice()

Retrieve the indices of the time axis falling between two extreme values.

Usage

CFAxisTime$slice(x, rightmost.closed = FALSE)

Arguments

Returns

An integer vector giving the indices in the time axis between values in x, or integer(0) if none of the values are valid.

Method subset()

Return an axis spanning a smaller coordinate range. This method returns an axis which spans the range of indices given by the rng argument.

Usage

CFAxisTime$subset(group, rng = NULL)

Arguments

Returns

A CFAxisTime instance covering the indicated range of indices. If the value of the argument is NULL, return the entire axis.

Method write()

Write the axis to a netCDF file, including its attributes. If the calendar name is "gregorian", it will be set to the functionally identical calendar "standard" as the former is deprecated.

Usage

CFAxisTime$write(nc = NULL)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisTime$clone(deep = FALSE)

Arguments

Parametric vertical CF axis object

Description

This class represents a parametric vertical axis. It is defined through an index value that is contained in the axis, with additional NCVariable instances that hold ancillary data with which to calculate dimensional axis values. It is used in atmosphere and ocean data sets. Non-parametric vertical axes are stored in an CFAxisNumeric instance.

Super classes

ncdfCF::CFObject -> ncdfCF::CFAxis -> ncdfCF::CFAxisNumeric -> CFAxisVertical

Public fields

Active bindings

Methods

Public methods

• CFAxisVertical$new()

• CFAxisVertical$clone()

Method new()

Create a new instance of this class.

Usage

CFAxisVertical$new(nc_var, nc_dim, values, standard_name)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisVertical$clone(deep = FALSE)

Arguments

References

https://cfconventions.org/Data/cf-conventions/cf-conventions-1.12/cf-conventions.html#parametric-vertical-coordinate

CF bounds variable

Description

This class represents the bounds of an axis or an auxiliary longitude-latitude grid.

The class manages the bounds information for an axis (2 vertices per element) or an auxiliary longitude-latitude grid (4 vertices per element).

Super class

ncdfCF::CFObject -> CFBounds

Public fields

Active bindings

Methods

Public methods

• CFBounds$new()

• CFBounds$print()

• CFBounds$range()

• CFBounds$sub_bounds()

• CFBounds$write()

• CFBounds$clone()

Method new()

Create an instance of this class.

Usage

CFBounds$new(nc_var, nc_dim, values)

Arguments

Method print()

Print a summary of the object to the console.

Usage

CFBounds$print(...)

Arguments

Method range()

Retrieve the lowest and highest value in the bounds.

Usage

CFBounds$range()

Method sub_bounds()

Return bounds spanning a smaller coordinate range.

This method returns bounds which spans the range of indices given by the rng argument.

Usage

CFBounds$sub_bounds(group, rng)

Arguments

Returns

A CFBounds instance covering the indicated range of indices.

Method write()

Write the bounds variable to a netCDF file. This method should not be called directly; instead, CFArray::save() will call this method automatically.

Usage

CFBounds$write(h, object_name)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CFBounds$clone(deep = FALSE)

Arguments

CF cell measure variable

Description

This class represents a CF cell measure variable, the object that indicates the area or volume of every grid cell in referencing data variables.

If a cell measure variable is external to the current file, an instance will still be created for it, but the user must link the external file to this instance before it can be used in analysis.

Public fields

Methods

Public methods

• CFCellMeasure$new()

• CFCellMeasure$print()

• CFCellMeasure$data()

• CFCellMeasure$register()

• CFCellMeasure$link()

• CFCellMeasure$clone()

Method new()

Create an instance of this class.

Usage

CFCellMeasure$new(grp, measure, name = NULL, nc_var = NULL, axes = NULL)

Arguments

Returns

An instance of this class.

Method print()

Print a summary of the cell measure variable to the console.

Usage

CFCellMeasure$print(...)

Arguments

Method data()

Retrieve the values of the cell measure variable.

Usage

CFCellMeasure$data()

Returns

The values of the cell measure as a CFArray instance.

Method register()

Register a CFVariable which is using this cell measure variable. A check is performed on the compatibility between the data variable and this cell measure variable.

Usage

CFCellMeasure$register(var)

Arguments

Returns

Self, invisibly.

Method link()

Link the cell measure variable to an external netCDF resource. The resource will be opened and the appropriate data variable will be linked to this instance. If the axes or other properties of the external resource are not compatible with this instance, an error will be raised.

Usage

CFCellMeasure$link(resource)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFCellMeasure$clone(deep = FALSE)

Arguments

CF data set

Description

This class represents a CF data set, the object that encapsulates a netCDF resource. You should never have to instantiate this class directly; instead, call open_ncdf() which will return an instance that has all properties read from the netCDF resource. 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

Active bindings

Methods

Public methods

• CFDataset$new()

• CFDataset$print()

• CFDataset$hierarchy()

• CFDataset$objects_by_standard_name()

• CFDataset$has_subgroups()

• CFDataset$find_by_name()

• CFDataset$variables()

• CFDataset$axes()

• CFDataset$attributes()

• CFDataset$attribute()

• CFDataset$clone()

Method new()

Create an instance of this class.

Usage

CFDataset$new(name, resource, keep_open, format)

Arguments

Method print()

Summary of the data set printed to the console.

Usage

CFDataset$print(...)

Arguments

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

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, scope = "CF")

Arguments

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

Returns

A data.frame of attributes.

Method attribute()

Retrieve global attributes of the data set.

Usage

CFDataset$attribute(att, field = "value")

Arguments

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 clone()

The objects of this class are cloneable with this method.

Usage

CFDataset$clone(deep = FALSE)

Arguments

CF grid mapping object

Description

This class contains the details for a coordinate reference system, or grid mapping in CF terms, of a data variable.

When reporting the coordinate reference system to the caller, a character string in WKT2 format is returned, following the OGC standard.

Super class

ncdfCF::CFObject -> CFGridMapping

Public fields

Active bindings

Methods

Public methods

• CFGridMapping$new()

• CFGridMapping$print()

• CFGridMapping$brief()

• CFGridMapping$wkt2()

• CFGridMapping$write()

• CFGridMapping$clone()

Method new()

Create a new instance of this class.

Usage

CFGridMapping$new(nc_var, name)

Arguments

Method print()

Prints a summary of the grid mapping to the console.

Usage

CFGridMapping$print()

Method brief()

Retrieve a 1-row data.frame with some information on this grid mapping.

Usage

CFGridMapping$brief()

Method wkt2()

Retrieve the CRS string for a specific variable.

Usage

CFGridMapping$wkt2(axis_info)

Arguments

Returns

A character string with the CRS in WKT2 format.

Method write()

Write the CRS object to a netCDF file.

Usage

CFGridMapping$write(h)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFGridMapping$clone(deep = FALSE)

Arguments

References

https://docs.ogc.org/is/18-010r11/18-010r11.pdf

CF label object

Description

This class represent CF labels, i.e. an NC variable of character type that provides a textual label for a discrete or general numeric axis. See also CFAxisCharacter, which is an axis with character labels.

Super class

ncdfCF::CFObject -> CFLabel

Public fields

Active bindings

Methods

Public methods

• CFLabel$new()

• CFLabel$print()

• CFLabel$subset()

• CFLabel$write()

• CFLabel$clone()

Method new()

Create a new instance of this class.

Usage

CFLabel$new(nc_var, nc_dim, values)

Arguments

Method print()

Prints a summary of the labels to the console.

Usage

CFLabel$print(...)

Arguments

Returns

self, invisibly.

Method subset()

Retrieve a subset of the labels.

Usage

CFLabel$subset(grp, rng)

Arguments

Returns

A CFLabel instance, or NULL if the rng values are invalid.

Method write()

Write the labels to a netCDF file, including its attributes.

Usage

CFLabel$write(nc)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFLabel$clone(deep = FALSE)

Arguments

CF base object

Description

This class is a basic ancestor to all classes that represent CF objects, specifically data variables and axes. More useful classes use this class as ancestor.

Public fields

Active bindings

Methods

Public methods

• CFObject$new()

• CFObject$attribute()

• CFObject$print_attributes()

• CFObject$set_attribute()

• CFObject$append_attribute()

• CFObject$delete_attribute()

• CFObject$write_attributes()

• CFObject$add_coordinates()

• CFObject$clone()

Method new()

Create a new CF object instance from a variable in a netCDF resource. This method is called upon opening a netCDF resource. It is rarely, if ever, useful to call this constructor directly from the console. Instead, use the methods from higher-level classes such as CFVariable.

Usage

CFObject$new(nc_var)

Arguments

Returns

A CFobject instance.

Method attribute()

Retrieve attributes of any CF object.

Usage

CFObject$attribute(att, field = "value")

Arguments

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 print_attributes()

Print the attributes of the CF object to the console.

Usage

CFObject$print_attributes(width = 50L)

Arguments

Method set_attribute()

Add an attribute. If an attribute name already exists, it will be overwritten.

Usage

CFObject$set_attribute(name, type, value)

Arguments

Returns

Self, invisibly.

Method append_attribute()

Append the text value of an 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

CFObject$append_attribute(name, value, sep = "; ", prepend = FALSE)

Arguments

Returns

Self, invisibly.

Method delete_attribute()

Delete an attribute. If an attribute name is not present this method simply returns.

Usage

CFObject$delete_attribute(name)

Arguments

Returns

Self, invisibly.

Method write_attributes()

Write the attributes of this object to a netCDF file.

Usage

CFObject$write_attributes(nc, nm)

Arguments

Returns

Self, invisibly.

Method add_coordinates()

Add names of axes to the "coordinates" attribute, avoiding duplicates and retaining previous values.

Usage

CFObject$add_coordinates(crds)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFObject$clone(deep = FALSE)

Arguments

NetCDF resource object

Description

This class contains the connection details to a netCDF resource.

There is a single instance of this class for every netCDF resource, owned by the CFDataset instance. The instance is shared by other objects, specifically NCGroup instances, for access to the underlying resource for reading of data.

This class should never have to be accessed directly. All access is handled by higher-level methods.

Public fields

Active bindings

Methods

Public methods

• CFResource$new()

• CFResource$close()

• CFResource$group_handle()

• CFResource$clone()

Method new()

Create a connection to a netCDF resource. This is called by open_ncdf() when opening a netCDF resource; you should never have to call this directly.

Usage

CFResource$new(uri)

Arguments

Returns

An instance of this class.

Method close()

Closing an open netCDF resource. It should rarely be necessary to call this method directly.

Usage

CFResource$close()

Method group_handle()

Every group in a netCDF file has its own handle, with the "root" group having the handle for the entire netCDF resource. The handle returned by this method is valid only for the named group.

Usage

CFResource$group_handle(group_name)

Arguments

Returns

The handle to the group.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFResource$clone(deep = FALSE)

Arguments

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

Methods

Public methods

• CFVariable$new()

• CFVariable$print()

• CFVariable$brief()

• CFVariable$shard()

• CFVariable$peek()

• CFVariable$data()

• CFVariable$subset()

• CFVariable$clone()

Method new()

Create an instance of this class.

Usage

CFVariable$new(nc_var, axes)

Arguments

Returns

An instance of this class.

Method print()

Print a summary of the data variable to the console.

Usage

CFVariable$print(...)

Arguments

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

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 coordinate values of the domain of each axis.

Usage

CFVariable$subset(..., .aoi = NULL, rightmost.closed = FALSE)

Arguments

Details

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.

Auxiliary coordinate variables

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 ....

Returns

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.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFVariable$clone(deep = FALSE)

Arguments

Base ancestor of CFVariable and CFArray

Description

This class is a basic ancestor to CFVariable and CFArray. It should not be instantiated directly, use the descendant classes instead.

This class provides access to common properties of data variables and the data they contain.

Super class

ncdfCF::CFObject -> CFVariableBase

Public fields

Methods

Public methods

• CFVariableBase$new()

• CFVariableBase$time()

• CFVariableBase$summarise()

• CFVariableBase$profile()

• CFVariableBase$clone()

Method new()

Create an instance of this class.

Usage

CFVariableBase$new(var, axes, crs)

Arguments

Returns

An instance of this class.

Method time()

Return the time object from the axis representing time.

Usage

CFVariableBase$time(want = "time")

Arguments

Returns

If want = "axis" the CFAxisTime axis; if want = "time" the CFTime instance of the axis, or NULL if the variable does not have a "time" axis.

Method summarise()

Summarise the temporal domain of the data, if present, to a lower resolution, using a user-supplied aggregation function.

Attributes are copied from the input data variable or data array. Note that after a summarisation the attributes may no longer be accurate. This method tries to sanitise attributes (such as removing scale_factor and add_offset, when present, as these will no longer be appropriate in most cases) but the onus is on the calling code (or yourself as interactive coder). Attributes like standard_name and cell_methods likely require an update in the output of this method, but the appropriate new values are not known to this method. Use CFArray$set_attribute() on the result of this method to set or update attributes as appropriate.

Usage

CFVariableBase$summarise(name, fun, period, era = NULL, ...)

Arguments

Returns

A CFData object, or a list thereof with as many CFData objects as fun returns values.

Method profile()

This method extracts profiles of values from the array of the variable, with the location along each axis to extract expressed in coordinate values of each axis.

Usage

CFVariableBase$profile(..., .names = NULL, .as_table = FALSE)

Arguments

Details

The coordinates along each axis to be sampled are expressed in values of the domain of the axis. Any axes which are not passed as arguments are extracted in whole to the result. If bounds are set on the axis, the coordinate whose bounds envelop the requested coordinate is selected. Otherwise, the coordinate along the axis closest to the supplied value will be used. If the value for a specified axis falls outside the valid range of that axis, NULL is returned.

A typical case is to extract the temporal profile as a 1D array for a given location. In this case, use arguments for the latitude and longitude on an X-Y-T data variable: profile(lat = -24, lon = 3). Other profiling options are also possible, such as a 2D zonal atmospheric profile at a given longitude for an X-Y-Z data variable: profile(lon = 34).

Multiple profiles can be extracted in one call by supplying vectors for the indicated axes: profile(lat = c(-24, -23, -2), lon = c(5, 5, 6)). The vectors need not have the same length, unless .as_table = TRUE. With unequal length vectors the result will be a list of CFArray instances with different dimensionality and/or different axes.

Auxiliary coordinate variables (CFVariable only)

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. If the data variable has such auxiliary coordinate variables then they will be used automatically if, and only if, the axes are specified as X and Y. Note that if you want to profile the data in the original grid units, you should specify the horizontal axis names.

Returns

If .as_table = FALSE, a CFArray instance, or a list thereof with each having one profile for each of the elements in the "location" vectors of argument ... and named with the respective .names value. If .as_table = TRUE, a data.table with a row for each element along all profiles, with a ".variable" column using the values from the .names argument.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFVariableBase$clone(deep = FALSE)

Arguments

CF data variable for the NASA L3b format

Description

This class represents a CF data variable that provides access to data sets in NASA level-3 binned format, used extensively for satellite imagery.

Super classes

ncdfCF::CFObject -> ncdfCF::CFVariableBase -> ncdfCF::CFVariable -> CFVariableL3b

Public fields

Methods

Public methods

• CFVariableL3b$new()

• CFVariableL3b$as_matrix()

• CFVariableL3b$data()

• CFVariableL3b$subset()

• CFVariableL3b$clone()

Method new()

Create an instance of this class.

Usage

CFVariableL3b$new(grp, units)

Arguments

Returns

An instance of this class.

Method as_matrix()

Read all the data from the file and turn the data into a matrix. If an aoi is specified, the data will be subset to that area.

This method returns a bare-bones matrix without any metadata or other identifying information. Use method data(), subset() or the [ operator rather than this method to obtain a more informative result.

Usage

CFVariableL3b$as_matrix(aoi = NULL)

Arguments

Returns

A matrix with the data of the variable in raw format.

Method data()

Retrieve all data of the L3b variable.

Usage

CFVariableL3b$data()

Returns

A CFArray instance with all data from this L3b variable.

Method subset()

This method extracts a subset of values from the data of the variable, with the range along both axes expressed in decimal degrees.

Usage

CFVariableL3b$subset(..., .aoi = NULL, rightmost.closed = FALSE)

Arguments

Details

The range of values along both axes of latitude and longitude is expressed in decimal degrees. 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 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.

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.

Returns

A CFArray instance, having an array with axes and attributes of the variable, or NULL if one or more of the elements in the ... 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

CFVariableL3b$clone(deep = FALSE)

Arguments

References

https://oceancolor.gsfc.nasa.gov/resources/docs/technical/ocean_level-3_binned_data_products.pdf

NetCDF dimension object

Description

This class represents an netCDF dimensions. It contains the information on a dimension that is stored in an netCDF file.

This class is not very useful for interactive use. Use the CFAxis descendent classes instead.

Super class

ncdfCF::NCObject -> NCDimension

Public fields

Methods

Public methods

• NCDimension$new()

• NCDimension$print()

• NCDimension$shard()

• NCDimension$write()

• NCDimension$clone()

Method new()

Create a new netCDF dimension. This class should not be instantiated directly, create CF objects instead. This class is instantiated when opening a netCDF resource.

Usage

NCDimension$new(id, name, length, unlim)

Arguments

Returns

A NCDimension instance.

Method print()

Summary of the NC dimension printed to the console.

Usage

NCDimension$print(...)

Arguments

Method shard()

Very concise information on the dimension. The information returned by this function is very concise and most useful when combined with similar information from other dimensions.

Usage

NCDimension$shard()

Returns

Character string with very basic dimension information.

Method write()

Write the dimension to a netCDF file.

Usage

NCDimension$write(h)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

NCDimension$clone(deep = FALSE)

Arguments

NetCDF group

Description

This class represents a netCDF group, the object that holds elements like dimensions and variables of a netCDF file. This class also holds references to any CF objects based on the netCDF elements held by the group.

Direct access to groups is usually not necessary. The principal objects held by the group, CF data variables and axes, are accessible via other means. Only for access to the group attributes is a reference to a group required.

Super class

ncdfCF::NCObject -> NCGroup

Public fields

Active bindings

Methods

Public methods

• NCGroup$new()

• NCGroup$print()

• NCGroup$hierarchy()

• NCGroup$find_by_name()

• NCGroup$find_dim_by_id()

• NCGroup$has_name()

• NCGroup$unused()

• NCGroup$addAuxiliaryLongLat()

• NCGroup$addCellMeasure()

• NCGroup$fullnames()

• NCGroup$dimensions()

• NCGroup$variables()

• NCGroup$axes()

• NCGroup$grid_mappings()

• NCGroup$clone()

Method new()

Create a new instance of this class.

Usage

NCGroup$new(id, name, fullname, parent, resource)

Arguments

Method print()

Summary of the group printed to the console.

Usage

NCGroup$print(stand_alone = TRUE, ...)

Arguments

Method hierarchy()

Prints the hierarchy of the group and its subgroups to the console, with a summary of contained objects. Usually called from the root group to display the full group hierarchy.

Usage

NCGroup$hierarchy(idx = 1L, total = 1L)

Arguments

Method find_by_name()

Find an object by its name. Given the name of an object, possibly preceded by an absolute or relative group path, return the object to the caller. Typically, this method is called programmatically; similar interactive use is provided through the ⁠[[.CFDataset⁠ operator.

Usage

NCGroup$find_by_name(name, scope = "CF")

Arguments

Returns

The object with the provided name in the requested scope. If the object is not found, returns NULL.

Method find_dim_by_id()

Find an NC dimension object by its id. Given the id of a dimension, return the NCDimension object to the caller. The dimension has to be found in the current group or any of its parents.

Usage

NCGroup$find_dim_by_id(id)

Arguments

Returns

The NCDimension object with an identifier equal to the id argument. If the object is not found, returns NULL.

Method has_name()

Has a given name been defined in this group already?

Usage

NCGroup$has_name(name, scope = "both")

Arguments

Returns

TRUE if name is present in the group, FALSE otherwise.

Method unused()

Find NC variables that are not referenced by CF objects. For debugging purposes only.

Usage

NCGroup$unused()

Returns

List of NCVariable.

Method addAuxiliaryLongLat()

Add an auxiliary long-lat variable to the group. This method creates a CFAuxiliaryLongLat from the arguments and adds it to the group CFlonglat list, but only if the combination of lon, lat isn't already present.

Usage

NCGroup$addAuxiliaryLongLat(lon, lat, bndsLong, bndsLat)

Arguments

Returns

self invisibly.

Method addCellMeasure()

Add a cell measure variable to the group.

Usage

NCGroup$addCellMeasure(cm)

Arguments

Returns

self invisibly.

Method fullnames()

This method lists the fully qualified name of this group, optionally including names in subgroups.

Usage

NCGroup$fullnames(recursive = TRUE)

Arguments

Returns

A character vector with group names.

Method dimensions()

List all the dimensions that are visible from this group including those that are defined in parent groups (by names not defined by any of their child groups in direct lineage to the current group).

Usage

NCGroup$dimensions()

Returns

A vector of NCDimension objects.

Method variables()

This method lists the CF data variables located in this group, optionally including data variables in subgroups.

Usage

NCGroup$variables(recursive = TRUE)

Arguments

Returns

A list of CFVariable.

Method axes()

This method lists the axes located in this group, optionally including axes in subgroups.

Usage

NCGroup$axes(recursive = TRUE)

Arguments

Returns

A list of CFAxis descendants.

Method grid_mappings()

This method lists the grid mappings located in this group, optionally including grid mappings in subgroups.

Usage

NCGroup$grid_mappings(recursive = TRUE)

Arguments

Returns

A list of CFGridMapping instances.

Method clone()

The objects of this class are cloneable with this method.

Usage

NCGroup$clone(deep = FALSE)

Arguments

NetCDF base object

Description

This class is a basic ancestor to all classes that represent netCDF objects, specifically groups, dimensions, variables and the user-defined types in a netCDF file. More useful classes use this class as ancestor.

The fields in this class are common among all netCDF objects. In addition, this class manages the attributes for its descendent classes.

Public fields

Methods

Public methods

• NCObject$new()

• NCObject$print_attributes()

• NCObject$attribute()

• NCObject$set_attribute()

• NCObject$append_attribute()

• NCObject$delete_attribute()

• NCObject$write_attributes()

• NCObject$add_coordinates()

• NCObject$clone()

Method new()

Create a new netCDF object. This class should not be instantiated directly, create descendant objects instead.

Usage

NCObject$new(id, name)

Arguments

Method print_attributes()

This function prints the attributes of the netCDF object to the console. Through object linkages, this also applies to the CF data variables and axes, which each link to a netCDF object.

Usage

NCObject$print_attributes(width = 50L)

Arguments

Method attribute()

This method returns an attribute of a netCDF object.

Usage

NCObject$attribute(att, field = "value")

Arguments

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. If an attribute name already exists, it will be overwritten.

Usage

NCObject$set_attribute(name, type, value)

Arguments

Returns

Self, invisibly.

Method append_attribute()

Append the text value of an 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

NCObject$append_attribute(name, value, sep = "; ", prepend = FALSE)

Arguments

Returns

Self, invisibly.

Method delete_attribute()

Delete attributes. If an attribute name is not present this method simply returns.

Usage

NCObject$delete_attribute(name)

Arguments

Returns

Self, invisibly.

Method write_attributes()

Write the attributes of this object to a netCDF file.

Usage

NCObject$write_attributes(nc, nm)

Arguments

Returns

Self, invisibly.

Method add_coordinates()

Add names of axes to the "coordinates" attribute, avoiding duplicates and retaining previous values.

Usage

NCObject$add_coordinates(crds)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

NCObject$clone(deep = FALSE)

Arguments

NetCDF user-defined type

Description

This class represents user-defined types in a netCDF file. Interpretation of the UDT typically requires knowledge of the data set or application.

Super class

ncdfCF::NCObject -> NCUDT

Public fields

Methods

Public methods

• NCUDT$new()

• NCUDT$clone()

Method new()

Create a new netCDF user-defined type. This class represents a user-defined type. It is instantiated when opening a netCDF resource.

Usage

NCUDT$new(id, name, clss, size, basetype, value, offset, subtype, dimsizes)

Arguments

Returns

An instance of this class.

Method clone()

The objects of this class are cloneable with this method.

Usage

NCUDT$clone(deep = FALSE)

Arguments

NetCDF variable

Description

This class represents a netCDF variable, the object that holds the properties and data of elements like dimensions and variables of a netCDF file.

Direct access to netCDF variables is usually not necessary. NetCDF variables are linked from CF data variables and axes and all relevant properties are thus made accessible.

Super class

ncdfCF::NCObject -> NCVariable

Public fields

Active bindings

Methods

Public methods

• NCVariable$new()

• NCVariable$print()

• NCVariable$shard()

• NCVariable$clone()

Method new()

Create a new netCDF variable. This class should not be instantiated directly, they are created automatically when opening a netCDF resource.

Usage

NCVariable$new(id, name, group, vtype, ndims, dimids)

Arguments

Returns

An instance of this class.

Method print()

Summary of the NC variable printed to the console.

Usage

NCVariable$print(...)

Arguments

Method 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.

Usage

NCVariable$shard()

Returns

Character string with very basic variable information.

Method clone()

The objects of this class are cloneable with this method.

Usage

NCVariable$clone(deep = FALSE)

Arguments

Extract data for a variable

Description

Extract data from a CFVariable instance, optionally sub-setting the axes to load only data of interest.

Usage

## S3 method for class 'CFVariable'
x[i, j, ..., drop = FALSE]

Arguments

Details

If all the data of the variable in x is to be extracted, simply use ⁠[]⁠ (unlike with regular arrays, this is required, otherwise the details of the variable are printed on the console).

The indices into the axes to be subset can be specified in a variety of ways; in practice it should (resolve to) be a vector of integers. A range (e.g. 100:200), an explicit 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. It is also possible to use a custom function as an argument.

This method works with "bare" indices into the axes of the array. If you want to use domain values of the axes (e.g. longitude values or timestamps) to extract part of the variable array, use the CFVariable$subset() method.

Scalar axes should not be included in the indexing as they do not represent a dimension into the data array.

Value

An array with dimnames and other attributes set.

Examples

fn <- system.file("extdata",
  "pr_day_EC-Earth3-CC_ssp245_r1i1p1f1_gr_20230101-20231231_vncdfCF.nc",
  package = "ncdfCF")
ds <- open_ncdf(fn)
pr <- ds[["pr"]]

# How are the dimensions organized?
dimnames(pr)

# Precipitation data for March for a single location
x <- pr[5, 12, 61:91]
str(x)

# Summer precipitation over the full spatial extent
summer <- pr[, , 173:263]
str(summer)

Extract data for a variable

Description

Extract data from a CFVariableL3b instance, optionally sub-setting the axes to load only data of interest.

Usage

## S3 method for class 'CFVariableL3b'
x[i, j, ..., drop = FALSE]

Arguments

Details

If all the data of the variable in x is to be extracted, simply use ⁠[]⁠ (unlike with regular arrays, this is required, otherwise the details of the variable are printed on the console).

The indices into the axes to be subset can be specified in a variety of ways; in practice it should (resolve to) be a vector of integers. A range (e.g. 100:200), an explicit 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. It is also possible to use a custom function as an argument.

This method works with "bare" indices into the axes of the array. If you want to use domain values of the axes (e.g. longitude values or timestamps) to extract part of the variable array, use the CFVariableL3b$subset() method.

Scalar axes should not be included in the indexing as they do not represent a dimension into the data array.

Value

An array with dimnames and other attributes set.

Examples

fn <- system.file("extdata",
  "pr_day_EC-Earth3-CC_ssp245_r1i1p1f1_gr_20230101-20231231_vncdfCF.nc",
  package = "ncdfCF")
ds <- open_ncdf(fn)
pr <- ds[["pr"]]

# How are the dimensions organized?
dimnames(pr)

# Precipitation data for March for a single location
x <- pr[5, 12, 61:91]
str(x)

# Summer precipitation over the full spatial extent
summer <- pr[, , 173:263]
str(summer)

Get a variable or axis object from a data set

Description

This method can be used to retrieve a variable or axis from the data set by name.

Usage

## S3 method for class 'CFDataset'
x[[i]]

Arguments

Details

If the data set has groups, the name i of the variable or axis should be fully qualified with the path to the group where the object is located. This fully qualified name can be retrieved with the names() and dimnames() functions, respectively.

Value

An instance of CFVariable or an CFAxis descendant class, or NULL if the name is not found.

Examples

fn <- system.file("extdata", "ERA5land_Rwanda_20160101.nc", package = "ncdfCF")
ds <- open_ncdf(fn)
v1 <- names(ds)[1]
var <- ds[[v1]]
var

Area of Interest

Description

This function constructs the area of interest of an analysis. It consists of an extent and a resolution of longitude and latitude, all in decimal degrees.

The AOI is used to define the subset of data to be extracted from a data variable that has an auxiliary longitude-latitude grid (see the CFAuxiliaryLongLat class) at a specified resolution. The data variable thus has a primary coordinate system where the horizontal components are not a geographic system of longitude and latitude coordinates.

Usage

aoi(lonMin, lonMax, latMin, latMax, resX, resY)

Arguments

Details

Following the CF Metadata Conventions, axis coordinates represent the center of grid cells. So when specifying aoi(20, 30, -10, 10, 1, 2), the south-west grid cell coordinate is at ⁠(20.5, -9)⁠. If the axes of the longitude-latitude grid have bounds, then the bounds will coincide with the AOI and the CFVariable$subset() method that uses the AOI will attach those bounds as attributes to the resulting array.

If no resolution is specified, it will be determined from the separation between adjacent grid cells in both longitude and latitude directions in the middle of the area of interest. If no extent is specified (meaning, none of the values; if some but not all values are specified an error will be thrown), then the whole extent of the variable is used, extended outwards by the bounds if they are set or half the resolution otherwise. Thus, to get the entire extent of the variable but in a longitude-latitude grid and with a resolution comparable to the resolution at the original Cartesian coordinate system of the variable, simply pass aoi() as an argument to CFVariable$subset(). Note that any missing arguments are calculated internally and stored in the returned object, but only after the call to CFVariable$subset().

Caching

In data collections that are composed of multiple data variables in a single netCDF resource, a single auxiliary longitude-latitude grid may be referenced by multiple data variables, such as in ROMS data which may have dozens of data variables using a shared grid. When subsetting with an AOI, the instance of this class is cached to improve performance. The successive calls to CFVariable$subset() should use the same object returned from a single call to this function for this caching to work properly.

Value

The return value of the function is an R6 object which uses reference semantics. Making changes to the returned object will be visible in all copies made of the object.

Examples

(aoi <- aoi(20, 60, -40, -20, 0.5))

The dimensions of the grid of an AOI

Description

This method returns the dimensions of the grid that would be created for the AOI.

Usage

## S3 method for class 'AOI'
dim(x)

Arguments

Value

A vector of two values giving the longitude and latitude dimensions of the grid that would be created for the AOI.

Examples

a <- aoi(30, 40, 10, 30, 0.1)
dim(a)

Axis length

Description

This method returns the lengths of the axes of a variable or axis.

Usage

## S3 method for class 'CFAxis'
dim(x)

Arguments

Value

Vector of axis lengths.

Examples

fn <- system.file("extdata", "ERA5land_Rwanda_20160101.nc", package = "ncdfCF")
ds <- open_ncdf(fn)
t2m <- ds[["t2m"]]
dim(t2m)

Create an axis

Description

With this method you can create an axis to use with new CFArray instances. Depending on the orientation argument and the type of the values argument an instance of a class descending from CFAxis will be returned.

Usage

makeAxis(name, group, orientation, values, bounds = NULL)

Arguments

Details

There are several restrictions on the combination of orientation and values arguments. Longitude and latitude axes (orientation of "X" or "Y") must have numeric values. For a time axis (orientation of "T") the values argument must be an instance of CFTime or CFClimatology.

Value

An instance of a class descending from CFAxis.

See Also

makeLongitudeAxis(), makeLatitudeAxis(), makeTimeAxis(), makeDiscreteAxis()

Create a discrete axis

Description

With this method you can create a discrete axis to use with new CFArray instances.

Usage

makeDiscreteAxis(name, group, length)

Arguments

Value

A CFAxisDiscrete instance. The values will be a sequence of size length.

Create a group in memory to hold CF objects

Description

With this function a group is created in memory, i.e. not associated with a netCDF resource on file. This can be used to prepare new CF objects before writing them to file. Extracting data from a CFVariable into a CFArray instance will also create a virtual group.

Usage

makeGroup(id = -1L, name = "/", fullname = "/", parent = NULL)

Arguments

Value

A NCGroup instance.

Create a latitude axis

Description

With this method you can create a latitude axis to use with new CFArray instances.

Usage

makeLatitudeAxis(name, group, values, bounds)

Arguments

Value

A CFAxisLatitude instance.

Create a longitude axis

Description

With this method you can create a longitude axis to use with new CFArray instances.

Usage

makeLongitudeAxis(name, group, values, bounds = NULL)

Arguments

Value

A CFAxisLongitude instance.

Create a time axis

Description

With this method you can create a time axis to use with new CFArray instances.

Usage

makeTimeAxis(name, group, values)

Arguments

Value

A CFAxisTime instance.

Names or dimension values of an CF object

Description

Retrieve the variable or dimension names of an ncdfCF object. The names() function gives the names of the variables in the data set, prepended with the path to the group if the resource uses groups. The return value of the dimnames() function differs depending on the type of object:

• CFDataset, CFVariable: The dimnames are returned as a vector of the names of the axes of the data set or variable, prepended with the path to the group if the resource uses groups. Note that this differs markedly from the base::dimnames() functionality.

• CFAxisNumeric, CFAxisLongitude, CFAxisLatitude, CFAxisVertical: The values of the elements along the axis as a numeric vector.

• CFAxisTime: The values of the elements along the axis as a character vector containing timestamps in ISO8601 format. This could be dates or date-times if time information is available in the axis.

• CFAxisCharacter: The values of the elements along the axis as a character vector.

• CFAxisDiscrete: The index values of the axis, from 1 to the length of the axis.

Usage

## S3 method for class 'CFDataset'
names(x)

groups(x)

## S3 method for class 'CFDataset'
groups(x)

Arguments

Value

A vector as described in the Description section.

Examples

fn <- system.file("extdata",
  "pr_day_EC-Earth3-CC_ssp245_r1i1p1f1_gr_20230101-20231231_vncdfCF.nc",
  package = "ncdfCF")
ds <- open_ncdf(fn)

# CFDataset
dimnames(ds)

# CFVariable
pr <- ds[["pr"]]
dimnames(pr)

# CFAxisNumeric
lon <- ds[["lon"]]
dimnames(lon)

# CFAxisTime
t <- ds[["time"]]
dimnames(t)

Open a netCDF resource

Description

This function will read the metadata of a netCDF resource and interpret the netCDF dimensions, variables and attributes to generate the corresponding CF objects. The data for the CF variables is not read, please see CFVariable for methods to read the variable data.

Usage

open_ncdf(resource, keep_open = FALSE)

Arguments

Value

An CFDataset instance, or an error if the resource was not found or errored upon reading.

Examples

fn <- system.file("extdata",
  "pr_day_EC-Earth3-CC_ssp245_r1i1p1f1_gr_20230101-20231231_vncdfCF.nc",
  package = "ncdfCF")
(ds <- open_ncdf(fn))

Examine a netCDF resource

Description

This function will read a netCDF resource and return a list of identifying information, including data variables, axes and global attributes. Upon returning the netCDF resource is closed.

Usage

peek_ncdf(resource)

Arguments

Details

If you find that you need other information to be included in the result, open an issue.

Value

A list with elements "variables", "axes" and global "attributes", each a data.frame.

Examples

fn <- system.file("extdata",
  "pr_day_EC-Earth3-CC_ssp245_r1i1p1f1_gr_20230101-20231231_vncdfCF.nc",
  package = "ncdfCF")
peek_ncdf(fn)

Compact display of an axis.

Description

Compact display of an axis.

Usage

## S3 method for class 'CFAxis'
str(object, ...)

Arguments

Compact display of a CFDataset

Description

Compact display of a CFDataset

Usage

## S3 method for class 'CFDataset'
str(object, ...)

Arguments