Package {geozarr}

Title: GeoZarr Conventions for Geospatial Data in Zarr Stores
Version: 0.1.0
Description: Large-scale gridded data stores are increasingly using the Zarr format. GeoZarr is defined in terms of a number of community conventions built on top of the Zarr specification. These conventions specify how Zarr metadata is to be interpreted to attach semantic meaning to the data in the Zarr array providing the metadata. This package implements a number of community conventions on top of the 'zarr' package, enabling the R community to use geospatial data stored in Zarr.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 8.0.0
Imports: CFtime (≥ 1.7.3), R6
Depends: R (≥ 4.2), zarr (≥ 0.4.2)
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
URL: https://github.com/R-CF/geozarr
BugReports: https://github.com/R-CF/geozarr/issues
NeedsCompilation: no
Packaged: 2026-07-16 12:13:50 UTC; patrickvanlaake
Author: Patrick Van Laake [aut, cre]
Maintainer: Patrick Van Laake <patrick@vanlaake.net>
Repository: CRAN
Date/Publication: 2026-07-23 13:50:19 UTC

Coordinate system

Description

This class implements the coordinate system class. This class definition implements the same class from the OGC geoAPI Java package, extended with specific code for this package.

Super class

IdentifiedObject -> CoordinateSystem

Active bindings

axes

(read-only) Retrieve the list of axes that make up this coordinate system.

Methods

Public methods

Inherited methods

CoordinateSystem$new()

Create a new coordinate system. The CS must have at least one axis.

Usage
CoordinateSystem$new(name, axes)
Arguments
name

Character string. Name of the coordinate system.

axes

A list of instances of CoordinateSystemAxis. There must be at least one axis in the list.

Returns

An instance of CoordinateSystem or an error.

CoordinateSystem$print()

Print a summary of the coordinate system to the console.

Usage
CoordinateSystem$print(...)
Arguments
...

Ignored.

Returns

Self, invisibly.

CoordinateSystem$print_axes()

Prints details of the axes of the coordinate system to the console. Used internally.

Usage
CoordinateSystem$print_axes(...)
Arguments
...

Arguments passed on to data.frame printing.

CoordinateSystem$getDimension()

Retrieve the dimension of the coordinate system, the number of axes that make up the coordinate system.

Usage
CoordinateSystem$getDimension()
Returns

Integer value with the dimension of the coordinate system.

CoordinateSystem$getAxis()

Retrieve an axis of the coordinate system by its ordinal number.

Usage
CoordinateSystem$getAxis(dimension)
Arguments
dimension

The dimension whose axis to retrieve. Note that this is 1-based.

Returns

The CoordinateSystemAxis that forms the dimension of the coordinate system, or an error if the dimension argument in deficient.

CoordinateSystem$clone()

The objects of this class are cloneable with this method.

Usage
CoordinateSystem$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Coordinate system axis

Description

This class implements the coordinate system axis class. The axis is always associated with a coordinate system.

In an extension over the OGC standard, an axis can have multiple sets of coordinates. The unit-of-measure is associated with the coordinates and thus not with the axis.

Super class

IdentifiedObject -> CoordinateSystemAxis

Active bindings

abbreviation

Set or retrieve the abbreviation of the axis.

coordinates

(read-only) Retrieve the currently active coordinates.

length

(read-only) Retrieve the length of the axis.

Methods

Public methods

Inherited methods

CoordinateSystemAxis$new()

Create a new axis instance for use in a coordinate system.

Usage
CoordinateSystemAxis$new(name, abbreviation, coordinates)
Arguments
name

Character string. Name of the axis.

abbreviation

Character string. Abbreviation of the axis.

coordinates

A list with one or more named instances of the Coordinates class, or any of its descendants. The first element in the list will be made active.

Returns

An instance of this class or an error.

CoordinateSystemAxis$print()

Print a summary of the coordinate system axis to the console.

Usage
CoordinateSystemAxis$print(...)
Arguments
...

Ignored.

Returns

Self, invisible.

CoordinateSystemAxis$brief()

Some details of the axis.

Usage
CoordinateSystemAxis$brief()
Returns

A 1-row data.frame with some details of the axis.

CoordinateSystemAxis$copy()

Return an exact copy of this axis.

Usage
CoordinateSystemAxis$copy()
Returns

A new instance of CoordinateSystemAxis.

CoordinateSystemAxis$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
CoordinateSystemAxis$subset(name = "", rng = NULL)
Arguments
name

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

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

A new CoordinateSystemAxis 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.

CoordinateSystemAxis$slice()

Given a range of domain coordinate values, returns the indices into this 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
CoordinateSystemAxis$slice(rng)
Arguments
rng

A numeric vector whose extreme values indicate the indices of coordinates to return.

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.

CoordinateSystemAxis$getAbbreviation()

Retrieve the abbreviation of the axis. This method is mandatory in the OGC standard.

Usage
CoordinateSystemAxis$getAbbreviation()
Returns

Character string with the abbreviation of the axis.

