create_geozarr_array: Create a new GeoZarr array

In geozarr: GeoZarr Conventions for Geospatial Data in Zarr Stores

Create a new GeoZarr array

Description

This function creates a new GeoZarr array in an existing Zarr store. Only the structure of the array will be created; data and other properties like attributes have to be added through additional method calls. This function is particularly well suited to creating an array that mimics the structure of a netCDF data variable.

Usage

create_geozarr_array(name, location, axes, data_type, fill_value)

Arguments

name	The name of the GeoZarr array to be created.
location	A zarr_group instance. The new array will be created in this group, with the indicated name.
axes	A named list with the axis information for the array. For every element in the list an axis will be created in the array with a length that equals the number of coordinates contained in the list element. See the Details section and the example for the formatting details of the list.
data_type	Character. The Zarr data type for the array.
fill_value	Optional. The sentinel value used to indicate parts of the array that do not have data assigned. The value of this argument must agree with the data_type. If not provided a default value will be used that is specific to the data_type.

Details

The axes argument provides all the details of the coordinate system of the new array in a compound list. The elements in the list are each a list, named after the names of the axes. The number of axes listed in the top-level list determines the rank of the new array: its number of dimensions. The order of the dimensions in the array that will be created is the same as the order of the axes in this argument. The sub-lists are structured as follows:

• coordinates: A vector of coordinate values. The length of the vector becomes the length of the corresponding dimension in the array.

• boundaries: Optional. For boundaries that are regular, meaning that the lower offset ⁠(-\eqn{\infty}, 0)⁠ for each coordinate is constant and the same for the higher offset ⁠(0, \eqn{\infty})⁠, then a vector of the lower and higher offset, in that order, may be supplied. Otherwise a matrix has to be supplied with as many columns as there are coordinates and the lower offsets in row 1 and the higher offsets in row 2.

• abbreviation: A character from the set ⁠(X, Y, Z, T)⁠. These values indicate the spatio-temporal dimensions of the array. If omitted, an empty string or a space character the axis will have no spatio-temporal meaning, such as for a categorical axis. Note that both "X" and "Y" must be present in the set of axes. Abbreviations may not be duplicated across axes.

• direction: The identifier of the direction of increasing coordinate values of the axis. Its value must be present in the AxisDirection object in this package. If omitted, the direction will be inferred from the abbreviation and coordinates fields of the axis, which is usually correct.

• unit: The unit-of-measure of the coordinate values. While not mandatory, it is highly recommended to include this information. For a temporal axis the acceptable values are "second", "minute", "hour", "day" and "year", as well as the abbreviation or plural version thereof; if omitted, "days" is used. When temporal coordinates are specific as numeric offsets, this field is required.

• calendar: Temporal axis only. The name of the calendar to use. This package supports all calendars of the CF Metadata Conventions, including the "model" calendars and leap seconds in the "utc" calendar. If omitted, "proleptic_gregorian" is used, which is almost identical to the common calendar used by regular R date-time functions. When temporal coordinates are specific as numeric offsets, this field is required.

• epoch: Temporal axis only. The starting point from which time coordinates are calculated. Must be specified in ISO 8601 format, but with support for model calendars. If omitted, "1970-01-01" is used, as in regular R date-time functions. When temporal coordinates are specific as numeric offsets, this field is required.

• chunk_weight: Optional chunking weight of this axis. Higher values lead to less fragmentation of the axis into separate chunks compared to lower values. If omitted, it is set to 1 for this axis. Typical values are in the range of 1 - 3.

The top-level list may have an additional element called .convention that can hold additional information specific to the convention used for encoding of the array metadata; see below for details.

Depending on the details of the coordinates argument, the GeoZarr object may use the "spatial" or "cs" convention for encoding.

"spatial" convention: The "spatial" convention encoding is the most compact and it will be used for arrays that have X and Y axes 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, it has no mechanism to attach coordinates to any axes other than X and Y. The X and Y coordinates must be numeric and regularly spaced and the Y coordinate values 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. The axis sub-list only requires the coordinates and abbreviation fields for each of the axes; chunk_weight will be used when specified, all other fields are ignored.

If a .convention element is present in the top-level axes list then it is searched for a registration member. Its value is a character string with a value of "node" or "pixel". If omitted, a value of "pixel" is used.

"cs" convention: The "cs" convention is used for all cases where the "spatial" convention does not apply. All fields for the axis sub-lists in the axes argument are interpreted.

If the coordinates along an axis are not regularly spaced, a secondary Zarr array will be created to hold the coordinate values. By default the secondary array will be stored in the same group as the main array or another existing group may be indicated. If the length of the axis is no more than the option GeoZarr.options$max_explicit its coordinates are stored in the array cs attributes.

Any time coordinates will be converted to a CFtime format with a user-defined epoch and calendar, or default values can be used to align with the common calendar. Time coordinates may be specified as a character vector with coordinates in ISO 8601 format, or as a numeric vector of offsets from an epoch. In this latter case, the vector may not be packed and the fields "unit", "calendar" and "epoch" must be given for the temporal axis. Boundary values may be set around numerical coordinates (both spatial and temporal).

If a .convention element is present in the top-level axes list then it is searched for a coordinate_group member. Its value is a character string giving the relative path from the newly created array to the group where external coordinate arrays are to be stored. That group must already exist. If omitted, a value of ".." is used, meaning that any external coordinate arrays are placed in the same group as the new array.

Value

The new geozarr_array instance.

Examples

z <- create_zarr()
grp <- z$add_group("/", "my_data_group")
ext <- z$add_group("/", "coords")
gza <- create_geozarr_array(name = "my_data_array", location = grp,
                            data_type = "float32", fill_value = -9e12,
                            axes = list(
         longitude   = list(coordinates = seq(from = -175, to = 175, by = 10),
                            boundaries = rbind(seq(from = -180, to = 170, by = 10),
                                               seq(from = -170, to = 180, by = 10)),
                            abbreviation = "X",
                            unit = "degrees"),
         latitude    = list(coordinates = c(-90, -75, -60, -50, -40, -30, -20, -10,
                                            0, 10, 20, 30, 40, 50, 60, 75, 90),
                            abbreviation = "Y",
                            unit = "degrees"),
         time        = list(coordinates = sprintf("2026-%02d-%02d",
                                                  rep(1:12, each = 30),
                                                  rep(1:30, times = 12)),
                            abbreviation = "T",
                            unit = "days",
                            calendar = "360_day",
                            epoch = "1850-01-01",
                            chunk_weight = 1.5),
         .convention = list(coordinate_group = "../../coords")
         )
       )
z$hierarchy()
gza

geozarr documentation built on Sept. 16, 2026, 1:07 a.m.