CFArray: Array data extracted from a CF data variable

In ncdfCF: Easy Access to NetCDF Files with CF Metadata Conventions

Array data extracted from a CF data variable

Description

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

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

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

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

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

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

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

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

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

Super classes

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

Active bindings

dimnames

(read-only) Retrieve dimnames of the data object.

Methods

Public methods

• CFArray$new()

• CFArray$print()

• CFArray$raw()

• CFArray$array()

• CFArray$terra()

• CFArray$data.table()

• CFArray$save()

• CFArray$clone()

Inherited methods

• ncdfCF::CFObject$append_attribute()
• ncdfCF::CFObject$attribute()
• ncdfCF::CFObject$delete_attribute()
• ncdfCF::CFObject$print_attributes()
• ncdfCF::CFObject$set_attribute()
• ncdfCF::CFObject$write_attributes()
• ncdfCF::CFVariableBase$summarise()
• ncdfCF::CFVariableBase$time()

---

Method new()

Create an instance of this class.

Usage

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

Arguments

name

The name of the object.

group

The group that this data should live in. This is usually an in-memory group, but it could be a regular group if the data is prepared for writing into a new netCDF file.

values

The data of this object. The structure of the data depends on the method that produced it.

values_type

The unpacked netCDF data type for this object.

axes

A list of CFAxis descendant instances that describe the axes of the argument value.

crs

The CFGridMapping instance of this data object, or NULL when no grid mapping is available.

attributes

A data.frame with the attributes associated with the data in argument value.

Returns

An instance of this class.

---

Method print()

Print a summary of the data object to the console.

Usage

CFArray$print(...)

Arguments

...

Arguments passed on to other functions. Of particular interest is ⁠width = ⁠ to indicate a maximum width of attribute columns.

---

Method raw()

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

Usage

CFArray$raw()

Returns

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

---

Method array()

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

Usage

CFArray$array()

Returns

An array of data in R ordering.

---

Method terra()

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

Usage

CFArray$terra()

Returns

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

---

Method data.table()

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

Usage

CFArray$data.table()

Returns

A data.table with all data points in individual rows. All axes, including scalar axes, will become columns. The name of this data variable will be used as the column that holds the data values. Two attributes are added: name indicates the long name of this data variable, units indicates the physical unit of the data values.

---

Method save()

Save the data object to a netCDF file.

Usage

CFArray$save(fn, pack = FALSE)

Arguments

fn

The name of the netCDF file to create.

pack

Logical to indicate if the data should be packed. Packing is only useful for numeric data; packing is not performed on integer values. Packing is always to the "NC_SHORT" data type, i.e. 16-bits per value.

Returns

Self, invisibly.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

CFArray$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

ncdfCF documentation built on April 16, 2025, 9:08 a.m.