CoordinateSystemAxis$getDirection()

Retrieve the direction of the axis. This method is mandatory in the OGC standard.

Usage
CoordinateSystemAxis$getDirection()
Returns

Character string with the direction of the axis.

CoordinateSystemAxis$getUnit()

Retrieve the unit of measure of the axis. This method is mandatory in the OGC standard.

Usage
CoordinateSystemAxis$getUnit()
Returns

Character string with the unit of measure of the axis.

CoordinateSystemAxis$getMinimumValue()

Retrieve the minimum coordinate value of this axis, in units of the unit of measure of the axis.

Usage
CoordinateSystemAxis$getMinimumValue()
Returns

Negative infinity.

CoordinateSystemAxis$getMaximumValue()

Retrieve the maximum coordinate value of this axis, in units of the unit of measure of the axis.

Usage
CoordinateSystemAxis$getMaximumValue()
Returns

Positive infinity.

CoordinateSystemAxis$getRangeMeaning()

Retrieve the minimum coordinate value of this axis, in units of the unit of measure of the axis.

Usage
CoordinateSystemAxis$getRangeMeaning()
Returns

The character string 'EXACT'.

CoordinateSystemAxis$clone()

The objects of this class are cloneable with this method.

Usage
CoordinateSystemAxis$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Coordinates

Description

This class implements the coordinates class. The coordinates are always associated with a coordinate system axis.

This class provides the basic interface for coordinate values and it manages numeric coordinate values, both integer and floating-point. Descendant classes manage packed numerical values, character values and time values.

The optional boundary values for numeric coordinate values that define the finite extent of each element in the coordinates are also managed by this class.

Active bindings

name

Set or retrieve the name of the coordinate set.

direction

Set or retrieve the direction of the coordinates.

values

(read-only) Retrieve the coordinate values as a full vector of values.

raw

(read-only) Retrieve the coordinate values as stored, either a full vector or packed.

bounds

(read-only) Retrieve the boundary values around coordinates.

range

(read-only) Retrieve the extreme values of the coordinates.

length

(read-only) The number of elements in this instance once the values are unpacked.

unit

Character string giving the unit-of-measure of the coordinate values.

Methods

Public methods

Coordinates$new()

Create a new coordinates instance for use with a coordinate system axis.

Usage
Coordinates$new(name, direction, unit, values, bounds = NULL)
Arguments
name

Character string. Name of the coordinate set.

direction

Character string. Direction of the coordinates. Must be one from a set of values.

unit

Character string. Unit of measure of the coordinates.

values

A vector of values. If argument values_packed is TRUE then there are two values: the initial coordinate value and the increment. Otherwise this is a vector of values.

bounds

Optional. If the boundaries are regularly spaced, a vector with the offset to the boundary lower and higher than the coordinate value, respectively. If the boundaries are irregularly spaced, a matrix with two rows and as many columns as there are elements, with the offset to the boundary below the coordinate value in row 1 and the offset to the boundary above the coordinate value in row 2. The boundaries represent the finite extent around the boundary value that this value is representative for. If this argument is not provided, the coordinate values are assumed to represent a point value.

Returns

An instance of this class or an error.

Coordinates$print()

Print a summary of the coordinates to the console.

Usage
Coordinates$print(...)
Arguments
...

Ignored.

Returns

Self, invisible.

Coordinates$brief()

Some details of the axis.

Usage
Coordinates$brief()
Returns

A 1-row data.frame with some details of the axis.

Coordinates$copy()

Return an exact copy of these coordinates.

Usage
Coordinates$copy()
Returns

A new instance of Coordinates.

Coordinates$subset()

Return coordinates spanning a smaller coordinate range.

Usage
Coordinates$subset(rng)
Arguments
rng

The range of indices to include in the returned coordinates.

Returns

A new Coordinates instance covering the indicated range of indices, including boundary values, present.

Coordinates$slice()

Given a range of domain coordinate values, returns the indices into the axis that fall within the supplied range. If the axis has boundary values, any coordinate whose boundary values fall entirely or partially within the supplied range will be included in the result.

Usage
Coordinates$slice(rng)
Arguments
rng

A numeric vector whose extreme values indicate the indices of coordinates to return.

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.

Coordinates$getDirection()

Retrieve the direction of the coordinates. This method is mandatory in the OGC standard for an axis.

Usage
Coordinates$getDirection()
Returns

Character string with the direction of the coordinates.

Coordinates$getUnit()

Retrieve the unit of measure of the coordinates. This method is mandatory in the OGC standard for an axis.

Usage
Coordinates$getUnit()
Returns

Character string with the unit of measure of the axis.

Coordinates$getMinimumValue()

Retrieve the minimum coordinate value of this set of coordinates, in units of the unit of measure of the coordinates.

Usage
Coordinates$getMinimumValue()
Returns

Negative infinity.

Coordinates$getMaximumValue()

Retrieve the maximum coordinate value of this set of coordinates, in units of the unit of measure of the coordinates.

