as_geozarr: Convert an R object into a GeoZarr array

In geozarr: GeoZarr Conventions for Geospatial Data in Zarr Stores

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 documentation built on Sept. 16, 2026, 1:07 a.m.