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

• create_ncdf(): Create a new CF data set.

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

• var_names(), axis_names: Return a character vector with the names of the objects.

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

• group(): Vector of groups defined 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, or a terra::SpatRaster 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

• https://r-cf.github.io/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$attach_to_group()

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

Attach the auxiliary long-lat grids and any bounds to a group. If there is another object with the same name in this group an error is thrown.

Usage

CFAuxiliaryLongLat$attach_to_group(grp, locations = list())

Arguments

Returns

Self, invisibly.

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 classes

ncdfCF::CFObject -> ncdfCF::CFData -> 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$attach_to_group()

• 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,
  group,
  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, name and attributes - 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 = "", group)

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

Arguments

Returns

NULL

Method indexOf()

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

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

Usage

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

Arguments

Returns

Numeric vector of the same length as x.

Method attach_to_group()

Attach this axis to a group. If there is another object with the same name in this group an error is thrown. For associated objects (such as bounds, etc), if another object with the same name is otherwise identical to the associated object then that object will be linked from the variable, otherwise an error is thrown.

Usage

CFAxis$attach_to_group(grp, locations = list())

Arguments

Returns

Self, invisibly.

Method write()

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

Usage

CFAxis$write()

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::CFData -> 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,
  group,
  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 = "", group)

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

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::CFData -> 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, group, 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 = "", group)

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 = "", group, 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::CFData -> 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,
  group,
  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 = "", group)

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 = "", group, values)

Arguments

Returns

The newly created axis.

Method subset()

Return a latitude 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 = "", group, 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::CFData -> 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,
  group,
  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 = "", group)

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 = "", group, 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 = "", group, 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::CFData -> 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,
  group,
  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 = "", group)

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

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 = "", group, 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::CFData -> 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, including its boundary values. A CFTime or CFClimatology instance will also be created to manage the time magic.

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

Usage

CFAxisTime$new(
  var,
  group,
  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 = "", group)

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

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 = "", group, 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()

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::CFData -> ncdfCF::CFAxis -> ncdfCF::CFAxisNumeric -> CFAxisVertical

Active bindings

Methods

Public methods

• CFAxisVertical$new()

• CFAxisVertical$attach_to_group()

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

Arguments

Method attach_to_group()

Attach this verical axis to a group, including any parameteric terms. If there is another object with the same name in this group an error is thrown. For associated objects (such as bounds, etc), if another object with the same name is otherwise identical to the associated object then that object will be linked from the variable, otherwise an error is thrown.

Usage

CFAxisVertical$attach_to_group(grp, locations = list())

Arguments

Returns

Self, invisibly.

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

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 = "", group, 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 = "", group, 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 classes

ncdfCF::CFObject -> ncdfCF::CFData -> CFBounds

Active bindings

Methods

Public methods

• CFBounds$new()

• CFBounds$print()

• CFBounds$range()

• CFBounds$copy()

• CFBounds$subset()

• CFBounds$append()

• CFBounds$write()

Method new()

Create an instance of this class.

Usage

CFBounds$new(
  var,
  group,
  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 = "", group)

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

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

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 object

Description

This class is a basic ancestor to all classes that contain data from a netCDF resource, specifically data variables and axes. More useful classes use this class as ancestor.

Super class

ncdfCF::CFObject -> CFData

Active bindings

Methods

Public methods

• CFData$new()

• CFData$detach()

• CFData$dim()

Method new()

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

Usage

CFData$new(
  obj,
  group,
  values,
  start = 1L,
  count = NA,
  attributes = data.frame()
)

Arguments

Returns

A CFData instance.

Method detach()

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

Usage

CFData$detach()

Method dim()

Retrieve the dimensions of the data of this object.

Usage

CFData$dim(dimension)

Arguments

Returns

Integer vector with the length of each requested dimension.

CF data set

Description

This class represents a CF data set, the object that encapsulates a netCDF resource. You should never instantiate this class directly; instead, call open_ncdf() which will return an instance that has all properties read from the netCDF resource, or create_ncdf() for a new, empty instance. Class methods can then be called, or the base R functions called with this instance.

The CF data set instance provides access to all the objects in the netCDF resource, organized in groups.

Public fields

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

• CFDataset$append_attribute()

• CFDataset$delete_attribute()

• CFDataset$add_variable()

• CFDataset$save()

• CFDataset$clone()

Method new()

Create an instance of this class. Do not instantiate this class directly; instead, call open_ncdf() which will return an instance that has all properties read from the netCDF resource, or create_ncdf() for a new, empty instance.

Usage

CFDataset$new(resource, format)

Arguments

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)

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

Add an attribute to the global attributes. If an attribute name already exists, it will be overwritten.

Usage

CFDataset$set_attribute(name, type, value)

Arguments

Returns

Self, invisibly.

Method append_attribute()

Append the text value of a global attribute. If an attribute name already exists, the value will be appended to the existing value of the attribute. If the attribute name does not exist it will be created. The attribute must be of "NC_CHAR" or "NC_STRING" type; in the latter case having only a single string value.