Usage
Coordinates$getMaximumValue()
Returns

Positive infinity.

Coordinates$getRangeMeaning()

Retrieve the interpretation of coordinate values, either as a direct value ("EXACT") or as a wrap-around value between the minimum and maximum value of the coordinates ("WRAPAROUND").

Usage
Coordinates$getRangeMeaning()
Returns

The character string 'EXACT'.

Ordinal coordinate values

Description

This class implements ordinal values. Ordinal values are typically assigned to axes that have no other coordinates assigned to them. By default, ordinal values start at 0 (as per the Zarr specification) but after subsetting or other forms of selection the value may be different.

Super classes

Coordinates -> CoordinatesPacked -> CoordinatesOrdinal

Methods

Public methods

Inherited methods

CoordinatesOrdinal$new()

Create an instance of this class.

Usage
CoordinatesOrdinal$new(name, direction, length, low = 0L)
Arguments
name

Character string. Name of the coordinate set.

direction

Character string. Direction of the coordinates. Must be one from a set of values.

length

Integer value giving the number of elements in this instance.

low

Optional. Integer value giving the lowest index value in this instance. When omitted, defaults to 0L.

Returns

An instance of this class.

CoordinatesOrdinal$copy()

Return an exact copy of these coordinates.

Usage
CoordinatesOrdinal$copy()
Returns

A new instance of CoordinatesOrdinal.

CoordinatesOrdinal$subset()

Return a subset of the coordinate values.

Usage
CoordinatesOrdinal$subset(rng)
Arguments
rng

The range of indices whose values from these coordinate values to include in the result.

Returns

A new CoordinatesOrdinal instance covering the indicated range of values.

CoordinatesOrdinal$clone()

The objects of this class are cloneable with this method.

Usage
CoordinatesOrdinal$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Packed coordinates

Description

This class implements the packed coordinates class. The coordinates are always associated with a coordinate system axis.

This class provides the specific interface for packed numeric coordinate values, both integer and floating-point.

Super class

Coordinates -> CoordinatesPacked

Active bindings

values

(read-only) Retrieve the unpacked coordinate values.

range

(read-only) Retrieve the extreme values of the coordinates.

Methods

Public methods

Inherited methods

CoordinatesPacked$new()

Create a new coordinates instance for use with a coordinate system axis for regularly spaced coordinate values.

Usage
CoordinatesPacked$new(name, direction, unit, values, length, bounds = NULL)
Arguments
name

Character string. Name of the coordinate set.

direction

Character string. Direction of the coordinates. Must be one from a set of values.

unit

Character string. Unit of measure of the coordinates.

values

A vector of values. There must be two values: the initial coordinate value and the increment.

length

Integer value giving the number of coordinates that this packed data is for.

bounds

Optional. If the boundaries are regularly spaced, a vector with the offset to the boundary lower and higher than the coordinate value, respectively. If the boundaries are irregularly spaced, a matrix with two rows and as many columns as there are elements, with the offset to the boundary below the coordinate value in row 1 and the offset to the boundary above the coordinate value in row 2. The boundaries represent the finite extent around the boundary value that this value is representative for. If this argument is not provided, the coordinate values are assumed to represent a point value.

Returns

An instance of this class or an error.

CoordinatesPacked$copy()

Return an exact copy of these coordinates.

Usage
CoordinatesPacked$copy()
Returns

A new instance of CoordinatesPacked.

CoordinatesPacked$subset()

Return coordinates spanning a smaller coordinate range.

Usage
CoordinatesPacked$subset(rng)
Arguments
rng

The range of indices to include in the returned coordinates.

Returns

A new CoordinatesPacked instance covering the indicated range of indices, including boundary values, present.

String-type coordinates

Description

This class implements the string-type coordinates class. The coordinates are always associated with a coordinate system axis.

This class provides the specific interface for string-type coordinate values.

Super class

Coordinates -> CoordinatesString

Methods

Public methods

Inherited methods

CoordinatesString$new()

Create a new coordinates instance for use with a coordinate system axis for string-type coordinate values.

Usage
CoordinatesString$new(name, direction, unit, values)
Arguments
name

Character string. Name of the coordinate set.

direction

Character string. Direction of the coordinates. Must be one from a set of values.

unit

Character string. Unit of measure of the coordinates.

values

A vector of values. There must be two values: the initial coordinate value and the increment.

Returns

An instance of this class or an error.

CoordinatesString$copy()

Return an exact copy of these coordinates.

Usage
CoordinatesString$copy()
Returns

A new instance of CoordinatesString.

CoordinatesString$subset()

Return coordinates spanning a smaller coordinate range.

Usage
CoordinatesString$subset(rng)
Arguments
rng

The range of indices to include in the returned coordinates.

Returns

A new CoordinatesString instance covering the indicated range of indices.

Time coordinates

Description

This class implements the coordinates class for time. Time coordinates can use any of the calendars defined by the CF Metadata Conventions.

