CFAxis: CF axis object

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

CF axis object

Description

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

This super-class does manage the "coordinates" of the axis, i.e. the values along the axis. This could be the values of the axis as stored on file, but it can also be the values from an auxiliary coordinate set, in the form of a CFLabel instance. The coordinate set to use in display, selection and processing is selectable through methods and fields in this class.

Super class

ncdfCF::CFObject -> CFAxis

Active bindings

friendlyClassName

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

dimid

The netCDF dimension id of this axis. Setting this value to anything other than the correct value will lead to disaster.

length

(read-only) The declared length of this axis.

orientation

Set or retrieve the orientation of the axis, a single character with a value of "X", "Y", "Z", "T". Setting the orientation of the axis should only be done when the current orientation is unknown. Setting a wrong value may give unexpected errors in processing of data variables.

values

(read-only) Retrieve the raw values of the axis. In general you should use the coordinates field rather than this one.

coordinates

(read-only) Retrieve the coordinate values of the active coordinate set from the axis.

bounds

Set or retrieve the bounds of this axis as a CFBounds object. When setting the bounds, the bounds values must agree with the coordinates of this axis.

auxiliary

Set or retrieve auxiliary coordinates for the axis. On assignment, the value must be an instance of CFLabel or a CFAxis descendant, which is added to the end of the list of coordinate sets. On retrieval, the active CFLabel or CFAxis instance or NULL when the active coordinate set is the primary axis coordinates.

coordinate_names

(read-only) Retrieve the names of the coordinate sets defined for the axis, as a character vector. The first element in the vector is the name of the axis and it refers to the values of the coordinates as stored in the netCDF file. Following elements refer to auxiliary coordinates.

coordinate_range

(read-only) Retrieve the range of the coordinates of the axis as a vector of two values. The mode of the result depends on the sub-type of the axis.

active_coordinates

Set or retrieve the name of the coordinate set to use with the axis for printing to the console as well as for processing methods such as subset().

unlimited

Logical to indicate if the axis is unlimited.

time

(read-only) Retrieve the CFTime object associated with the axis. Always returns NULL but CFAxisTime overrides this field.

is_parametric

(read-only) Logical flag that indicates if the axis has dimensional coordinates. Always FALSE for all axes except for CFAxisVertical which overrides this method.

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

Inherited methods

• ncdfCF::CFObject$append_attribute()
• ncdfCF::CFObject$attribute()
• ncdfCF::CFObject$delete_attribute()
• ncdfCF::CFObject$dim()
• ncdfCF::CFObject$print_attributes()
• ncdfCF::CFObject$set_attribute()
• ncdfCF::CFObject$update_coordinates_attribute()
• ncdfCF::CFObject$write_attributes()

---

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

Arguments

var

The name of the axis when creating a new axis. When reading an axis from file, the NCVariable object that describes this instance.

values

Optional. The values of the axis in a vector. Ignored when argument var is a NCVariable object.

start

Optional. Integer index where to start reading axis data from file. The index may be NA to start reading data from the start.

count

Optional. Number of elements to read from file. This may be NA to read to the end of the data.

orientation

Optional. The orientation of the axis: "X", "Y", "Z" "T", or "" (default) when not known or relevant.

attributes

Optional. A data.frame with the attributes of the axis. When an empty data.frame (default) and argument var is an NCVariable instance, attributes of the axis will be taken from the netCDF resource.

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

...

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

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

from

A CFAxisVertical instance that will receive references to the parametric terms.

original_axes

List of CFAxis instances from the CF object that these parametric terms are copied from.

new_axes

List of CFAxis instances to use with the formula term objects.

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

axes

List of CFAxis instances.

Returns

NULL

---

Method identical()

Tests if the axis passed to this method is identical to self. This only tests for generic properties - class, length and name - with further assessment done in sub-classes.

Usage

CFAxis$identical(axis)

Arguments

axis

The CFAxis instance to test.

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

axis

The CFAxis descendant instance to test.

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

Arguments

name

The name for the new axis. If an empty string is passed, will use the name of this axis.

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

Arguments

name

The name for the new axis. If an empty string is passed, will use the name of this axis.

values

The values to the used with the copy of this axis.

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

Arguments

name

The name for the new axis if the rng argument is provided.

rng

The range of indices whose values from this axis to include in the returned axis. If the value of the argument is NULL, return a copy of the axis.

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

x

Vector of numeric, timestamp or categorial coordinates to find axis indices for. The timestamps can be either character, POSIXct or Date vectors. The type of the vector has to correspond to the type of the axis values.

method

Single character value of "constant" or "linear".

rightmost.closed

Whether or not to include the upper limit. Default is TRUE.

Returns

Numeric vector of the same length as x.

---

Method write()

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

Usage

CFAxis$write(nc = NULL)

Arguments

nc

The handle of the netCDF file opened for writing or a group in the netCDF file. If NULL, write to the file or group where the axis was read from (the file must have been opened for writing).

Returns

Self, invisibly.

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