Package 'ncdfCF'

Description

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

Usage

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

Arguments

Details

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

The indices into the axes to be subset can be specified in a variety of ways; in practice it should (resolve to) be a vector of integers. A range (e.g. 100:200), an explicit vector (⁠c(23, 46, 3, 45, 17⁠), a sequence (⁠seq(from = 78, to = 100, by = 2⁠), all work. Note, however, that only a single range is generated from the vector so these examples resolve to 100:200, 3:46, and 78:100, respectively. It is also possible to use a custom function as an argument.

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

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

Value

An array with dimnames and other attributes set.

Examples

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

# How are the dimensions organized?
dimnames(pr)

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

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

Description

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)

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

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

Description

With this function you can convert an R object into a CFDataset or CFVariable, depending on the characteristics of the argument obj. The object to convert can be an array, matrix or vector of type logical, integer, numeric or character, or a terra::SpatRaster.

Usage

as_CF(name, obj)

## Default S3 method:
as_CF(name, obj)

## S3 method for class 'SpatRaster'
as_CF(name, obj)

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 instance(s) are oriented as in the object. Note that this is different from standard practice in the netCDF community and the portability of saved data sets is thus limited. You can improve this situation by setting the orientation of the axes and by adding attributes.

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

Value

An instance of class CFDataset or CFVariable.

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

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, with_attributes = FALSE)

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.

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.

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. A discrete axis does not have any attributes or values to write.

Usage

CFAxisDiscrete$write()

Returns

Self, invisibly.

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.

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.

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.

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

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

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

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

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

Print the boundary values to the console. This method is not very useful to call directly - instead, call ⁠$print()⁠, which will call this method. These boundary values are also printed when printing an axis that has boundary values associated with it.

Usage

CFBounds$print_boundary_values()

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

Arguments

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

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

• CFData$read_data()

• CFData$read_chunk()

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. Read the data of the CF object from the NC file. The data is cached by self so repeated calls do not access the netCDF resource, unless argument refresh is TRUE. This method will not assess how big the data is before reading it so there is a chance that memory will be exhausted. The calling code should check for this possibility and break up the reading of data into chunks.

Method read_data()

Usage

CFData$read_data(refresh = FALSE)

Arguments

Returns

An array of data, invisibly, as prescribed by the start and count values used to create this object. If the object is not backed by a netCDF resource, returns NULL. Read a chunk of raw data of the CF object, as defined by the start and count vectors. Note that these vectors are relative to any subset of the data variable that this CF object refers to. The data read by this method will not be stored in self so the calling code must take a reference to it.

Method read_chunk()

Usage

CFData$read_chunk(start, count)

Arguments

Returns

An array of data, as prescribed by the start and count arguments, or NULL if there is no data.

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 = NULL, pack = FALSE)

Arguments

Returns

Self, invisibly.

Method clone()

The objects of this class are cloneable with this method.

Usage

CFDataset$clone(deep = FALSE)

Arguments

Description

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

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

Super class

ncdfCF::CFObject -> CFGridMapping

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

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$remove_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 remove_CF_object()

Remove a CF objects from the current group. This is an internal method that should not be invoked by the user. The objects to be removed are considered atomic and not assessed for any contained objects.

Usage

CFGroup$remove_CF_object(obj)

Arguments

Returns

Self, invisibly.

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.

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.

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

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

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

• CFVariable$add_cell_measure()

• CFVariable$add_auxiliary_coordinate()

• CFVariable$add_ancillary_variable()

• CFVariable$attach_to_group()

• CFVariable$terra()

• CFVariable$data.table()

• 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, or NULL if the era argument falls entirely outside of the range of the time axis.

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. The attributes are not assessed.

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

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

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

Description

This function creates a new, empty data set in memory. You can add groups, data variables and attributes to this data set as appropriate. The data set can be saved with CFDataset$save(), if so desired.

Usage

create_ncdf()

Description

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

Usage

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

Arguments

Value

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

Examples

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

Description

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

Usage

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

Arguments

Value

For a CFVariable instance in argument x, a named vector of axis lengths, excluding any scalar axes. For a CFAxis descendant instance in argument x, the length of the axis.

Examples

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

Description

This is a basic function to support plotting of ncdfCF data with the ggplot2 package. Specifically, this function creates a geo_ncdf object which can be used like a geom_raster. The geom_ncdf takes a CFVariable instance as its data. The CFVariable should be properly pre-processed to make it suitable for plotting. The ⁠$subset()⁠ method is well suited for this task. Note that currently only map plotting works, e.g. the CFVariable should have X and Y axes.

Usage

geom_ncdf(mapping = NULL, data, ...)

Arguments

Value

A ⁠geom_*⁠ object that can be used in ggplot2 plot composition.

Examples

library(ggplot2)
fn <- system.file("extdata", "tasmax_NAM-44_day_20410701-vncdfCF.nc", package = "ncdfCF")
ds <- open_ncdf(fn)
tasmax <- ds[["tasmax"]]
ggplot() + geom_ncdf(data = tasmax) + coord_equal() + scale_fill_viridis_c()

Description

List the groups in the CF object, recursively.

Usage

groups(x)

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

Arguments

Value

A character vector with group names in the object.

Examples

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

Description

With this function 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 = data.frame(),
  group = 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.