This class will store the explicit values of the time coordinate, and optionally its boundaries, just like other instances of the base class Coordinates. Additionally, it stores an instance of CFTime, which converts the raw values to intelligible coordinates, such as "2026-06-01T12:04:15".

Super class

Coordinates -> CoordinatesTime

Active bindings

values

(read-only) Retrieve the coordinate values as timestamps.

time

(read-only) The CFTime instance managing the coordinates.

offsets

(read-only) Retrieve the numeric offsets of the time coordinate values.

Methods

Public methods

Inherited methods

CoordinatesTime$new()

Create a new coordinates instance for use with a coordinate system axis for time.

Usage
CoordinatesTime$new(
  name,
  direction,
  unit,
  epoch,
  calendar = "standard",
  values,
  bounds = NULL
)
Arguments
name

Character string. Name of the coordinate set.

direction

Character string. Direction of increasing coordinate values. Must be either "FUTURE" or "PAST".

unit

Character string. Unit of measure of the time coordinates. Must be "second", "minute", "hour", "day" or "year", or the abbreviation or plural thereof.

epoch

Character string. An ISO 8601 time stamp providing the reference point for time coordinate calculations.

calendar

Character string, optional. The calendar to use for the time coordinates. Must be one of the calendars supported by the CF Metadata Conventions. If not given, defaults to "standard".

values

A vector of values. They may be numeric, in which case they are taken to be offsets from the epoch in the given unit, or character, in which case they must be ISO 8601 time stamps.

bounds

Optional. If the boundaries are regularly spaced, a vector with the offset to the boundary lower and higher than the coordinate value, respectively. If the boundaries are irregularly spaced, a matrix with two rows and as many columns as there are elements, with the offset to the boundary below the coordinate value in row 1 and the offset to the boundary above the coordinate value in row 2. The boundaries represent the finite extent around the boundary value that this value is representative for. If this argument is not provided, the coordinate values are assumed to represent a point value.

Returns

An instance of this class or an error.

CoordinatesTime$copy()

Return an exact copy of these coordinates.

Usage
CoordinatesTime$copy()
Returns

A new instance of CoordinatesTime.

CoordinatesTime$slice()

Retrieve the indices of the time axis falling between two extreme values.

Usage
CoordinatesTime$slice(x, rightmost.closed = FALSE)
Arguments
x

A vector of two timestamps in between of which all indices into the time axis to extract.

rightmost.closed

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

Returns

An integer vector giving the indices in the time axis between values in x, or NULL if none of the values are valid.

Identified object

Description

This class definition implements the same class from the OGC geoAPI Java package, extended with specific code for this package. This class is ancestor to many other, more useful classes. This class just provides basic identification properties. It is not very useful to instantiate this class directly; instead, use descendant classes.

Active bindings

name

(read-only) The name of the object.

Methods

Public methods

IdentifiedObject$new()

Create a new object.

Usage
IdentifiedObject$new(name)
Arguments
name

Character string. Name of the object.

Returns

A new instance of the object, or an error if the object could not be created.

IdentifiedObject$getName()

Retrieve the name of the object. This method is mandatory in the OGC standard.

Usage
IdentifiedObject$getName()
Returns

Character string with the name of the object.

IdentifiedObject$setAlias()

Set aliases for the object. The aliases are added at the end of the defined aliases.

Usage
IdentifiedObject$setAlias(alias)
Arguments
alias

Character vector with aliases for the object.

Returns

Self, invisibly.

IdentifiedObject$getAlias()

Retrieve the list of aliases for the name of the object. This method is optional in the OGC standard.

Usage
IdentifiedObject$getAlias()
Returns

List of aliases for the name of the object.

IdentifiedObject$setIdentifiers()

Set identifiers for the object. The identifiers are added at the end of the defined identifiers.

Usage
IdentifiedObject$setIdentifiers(id)
Arguments
id

Character vector with identifiers for the object.

Returns

Self, invisibly.

IdentifiedObject$getIdentifiers()

Retrieve the list of identifiers of the object. This method is optional in the OGC standard.

Usage
IdentifiedObject$getIdentifiers()
Returns

List of identifiers for the object.

IdentifiedObject$setRemarks()

Set remarks for the object.

Usage
IdentifiedObject$setRemarks(remarks)
Arguments
remarks

Character string with remarks for the object.

Returns

Self, invisibly.

IdentifiedObject$getRemarks()

Retrieve the remarks of the object. This method is optional in the OGC standard.

Usage
IdentifiedObject$getRemarks()
Returns

Character string with remarks or NA if no remarks have been set.

IdentifiedObject$clone()

The objects of this class are cloneable with this method.

Usage
IdentifiedObject$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

Convert an R object into a GeoZarr array

Description

This function creates a GeoZarr object from an R matrix or array. A GeoZarr object is like a Zarr object but with special attributes to establish a coordinate system. Default settings will be taken from the R object (data type, shape). Data is chunked into chunks of length 100 (or less if the array is smaller) and compressed.

Usage

