Package 'ncdfCF'

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)

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

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 variable that has an auxiliary longitude-latitude grid (see the CFAuxiliaryLongLat class) at a specified resolution. The 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 variables in a single netCDF resource, a single auxiliary longitude-latitude grid may be referenced by multiple variables, such as in ROMS data which may have dozens of 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))

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.

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.

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 = 0.1)

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

Description

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

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$sub_axis()

• CFAxis$indexOf()

• CFAxis$label_set()

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

Usage

CFAxis$new(grp, 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()

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. This stub is here to make the call to this method succeed with no result for the other axis descendants.

Usage

CFAxis$time()

Returns

NULL

Method sub_axis()

Return an axis spanning a smaller dimension 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 other axis descendants that do not implement this method.

Usage

CFAxis$sub_axis(group, rng = NULL)

Arguments

Returns

NULL

Method indexOf()

Find indices in the axis domain. Given a vector of numerical, timestamp or categorical values x, find their indices in the values of the axis. With method = "constant" this returns the index of the value lower than the supplied values in x. With method = "linear" the return value includes any fractional part.

If bounds are set on the numerical or time axis, the indices are taken from those bounds. Returned indices may fall in between bounds if the latter are not contiguous, with the exception of the extreme values in x.

Usage

CFAxis$indexOf(x, method = "constant")

Arguments

Returns

Numeric vector of the same length as x. If method = "constant", return the index value for each match. If method = "linear", return the index value with any fractional value. Values of x outside of the range of the values in the axis are returned as 0 and .Machine$integer.max, respectively.

Method label_set()

Retrieve a set of character labels corresponding to the elements of an axis. An axis can have multiple sets of labels and by default the first set is returned.

Usage

CFAxis$label_set(index = 1L)

Arguments

Returns

A character vector of string labels with as many elements as the axis has, or NULL when no labels have been set or when argument index is not valid.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxis$clone(deep = FALSE)

Arguments

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.

Super classes

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

Public fields

Active bindings

Methods

Public methods

• CFAxisCharacter$new()

• CFAxisCharacter$brief()

• CFAxisCharacter$indexOf()

• CFAxisCharacter$clone()

Method new()

Create a new instance of this class.

Usage

CFAxisCharacter$new(grp, 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 indexOf()

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

Usage

CFAxisCharacter$indexOf(x, method = "constant")

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

The objects of this class are cloneable with this method.

Usage

CFAxisCharacter$clone(deep = FALSE)

Arguments

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$brief()

• CFAxisDiscrete$indexOf()

• CFAxisDiscrete$clone()

Method new()

Create a new instance of this class.

Usage

CFAxisDiscrete$new(grp, nc_var, nc_dim, orientation)

Arguments

Method brief()

Some details of the axis.

Usage

CFAxisDiscrete$brief()

Returns

A 1-row data.frame with some details of the 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")

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 0 and .Machine$integer.max, respectively.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisDiscrete$clone(deep = FALSE)

Arguments

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$sub_axis()

• CFAxisLatitude$clone()

Method new()

Create a new instance of this class.

Usage

CFAxisLatitude$new(grp, nc_var, nc_dim, values)

Arguments

Method sub_axis()

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

Usage

CFAxisLatitude$sub_axis(group, rng = NULL)

Arguments

Returns

A CFAxisLatitude instance covering the indicated range of indices. If the rng argument includes only a single value, an CFAxisScalar instance is returned with the value from this axis. If the value of the argument is NULL, return the entire axis (possibly as a scalar axis).

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisLatitude$clone(deep = FALSE)

Arguments

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$sub_axis()

• CFAxisLongitude$clone()

Method new()

Create a new instance of this class.

Usage

CFAxisLongitude$new(grp, nc_var, nc_dim, values)

Arguments

Method sub_axis()

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

Usage

CFAxisLongitude$sub_axis(group, rng = NULL)

Arguments

Returns

A CFAxisLongitude instance covering the indicated range of indices. If the rng argument includes only a single value, an CFAxisScalar instance is returned with the value from this axis. If the value of the argument is NULL, return the entire axis (possibly as a scalar axis).

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisLongitude$clone(deep = FALSE)

Arguments

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

Public fields

Active bindings

Methods

Public methods

• CFAxisNumeric$new()

• CFAxisNumeric$print()

• CFAxisNumeric$brief()

• CFAxisNumeric$range()

• CFAxisNumeric$indexOf()

• CFAxisNumeric$sub_axis()

• CFAxisNumeric$clone()

Method new()

Create a new instance of this class.

Usage

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

Arguments

Method print()

Summary of the time axis printed to the console.

Usage

CFAxisNumeric$print()

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 values on the axis. If the axis has bounds then the supplied values must fall within the bounds to be considered valid.

Usage

CFAxisNumeric$indexOf(x, method = "constant")

Arguments

Returns

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

Method sub_axis()

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

Usage

CFAxisNumeric$sub_axis(group, rng = NULL)

Arguments

Returns

A CFAxisNumeric instance covering the indicated range of indices. If the rng argument includes only a single value, an CFAxisScalar instance is returned with the value from this axis. If the value of the argument is NULL, return the entire axis (possibly as a scalar axis).

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisNumeric$clone(deep = FALSE)

Arguments

Description

This class represents a scalar axis. Its single value can be of any type. It is typically used as an auxiliary axis to record some parameter of interest such as the single time associated with a spatial grid with longitude, latitude and vertical axes.

Super classes

ncdfCF::CFObject -> ncdfCF::CFAxis -> CFAxisScalar

Public fields

Active bindings

Methods

Public methods

• CFAxisScalar$new()

• CFAxisScalar$print()

• CFAxisScalar$brief()

• CFAxisScalar$sub_axis()

• CFAxisScalar$clone()

Method new()

Create an instance of this class.

Usage

CFAxisScalar$new(grp, nc_var, orientation, value)

Arguments

Method print()

Summary of the scalar axis printed to the console.

Usage

CFAxisScalar$print()

Method brief()

Some details of the axis.

Usage

CFAxisScalar$brief()

Returns

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

Method sub_axis()

Return the axis. This method returns a clone of this axis, given that a scalar axis cannot be subset.

Usage

CFAxisScalar$sub_axis(group, rng = NULL)

Arguments

Returns

A CFAxisScalar cloned from this axis.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisScalar$clone(deep = FALSE)

Arguments

Description

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

Super classes

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

Public fields

Active bindings

Methods

Public methods

• CFAxisTime$new()

• CFAxisTime$print()

• CFAxisTime$brief()

• CFAxisTime$time()

• CFAxisTime$indexOf()

• CFAxisTime$sub_axis()

• CFAxisTime$clone()

Method new()

Create a new instance of this class.

Usage

CFAxisTime$new(grp, nc_var, nc_dim, values)

Arguments

Method print()

Summary of the time axis printed to the console.

Usage

CFAxisTime$print()

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

Usage

CFAxisTime$time()

Returns

An instance of CFtime.

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 integer(0) if none of the values are valid.

Method sub_axis()

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

Usage

CFAxisTime$sub_axis(group, rng = NULL)

Arguments

Returns

A CFAxisTime instance covering the indicated range of indices. If the rng argument includes only a single value, an CFAxisScalar instance is returned with its value being the character timestamp of the value in this axis. If the value of the argument is NULL, return the entire axis (possibly as a scalar axis).

Method clone()

The objects of this class are cloneable with this method.

Usage

CFAxisTime$clone(deep = FALSE)

Arguments

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(grp, 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.11/cf-conventions.html#parametric-vertical-coordinate

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

Method new()

Create an instance of this class.

Usage

CFBounds$new(nc_var, values)

Arguments

Method print()

Print a summary of the object to the console.

Usage

CFBounds$print()

Method range()

Retrieve the lowest and highest value in the bounds.

Usage

CFBounds$range()

Method sub_bounds()

Return bounds spanning a smaller dimension 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 clone()

The objects of this class are cloneable with this method.

Usage

CFBounds$clone(deep = FALSE)

Arguments

Description

This class holds the data that is extracted from a CFVariable, using the subset() 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.

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.

  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 class

ncdfCF::CFObject -> CFData

Public fields

Methods

Public methods

• CFData$new()

• CFData$print()

• CFData$raw()

• CFData$array()

• CFData$terra()

• CFData$clone()

Method new()

Create an instance of this class.

Usage

CFData$new(name, group, value, axes, crs, attributes)

Arguments

Returns

An instance of this class.

Method print()

Print a summary of the data object to the console.

Usage

CFData$print()

Method raw()

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

Usage

CFData$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

CFData$array()

Returns

An array of data in R ordering.

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.

Usage

CFData$terra()

Returns

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

Method clone()

The objects of this class are cloneable with this method.

Usage

CFData$clone(deep = FALSE)

Arguments

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

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" or "length", a character vector named with the att values that were found in the attributes. If argument field is "value", a list with elements named with the att values, containing the attribute value(s), except when argument att names a single attribute, in which case that attribute value is returned as a character string. If no attribute is named with a value of argument att an empty list is returned, or an empty string if there was only one value in argument att.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFDataset$clone(deep = FALSE)

Arguments

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$crs()

• CFGridMapping$clone()

Method new()

Create a new instance of this class.

Usage

CFGridMapping$new(grp, 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 crs()

Retrieve the CRS string for a specific variable.

Usage

CFGridMapping$crs(axis_info)

Arguments

Returns

A character string with the CRS in WKT2 format.

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

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

Method new()

Create a new instance of this class.

Usage

CFLabel$new(grp, nc_var, nc_dim, values)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CFLabel$clone(deep = FALSE)

Arguments

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$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, group)

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" or "length", a character vector named with the att values that were found in the attributes. If argument field is "value", a list with elements named with the att values, containing the attribute value(s), except when argument att names a single attribute, in which case that attribute value is returned as a character string. If no attribute is named with a value of argument att an empty list is returned, or an empty string if there was only one value in argument att.

Method print_attributes()

Print the attributes of the CF object to the console.

Usage

CFObject$print_attributes(width = 50L)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CFObject$clone(deep = FALSE)

Arguments

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 and CFVariable 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$finalize()

• 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 finalize()

This method is called automatically when the instance is deleted, ensuring that file handles are properly closed.

Usage

CFResource$finalize()

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

Description

This class represents a CF data variable, the object that provides access to an array of data.

The CF data variable instance provides access to the data array from the netCDF resource, as well as all the details that have been associated with the data variable, such as axis information, grid mapping parameters, etc.

Super class

ncdfCF::CFObject -> CFVariable

Public fields

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(grp, 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()

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. Scalar variables are not present in the result.

Usage

CFVariable$data()

Returns

A CFData instance with all data from this variable.

Method subset()

This method extracts a subset of values from the array of the variable, with the range along each axis to extract expressed in values of the domain of each axis.

Usage

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

Arguments

Details

The range of values along each axis to be subset is expressed in values of the domain of the axis. Any axes for which no information is provided in the subset argument are extracted in whole. Values can be specified in a variety of ways that are specific to the nature of the axis. For numeric axes it should (resolve to) be a vector of real values. A range (e.g. 100:200), a vector (⁠c(23, 46, 3, 45, 17⁠), a sequence (⁠seq(from = 78, to = 100, by = 2⁠), all work. Note, however, that only a single range is generated from the vector so these examples resolve to ⁠(100, 200)⁠, ⁠(3, 46)⁠, and ⁠(78, 100)⁠, respectively. For time axes a vector of character timestamps, POSIXct or Date values must be specified. As with numeric values, only the two extreme values in the vector will be used.

If the range of values for an axis in argument subset extend the valid range of the axis in x, the extracted slab will start at the beginning for smaller values and extend to the end for larger values. If the values envelope the valid range the entire axis will be extracted in the result. If the range of subset values for any axis are all either smaller or larger than the valid range of the axis in x then nothing is extracted and NULL is returned.

The extracted data has the same dimensional structure as the data in the variable, with degenerate dimensions dropped. The order of the axes in argument subset does not reorder the axes in the result; use the CFData$array() method for this.

As an example, to extract values of a variable for Australia for the year 2020, where the first axis in x is the longitude, the second axis is the latitude, both in degrees, and the third (and final) axis is time, the values are extracted by x$subset(list(X = c(112, 154), Y = c(-9, -44), T = c("2020-01-01", "2021-01-01"))). You could take the longitude-latitude values from sf::st_bbox() or terra::ext() if you have specific spatial geometries for whom you want to extract data. Note that this works equally well for projected coordinate reference systems - the key is that the specification in argument subset uses the same domain of values as the respective axes in x use.

Auxiliary coordinate variables

A special case exists for variables where the horizontal dimensions (X and Y) are not in longitude and latitude values but in some other coordinate system. In this case the netCDF resource may have so-called auxiliary coordinate variables for longitude and latitude that are two grids with the same dimension as the horizontal axes of the data variable where each pixel gives the corresponding value for the longitude and latitude. If the variable has such auxiliary coordinate variables then they will be used automatically if, and only if, the axes are labeled in argument subset as X and Y. The resolution of the grid that is produced by this method is automatically calculated. If you want to subset those axes then specify values in decimal degrees; if you want to extract the full extent, specify NA. Note that if you want to extract the data in the original grid, you should use the horizontal axis names in argument subset.

Returns

An CFData instance, having an array with its axes and attributes of the variable, or NULL if one or more of the elements in the subset argument falls entirely outside of the range of the axis. Note that degenerate dimensions (having length(.) == 1) are dropped from the array but the corresponding axis is maintained in the result as a scalar axis.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFVariable$clone(deep = FALSE)

Arguments

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)

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

Examples

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

Description

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

Usage

makeLatitudeAxis(id, name, group, length, values, bounds, units)

Arguments

Value

A CFAxisLatitude instance.

Description

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

Usage

makeLongitudeAxis(id, name, group, length, values, bounds = NULL, units = "")

Arguments

Value

A CFAxisLongitude instance.

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 CFData instance will also create a memory group.

Usage

makeMemoryGroup(id, name, fullname, title, history)

Arguments

Value

A MemoryGroup instance.

Description

This class represents a CF group in memory. It descends from NCGroup and functions as such with the exception that it has no associated CFResource and the handle field thus always returns NULL.

Details

This object descends from NCGroup and functions as such with the exception that it has no associated CFResource and the handle field thus always returns NULL.

Super classes

ncdfCF::NCObject -> ncdfCF::NCGroup -> MemoryGroup

Active bindings

Methods

Public methods

• MemoryGroup$new()

• MemoryGroup$clone()

Method new()

Create an instance of this class.

Usage

MemoryGroup$new(id, name, fullname, parent, title, history)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

MemoryGroup$clone(deep = FALSE)

Arguments

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.

• CFAxisScalar: The value of the scalar.

• 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)

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

The objects of this class are cloneable with this method.

Usage

NCDimension$clone(deep = FALSE)

Arguments

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$unused()

• NCGroup$addAuxiliaryLongLat()

• NCGroup$fullnames()

• 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(...)

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

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$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 netCDF object attributes.

Usage

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

Arguments

Returns

If the field argument is "type" or "length", a character vector named with the att values that were found in the attributes. If argument field is "value", a list with elements named with the att values, containing the attribute value(s), except when argument att names a single attribute, in which case that attribute value is returned as a character string. If no attribute is named with a value of argument att an empty list is returned, or an empty string if there was only one value in argument att.

Method clone()

The objects of this class are cloneable with this method.

Usage

NCObject$clone(deep = FALSE)

Arguments

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

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

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

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: https://github.com/pvanlaake/ncdfCF/issues.

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)