CFObject: CF base object

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

CF base object

Description

This class is a basic ancestor to all classes that represent CF objects, specifically data variables and axes. More useful classes use this class as ancestor.

Active bindings

friendlyClassName

(read-only) A nice description of the class.

id

(read-only) Retrieve the identifier of the CF object.

name

Set or retrieve the name of the CF object. The name must be a valid netCDF name: start with a character, use only characters, numbers and the underscore, and be at most 255 characters long.

fullname

(read-only) The fully-qualified name of the CF object.

group

(read-only) Retrieve the NCGroup that this object is located in.

attributes

(read-only) Retrieve a data.frame with the attributes of the CF object.

has_resource

(read-only) Flag that indicates if this object has an underlying netCDF resource.

NCvar

(read-only) The NCVariable object that links to an underlying netCDF resource, or NULL if not linked.

data_type

Set or retrieve the data type of the data in the object. Setting the data type to a wrong value can have unpredictable but catastrophic consequences.

ndims

(read-only) Retrieve the dimensionality of the data in the array, or the netCDF resource.

array_indices

Returns a list with columns "start" and "count" giving the indices for reading the data of this object from a netCDF resource.

Methods

Public methods

• CFObject$new()

• CFObject$detach()

• CFObject$dim()

• CFObject$attribute()

• CFObject$print_attributes()

• CFObject$set_attribute()

• CFObject$append_attribute()

• CFObject$delete_attribute()

• CFObject$write_attributes()

• CFObject$update_coordinates_attribute()

• CFObject$clone()

---

Method new()

Create a new CFobject instance from a variable in a netCDF resource. This method is called upon opening a netCDF resource. It is rarely, if ever, useful to call this constructor directly. Instead, use the methods from higher-level classes such as CFVariable.

Usage

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

Arguments

var

The NCVariable instance upon which this CF object is based when read from a netCDF resource, or the name for the new CF object to be created.

values

Optional. The values of the object in an array.

start

Optional. Vector of indices where to start reading data along the dimensions of the array on file. The vector must be NA to read all data, otherwise it must have agree with the dimensions of the array on file. Ignored when argument var is not an NCVariable instance.

count

Optional. Vector of number of elements to read along each dimension of the array on file. The vector must be NA to read to the end of each dimension, otherwise its value must agree with the corresponding start value and the dimension of the array on file. Ignored when argument var is not an NCVariable instance.

attributes

Optional. A data.frame with the attributes of the object. When argument var is an NCVariable instance and this argument is an empty data.frame (default), arguments will be read from the resource.

Returns

A CFObject instance.

---

Method detach()

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

Usage

CFObject$detach()

---

Method dim()

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

Usage

CFObject$dim(dimension)

Arguments

dimension

Optional. The index of the dimension to retrieve the length for. If omitted, retrieve the lengths of all dimensions.

Returns

Integer vector with the length of each requested dimension.

---

Method attribute()

Retrieve an attribute of a CF object.

Usage

CFObject$attribute(att, field = "value")

Arguments

att

Single character string of attribute to return.

field

The field of the attribute to return values from. This must be "value" (default) or "type".

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

width

The maximum width of each column in the data.frame when printed to the console.

---

Method set_attribute()

Add an attribute. If an attribute name already exists, it will be overwritten.

Usage

CFObject$set_attribute(name, type, value)

Arguments

name

The name of the attribute. The name must begin with a letter and be composed of letters, digits, and underscores, with a maximum length of 255 characters. UTF-8 characters are not supported in attribute names.

type

The type of the attribute, as a string value of a netCDF data type.

value

The value of the attribute. This can be of any supported type, including a vector or list of values. Matrices, arrays and like compound data structures should be stored as a data variable, not as an attribute and they are thus not allowed. In general, an attribute should be a character value, a numeric value, a logical value, or a short vector or list of any of these. Values passed in a list will be coerced to their common mode.

Returns

Self, invisibly.

---

Method append_attribute()

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

Usage

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

Arguments

name

The name of the attribute. The name must begin with a letter and be composed of letters, digits, and underscores, with a maximum length of 255 characters. UTF-8 characters are not supported in attribute names.

value

The character value of the attribute to append. This must be a character string.

sep

The separator to use. Default is "; ".

prepend

Logical to flag if the supplied value should be placed before the existing value. Default is FALSE.

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

name

Vector of names of the attributes to delete.

Returns

Self, invisibly.

---

Method write_attributes()

Write the attributes of this object to a netCDF file.

Usage

CFObject$write_attributes(nc, nm)

Arguments

nc

The handle to the netCDF file opened for writing.

nm

The NC variable name or "NC_GLOBAL" to write the attributes to.

Returns

Self, invisibly.

---

Method update_coordinates_attribute()

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

Usage

CFObject$update_coordinates_attribute(crds)

Arguments

crds

Vector of axis or auxiliary coordinate names to add to the attribute.

Returns

Self, invisibly.

---

Method clone()

The objects of this class are cloneable with this method.

Usage

CFObject$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

ncdfCF documentation built on Sept. 13, 2025, 5:07 p.m.