as_geozarr(x, name = NULL, location = NULL, registration = "pixel")

Arguments

x

The R object to convert. Must be a matrix or array of a numeric or logical type.

name

Optional. The name of the GeoZarr array to be created. If omitted, an array will be created at the root of the Zarr store.

location

Optional. If supplied, either an existing zarr_group in a zarr object, or a character string giving the location on a local file system where to persist the data. If the argument is a zarr_group, argument name must be provided. If the argument gives the location for a new Zarr store then the location must be writable by the calling code. As per the Zarr specification, it is recommended to use a location that ends in ".zarr" when providing a location for a new store. If argument name is given then the geozarr_array will be created in the root of the zarr store with that name. If the name argument is not given, a single-array Zarr store will be created. If the location argument is not given, a zarr object is created in memory.

registration

Either "pixel" (the default) or "node". Pixel registration interprets the coordinates in the "dimnames" of argument x as being the upper-left corner of each grid cell. Node registration interprets them as the centers of grid cells. In both cases the elements in the array are assumed to represent an area.

Details

Depending on the properties of the R object, the GeoZarr object may use the "spatial" or "cs" convention for encoding. The "spatial" encoding is the most compact and it will be used for R objects that have at least X and Y dimensions, identified by the names set on the dimensions, and an optional third axis which is typically an image band or a discrete (class) axis – the third axis may not represent height/depth (Z) or time (T). While the "spatial" convention does work on Zarr arrays with more dimensions, there is no mechanism to attach coordinates to any additional axes. The coordinates must be numeric and regularly spaced and the Y coordinates must be decreasing. In other words, the "spatial" convention will be used for imagery style, north-up arrays with a coordinate system tied to the top-left corner of the array space. For all other cases the "cs" convention will be used.

If the coordinates along the axes (the dimnames of the R object) are not regularly spaced, secondary Zarr arrays will be created in the same group as the main Zarr array with the axis coordinates, if the length of the axis is longer than the option GeoZarr.options$max_explicit – shorter sets of coordinates are stored in the Zarr array cs attributes.

Any time coordinates will be converted to a CFtime format with a reference of "days since 1970-01-01", compatible with the standard system clock.

For more exacting requirements, you should manually construct the GeoZarr object from R objects.

Value

If the location argument is a zarr_group, the new geozarr_array instance is returned. Otherwise, the zarr object that is newly created and which contains the GeoZarr array in the root group, or an error if the zarr object could not be created.

Examples

x <- array(1:400, c(5, 20, 4))
dimnames(x) <- list(x = 100000 + 0:4 * 10000, y = 19:0 * 5000, cls = letters[1:4])
z <- as_geozarr(x, "my_data")
z

GeoZarr Array

Description

This class implements a GeoZarr array. A GeoZarr array is like a regular Zarr array but it has attributes and/or associated Zarr arrays that provide a coordinate system for the array.

Super classes

zarr::zarr_node -> zarr::zarr_array -> geozarr_array

Active bindings

coordinate_system

(read-only) Retrieve the coordinate system of this array.

Methods

Public methods

Inherited methods

geozarr_array$new()

Initialize a new GeoZarr array.

Usage
geozarr_array$new(name, metadata, parent, store, coord_sys)
Arguments
name

The name of the GeoZarr array.

metadata

List with the metadata of the array.

parent

The parent zarr_group instance of this new array, can be missing or NULL if the Zarr object should have just this array.

store

The zarr_store instance to persist data in.

coord_sys

Optional, an instance of CoordinateSystem providing the coordinate system of the array. If not provided, the coordinate system is constructed from the metadata of the array persisted in the store.

Returns

An instance of geozarr_array.

geozarr_array$post_open()

Perform any processing after the Zarr hierarchy is in place and out-of-group references can be resolved.

Usage
geozarr_array$post_open()
Returns

Self, invisibly.

geozarr_array$build_coordsys()

Build the coordinate system of the GeoZarr array if it has not been set yet. This should only be called when the Zarr hierarchy is in place and out-of-group references can be resolved, particularly for the cs convention.

Usage
geozarr_array$build_coordsys()
Returns

Self, invisibly.

geozarr_array$subset()

This method extracts a subset of values from the GeoZarr array, with the range along each axis to extract expressed in coordinate values of the domain of each axis.

Usage
geozarr_array$subset(
  ...,
  .name = NULL,
  .location = NULL,
  .rightmost.closed = FALSE
)
Arguments
...

One or more arguments of the form axis = range. The "axis" part should be the name of an axis or its abbreviation X, Y, Z or T. The "range" part is a vector of values representing coordinates along the axis where to extract data. Axis abbreviations and names are case-sensitive and can be specified in any order. If values for the range per axis fall outside of the extent of the axis, the range is clipped to the extent of the axis.

.name

The name of the GeoZarr array to be created. If omitted, an array will be created at the root of a new in-memory Zarr store.

.location

