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 most common features of the CF conventions, including group traversal with scoping rules, 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.

• Calculate coordinate fields for parametric vertical axes.

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 from a file or an online resource.

• 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 any other named 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 value 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

• subset(): Select a subset of data from a variable by specifying extents in real-world coordinates for the axes into a CFVariable 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 CFVariable 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 CFVariable objects is returned, one for each result of the function.

• profile(): Extract a profile of data from the variable into a CFVariable or a data.table. Profiles can be for a single location, or zonal (e.g. across a longitude); multiple profiles can be extracted in a single call.

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

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

New data variables

New CFVariable objects can be constructed from R vectors, matrices or arrays, optionally creating axes from dimnames on the R object, using the as_CF() 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.

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.

• coordinate_range: A vector with the extreme coordinate values of the axis.

S3 methods for CFAxis

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

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

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 of this class manually therefore has no practical purpose.

Active bindings

Methods

Public methods

• CFAuxiliaryLongLat$new()

• CFAuxiliaryLongLat$print()

• CFAuxiliaryLongLat$brief()

• CFAuxiliaryLongLat$sample_index()

• CFAuxiliaryLongLat$grid_index()

• CFAuxiliaryLongLat$clear_cache()

• CFAuxiliaryLongLat$detach()

• 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 = NULL, boundsLat = NULL)

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

Method detach()

Detach the latitude and longitude from an underlying netCDF resource.

Usage

CFAuxiliaryLongLat$detach()

Returns

Self, invisibly.

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

Active bindings

Methods

Public methods

• CFAxis$new()

• CFAxis$print()

• CFAxis$brief()

• CFAxis$shard()

• CFAxis$peek()

• CFAxis$detach()

• CFAxis$copy_terms()

• CFAxis$configure_terms()

• CFAxis$identical()

• CFAxis$can_append()

• CFAxis$copy()

• CFAxis$copy_with_values()

• CFAxis$subset()

• CFAxis$indexOf()

• CFAxis$write()

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(
  var,
  values,
  start = 1L,
  count = NA,
  orientation = "",
  attributes = data.frame()
)

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

Returns

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

Method detach()

Detach the axis from its underlying netCDF resource, including any dependent CF objects.

Usage

CFAxis$detach()

Returns

Self, invisibly.

Method copy_terms()

Copy the parametric terms of a vertical axis. This method is only useful for CFAxisVertical instances having a parametric formulation. This stub is here to make the call to this method succeed with no result for the other descendant classes.

Usage

CFAxis$copy_terms(from, original_axes, new_axes)

Arguments

Returns

NULL

Method configure_terms()

Configure the function terms of a parametric vertical axis. This method is only useful for CFAxisVertical instances having a parametric formulation. This stub is here to make the call to this method succeed with no result for the other descendant classes.

Usage

CFAxis$configure_terms(axes)

Arguments

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

Create a copy of this axis. 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$copy(name = "")

Arguments

Returns

NULL

Method copy_with_values()

Create a copy of this axis but using the supplied values. 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$copy_with_values(name = "", values)

Arguments

Returns