Usage

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

Arguments

Returns

Self, invisibly.

Method delete_attribute()

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

Usage

CFDataset$delete_attribute(name)

Arguments

Returns

Self, invisibly.

Method add_variable()

Add a CFVariable object to the data set. If there is another object with the same name in the group where the data variable should be placed an error is thrown. For objects associated with the data variable (such as axes, CRS, boundary variables, etc), if another object with the same name is otherwise identical to the associated object then that object will be linked from the variable, otherwise an error is thrown.

Usage

CFDataset$add_variable(var, group, locations = list())

Arguments

Returns

Argument var, invisibly.

Method save()

Save the data set to file, including its subordinate objects such as attributes, data variables, axes, CRS, etc.

Usage

CFDataset$save(fn, pack = FALSE)

Arguments

Returns

Self, invisibly.

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

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

Returns

Self, invisibly.

References

https://docs.ogc.org/is/18-010r11/18-010r11.pdf https://cfconventions.org/cf-conventions/cf-conventions.html#appendix-grid-mappings

Group for CF objects

Description

This class represents a CF group, the object that holds elements like dimensions and variables of a CFDataset.

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::CFObject -> CFGroup

Active bindings

Methods

Public methods

• CFGroup$new()

• CFGroup$print()

• CFGroup$hierarchy()

• CFGroup$subgroup_names()

• CFGroup$create_subgroup()

• CFGroup$add_subgroups()

• CFGroup$add_CF_object()

• CFGroup$objects()

• CFGroup$find_by_name()

• CFGroup$add_variable()

• CFGroup$write()

• CFGroup$write_variables()

Method new()

Create a new CF group instance.

Usage

CFGroup$new(grp, parent)

Arguments

Returns

An instance of this class.

Method print()

Summary of the group printed to the console.

Usage

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

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

Arguments

Method subgroup_names()

Retrieve the names of the subgroups of the current group.

Usage

CFGroup$subgroup_names(recursive = TRUE)

Arguments

Returns

A character vector with the names of the subgroups of the current group. If recursive = TRUE, the names will be fully qualified with their path.

Method create_subgroup()

Create a new group as a subgroup of the current group.

Usage

CFGroup$create_subgroup(name)

Arguments

Returns

The newly created group, or an error.

Method add_subgroups()

Add subgroups to the current group. These subgroups must be fully formed, including having set their parent to this group. Use the create_subgroup() method to add a group from scratch.

Usage

CFGroup$add_subgroups(grps)

Arguments

Returns

Self, invisibly.

Method add_CF_object()

Add one or more CF objects to the current group. This is an internal method that should not be invoked by the user. The objects to be added are considered atomic and not assessed for any contained objects. Use a method like add_variable() to add a CF variable to this group as well as its composing sub-objects such as axes.

Usage

CFGroup$add_CF_object(obj, silent = TRUE)

Arguments

Returns

Self, invisibly, or an error.

Method objects()

This method lists the CF objects of a certain class located in this group, optionally including objects in subgroups.

Usage

CFGroup$objects(cls, recursive = TRUE)

Arguments

Returns

A list of CFObject instances.

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

CFGroup$find_by_name(name)

Arguments

Returns

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

Method add_variable()

Add a CFVariable object to the group. If there is another object with the same name in this group an error is thrown. For associated objects (such as axes, CRS, boundary variables, etc), if another object with the same name is otherwise identical to the associated object then that object will be linked from the variable, otherwise an error is thrown.

Usage

CFGroup$add_variable(var, locations = list())

Arguments

Returns

Argument var, invisibly.

Method write()

Write the group to file, including its attributes, if it doesn't already exist.

Usage

CFGroup$write(recursive = TRUE)

Arguments

Returns

Self, invisibly.

Method write_variables()

Write data variables in the group to file, including its associated objects, if it doesn't already exist.

Usage

CFGroup$write_variables(pack = FALSE, recursive = TRUE)

Arguments

Returns

Self, invisibly.

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 classes

ncdfCF::CFObject -> ncdfCF::CFData -> CFLabel

Active bindings

Methods

Public methods

• CFLabel$new()

• CFLabel$print()

• CFLabel$identical()

• CFLabel$copy()

• CFLabel$slice()

• CFLabel$subset()

• CFLabel$write()

Method new()

Create a new instance of this class.

Usage