Optional. If supplied, either an existing zarr_group in a zarr object, or a character string giving the location on a local file system where to persist the data. If the argument is a zarr_group, argument .name must be provided. If the argument gives the location for a new Zarr store then the location must be writable by the calling code. As per the Zarr specification, it is recommended to use a location that ends in ".zarr" when providing a location for a new store. If argument .name is given then the geozarr_array will be created in the root of the zarr store with that name. If the .name argument is not given, a single-array Zarr store will be created. If the location argument is not given, a zarr object is created in memory.

.rightmost.closed

Optional. Single logical value to indicate if the upper boundary of range in each axis should be included.

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 from which the range is computed. 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. For character axes the order in the axis will be used, with the first and last value in the supplied range.

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 array, with degenerate dimensions preserved. The order of the axes in argument ... does not reorder the axes in the result.

Arguments following ... must be explicitly named, like .rightmost.closed = TRUE, to avoid the argument being treated as an axis name.

As an example, to extract values of a variable for Australia for the year 2020, where the first axis in GeoZarr array 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.

Returns

If the .location argument is a zarr_group, the new Zarr geozarr_array is returned, with a subset of data from this GeoZarr array, having the axes and attributes of this GeoZarr array. Otherwise, the zarr object that is newly created and which contains the geozarr_array instance, or an error if the zarr object could not be created. If one or more of the selectors in the ... argument fall entirely outside of the range of the axis NULL is returned.

GeoZarr Group

Description

This class implements a GeoZarr group. A GeoZarr group is a group in the hierarchy of a Zarr object having GeoZarr attributes. A GeoZarr group is a container for other groups and arrays.

Super classes

zarr::zarr_node -> zarr::zarr_group -> geozarr_group

Methods

Public methods

Inherited methods

geozarr_group$new()

Open a GeoZarr group in a Zarr hierarchy.

Usage
geozarr_group$new(name, metadata, parent, store)
Arguments
name

The name of the group. For a root group, this is the empty string "".

metadata

List with the metadata of the group.

parent

The parent Zarr group instance of this new group, can be missing or NULL for the root group.

store

The zarr_store instance to persist data in.

Returns

An instance of geozarr_group.

GeoZarr package options

Description

Use this function to read or modify package options.

Usage

geozarr_options(key, value)

Arguments

key

Character. A key whose value to modify. If missing, all options are returned.

value

The new value for the option.

Value

A list with all options if argument key is not provided, nothing otherwise.

Examples

geozarr_options()

GeoZarr "proj" convention

Description

This class implements the GeoZarr "proj" convention. In particular, the following convention is implemented here: 

{
  "schema_url": "https://raw.githubusercontent.com/zarr-conventions/geo-proj/refs/tags/v1/schema.json",
  "spec_url": "https://github.com/zarr-conventions/geo-proj/blob/v1/README.md",
  "uuid": "f17cb550-5864-4468-aeb7-f3180cfb622f",
  "name": "proj",
  "description": "Coordinate reference system information for geospatial data"
}

Super class

zarr::zarr_convention -> zarr_conv_proj

Active bindings

code

The "proj:code" attribute, a character string in "authority:code" format identifying a CRS.

wkt2

The "proj:wkt2" attribute, a character string giving a CRS in WKT2 format.

projjson

The "proj:projjson" attribute, a character string giving a CRS in PROJJSON format.

Methods

Public methods

Inherited methods

zarr_conv_proj$new()

Create a new instance of a "proj" convention agent.

Usage
zarr_conv_proj$new()
Returns

A new instance of a "proj" convention agent.

zarr_conv_proj$write()

Write the data of this instance in the attributes of a Zarr object.

Usage
zarr_conv_proj$write(attributes)
Arguments
attributes

A list with Zarr attributes for a group or array. The properties will be written at the root level of attributes.

Returns

The updated attributes.

GeoZarr "spatial" convention

Description

This class implements the GeoZarr "spatial" convention. In particular, the following convention is implemented here: 

{
  "schema_url": "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json",
  "spec_url": "https://github.com/zarr-conventions/spatial/blob/v1/README.md",
  "uuid": "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4",
  "name": "spatial",
  "description": "Spatial coordinate information"
}

Super class

zarr::zarr_convention -> zarr_conv_spatial

Active bindings

dimensions

The "spatial:dimensions" attribute, a character vector of dimension names for the Y and X axes, in that order. These names must correspond to the names in the "dimension_names" attribute of the array that this convention relates to.

bbox

The "spatial:bbox" attribute, a numeric vector of 4 values in order ⁠xmin, ymin, xmax, ymax⁠ giving the boundary coordinates of the data array.

transform_type

(read-only) The "spatial:transform_type" attribute, a character string giving the type of coordinate transformation. The only valid value (currently) is "affine".

transform

The "spatial:transform" attribute, a numeric vector of 6 values (1) X resolution; (2) 0; (3) X coordinate of UL corner; (4) 0; (5) Y resolution; (6) Y coordinate of UL corner, giving the transformation coefficients of the coordinates of the data array.

shape

