| Title: | GeoZarr Conventions for Geospatial Data in Zarr Stores |
| Version: | 0.4.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.4), zarr (≥ 1.0.1) |
| Suggests: | cli, 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-11-17 07:30:11 UTC; patrickvanlaake |
| Author: | Patrick Van Laake [aut, cre] |
| Maintainer: | Patrick Van Laake <patrick@vanlaake.net> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-17 09:00:08 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 classes
zarr::zarr_object -> IdentifiedObject -> CoordinateSystem
Active bindings
axes(read-only) Retrieve the list of axes that make up this coordinate system.
crsSet or retreive the CRS identifier of the coordinate system.
geolocationSet or retrieve the geolocation arrays of the coordinate system, an instance of zarr_convention_geolocation, or
NULLwhen there are none. Thexandyarrays of the geolocation correspond to the axes of the coordinate system with abbreviation "X" and "Y", respectively. Set toNULLto remove the geolocation. Setting the field removes any geolocation data of the same kinds that was set withset_geolocation().An error is thrown when setting a value that is not a
zarr_convention_geolocationinstance with geolocation arrays set, or when the coordinate system does not have exactly one axis with abbreviation "X" and one with abbreviation "Y".geolocation_data(read-only) The geolocation data set with
set_geolocation()that has not yet been written to a Zarr store, alistkeyed by "geodetic" and/or "planar". Empty when there is none.
Methods
Public methods
Inherited methods
zarr::zarr_object$append_array_attribute()zarr::zarr_object$attribute()zarr::zarr_object$delete_attribute()zarr::zarr_object$print_attributes()zarr::zarr_object$set_attribute()IdentifiedObject$getAlias()IdentifiedObject$getIdentifiers()IdentifiedObject$getName()IdentifiedObject$getRemarks()IdentifiedObject$setAlias()IdentifiedObject$setIdentifiers()IdentifiedObject$setRemarks()
CoordinateSystem$new()
Create a new coordinate system. The CS must have at least one axis.
Usage
CoordinateSystem$new(name, axes, crs = "", attributes = list())
Arguments
nameCharacter string. Name of the coordinate system.
axesA
listof instances of CoordinateSystemAxis. There must be at least one axis in the list. The elements in the list must be in the order of the dimensions of the array that this coordinate system is used for; in other words, the first axis corresponds to the first array dimension, etc. - scalar axes (those not associated with an array dimension) are listed after the axes associated with a dimension.crsOptional, character string with the description of the CRS of this coordinate system, always assumed to be compound.
attributesOptional. A
listof attributes of the coordinate system.
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.frameprinting.
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
dimensionThe 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$set_geolocation()
Set geolocation data for the coordinate system, giving
coordinates in a geodetic or planar CRS for every element of the "X"
and "Y" axes. The data is written to the Zarr store with
geozarr_array$write_geolocation(), after which it is removed from
memory and the geolocation field references the written arrays.
Any geolocation of the same kind is replaced.
Usage
CoordinateSystem$set_geolocation( kind, x, y, dims, names, id = NULL, attributes = list(list(), list()), x_bounds = NULL, y_bounds = NULL, bounds_dims = NULL, bounds_names = NULL )
Arguments
kindCharacter string, either "geodetic" or "planar".
x, yNumeric arrays with the coordinates of the X and Y axes in the target CRS, i.e. longitude and latitude for "geodetic".
dimsCharacter vector with the names of the axes of the coordinate system that the dimensions of
xandycorrespond to, in order.namesCharacter vector of two values with the names of the Zarr arrays to write
xandyto.idOptional. An instance of zarr_conv_proj identifying the target CRS.
attributesOptional. A
listof two named lists (not data frames) with the attributes to write with the arrays forxandy, such as "units" and "standard_name".x_bounds, y_boundsOptional. Numeric arrays with the four vertices of each cell of
xandy, in the order of the geolocation convention. Must supply both or neither.bounds_dimsCharacter vector with the names of the dimensions of
x_boundsandy_bounds, in order: the names indimsplus the name of the vertex dimension, in any order. Required withx_boundsandy_bounds.bounds_namesOptional character vector of two values with the names of the Zarr arrays to write
x_boundsandy_boundsto. Defaults tonameswith "_bnds" appended.
Details
An error is thrown when the coordinate system does not have
exactly one axis with abbreviation "X" and one with abbreviation "Y";
when dims does not include the names of these two axes or names an
axis that is not in the coordinate system; when the dimensions of x
or y do not match the lengths of the axes in dims; when only one
of x_bounds and y_bounds is given; when bounds_dims is not
dims plus one other name that is not an axis of the coordinate
system; when the dimensions of x_bounds or y_bounds do not match
the lengths of the axes in bounds_dims, with length 4 for the vertex
dimension; or when the other arguments are malformed.
Returns
Self, invisibly.
CoordinateSystem$clone()
The objects of this class are cloneable with this method.
Usage
CoordinateSystem$clone(deep = FALSE)
Arguments
deepWhether 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 classes
zarr::zarr_object -> IdentifiedObject -> CoordinateSystemAxis
Active bindings
abbreviationSet or retrieve the abbreviation of the axis.
coordinates_list(read-only) Retrieve all coordinates in a
list.coordinates(read-only) Retrieve the currently active coordinates.
active_coordinatesSet 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(). When setting, provide the name of the requested coordinates. If the name is not known a warning will be generated and the currently active coordinates stay active. When retrieving, theCoordinatesinstance that is currently active.length(read-only) Retrieve the length of the axis.
Methods
Public methods
Inherited methods
zarr::zarr_object$append_array_attribute()zarr::zarr_object$attribute()zarr::zarr_object$delete_attribute()zarr::zarr_object$print_attributes()zarr::zarr_object$set_attribute()IdentifiedObject$getAlias()IdentifiedObject$getIdentifiers()IdentifiedObject$getName()IdentifiedObject$getRemarks()IdentifiedObject$setAlias()IdentifiedObject$setIdentifiers()IdentifiedObject$setRemarks()
CoordinateSystemAxis$new()
Create a new axis instance for use in a coordinate system.
Usage
CoordinateSystemAxis$new(name, abbreviation, coordinates, attributes = list())
Arguments
nameCharacter string. Name of the axis.
abbreviationCharacter string. Abbreviation of the axis.
coordinatesA 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.
attributesOptional. A
listof attributes of the axis.
Returns
An instance of this class or an error.
CoordinateSystemAxis$add_coordinates()
Add a set of coordinates to the axis. The new coordinates are not made active.
Usage
CoordinateSystemAxis$add_coordinates(coordinates)
Arguments
coordinatesAn instance of the
Coordinatesclass, or any of its descendants, with the same length as the axis and a name that is not yet used by the coordinates of the axis.
Returns
Self, invisibly.
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
nameThe name for the new axis. If an empty string is passed (default), will use the name of this axis.
rngThe 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
rngA 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$clone()
The objects of this class are cloneable with this method.
Usage
CoordinateSystemAxis$clone(deep = FALSE)
Arguments
deepWhether 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.
Super class
zarr::zarr_object -> Coordinates
Active bindings
nameSet or retrieve the name of the coordinate set.
directionSet 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.
boundsSet or retrieve the boundary values around coordinates. When setting, assign a matrix with 2 rows and as many columns as there are coordinates values. When retrieving, a matrix as just described or
NULLif boundary values have not been set.bounds_raw(read-only) Retrieve the boundary values around coordinates exactly as they are stored with the coordinate. If the boundary values are packed, a vector of length 2 is returned, otherwise a matrix with 2 rows and as many columns as there are coordinates values or
NULLif boundary values have not been set.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.
unitCharacter string giving the unit-of-measure of the coordinate values.
attributes(read-only) A named
listwith the attributes of this object.
Methods
Public methods
Inherited methods
Coordinates$new()
Create a new coordinates instance for use with a coordinate system axis.
Usage
Coordinates$new( name, direction, unit, values, bounds = NULL, attributes = list() )
Arguments
nameCharacter string. Name of the coordinate set.
directionCharacter string. Direction of the coordinates. Must be one from the set of values given in
AxisDirection.unitCharacter string. Unit of measure of the coordinates.
valuesA vector of values.
boundsOptional. If the boundaries are regularly spaced, a vector with the offset to the boundary lower and higher than the coordinate value, respectively. Otherwise, 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 coordinate value that this value is representative for. If this argument is not provided, the coordinate values are assumed to represent a point value.
attributesOptional. A
listof attributes of the coordinates.
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 coordinates.
Usage
Coordinates$brief()
Returns
A 1-row data.frame with some details of the coordinates.
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
rngThe 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
rngA 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.
Regular coordinates
Description
This class implements the coordinates class for ordinary, numeric coordinates.
This class manages numeric coordinate values, both integer and floating-point. Coordinate values may be irregularly spaced but they have to be monotonic.
Super classes
zarr::zarr_object -> Coordinates -> CoordinatesIrregular
Methods
Public methods
Inherited methods
CoordinatesIrregular$new()
Create a new regular coordinates instance for use with a coordinate system axis.
Usage
CoordinatesIrregular$new( name, direction, unit, values, bounds = NULL, attributes = list() )
Arguments
nameCharacter string. Name of the coordinate set.
directionCharacter string. Direction of the coordinates. Must be one from the set of values given in
AxisDirection.unitCharacter string. Unit of measure of the coordinates.
valuesA vector of values.
boundsOptional. If the boundaries are regularly spaced around the coordinate values, a vector with the offset to the boundary lower and higher than the coordinate value, respectively. Otherwise, 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 coordinate value that this value is representative for. If this argument is not provided, the coordinate values are assumed to represent a point value.
attributesOptional. A
listof attributes of the coordinates.
Returns
An instance of this class.
CoordinatesIrregular$copy()
Return an exact copy of these coordinates.
Usage
CoordinatesIrregular$copy()
Returns
A new instance of CoordinatesIrregular.
CoordinatesIrregular$subset()
Return coordinates spanning a smaller coordinate range.
Usage
CoordinatesIrregular$subset(rng)
Arguments
rngThe range of indices to include in the returned coordinates.
Returns
A new CoordinatesIrregular or CoordinatesPacked instance
covering the indicated range of indices, including boundary values,
present.
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
zarr::zarr_object -> Coordinates -> CoordinatesPacked -> CoordinatesOrdinal
Methods
Public methods
Inherited methods
CoordinatesOrdinal$new()
Create an instance of this class.
Usage
CoordinatesOrdinal$new(name, direction, length, low = 0L, attributes = list())
Arguments
nameCharacter string. Name of the coordinate set.
directionCharacter string. Direction of the coordinates. Must be one from a set of values.
lengthInteger value giving the number of elements in this instance.
lowOptional. Integer value giving the lowest index value in this instance. When omitted, defaults to 0L.
attributesOptional. A
listof attributes of the coordinates.
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
rngThe 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.
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 classes
zarr::zarr_object -> 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, attributes = list() )
Arguments
nameCharacter string. Name of the coordinate set.
directionCharacter string. Direction of the coordinates. Must be one from a set of values.
unitCharacter string. Unit of measure of the coordinates.
valuesA vector of values. There must be two values: the initial coordinate value and the increment.
lengthInteger value giving the number of coordinates that this packed data is for.
boundsOptional. If the boundaries are regularly spaced, a vector with the offset to the boundary lower and higher than the coordinate value, respectively. Otherwise, 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.
attributesOptional. A
listof attributes of the coordinates.
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
rngThe 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 classes
zarr::zarr_object -> 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, attributes = list())
Arguments
nameCharacter string. Name of the coordinate set.
directionCharacter string. Direction of the coordinates. Must be one from a set of values.
unitCharacter string. Unit of measure of the coordinates.
valuesA vector of values. There must be two values: the initial coordinate value and the increment.
attributesOptional. A
listof attributes of the coordinates.
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
rngThe 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 classes
zarr::zarr_object -> Coordinates -> CoordinatesTime
Active bindings
values(read-only) Retrieve the coordinate values as timestamps.
boundsSet or retrieve the boundary values around time coordinates. When setting, assign a matrix with 2 rows and as many columns as there are coordinates values, or a vector of two values with the lower and higher offset of the regular boundaries. When retrieving, a matrix as just described or
NULLif boundary values have not been set.bounds_raw(read-only) Retrieve the boundary values around time coordinates, packed if possible. If the boundary values are packed, a vector of length 2 is returned, otherwise a matrix with 2 rows and as many columns as there are coordinates values or
NULLif boundary values have not been set.time(read-only) The
CFTimeinstance 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, attributes = list() )
Arguments
nameCharacter string. Name of the coordinate set.
directionCharacter string. Direction of increasing coordinate values. Must be either "FUTURE" or "PAST".
unitCharacter string. Unit of measure of the time coordinates. Must be "second", "minute", "hour", "day" or "year", or the abbreviation or plural thereof.
epochCharacter string. An ISO 8601 time stamp providing the reference point for time coordinate calculations.
calendarCharacter 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".
valuesA vector of values. They may be numeric, in which case they are taken to be offsets from the epoch in the given unit and the values may not be packed, or character, in which case they must be ISO 8601 time stamps.
boundsOptional. 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.
attributesOptional. A
listof attributes of the coordinates.
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$subset()
Return time coordinates spanning a smaller coordinate range.
Usage
CoordinatesTime$subset(rng)
Arguments
rngThe range of indices to include in the returned time coordinates.
Returns
A new CoordinatesTime instance covering the indicated range of
indices, including boundary values, present.
CoordinatesTime$slice()
Retrieve the indices of the time axis falling between two extreme values.
Usage
CoordinatesTime$slice(x, rightmost.closed = FALSE)
Arguments
xA vector of two timestamps in between of which all indices into the time axis to extract.
rightmost.closedWhether 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.
Super class
zarr::zarr_object -> IdentifiedObject
Active bindings
name(read-only) The name of the object.
attributes(read-only) A named
listwith the attributes of this object.
Methods
Public methods
Inherited methods
IdentifiedObject$new()
Create a new object.
Usage
IdentifiedObject$new(name, attributes = list())
Arguments
nameCharacter string. Name of the object.
attributesOptional. A
listof attributes 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
aliasCharacter 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
idCharacter 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
remarksCharacter 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
deepWhether 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 |
registration |
Optional, for the "spatial" convention only. Either "pixel" (the default) or "node". Pixel registration records the coordinates of the upper-left corner of each grid cell. Node registration records the centers of grid cells. In both cases the elements in the array are assumed to represent an area and the coordinate is located in the center of the grid cell. |
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
The new geozarr_array.
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])
arr <- as_geozarr(x, "my_data")
arr
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, crs = NULL)
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 |
axes |
A named |
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 |
crs |
Optional. A |
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(-\infty, 0)for each coordinate is constant and the same for the higher offset(0, \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 theAxisDirectionobject in this package. If omitted, the direction will be inferred from theabbreviationandcoordinatesfields 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, "day" 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. -
attributes: Optional namedlistwith the attributes of the coordinates of this axis, such as "long_name" or "standard_name". They are stored with the coordinates in thecsattributes of the array or, for external coordinates, with the external array. The attributes are only used with the "cs" convention. An error is thrown if the value is not a namedlist.
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.
No attributes will be assigned to the axes given that the "spatial"convention has no support for that.
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.
Pixel registration records the coordinates of the upper-left corner of each
grid cell. Node registration records the centers of grid cells. In both
cases the elements in the array are assumed to represent an area and the
coordinate is located in the center of the grid cell.
"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 = "degree",
attributes = list(long_name = "longitude",
standard_name = "Longitude")),
latitude = list(coordinates = c(-90, -75, -60, -50, -40, -30, -20, -10,
0, 10, 20, 30, 40, 50, 60, 75, 90),
abbreviation = "Y",
unit = "degree",
attributes = list(long_name = "latitude",
standard_name = "Latitude")),
time = list(coordinates = sprintf("2026-%02d-%02d",
rep(1:12, each = 30),
rep(1:30, times = 12)),
abbreviation = "T",
unit = "day",
calendar = "360_day",
epoch = "1850-01-01",
chunk_weight = 1.5),
.convention = list(coordinate_group = "../../coords")
)
)
z$hierarchy()
gza
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_object -> 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
zarr::zarr_object$print_attributes()zarr::zarr_node$absolute_path()zarr::zarr_node$append_array_attribute()zarr::zarr_node$attribute()zarr::zarr_node$delete_attribute()zarr::zarr_node$relative_path()zarr::zarr_node$save()zarr::zarr_node$set_attribute()zarr::zarr_node$walk_path()zarr::zarr_array$copy_to()zarr::zarr_array$flush()zarr::zarr_array$hierarchy_nodes()zarr::zarr_array$print()zarr::zarr_array$promote()zarr::zarr_array$read()zarr::zarr_array$resize()zarr::zarr_array$write()
geozarr_array$new()
Initialize a new GeoZarr array.
Usage
geozarr_array$new(name, metadata, parent, coord_sys)
Arguments
nameThe name of the GeoZarr array.
metadataList with the metadata of the array.
parentThe parent
zarr_groupinstance of this new array, can be can be azarrinstance if the Zarr object should have just this array.coord_sysOptional, 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$details()
Produce a named character vector with a summary of the array including its name, data type, shape (with axis names, including scalar ones) and the chunking.
Usage
geozarr_array$details()
Returns
Named character vector with details of the array.
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, .external_group = NULL )
Arguments
...One or more arguments of the form
axis = range. The "axis" part should be the name of an axis or its abbreviationX,Y,ZorT. 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..nameThe name of the GeoZarr array to be created. If omitted, an array will be created at the root of a new Zarr store. The new array can then not have any associated arrays, such as for irregular coordinate values or boundaries.
.locationOptional. 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.namemust 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 the.locationargument is not given, azarrobject is created in memory..external_groupOptional. The group, relative to the new array, where to write its external coordinate and boundary arrays, such as
"../coordinates". If omitted, the group is taken from the external arrays of this array; see Details.
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.
Geolocation arrays of the coordinate system are not subset, so the result has no geolocation.
Coordinate values that are irregular and long, and irregular boundary
values, are written to external arrays next to the new array. Unless
argument .external_group is given, these go to the same group,
relative to the array, as the external arrays of this array, e.g.
../coordinates; that group is created if it does not exist. If this
array has no external arrays, or only external arrays in another
store, or if its group would lie above the root of the store of the
new array, the external arrays go to the group of the new array.
Pitfalls:
External arrays are named after their axis. When the new array is put in the same store as this array, its external arrays may resolve to those of this array. If the subset has different coordinates there, an error is raised; use
.external_groupto put them elsewhere.Without
.name, the new array is the only node in its store and cannot have external arrays. An error is raised before anything is written if the subset needs them.
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
The new geozarr_array, with a subset of data from this GeoZarr
array, having the axes and attributes of this GeoZarr array. If one or
more of the selectors in the ... argument fall entirely outside of
the range of the axis NULL is returned.
geozarr_array$geolocation()
Retrieve the geolocation arrays of this array. The arrays are referenced from the coordinate system, for its axes with abbreviation "X" and "Y".
Usage
geozarr_array$geolocation(kind = c("geodetic", "planar"))
Arguments
kindCharacter string, either "geodetic" (default) or "planar".
Details
The geolocation arrays must have the names of the "X" and "Y"
axes of this array in their dimension_names. Any other dimension of
a geolocation array must also be a dimension of this array. The
lengths of matching dimensions must be equal; their order is not
constrained. Boundary arrays, if given, must have the dimensions of
their geolocation array plus one vertex dimension of length 4. An error
is thrown when a geolocation or boundary array cannot be found or when
its dimensions do not match.
Returns
A list with elements "x" and "y" holding the zarr_array
instances of the geolocation arrays and, if the geolocation has
boundaries, "x_bounds" and "y_bounds" holding those of the boundary
arrays; or NULL if this array has no geolocation of the requested
kind. The CRS of the geolocation arrays, if given, is available from
the geolocation field of the coordinate system.
geozarr_array$write_geolocation()
Write the geolocation data of the coordinate system of
this array, set with CoordinateSystem$set_geolocation(), to the Zarr
arrays referenced in the geolocation object in the metadata of this
array. If an array already exists, as when geolocation arrays are
shared by multiple arrays, it is verified to be identical instead.
After writing, the data is removed from memory and the geolocation
field of the coordinate system references the written arrays.
Usage
geozarr_array$write_geolocation(create_groups = FALSE)
Arguments
create_groupsLogical, default
FALSE. IfTRUE, missing groups on the path to the geolocation arrays are created. Only groups below the nodes that the path moves up to ("..") can be created.
Details
The groups that the geolocation arrays are written to must
exist, unless create_groups = TRUE. An error is thrown when a group
does not exist and is not created, when the metadata of this array has no
geolocation object for the data, when this array is the only array in
its Zarr store, or when an existing array differs from the data in its
dimension names, shape, units or values.
Returns
Self, invisibly.
geozarr_array$write_external_coordinates()
Write any external coordinates of this array to the
underlying Zarr store. The metadata of this array is scanned for ref
objects in the cs convention attributes. The values of the external
coordinates are taken from the CoordinateSystem instance of this
array. Any geolocation data of the coordinate system is written with
write_geolocation().
Usage
geozarr_array$write_external_coordinates(create_groups = FALSE)
Arguments
create_groupsLogical, default
FALSE. IfTRUE, missing groups on the path to the external arrays are created. Only groups below the nodes that the path moves up to ("..") can be created.
Returns
Self, invisibly.
geozarr_array$add_coordinates()
Add a set of coordinates to an axis of this array, such as a
set of labels. The cs convention metadata of the array is rebuilt and
persisted, and the values of the new coordinates are written to an
external array if they are longer than the option
GeoZarr.options$max_explicit.
The array must use the cs convention: an error is thrown for an array
that uses another convention, which cannot represent multiple sets of
coordinates. An error is also thrown if the axis is not in the
coordinate system of the array, if the coordinates are not of the same
length as the axis or if the name of the coordinates is already used on
the axis. The array is not modified if an error is thrown.
Usage
geozarr_array$add_coordinates( axis, coordinates, external_group = NULL, create_groups = FALSE )
Arguments
axisCharacter string. The name of the axis to add the coordinates to.
coordinatesAn instance of the
Coordinatesclass, or any of its descendants, such asCoordinatesString.external_groupOptional. The path to the group, relative to the location of this array, for any external array with the new coordinates. If omitted, the group of any existing external coordinate arrays of this array is used, or the group of the array itself if there are none.
create_groupsLogical, default
FALSE. IfTRUE, missing groups on the path to the external array are created, seewrite_external_coordinates().
Returns
Self, invisibly.
geozarr_array$set_geolocation()
Set geolocation arrays on this array, such as the longitude and latitude of a curvilinear grid. The metadata of the array is updated, the geolocation arrays are written to the Zarr store and the array is saved.
Usage
geozarr_array$set_geolocation( ..., geolocation_group = NULL, create_groups = FALSE )
Arguments
...Arguments passed on to
CoordinateSystem$set_geolocation().geolocation_groupOptional. Character string with the group, relative to this array, where the geolocation arrays are written. Defaults to the group of the external coordinate arrays of this array, or
"..", the group of this array, if there are none.create_groupsLogical, default
FALSE. IfTRUE, missing groups on the path to the geolocation arrays are created.
Details
The array must use the "cs" convention and its coordinate
system must have exactly one "X" and one "Y" axis. The arguments
... are those of CoordinateSystem$set_geolocation(), which see for
the errors that are thrown. Existing geolocation of the same kind
is replaced. An error is thrown when the array is the only array in
its Zarr store.
Returns
Self, invisibly.
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_object -> zarr::zarr_node -> zarr::zarr_group -> geozarr_group
Active bindings
multiscales(read-only) The zarr_convention_multiscales instance with the multiscales layout of this group, or
NULLwhen the group does not declare the "multiscales" convention. A warning is given, once, when themultiscalesattribute is not valid; the layout is then ignored.
Methods
Public methods
Inherited methods
zarr::zarr_object$print_attributes()zarr::zarr_node$absolute_path()zarr::zarr_node$append_array_attribute()zarr::zarr_node$attribute()zarr::zarr_node$delete_attribute()zarr::zarr_node$relative_path()zarr::zarr_node$save()zarr::zarr_node$set_attribute()zarr::zarr_node$walk_path()zarr::zarr_group$add_array()zarr::zarr_group$add_group()zarr::zarr_group$build_hierarchy()zarr::zarr_group$copy_to()zarr::zarr_group$count_arrays()zarr::zarr_group$delete()zarr::zarr_group$delete_all()zarr::zarr_group$get_node()zarr::zarr_group$hierarchy()zarr::zarr_group$hierarchy_nodes()zarr::zarr_group$post_open()zarr::zarr_group$print()zarr::zarr_group$set_node()
geozarr_group$new()
Open a GeoZarr group in a Zarr hierarchy.
Usage
geozarr_group$new(name, metadata, parent)
Arguments
nameThe name of the group. For a root group, this is the empty string
"".metadataList with the metadata of the group.
parentThe parent Zarr group instance of this new group, can be missing or
NULLfor the root group.
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()
Set the GeoZarr convention with array details in the metadata of the array
Description
This function will write the GeoZarr convention with all details into the metadata of a Zarr array.
Usage
set_convention(metadata, coord_sys, crs = NULL, ...)
Arguments
metadata |
A |
coord_sys |
The CoordinateSystem instance of the GeoZarr array. |
crs |
Optional, a |
... |
Optional argument specific to the conventions. Currently supported
arguments are "external_group": the path to the group, relative to the
location of the array, that stores any external arrays with coordinate
values, default is ".." (the same group as the array); "geolocation_group":
the path to the group, relative to the location of the array, where
geolocation data set with |
Value
A list with the metadata updated with convention attributes.
Examples
ab <- zarr::array_builder$new()
ab$data_type <- "int32"
ab$shape <- c(1000L, 20L)
crd1 <- CoordinatesPacked$new("X_coordinates", "EAST", "m", c(0, 1000), 1000L)
ax1 <- CoordinateSystemAxis$new("Axis1", "X", crd1)
crd2 <- CoordinatesPacked$new("Y_coordinates", "NORTH", "m", c(0, 1000), 20L)
ax2 <- CoordinateSystemAxis$new("Axis2", "Y", crd2)
cs <- CoordinateSystem$new("CS", list(Axis1 = ax1, Axis2 = ax2))
crs <- list(spatial = list(code = "EPSG:4326"))
set_convention(ab$metadata(), cs, crs)
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/proj/refs/tags/v0.1/schema.json",
"spec_url": "https://github.com/zarr-conventions/proj/blob/v0.1/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
codeThe "proj:code" attribute, a character string in "authority:code" format identifying a CRS.
wkt2The "proj:wkt2" attribute, a character string giving a CRS in WKT2 format.
projjsonThe "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(attributes)
Arguments
attributesOptional, a named
listwith one or more of theprojattributes. The elements in the list must be one or more of "code", "wkt2" and "projjson".
Returns
A new instance of a "proj" convention agent.
zarr_conv_proj$as_list()
Retrieve the data of this instance as a list.
Usage
zarr_conv_proj$as_list()
Returns
A list with the attributes of this convention.
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/v0.1/schema.json",
"spec_url": "https://github.com/zarr-conventions/spatial/blob/v0.1/README.md",
"uuid": "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4",
"name": "spatial",
"description": "Spatial coordinate information"
}
Super class
zarr::zarr_convention -> zarr_conv_spatial
Active bindings
dimensionsThe "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.
bboxThe "spatial:bbox" attribute, a numeric vector of 4 values in order
xmin, ymin, xmax, ymaxgiving 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".
transformThe "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.
shapeThe "spatial:shape" attribute, an integer vector of length 2 giving the length of the X and Y dimensions.
registrationThe "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, yCoordinates for the
XandYaxes, 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 forythe resolution must be negative.shapeThe length of each axis
xandy.registrationGrid cell registration. "pixel" (the default) means that the coordinates in
xandyare 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$as_list()
Retrieve the data of this instance as a list.
Usage
zarr_conv_spatial$as_list()
Returns
A list with the attributes of this convention.
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_conventions_cs/refs/heads/main/schema.json",
"spec_url": "https://raw.githubusercontent.com/R-CF/zarr_conventions_cs/refs/heads/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": [
{
"type": "compound" | "planar" | "vertical" | "temporal" | "undefined",
"description: "optional text",
"axes": {
"<dimension_name>": {
"abbreviation": "X",
"direction": "EAST",
"coordinates": [ { "unit": "degrees",
"values": { "regular": [0.0, 0.5] } } ]
}
}
}
],
"id": "Identifier of a compound CRS",
"attributes": { <optional attributes as a JSON sub-schema> }
}
}
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
cs_nameOptional descriptive name for the coordinate set.
cs_crsOptional top-level CRS identifier, an instance of zarr_conv_proj.
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, type = "undefined", id = NULL, geolocation = NULL )
Arguments
axesA named list of axis definitions, keyed by the dimension name that appears in the Zarr array's
dimension_namesmetadata. If the argument isNULLor an empty list, the call is a no-op.typeOptional, character string. Type of CRS, one of "compound", "planar", "vertical", "temporal", "undefined" (default).
idOptional. An instance of zarr_conv_proj providing the formal OGC description of the CRS.
geolocationOptional. An instance of zarr_convention_geolocation referencing the geolocation arrays for the axes of this CRS, typically for curvilinear grids. This should only be included for CRS's that represent a planar coordinate system. The caller must register the "geolocation" convention in the attributes of the Zarr node.
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
coordinatesA list of coordinate-set definitions, each produced by
coordinates(). Must have at least one element.abbreviationOptional character string. Axis abbreviation, e.g.
"X","Y","Z", or"T".directionOptional 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, attributes = NULL )
Arguments
valuesA values definition produced by one of
values_regular(),values_explicit(), orvalues_external().nameOptional, character string. Descriptive name for this set of coordinates.
unitOptional, character string. Unit of measure (e.g.
"degrees_east","m","1").boundariesOptional boundaries definition produced by
boundaries_regular()orvalues_external().parametricOptional parametric definition produced by
parametric().timeOptional time definition produced by
time().attributesOptional list with attributes for the coordinates.
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
startNumeric. The coordinate value at shape index 0.
incrementNumeric. 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
valuesA 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
nodeCharacter string. Path to the 1-dimensional Zarr array containing the coordinate values, relative to the referring node.
uriOptional 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 relative to the coordinate value
so below must be non-positive and above must be non-negative.
Usage
zarr_convention_cs$boundaries_regular(below, above)
Arguments
below, aboveNumeric. 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
unitCharacter string. The time unit, e.g.
"days","hours","seconds".epochCharacter string. The reference date/time in ISO 8601 format, e.g.
"1970-01-01".calendarOptional 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
formulaCharacter string. The CF
standard_nameof the parametric coordinate formula, e.g."ocean_s_coordinate_g2".termsA named list of formula term values. Each element must be a
valuesattribute object. Scalar or short constants should use explicit coordinate values; full-length arrays should use external Zarr arrays.
Returns
A parametric list.
GeoZarr "geolocation" convention
Description
This class implements the "geolocation" convention. The convention attaches references to geolocation arrays to a Zarr array whose own coordinate system lacks a simple mapping to a coordinate reference system, such as a level-1 satellite swath or a model grid on a rotated or tripolar grid. The geolocation arrays give, for every element of the referring array, the coordinates in a geodetic and/or a planar CRS.
The convention is registered via the following CMO:
{
"schema_url": "https://raw.githubusercontent.com/R-CF/zarr_convention_geolocation/refs/tags/v2.0.0/schema.json",
"spec_url": "https://github.com/R-CF/zarr_convention_geolocation/blob/v2.0.0/README.md",
"uuid": "bb9ee930-8c60-4c47-ad6b-8daa558987ed",
"name": "geolocation",
"description": "Convention for storing geolocation arrays"
}
The geolocation object has the following structure:
{
"geolocation": {
"geodetic": {
"x": { "values": { "ref": { "node": "../longitude" } },
"boundaries": { "ref": { "node": "../longitude_bnds" } } },
"y": { "values": { "ref": { "node": "../latitude" } },
"boundaries": { "ref": { "node": "../latitude_bnds" } } },
"id": { "proj:code": "EPSG:4326" }
},
"planar": { ... }
}
}
The convention does not determine where the geolocation object is placed
in the attributes; that follows from the principal convention providing
the coordinates of the array. With the "spatial" convention the object is
placed at the top level of the attributes; with the "cs" convention it is
nested in a CRS object, by passing this instance to
zarr_convention_cs$add_crs().
The values and optional boundaries fields of x and y always hold
"ref" convention objects, so
registering this convention with register() also registers the "ref"
convention, as well as the "proj" convention when any id is present.
Call register() after the geolocation arrays have been set.
Super class
zarr::zarr_convention -> zarr_convention_geolocation
Methods
Public methods
zarr_convention_geolocation$new()
Create a new instance of a "geolocation" convention agent.
Usage
zarr_convention_geolocation$new(geolocation)
Arguments
geolocationOptional. A
geolocationobject as read from the attributes of a Zarr node, in the form of a namedlistwith elements "geodetic" and/or "planar".
Details
An error is thrown if argument geolocation is given but it
is not a named list with elements "geodetic" and/or "planar", each
having elements "x" and "y" with a "values" field and, for both or for
neither, a "boundaries" field, all of which are ref objects with a
"node" field.
Returns
A new instance of a "geolocation" convention agent.
zarr_convention_geolocation$register()
Register the use of this convention, and of the "ref" and "proj" conventions that it composes, in the attributes of a Zarr object.
Usage
zarr_convention_geolocation$register(attributes, brief = FALSE)
Arguments
attributesA
listwith Zarr attributes for a group or array.briefLogical flag to indicate if the registration should only include the name and the schema URL or all details (default).
Returns
The updated attributes.
zarr_convention_geolocation$set()
Set the geolocation arrays for geodetic or planar
coordinates. Setting the same kind again replaces the earlier
setting.
Usage
zarr_convention_geolocation$set( kind, x, y, uri = NULL, id = NULL, x_bounds = NULL, y_bounds = NULL )
Arguments
kindCharacter string, either "geodetic" or "planar".
x, yCharacter strings. Paths to the Zarr arrays holding the X and Y coordinates, respectively. For "geodetic" these are the longitude and latitude arrays. The paths are relative to the referring node when
uriis missing, absolute from the root of the store inuriotherwise.uriOptional character string. URI of an external Zarr store that holds all arrays. Omit for arrays in the same store as the referring node.
idOptional. An instance of zarr_conv_proj identifying the CRS of the coordinates in the
xandyarrays. This should be a geodetic CRS forkind = "geodetic".x_bounds, y_boundsOptional character strings. Paths to the Zarr arrays holding the cell vertices of the X and Y coordinates. Give both or neither.
Details
An error is thrown when only one of x_bounds and y_bounds
is given, or when a path or uri is not a valid reference.
Returns
Self, invisibly.
zarr_convention_geolocation$clear()
Clear the geolocation arrays that have been set.
Usage
zarr_convention_geolocation$clear()
zarr_convention_geolocation$as_list()
Retrieve the geolocation object as a list.
Usage
zarr_convention_geolocation$as_list()
Returns
A list with elements "geodetic" and/or "planar".
GeoZarr "multiscales" convention
Description
This class implements the "multiscales" convention. The convention is placed in the attributes of a Zarr group and lists the nodes below that group that hold the same data at different resolutions, with for each such level the level that it was derived from.
The convention is registered via the following CMO:
{
"schema_url": "https://raw.githubusercontent.com/zarr-conventions/multiscales/refs/tags/v0.1/schema.json",
"spec_url": "https://github.com/zarr-conventions/multiscales/blob/v0.1/README.md",
"uuid": "d35379db-88df-4056-af3a-620245f8e347",
"name": "multiscales",
"description": "Multiscale layout of zarr datasets"
}
The multiscales object has the following structure:
{
"multiscales": {
"layout": [
{ "asset": "0",
"spatial:shape": [1200, 1200],
"spatial:transform": [10.0, 0.0, 500000.0, 0.0, -10.0, 5000000.0] },
{ "asset": "1",
"derived_from": "0",
"transform": { "scale": [2.0, 2.0], "translation": [0.0, 0.0] },
"spatial:shape": [600, 600],
"spatial:transform": [20.0, 0.0, 500000.0, 0.0, -20.0, 5000000.0] }
],
"resampling_method": "average"
}
}
Assets. An asset is a path relative to the group holding the
multiscales object. It may resolve to a group or to an array; the
attributes do not tell which, that follows from the node itself.
Scale. The scale of a level is relative to the level named in its
derived_from, not to the full-resolution level. The levels thus form a
tree and the scale relative to the root of that tree is the product of the
scales on the path to the root, see cumulative_scale(). A transform on
a level without derived_from has no meaning and is ignored.
What this class does not interpret. The specification does not define
to which dimensions the entries of scale and translation apply, nor in
what order, nor the units of translation. This class therefore stores
these properties but never derives georeferencing from them. The
spatial:transform and spatial:shape of a level, when present, are the
authoritative description of its grid. Levels added with add_level()
always have a zero translation.
Registering this convention with register() also registers the "spatial"
convention when any level has spatial: properties. Call register()
after the levels have been set.
Interpretation
Arrays in the levels of a multiscales group that uses the "spatial"
convention are opened as geozarr_array. The specification is ambiguous or
silent on several points; this implementation reads it as follows:
Interpretation:
An
assetmay be a group or an array; which one follows from the node, not from the attributes. An array takes part in a level when the "spatial" convention is declared on the multiscales group or on the array, and both names inspatial:dimensionsare among itsdimension_names. Other arrays in a level group, such as coordinate arrays, are left as plain Zarr arrays.-
scaleis relative to the level inderived_from, not to the full-resolution level.cumulative_scale()gives the product alongderived_fromto the root. Atransformon a level withoutderived_fromis ignored there. -
scaleandtranslationare never used for georeferencing, because the specification does not define the dimensions they apply to, their order, or the units oftranslation. The grid of a level comes from itsspatial:transform. -
spatial:andproj:attributes are taken, in order, from the array, its parent group, the layout object of the level, and the multiscales group. Attributes of the multiscales group thus reach arrays that are not its direct children, and aspatial:transformon the multiscales group never overrides that of a level. Arrays in a level need not declare a convention themselves. The multiscales layout takes precedence over XArray-style coordinate arrays in a level group.
Stricter than the schema:
The layout is rejected when an asset is listed more than once, when a
derived_fromdoes not name an asset in the layout, when thederived_fromreferences form a cycle, or whenscalearrays differ in length. A rejectedmultiscalesattribute is ignored with a warning; the store still opens.A
scalethat is not the ratio of the cell sizes in thespatial:transformof a level and its source gives a warning on reading and an error inadd_level().The convention must be declared in
zarr_conventions. Stores citing thev1tags are not recognised.Writing with
add_level():A level must be added after its source.
scaleis required withderived_from,translationis always zero, and notransformis written for a level withoutderived_from.Unknown properties of layout objects are preserved; other properties of the
multiscalesobject are not.
Not supported:
Levels without their own
spatial:transform. Such a level takes thespatial:transformof the multiscales group when there is one, which is wrong for all but the full-resolution level; otherwise opening the store fails.A multiscales group without the "spatial" convention: the layout is available but the arrays are plain Zarr arrays.
A non-zero
translation.
Super class
zarr::zarr_convention -> zarr_convention_multiscales
Active bindings
assets(read-only) Character vector with the
assetof every level, in the order of the layout.layout(read-only) A
listwith for every level a list of its properties. Properties of other conventions and unknown properties are included as read.resampling_methodThe default resampling method of the levels, a character string.
Methods
Public methods
Inherited methods
zarr_convention_multiscales$new()
Create a new instance of a "multiscales" convention agent.
Usage
zarr_convention_multiscales$new(multiscales)
Arguments
multiscalesOptional. A
multiscalesobject as read from the attributes of a Zarr group, in the form of a namedlistwith element "layout" and optionally "resampling_method".
Details
An error is thrown if argument multiscales is given but:
it is not a list with a non-empty "layout" whose elements each have an "asset" that is a relative path without ".." segments, the same for "derived_from" when present;
an asset is listed more than once;
a "derived_from" does not name an asset in the layout, or the "derived_from" references form a cycle;
the "scale" arrays of the levels differ in length.
A warning is given for levels whose "scale" disagrees with the "spatial:transform" of the level and its source. For those levels the "spatial:transform" should be used.
Returns
A new instance of a "multiscales" convention agent.
zarr_convention_multiscales$register()
Register the use of this convention, and of the "spatial"
convention when any level has spatial: properties, in the attributes
of a Zarr group.
Usage
zarr_convention_multiscales$register(attributes, brief = FALSE)
Arguments
attributesA
listwith Zarr attributes for a group.briefLogical flag to indicate if the registration should only include the name and the schema URL or all details (default).
Returns
The updated attributes.
zarr_convention_multiscales$add_level()
Add a level to the layout. A level must be added after the level that it is derived from, so the full-resolution level comes first.
Usage
zarr_convention_multiscales$add_level( asset, derived_from = NULL, scale = NULL, resampling_method = NULL, spatial_transform = NULL, spatial_shape = NULL )
Arguments
assetCharacter string. Path to the group or array of the level, relative to the group holding the
multiscalesobject.derived_fromOptional character string. The
assetof the level that the data of this level was resampled from. Omit for a level that is not derived from another level.scaleNumeric vector, required with
derived_from. The ratio of the cell size of this level to that ofderived_from, one value per scaled dimension.resampling_methodOptional character string. The resampling method of this level, when different from the default set with field
resampling_method.spatial_transformOptional numeric vector of 6 values, the
spatial:transformof this level. See zarr_conv_spatial.spatial_shapeOptional integer vector of 2 values, the
spatial:shapeof this level.
Details
An error is thrown when:
-
assetis not a relative path without ".." segments or is already in the layout; -
derived_fromis not an asset in the layout; -
scaleis given withoutderived_from, is missing withderived_from, is not positive and finite, or differs in length from thescaleof the other levels; -
spatial_transformis given for both this level and its source andscaleis not the ratio of their cell sizes.
Returns
Self, invisibly.
zarr_convention_multiscales$cumulative_scale()
The scale of every level relative to the root of its
derived_from tree, being the product of the scale of the level
and of all levels between it and the root.
Usage
zarr_convention_multiscales$cumulative_scale()
Returns
A numeric matrix with a row for each level, named by asset, and
a column for each entry in scale. A root level has scale 1. A row is
NA when the level, or a level between it and the root, has no
scale.
zarr_convention_multiscales$clear()
Clear the levels that have been set.
Usage
zarr_convention_multiscales$clear()
zarr_convention_multiscales$as_list()
Retrieve the multiscales object as a list.
Usage
zarr_convention_multiscales$as_list()
Details
An error is thrown when no levels have been set.
Returns
A list with element "layout" and, when set,
"resampling_method".
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 "multiscales" for a group, or the array has to
be in a level of a multiscales group that uses the "spatial"
convention, or the Zarr store has to be formatted using XArray, or
this domain will decline to manage the node.
Usage
zarr_domain_geozarr$build(name, metadata, parent)
Arguments
nameThe name of the node.
metadataList with the metadata of the node.
parentThe parent node of this new node. May be
NULLfor a root node.
Returns
A geozarr_array or geozarr_group instance if supported,
FALSE otherwise.