CFLabel$new(var, group, 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 identical()

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

Usage

CFLabel$identical(lbl)

Arguments

Returns

TRUE if the two label sets are identical, FALSE if not.

Method copy()

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

Usage

CFLabel$copy(name = "", group)

Arguments

Returns

The newly created label set.

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

Returns

Self, invisibly.

CF base object

Description

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

Active bindings

Methods

Public methods

• CFObject$new()

• CFObject$attach_to_group()

• CFObject$detach()

• CFObject$attribute()

• CFObject$print_attributes()

• CFObject$set_attribute()

• CFObject$attributes_identical()

• CFObject$append_attribute()

• CFObject$delete_attribute()

• CFObject$write_attributes()

• CFObject$clone()

Method new()

Create a new CFobject instance in memory or from an object in a netCDF resource when 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(obj, attributes = data.frame(), group = NULL)

Arguments

Returns

A CFObject instance.

Method attach_to_group()

Attach this CF object to a group. If there is another object with the same name in this group an error is thrown. This is the basic method that may be overridden by descendant classes.

Usage

CFObject$attach_to_group(grp, locations = list())

Arguments

Returns

Self, invisibly.

Method detach()

Detach the current object from its underlying netCDF resource.

Usage

CFObject$detach()

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

Test if the supplied attributes are identical to the attributes of this instance. The order of the attributes may differ but the names, types and values must coincide.

Usage

CFObject$attributes_identical(cmp)

Arguments

Returns

TRUE if attributes in argument cmp are identical to the attributes of this instance, FALSE otherwise.

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

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFObject$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 classes

ncdfCF::CFObject -> ncdfCF::CFData -> 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$add_ancillary_variable()

• CFVariable$attach_to_group()

• CFVariable$write()

• CFVariable$save()

Method new()

Create an instance of this class.

Usage

CFVariable$new(
  var,
  group,
  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, .resolution = NULL)

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

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. In all cases the result will be attached to a private group.

Method summarise()

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

Usage

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

Arguments

Details

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.

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, in a new private group.

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

Add an ancillary variable to this variable.

Usage

CFVariable$add_ancillary_variable(var)

Arguments

Returns

Self, invisibly.

Method attach_to_group()

Attach this variable to a group. If there is another object with the same name in this group an error is thrown. For associated objects (such as axes, CRS, boundary variables, etc), if another object with the same name is otherwise identical to the associated object then that object will be linked from the variable, otherwise an error is thrown.

Usage

CFVariable$attach_to_group(grp, locations = list())

Arguments

Returns

Self, invisibly.

Method write()

Write the data variable to a netCDF file, including all of its dependent objects, such as axes and attributes.

Axes with length == 1L are written as a "scalar axis", unless they are unlimited.

Usage

CFVariable$write(pack)

Arguments

Returns

Self, invisibly.

Method save()

Save the data variable to a netCDF file, including its subordinate objects such as axes, CRS, etc. Note that saving a data variable will create a "bare-bones" netCDF file and its associated CFDataset.

Usage

CFVariable$save(fn, pack = FALSE)

Arguments

Returns

The newly create CFDataset, invisibly.

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::CFData -> ncdfCF::CFVariable -> CFVariableL3b

Methods

Public methods

• CFVariableL3b$new()

• CFVariableL3b$subset()

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.

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::CFData -> ncdfCF::CFVariable -> CFVerticalParametricTerm

Active bindings

Methods

Public methods

• CFVerticalParametricTerm$new()

• CFVerticalParametricTerm$print()

• CFVerticalParametricTerm$subset()

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.

NetCDF dimension object

Description

This class represents an netCDF dimension. 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 = 1L, unlim = FALSE, 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.

Direct access to groups is usually not necessary. The principal objects of interest, CF data variables and axes, are accessible via CFGroup. Changing the properties of a netCDF 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$find_by_name()

• NCGroup$find_dim_by_id()

• NCGroup$has_name()

• NCGroup$set_name()

• NCGroup$unused()

• NCGroup$create_group()

• NCGroup$append()

• NCGroup$fullnames()

• NCGroup$dimensions()

• NCGroup$clone()

Method new()

Create a new instance of this class.

Usage

NCGroup$new(id, name, attributes = data.frame(), parent, resource)

Arguments

Returns

An instance of this class.

Method print()

Summary of the group printed to the console.

Usage

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

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. Usually this method is called programmatically.

Usage

NCGroup$find_by_name(name)

Arguments

Returns

The object with the provided name. 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)

Arguments

Returns

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

Method set_name()

Change the name of the NC group. The new name must be valid and should not duplicate a sibling group.

Usage

NCGroup$set_name(new_name)

Arguments

Returns

Self, invisibly.

Method unused()

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

Usage

NCGroup$unused()

Returns

List of NCVariable.

Method create_group()

Create a new group as a sub-group of the current group. This writes the new group to the netCDF resource, but only if it is open for writing.

Usage

NCGroup$create_group(CFgroup)

Arguments

Returns

The newly created group as a NCGroup instance, invisibly.

Method append()

Append an object to this group.

Usage

NCGroup$append(obj)

Arguments

Returns

Self, invisible.

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 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. This will retain existing attributes, update modified attributes, and delete and add missing attributes from the passed in argument.

Usage

NCObject$write_attributes(nm, new_atts)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

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

• NCResource$new()

• NCResource$print()

• NCResource$create()

• NCResource$close()

• NCResource$sync()

• NCResource$group_handle()

• NCResource$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

NCResource$new(uri, write)

Arguments

Returns

An instance of this class.

Method print()

Print a summary of the netCDF resource to the console.

Usage

NCResource$print()

Returns

Self, invisibly.