CFArray {ncdfCF} | R Documentation |
Array data extracted from a CF data variable
Description
This class holds the data that is extracted from a CFVariable
using the data()
, subset()
or profile()
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 aterra::SpatRaster
(3D) orterra::SpatRasterDataset
(4D) object, with all relevant structural metadata set. Packageterra
must be installed for this to work. -
data.table()
: The data is returned as adata.table
, with all data points on individual rows. Metadata is not maintained. Packagedata.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 newCFArray
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
Inherited methods
ncdfCF::CFObject$add_coordinates()
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$profile()
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 argumentvalues
.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 argumentvalues
.
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 append()
Append the data from another CFArray
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
CFArray$append(from, along)
Arguments
from
The
CFArray
instance to append from.along
The name of the axis to append along. This must be a single character string and the named axis has to be present both in
self
and in theCFArray
instance in argumentfrom
.
Returns
self
, invisibly, with the arrays from self
and from
appended.
Method terra()
Convert the data to a terra::SpatRaster
(3D) or a
terra::SpatRasterDataset
(4D) object. The data
will be oriented to North-up. The 3rd dimension in the data will become
layers in the resulting SpatRaster
, any 4th dimension the data sets.
The terra
package needs to be installed for this method to work.
Usage
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(var_as_column = FALSE)
Arguments
var_as_column
Logical to flag if the name of the variable should become a column (
TRUE
) or be used as the name of the column with the data values (FALSE
, default). Including the name of the variable as a column is useful when multipledata.table
s are merged into one.
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 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.