The "spatial:shape" attribute, an integer vector of length 2 giving the length of the X and Y dimensions.

registration

The "spatial:registration" attribute, a string with value "node" or "pixel". "pixel" (the default) means that the coordinates of the UL corner of each grid cell are recorded; "node" means that the coordinates of the center of each grid cell are recorded.

Methods

Public methods

Inherited methods

zarr_conv_spatial$new()

Create a new instance of a "spatial" convention agent.

Usage
zarr_conv_spatial$new()
Returns

A new instance of a "spatial" convention agent.

zarr_conv_spatial$set_coordinates()

Set the coordinate system for this instance. This method sets the affine transform coefficients, as well as the grid cell registration and the bounding box.

Usage
zarr_conv_spatial$set_coordinates(x, y, shape, registration = "pixel")
Arguments
x, y

Coordinates for the X and Y axes, as a numeric vector of two values: the top-left coordinate of the top-left grid cell and the resolution along the axis, respectively. Note that for y the resolution must be negative.

shape

The length of each axis x and y.

registration

Grid cell registration. "pixel" (the default) means that the coordinates in x and y are interpreted as the UL corner of each grid cell; "node" means that the coordinates are interpreted as the center of each grid cell.

Returns

Self, invisibly.

zarr_conv_spatial$write()

Write the data of this instance in the attributes of a Zarr object.

Usage
zarr_conv_spatial$write(attributes)
Arguments
attributes

A list with Zarr attributes for a group or array. The properties will be written at the root level of attributes.

Returns

The updated attributes.

GeoZarr "cs" convention

Description

This class implements the GeoZarr "cs" (coordinate set) convention. The convention attaches a full coordinate system to a Zarr array by recording, for each dimension, the axis abbreviation and direction, one or more sets of coordinate values and their optional cell-boundary values, and, where applicable, the parametric formula and its terms needed to derive physical coordinates from stored index coordinates.

The convention is registered via the following CMO: 

{
  "schema_url": "https://raw.githubusercontent.com/R-CF/zarr_convention_cs/main/schema.json",
  "spec_url":   "https://raw.githubusercontent.com/R-CF/zarr_convention_cs/main/README.md",
  "uuid":       "e4dbf0b7-7a00-4ce6-b23e-484292014ab4",
  "name":       "cs",
  "description": "Coordinate set convention for Zarr arrays"
}

The cs attribute written to the array metadata has the following structure (simplified): 

{
  "cs": {
    "crs": [
      {
        "axes": {
          "<dimension_name>": {
            "abbreviation": "X",
            "direction":    "EAST",
            "coordinates":  [ { "unit": "degrees",
                                "values": { "regular": [0.0, 0.5] } } ]
          }
        }
      }
    ]
  }
}

Build a convention instance, add one or more CRS objects (each covering one or more dimension axes), then call as_list() to retrieve everything for inclusion as the "cs" attribute in the Zarr node metadata.

Super class

zarr::zarr_convention -> zarr_convention_cs

Active bindings

name

Optional descriptive name for the coordinate set.

crs

(read-only) The list of CRS objects accumulated so far.

Methods

Public methods

Inherited methods

zarr_convention_cs$new()

Create a new instance of a "cs" convention agent.

Usage
zarr_convention_cs$new()
Returns

A new instance of a "cs" convention agent.

zarr_convention_cs$add_crs()

Add a CRS object to this coordinate set. Each CRS covers one or more axes (dimensions). Multiple calls add further CRS objects to the array, which is necessary when the array spans domains described by separate OGC coordinate reference systems (e.g. a horizontal CRS plus a vertical CRS plus a temporal CRS).

Usage
zarr_convention_cs$add_crs(axes, name = NULL, id = NULL, geolocation = NULL)
Arguments
axes

A named list of axis definitions, keyed by the dimension name that appears in the Zarr array's dimension_names metadata. If the argument is NULL or an empty list, the call is a no-op.

name

Optional character string. Descriptive name for the CRS.

id

Optional. Convention proj attributes (proj:code, proj:wkt2, or proj:projjson) providing the formal OGC description of the CRS.

geolocation

Optional list. Geolocation grid definition for curvilinear grids. This should only be included for CRS's that represent a planar coordinate system.

Returns

Self, invisibly.

zarr_convention_cs$as_list()

Retrieve the cs attributes as a list.

Usage
zarr_convention_cs$as_list()
Returns

A list with the updated attributes for this convention.

zarr_convention_cs$axis()

Build an axis definition.

Usage
zarr_convention_cs$axis(coordinates, abbreviation = NULL, direction = NULL)
Arguments
coordinates

A list of coordinate-set definitions, each produced by coordinates(). Must have at least one element.

abbreviation

Optional character string. Axis abbreviation, e.g. "X", "Y", "Z", or "T".

direction

Optional character string. Direction of increasing coordinate values taken from Table 48 of the OGC standard "Referencing by Coordinates" (e.g. "EAST", "NORTH", "UP", "FUTURE").

Returns