NULL

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 self. 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(name = "", 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.

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

• CFAxisCharacter$copy_with_values()

• CFAxisCharacter$slice()

• CFAxisCharacter$subset()

• CFAxisCharacter$identical()

• CFAxisCharacter$append()

• CFAxisCharacter$indexOf()

Method new()

Create a new instance of this class.

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

Usage

CFAxisCharacter$new(
  var,
  values,
  start = 1L,
  count = NA,
  attributes = data.frame()
)

Arguments

Method brief()

Some details of the axis.

Usage

CFAxisCharacter$brief()

Returns

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

Method copy()

Create a copy of this axis. The copy is completely separate from this axis, meaning that the new axis and all of its components are made from new instances. If this axis is backed by a netCDF resource, the copy will retain the reference to the resource.

Usage

CFAxisCharacter$copy(name = "")

Arguments

Returns

The newly created axis.

Method copy_with_values()

Create a copy of this axis but using the supplied values. The attributes are copied to the new axis. Boundary values and auxiliary coordinates are not copied.

After this operation the attributes of the newly created axes may not be accurate, except for the "actual_range" attribute. The calling code should set, modify or delete attributes as appropriate.

Usage

CFAxisCharacter$copy_with_values(name = "", values)

Arguments

Returns

The newly created axis.

Method slice()

Given a range of domain coordinate values, returns the indices into the axis that fall within the supplied range.

Usage

CFAxisCharacter$slice(rng)

Arguments

Returns

An integer vector of length 2 with the lower and higher indices into the axis that fall within the range of coordinates in argument rng. Returns NULL if no values of the axis fall within the range of coordinates.

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

CFAxisCharacter$subset(name = "", rng = NULL)

Arguments

Returns

A new CFAxisCharacter instance covering the indicated range of indices. If the value of the argument rng is NULL, return a copy of this axis as the new 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.

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

• CFAxisDiscrete$indexOf()

• CFAxisDiscrete$slice()

• CFAxisDiscrete$subset()

• CFAxisDiscrete$append()

• CFAxisDiscrete$write()

Method new()

Create a new instance of this class. The values of this axis are always a sequence, but the sequence may start with any positive value such that the length of this instance falls within the length of the axis on file, if there is one.

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

Usage

CFAxisDiscrete$new(var, start = 1L, count)

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

Create a copy of this axis. The copy is completely separate from this axis, meaning that both this axis and all of its components are made from new instances.

Usage

CFAxisDiscrete$copy(name = "")

Arguments

Returns

The newly created 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. 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 slice()

Given a range of coordinate values, returns the indices into the axis that fall within the supplied range. If the axis has auxiliary coordinates selected then these will be used for the identification of the indices to return.

Usage

CFAxisDiscrete$slice(rng)

Arguments

Returns

An integer vector of length 2 with the lower and higher indices into the axis that fall within the range of coordinates in argument rng. Returns NULL if no (boundary) values of the axis fall within the range of coordinates.

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(name = "", rng = NULL)

Arguments

Returns

A new CFAxisDiscrete instance covering the indicated range of indices. If the value of the argument is NULL, return a copy of self as the new axis.

Method append()

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

Usage

CFAxisDiscrete$append(from)

Arguments

Returns

A new CFAxisDiscrete instance with a length that is the sum of the lengths of this axis and the from 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.

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

• CFAxisLatitude$copy_with_values()

• CFAxisLatitude$subset()

• CFAxisLatitude$append()

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(
  var,
  values,
  start = 1L,
  count = NA,
  attributes = data.frame()
)

Arguments

Method copy()

Create a copy of this axis. The copy is completely separate from self, meaning that both self and all of its components are made from new instances.

Usage

CFAxisLatitude$copy(name = "")

Arguments

Returns

The newly created axis.

Method copy_with_values()

Create a copy of this axis but using the supplied values. The attributes are copied to the new axis. Boundary values and auxiliary coordinates are not copied.

After this operation the attributes of the newly created axes may not be accurate, except for the "actual_range" attribute. The calling code should set, modify or delete attributes as appropriate.

Usage

CFAxisLatitude$copy_with_values(name = "", values)

Arguments

Returns

The newly created axis.

Method subset()

Return alatitude 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(name = "", rng = NULL)

Arguments

Returns

A new CFAxisLatitude instance covering the indicated range of indices. If the value of the argument rng is NULL, return a copy of self as the new axis.

Method append()

Append a vector of values at the end of the current values of the axis. Boundary values are appended as well but if either this axis or the from axis does not have boundary values, neither will the resulting axis.

Usage

CFAxisLatitude$append(from)

Arguments

Returns

A new CFAxisLatitude instance with values from this axis and the from axis appended.

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

• CFAxisLongitude$copy_with_values()

• CFAxisLongitude$subset()

• CFAxisLongitude$append()

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(
  var,
  values,
  start = 1L,
  count = NA,
  attributes = data.frame()
)

Arguments

Method copy()

Create a copy of this axis. The copy is completely separate from self, meaning that both self and all of its components are made from new instances.

Usage

CFAxisLongitude$copy(name = "")

Arguments

Returns

The newly created axis.

Method copy_with_values()

Create a copy of this axis but using the supplied values. The attributes are copied to the new axis. Boundary values and auxiliary coordinates are not copied.

After this operation the attributes of the newly created axes may not be accurate, except for the "actual_range" attribute. The calling code should set, modify or delete attributes as appropriate.

Usage

CFAxisLongitude$copy_with_values(name = "", values)

Arguments

Returns

The newly created axis.

Method subset()

Return a longitude 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(name = "", rng = NULL)

Arguments

Returns

A new CFAxisLongitude instance covering the indicated range of indices. If the value of the argument rng is NULL, return a copy of self as the new axis.

Method append()

Append a vector of values at the end of the current values of the axis. Boundary values are appended as well but if either this axis or the from axis does not have boundary values, neither will the resulting axis.

Usage

CFAxisLongitude$append(from)

Arguments

Returns

A new CFAxisLongitude instance with values from this axis and the from axis appended.

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

• CFAxisNumeric$copy()

• CFAxisNumeric$copy_with_values()

• CFAxisNumeric$identical()

• CFAxisNumeric$append()

• CFAxisNumeric$subset()

Method new()

Create a new instance of this class.

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

Usage

CFAxisNumeric$new(
  var,
  values,
  start = 1L,
  count = NA,
  orientation = "",
  attributes = data.frame()
)

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 boundary values then the supplied coordinates must fall within the boundaries of an axis coordinate 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. If the axis has boundary values, then values of x that do not fall on or between the boundaries of an axis coordinate are returned as NA.

Method slice()

Given a range of domain coordinate values, returns the indices into the axis that fall within the supplied range. If the axis has bounds, any coordinate whose boundary values fall entirely or partially within the supplied range will be included in the result.

Usage

CFAxisNumeric$slice(rng)

Arguments

Returns

An integer vector of length 2 with the lower and higher indices into the axis that fall within the range of coordinates in argument rng. Returns NULL if no (boundary) values of the axis fall within the range of coordinates.

Method copy()

Create a copy of this axis. The copy is completely separate from self, meaning that both self and all of its components are made from new instances.

Usage

CFAxisNumeric$copy(name = "")

Arguments

Returns

The newly created axis.

Method copy_with_values()

Create a copy of this axis but using the supplied values. The attributes are copied to the new axis. Boundary values and auxiliary coordinates are not copied.

After this operation the attributes of the newly created axes may not be accurate, except for the "actual_range" attribute. The calling code should set, modify or delete attributes as appropriate.

Usage

CFAxisNumeric$copy_with_values(name = "", values)

Arguments

Returns

The newly created axis.

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. Boundary values are appended as well but if either this axis or the from axis does not have boundary values, neither will the resulting axis.

Usage

CFAxisNumeric$append(from)

Arguments

Returns

A new CFAxisNumeric instance with values from this axis 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(name = "", rng = NULL)

Arguments

Returns

A new CFAxisNumeric instance covering the indicated range of indices. If the value of the argument rng is NULL, return a copy of this axis as the new axis.

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

• CFAxisTime$copy()

• CFAxisTime$copy_with_values()

• CFAxisTime$append()

• CFAxisTime$indexOf()

• CFAxisTime$slice()

• CFAxisTime$subset()

• CFAxisTime$write()

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(var, values, start = 1L, count = NA, attributes = data.frame())

Arguments

Method print()

Summary of the time axis printed to the console.

Usage

CFAxisTime$print(...)

Arguments

Method brief()

Some details of the axis.

Usage

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

CFAxisTime$identical(axis)

Arguments

Returns

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

Method copy()

Create a copy of this axis. The copy is completely separate from self, meaning that both self and all of its components are made from new instances.

Usage

CFAxisTime$copy(name = "")

Arguments

Returns

The newly created axis.

Method copy_with_values()

Create a copy of this axis but using the supplied values. The attributes are copied to the new axis. Boundary values and auxiliary coordinates are not copied.

After this operation the attributes of the newly created axes may not be accurate, except for the "actual_range" attribute. The calling code should set, modify or delete attributes as appropriate.

Usage

CFAxisTime$copy_with_values(name = "", values)

Arguments

Returns

The newly created axis.

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

A 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(name = "", rng = NULL)

Arguments

Returns

A new CFAxisNumeric instance covering the indicated range of indices. If the value of the argument rng is NULL, return a copy of self as the new 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.

Vertical CF axis object

Description

This class represents a vertical axis, which may be parametric. A regular vertical axis behaves like any other numeric axis. A parametric vertical axis, on the other hand, is defined through an index value that is contained in the axis coordinates, with additional data variables that hold ancillary "formula terms" with which to calculate dimensional axis coordinates. It is used in atmosphere and ocean data sets.

Parametric vertical axes can only be read from file, not created from scratch.

Super classes

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

Active bindings

Methods

Public methods

• CFAxisVertical$new()

• CFAxisVertical$detach()

• CFAxisVertical$copy()

• CFAxisVertical$copy_with_values()

• CFAxisVertical$set_parametric_terms()

• CFAxisVertical$append()

• CFAxisVertical$subset()

• CFAxisVertical$subset_parametric_terms()

Method new()

Create a new instance of this class.

Usage

CFAxisVertical$new(
  var,
  values,
  start = 1L,
  count = NA,
  attributes = data.frame()
)

Arguments

Method detach()

Detach the parametric terms from an underlying netCDF resource.

Usage

CFAxisVertical$detach()

Returns

Self, invisibly.

Method copy()

Create a copy of this axis. The copy is completely separate from this instance, meaning that the copies of both this instance and all of its components are made as new instances.

Usage

CFAxisVertical$copy(name = "")

Arguments

Returns

The newly created axis.

Method copy_with_values()

Create a copy of this axis but using the supplied values. The attributes are copied to the new axis. Boundary values, parametric coordinates and auxiliary coordinates are not copied.

After this operation the attributes of the newly created axes may not be accurate, except for the "actual_range" attribute. The calling code should set, modify or delete attributes as appropriate.

Usage

CFAxisVertical$copy_with_values(name = "", values)

Arguments

Returns

The newly created axis.

Method set_parametric_terms()

Set the parametric terms for this axis. The name and the terms have to fully describe a CF parametric vertical axis.

The terms must also agree with the other axes used by any data variable that refers to this axis. That is not checked here so the calling code must make that assertion.

Usage

CFAxisVertical$set_parametric_terms(sn, terms)

Arguments

Method append()

Append a vector of values at the end of the current values of the axis. Boundary values are appended as well but if either this axis or the from axis does not have boundary values, neither will the resulting axis.

This method is not recommended for parametric vertical axes. Any parametric terms will be deleted. If appending of parametric axes is required, the calling code should first read out the parametric terms and merge them with the parametric terms of the from axis before setting them back for this axis.

Usage

CFAxisVertical$append(from)

Arguments

Returns

A new CFAxisVertical instance with values from this axis 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. If this axis has parametric terms, these are not subset here - they should be separately treated once all associated axes in the terms have been subset. That happens automatically in CFVariable methods which call the subset_parametric_terms() method.

Usage

CFAxisVertical$subset(name = "", rng = NULL)

Arguments

Returns

A new CFAxisVertical instance covering the indicated range of indices. If the value of the argument rng is NULL, return a copy of this axis as the new axis.

Method subset_parametric_terms()

Subset the parametric terms of this axis.

Usage

CFAxisVertical$subset_parametric_terms(
  original_axis_names,
  new_axes,
  start,
  count,
  aux = NULL,
  ZT_dim = NULL
)

Arguments

Returns

Self, invisibly. The parametric terms will have been subset in this axis.

References

https://cfconventions.org/Data/cf-conventions/cf-conventions.html#parametric-vertical-coordinate https://www.myroms.org/wiki/Vertical_S-coordinate

CF boundary variable

Description

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

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

Super class

ncdfCF::CFObject -> CFBounds

Active bindings

Methods

Public methods

• CFBounds$new()

• CFBounds$print()

• CFBounds$range()

• CFBounds$copy()

• CFBounds$subset()

• CFBounds$append()

• CFBounds$write()

• CFBounds$clone()

Method new()

Create an instance of this class.

Usage

CFBounds$new(
  var,
  values,
  start = NA,
  count = NA,
  attributes = data.frame(),
  owner_dims = 1L
)

Arguments

Returns

A new instance of this class.

Method print()

Print a summary of the object to the console.

Usage

CFBounds$print(attributes = TRUE, ...)

Arguments

Method range()

Retrieve the lowest and highest value in the bounds.

Usage

CFBounds$range()

Method copy()

Create a copy of this bounds object The copy is completely separate from self, meaning that both self and all of its components are made from new instances.

Usage

CFBounds$copy(name = "")

Arguments

Returns

The newly created bounds object.

Method subset()

Return a boundary variable spanning a smaller coordinate range. This currently only applies to 1-D axes.

This method returns boundary values which span the range of indices given by the rng argument.

Usage

CFBounds$subset(rng)

Arguments

Returns

A CFBounds instance covering the indicated range of indices.

Method append()

Append boundary values at the end of the current values of the boundary variable.

Usage

CFBounds$append(from)

Arguments

Returns

A new CFBounds instance with values from this boundary variable and the from boundary variable appended. If argument from is NULL, return NULL.

Method write()

Write the boundary variable to a netCDF file. This method should not be called directly; instead, CFVariable::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.

Active bindings

Methods

Public methods

• CFCellMeasure$new()

• CFCellMeasure$print()

• CFCellMeasure$data()

• CFCellMeasure$register()

• CFCellMeasure$link()

• CFCellMeasure$detach()

• CFCellMeasure$clone()

Method new()

Create an instance of this class.

Usage

CFCellMeasure$new(measure, name, 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 CFVariable 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 detach()

Detach the internal data variable from an underlying netCDF resource.

Usage

CFCellMeasure$detach()

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(resource, 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

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.

Note that when a new grid mapping object is created (as opposed to reading from a netCDF resource), only the grid_mapping_name attribute will be set. The caller must set all other parameters through their respective attributes, following the CF Metadata Conventions.

Usage

CFGridMapping$new(var, grid_mapping_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 https://cfconventions.org/cf-conventions/cf-conventions.html#appendix-grid-mappings

CF label object

Description

This class represent CF labels, i.e. a 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

Active bindings

Methods

Public methods

• CFLabel$new()

• CFLabel$print()

• CFLabel$slice()

• CFLabel$subset()

• CFLabel$write()

• CFLabel$clone()

Method new()

Create a new instance of this class.

Usage

CFLabel$new(var, values = NA, start = NA, count = NA)

Arguments

Returns

A CFLabel instance.

Method print()

Prints a summary of the labels to the console.

Usage

CFLabel$print(...)

Arguments

Method slice()

Given a range of domain coordinate values, returns the indices into the axis that fall within the supplied range.

Usage

CFLabel$slice(rng)

Arguments

Returns

An integer vector of length 2 with the lower and higher indices into the axis that fall within the range of coordinates in argument rng. Returns NULL if no values of the axis fall within the range of coordinates.

Method subset()

Retrieve a subset of the labels.

Usage

CFLabel$subset(name, 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, dim)

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.

Active bindings

Methods

Public methods

• CFObject$new()

• CFObject$detach()

• CFObject$dim()

• CFObject$attribute()

• CFObject$print_attributes()

• CFObject$set_attribute()

• CFObject$append_attribute()

• CFObject$delete_attribute()

• CFObject$write_attributes()

• CFObject$update_coordinates_attribute()

• CFObject$clone()

Method new()

Create a new CFobject 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. Instead, use the methods from higher-level classes such as CFVariable.

Usage

CFObject$new(var, values, start = 1L, count = NA, attributes = data.frame())

Arguments

Returns

A CFObject instance.

Method detach()

Detach the current object from its underlying netCDF resource. If necessary, data is read from the resource before detaching.

Usage

CFObject$detach()

Method dim()

Retrieve the dimensions of the data of this object. This could be for the data on file or for in-memory data.

Usage

CFObject$dim(dimension)

Arguments

Returns

Integer vector with the length of each requested dimension.

Method attribute()

Retrieve an attribute of a 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 = 30L)

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 attributes. 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 update_coordinates_attribute()

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

Usage

CFObject$update_coordinates_attribute(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$create()

• 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 or when saving a dataset to file. You should never have to call this directly.

Usage

CFResource$new(uri)

Arguments

Returns

An instance of this class.

Method create()

Create a new file on disk for the netCDF resource.

Usage

CFResource$create()

Returns

Self, invisibly.

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 Standard names table

Description

The CF Metadata Conventions define a large number of standard names for physical parameters, including axes and data variables. This class accesses the standard names table. For each of the entries in the table two properties are provided: the canonical unit and a description. These properties are retrieved when searching for a given name.

Access to this class is through the CF environment. Use the CF$standard_names$find("name_of_interest") method to access a particular standard name. It is strongly recommended not to instantiate this class manually as that may introduce problems with accessing the underlying XML file.

The XML table is retrieved from the CF Metadata Conventions web site here and stored locally in the cache of the ncdfCF package. A check is performed periodically for an updated version, which will then be downloaded automatically. The frequency of the update check can be controlled with the CF.options$cache_stale_days option.

Active bindings

Methods

Public methods

• CFStandardNames$new()

• CFStandardNames$print()

• CFStandardNames$find()

• CFStandardNames$load()

• CFStandardNames$clone()

Method new()

Initialize an instance of this class. This is done automatically when the package is loaded.

Usage

CFStandardNames$new()

Method print()

Print the version number of the standard names table in use, if it is loaded. The table is loaded automatically when it is first used.

Usage

CFStandardNames$print()

Method find()

Retrieve the information on the specified names.

Usage

CFStandardNames$find(names)

Arguments

Returns

If an entry with a value in names is found, returns a data.frame with with with the canonical units and a description of the name. If no names are found in the table NULL is returned.

Method load()

Load the standard names table so that it's contents may be used in display and analysis. Note that the table may be downloaded (4.3MB at version 91) if not available or stale.

Usage

CFStandardNames$load()

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFStandardNames$clone(deep = FALSE)

Arguments

References

https://cfconventions.org/cf-conventions/cf-conventions.html#standard-name

CF data variable

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 all the details that have been associated with the data variable, such as axis information, grid mapping parameters, etc.

Super class

ncdfCF::CFObject -> CFVariable

Active bindings

Methods

Public methods

• CFVariable$new()

• CFVariable$print()

• CFVariable$brief()

• CFVariable$shard()

• CFVariable$peek()

• CFVariable$detach()

• CFVariable$time()

• CFVariable$raw()

• CFVariable$array()

• CFVariable$subset()

• CFVariable$summarise()

• CFVariable$profile()

• CFVariable$append()

• CFVariable$terra()

• CFVariable$data.table()

• CFVariable$is_coincident()

• CFVariable$add_cell_measure()

• CFVariable$add_auxiliary_coordinate()

• CFVariable$save()

• CFVariable$clone()

Method new()

Create an instance of this class.

Usage

CFVariable$new(
  var,
  axes,
  values = values,
  start = NA,
  count = NA,
  attributes = data.frame()
)

Arguments

Returns

A CFVariable instance.

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

Returns

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

Method detach()

Detach the various properties of this variable from an underlying netCDF resource.

Usage

CFVariable$detach()

Returns

Self, invisibly.

Method time()

Return the time object from the axis representing time.

Usage

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

Retrieve the data in the object exactly as it was read from a netCDF resource or produced by an operation.

Usage

CFVariable$raw()

Returns

An array, matrix or vector with (dim)names set.

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

CFVariable$array()

Returns

An array or matrix of data in R ordering, or a vector if the data has only a single dimension.

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(..., 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 ... extends the valid range of the axis, 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 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")). 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 you can specify their names (instead of specifying the names of the primary planar axes). 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 axes.

Returns

A CFVariable instance, having the 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 data array but the corresponding axis is maintained in the result as a scalar axis.

If self is linked to a netCDF resource then the result will be linked to the same netCDF resource as well, except when auxiliary coordinate variables have been selected for the planar axes.

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 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 CFVariable$set_attribute() on the result of this method to set or update attributes as appropriate.

Usage

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

Arguments

Returns

A CFVariable object, or a list thereof with as many CFVariable 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

CFVariable$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 CFVariable instances with different dimensionality and/or different axes.

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. If the variable has such auxiliary coordinate variables then you can specify their names (instead of specifying the names of the primary planar axes).

Returns

If .as_table = FALSE, a CFVariable 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 append()

Append the data from another CFVariable 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

CFVariable$append(from, along)

Arguments

Returns

self, invisibly, with the arrays from this data variable 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

CFVariable$terra()

Returns

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

Method data.table()

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

The attributes associated with this data variable will be mostly lost. If present, attributes 'long_name' and 'units' are attached to the data.table as attributes, but all others are lost.

Usage

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

Tests if the other object is coincident with this data variable: identical axes.

Usage

CFVariable$is_coincident(other)

Arguments

Returns

TRUE if the data variables are coincident, FALSE otherwise.

Method add_cell_measure()

Add a cell measure variable to this variable.

Usage

CFVariable$add_cell_measure(cm)

Arguments

Returns

Self, invisibly.

Method add_auxiliary_coordinate()

Add an auxiliary coordinate to the appropriate axis of this variable. The length of the axis must be the same as the length of the auxiliary labels.

Usage

CFVariable$add_auxiliary_coordinate(aux, axis)

Arguments

Returns

Self, invisibly.

Method save()

Save the data object to a netCDF file.

Usage

CFVariable$save(fn, pack = FALSE)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFVariable$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::CFVariable -> CFVariableL3b

Methods

Public methods

• CFVariableL3b$new()

• 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 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(..., 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 CFVariable$array() method for this.

Returns

A CFVariable 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

Parametric formula term for a vertical CF axis object

Description

This class represents a formula term for a parametric vertical axis.

Super classes

ncdfCF::CFObject -> ncdfCF::CFVariable -> CFVerticalParametricTerm

Active bindings

Methods

Public methods

• CFVerticalParametricTerm$new()

• CFVerticalParametricTerm$print()

• CFVerticalParametricTerm$subset()

• CFVerticalParametricTerm$clone()

Method new()

Create an instance of this class.

Usage

CFVerticalParametricTerm$new(
  var,
  axes,
  values = values,
  start = NA,
  count = NA,
  attributes = data.frame()
)

Arguments

Returns

An instance of this class.

Method print()

Prints a summary of the parametric formula term to the console.

Usage

CFVerticalParametricTerm$print(...)

Arguments

Returns

self, invisibly.

Method subset()

Subset the indices to read a smaller portion of the data from the netCDF file. The passed indices should be named after the axes that they refer to. There may be more indices than axes and they may be in a different order than the axes of the term.

Usage

CFVerticalParametricTerm$subset(
  original_axis_names,
  new_axes,
  start,
  count,
  aux = NULL,
  ZT_dim = NULL
)

Arguments

Returns

The new parametric term object.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFVerticalParametricTerm$clone(deep = FALSE)

Arguments

NetCDF dimension object

Description

This class represents an netCDF dimensions. It contains the information on a dimension that is stored in an netCDF file. Consequently, the properties of this class are all read-only. The length of the dimension may change if data is written to an unlimited dimension, but that is managed internally.

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

Super class

ncdfCF::NCObject -> NCDimension

Active bindings

Methods

Public methods

• NCDimension$new()

• NCDimension$print()

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

Arguments

Returns

A NCDimension instance.

Method print()

Summary of the NC dimension printed to the console.

Usage

NCDimension$print(...)

Arguments

Method write()

Write the dimension to a netCDF file.

Usage

NCDimension$write(h)

Arguments

Returns

Self, invisibly.

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. Changing the properties of a group other than its name may very well invalidate the CF objects or even the netCDF file.

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

• NCGroup$add_auxiliary_longlat()

• 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, attributes = data.frame(), 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 add_auxiliary_coordinate()

Add an auxiliary coordinate variable to the group. This method adds the passed auxiliary coordinate to the group CFaux list.

Usage

NCGroup$add_auxiliary_coordinate(aux)

Arguments

Returns

self invisibly.

Method add_auxiliary_longlat()

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$add_auxiliary_longlat(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, possibly 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(scope = "all")

Arguments

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.

Active bindings

Methods

Public methods

• NCObject$new()

• NCObject$print_attributes()

• NCObject$attribute()

• NCObject$write_attributes()

• 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, attributes = data.frame())

Arguments

Method print_attributes()

This function prints the attributes of the netCDF object to the console.

Usage

NCObject$print_attributes(width = 50L)

Arguments

Method attribute()

Retrieve an attribute of a NC 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 write_attributes()

Write the attributes of this object to a netCDF file.

Usage

NCObject$write_attributes(nc, nm)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

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

Active bindings

Methods

Public methods

• NCVariable$new()

• NCVariable$print()

• NCVariable$shard()

• NCVariable$detach()

• NCVariable$get_data()

• NCVariable$dimension()

• NCVariable$dim()

• 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,
  dimids,
  attributes = data.frame(),
  netcdf4 = list()
)

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

Detach the passed object from this NC variable.

Usage

NCVariable$detach(obj)

Arguments

Returns

obj, invisibly.

Method get_data()

Read (a chunk of) data from the netCDF file. Degenerate dimensions are maintained and data is always returned in its smallest type.

Usage

NCVariable$get_data(start = NA, count = NA)

Arguments

Returns

An array with the requested data, or an error object.

Method dimension()

Get the NCDimension object(s) that this variable uses.

Usage

NCVariable$dimension(id)

Arguments

Returns

A NCDimension object or a list thereof. If no NCDimensions were found, return NULL.

Method dim()

The lengths of the data dimensions of this object.

Usage

NCVariable$dim(dimension)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

NCVariable$clone(deep = FALSE)

Arguments

Operations on CFVariable objects

Description

Basic arithmetic, mathematical and logical operations can be applied on the data of CFVariable objects having a suitable data type, specifically the base R functions from the Ops and Math groups of the S3 groupGeneric functions.

Usage

## S3 method for class 'CFVariable'
Ops(e1, e2)

## S3 method for class 'CFVariable'
Math(x, ...)

Arguments

Details

The functions always return a new CFVariable object. Functions can thus be concatenated to create more complex expressions. The data type of the new object is determined by the base R function; its name is concatenated from the names in the argument object(s).

For the Ops functions with two arguments, if both arguments are a CFVariable object they have to be compatible: same shape, axis coordinate values and coordinate reference system. The resulting CFVariable object will use the same axes as the CFVariable object(s) used as argument.

The attributes of the resulting CFVariable object should be updated to reflect its contents, in particular the "name", "long_name", "standard_name" and "units" attributes. Attributes are not copied over from the CFVariable objects in the arguments.

Value

A new CFVariable object. The object will have the same coordinate space as the CFVariable object used as argument. Arguments are not copied and the new object will only have the "actual_range" attribute set.

Results that are logical (see the examples) are stored using the NC_SHORT data type because netCDF does not have a native logical data type.

Examples

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

# Temperature data in K
t2m <- ds[["t2m"]]

# Convert to degrees_Celsius
t2mC <- t2m - 273.15
t2mC$name <- "t2m_Celsius"
t2mC$set_attribute("units", "NC_CHAR", "degrees_Celsius")
t2mC

hot <- t2mC > 20
hot$name <- "t2m_Celsius_over_20"
hot$set_attribute("long_name", "NC_CHAR", "Flag to indicate where temperature is 20C or hotter")
hot$set_attribute("units", "NC_CHAR", "1")
hot

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 <- ds$var_names[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))

Create a CFVariable instance from an R object

Description

With this function you can convert an R object into a CFVariable. This can be an array, matrix or vector of type logical, integer, numeric or character.

Usage

as_CF(name, values)

Arguments

Details

Dimnames on the R object will be converted to instances of a CFAxis descendant class, depending on their values. If the dimnames along a dimension of the R object can be converted to numeric, then it will be an instance of CFAxisNumeric. If the dimnames are character, a first attempt is made to create a CFAxisTime (i.e. the dimnames have to represent timestamps), failing that a CFAxisCharacter will be created. If no dimnames are set, an instance of CFAxisDiscrete is generated.

The axes of the CFVariable are oriented as in the R object. Note that this is different from standard practice in the netCDF community and the portability of saved datasets is thus limited. You can improve this situation by setting the orientation of the axes and by adding attributes.

After creation of the CFVariable, it is recommended to set other properties, such as attributes or a coordinate reference system.

Value

An instance of class CFVariable.

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 CFVariable 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, orientation, values, bounds = NULL, attributes = NULL)

Arguments

Details

There are several restrictions on the combination of orientation and values arguments. Longitude, latitude and depth axes (orientation of "X", "Y" or "Z") 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 character axis

Description

With this method you can create a character axis to use with new CFVariable instances.

Usage

makeCharacterAxis(name, values, attributes = data.frame())

Arguments

Value

A CFAxisCharacter instance.

Create a discrete axis

Description

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

Usage

makeDiscreteAxis(name, length)

Arguments

Value

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

Create a latitude axis

Description

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

Usage

makeLatitudeAxis(name, values, bounds, attributes = NULL)

Arguments

Value

A CFAxisLatitude instance.

Create a longitude axis

Description

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

Usage

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

Arguments

Value

A CFAxisLongitude instance.

Create a time axis

Description

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

Usage

makeTimeAxis(name, values, attributes = NULL)

Arguments

Value

A CFAxisTime instance.

Create a vertical axis

Description

With this method you can create a vertical axis to use with new CFVariable instances. Note that you should set the "positive" attribute after creating the axis to indicate if values are increasing going upwards (positive = "up") or downwards (positive = "down").

Usage

makeVerticalAxis(name, values, bounds, attributes = NULL)

Arguments

Value

A CFAxisVertical instance.

Names or axis values of an CF object

Description

Retrieve the variable or axis names of an ncdfCF object. The names() function gives the names of the variables in the data set, preceded by 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, preceded 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 coordinate values along the axis as a numeric vector.

• CFAxisTime: The coordinate values 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 coordinate values along the axis as a character vector.

• CFAxisDiscrete: The index values of the axis, either along the entire axis, or a portion thereof.

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)

# Names of data variables
names(ds)

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

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