A named list representing one axis entry.

zarr_convention_cs$coordinates()

Build a coordinate-set definition for use in axis().

Usage
zarr_convention_cs$coordinates(
  values,
  name = NULL,
  unit = NULL,
  boundaries = NULL,
  parametric = NULL,
  time = NULL
)
Arguments
values

A values definition produced by one of values_regular(), values_explicit(), or values_external().

name

Optional, character string. Descriptive name for this set of coordinates.

unit

Optional, character string. Unit of measure (e.g. "degrees_east", "m", "1").

boundaries

Optional boundaries definition produced by boundaries_regular() or values_external().

parametric

Optional parametric definition produced by parametric().

time

Optional time definition produced by time().

Returns

A named list representing one coordinates entry.

zarr_convention_cs$values_regular()

Regularly-spaced coordinate values.

Usage
zarr_convention_cs$values_regular(start, increment)
Arguments
start

Numeric. The coordinate value at shape index 0.

increment

Numeric. The constant spacing between successive values. May be negative for decreasing coordinates (e.g. north-to-south latitudes); it cannot be 0.

Returns

A values list with a regular element.

zarr_convention_cs$values_explicit()

Explicitly listed coordinate values.

Usage
zarr_convention_cs$values_explicit(values)
Arguments
values

A vector of coordinate values. May be numeric, integer, or character.

Returns

A values list with an explicit element.

zarr_convention_cs$values_external()

Coordinate values stored in an external array

Usage
zarr_convention_cs$values_external(node, uri)
Arguments
node

Character string. Path to the 1-dimensional Zarr array containing the coordinate values, relative to the referring node.

uri

Optional character string. URI of an external store. Omit for arrays in the same local store.

Returns

A values list with an external element.

zarr_convention_cs$boundaries_regular()

Regularly-spaced cell-boundary values.

The two values give the offset below and above the coordinate value that define the extent of each cell, in the same unit as the coordinates. Both offsets are expressed as positive magnitudes; the convention interprets "below" as the lower-valued boundary and "above" as the higher-valued boundary regardless of the sign of the axis increment.

Usage
zarr_convention_cs$boundaries_regular(below, above)
Arguments
below, above

Numeric. Positive offset from the coordinate value to the lower and upper boundary, respectively.

Returns

A boundaries list with a regular element.

zarr_convention_cs$time()

Provides the time reference information needed to interpret numeric coordinate values on a temporal axis.

Usage
zarr_convention_cs$time(unit, epoch, calendar = NULL)
Arguments
unit

Character string. The time unit, e.g. "days", "hours", "seconds".

epoch

Character string. The reference date/time in ISO 8601 format, e.g. "1970-01-01".

calendar

Optional character string. The CF calendar name, e.g. "standard", "360_day". Defaults to "proleptic_gregorian" when omitted.

Returns

A time list.

zarr_convention_cs$parametric()

Records the CF formula name and the set of formula terms needed to derive physical coordinates from the stored parametric index coordinates. This object sits alongside values inside a coordinates() call; values provides the stored parametric coordinates (e.g. s_rho), while parametric provides the machinery to recover the physical coordinates (e.g. depth in metres).

Usage
zarr_convention_cs$parametric(formula, terms)
Arguments
formula

Character string. The CF standard_name of the parametric coordinate formula, e.g. "ocean_s_coordinate_g2".

terms

A named list of formula term values. Each element must be a values attribute object. Scalar or short constants should use explicit coordinate values; full-length arrays should use external Zarr arrays.

Returns

A parametric list.

GeoZarr domain object

Description

This class implements a GeoZarr domain object. A GeoZarr domain object is a zarr_domain descendant object identifying groups and arrays in a zarr object that are formatted using GeoZarr conventions.

This domain supports the standard conventions for GeoZarr data sets, specifically the cs and spatial conventions, as well as two other formats for geospatial Zarr data that predate GeoZarr: the format used by the Python XArray library (Zarr v.2 and v.3) and the NCZarr format (Zarr v.2).

Super class

zarr::zarr_domain -> zarr_domain_geozarr

Methods

Public methods

zarr_domain_geozarr$new()

Create a new GeoZarr domain instance. The GeoZarr domain instance manages the groups and arrays in the Zarr store that it refers to. This instance provides access to all objects in the Zarr store.

Usage
zarr_domain_geozarr$new()
Returns

A zar_domain_geozarr object.

zarr_domain_geozarr$build()

This method will create a geozarr_array for an array node and a geozarr_group for a group node with GeoZarr conventions declared in its attributes. Either the "spatial" or "cs" convention has to be declared or the Zarr store has to be formatted using XArray or NCZarr or this domain will decline to manage the node.

Usage
zarr_domain_geozarr$build(name, metadata, parent, store)
Arguments
name

The name of the node.

metadata

List with the metadata of the node.

parent

The parent node of this new node. May be NULL for a root node.

store

The store to persist data in.

Returns

A geozarr_array or geozarr_group instance if supported, FALSE otherwise.