| Title: | GeoZarr Conventions for Geospatial Data in Zarr Stores |
|---|---|
| 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. |
| Authors: | Patrick Van Laake [aut, cre] |
| Maintainer: | Patrick Van Laake <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 0.1.0 |
| Built: | 2026-07-23 15:50:40 UTC |
| Source: | https://github.com/cran/geozarr |
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.
as_geozarr(x, name = NULL, location = NULL, registration = "pixel")as_geozarr(x, name = NULL, location = NULL, registration = "pixel")
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 |
Either "pixel" (the default) or "node". Pixel
registration interprets the coordinates in the "dimnames" of argument |
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.
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.
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") zx <- 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
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.
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.
bounds(read-only) Retrieve the boundary values around coordinates.
range(read-only) Retrieve the extreme values of the coordinates.
length(read-only) The number of elements in this instance once the values are unpacked.
unitCharacter string giving the unit-of-measure of the coordinate values.
Coordinates$new()Create a new coordinates instance for use with a coordinate system axis.
Coordinates$new(name, direction, unit, values, bounds = NULL)
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. If argument values_packed is TRUE
then there are two values: the initial coordinate value and the
increment. Otherwise this is a vector of values.
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.
An instance of this class or an error.
Coordinates$print()Print a summary of the coordinates to the console.
Coordinates$print(...)
...Ignored.
Self, invisible.
Coordinates$brief()Some details of the axis.
Coordinates$brief()
A 1-row data.frame with some details of the axis.
Coordinates$copy()Return an exact copy of these coordinates.
Coordinates$copy()
A new instance of Coordinates.
Coordinates$subset()Return coordinates spanning a smaller coordinate range.
Coordinates$subset(rng)
rngThe range of indices to include in the returned coordinates.
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.
Coordinates$slice(rng)
rngA numeric vector whose extreme values indicate the indices of coordinates to return.
An integer vector of length 2 with the lower and higher indices
into the axis that fall within the range of coordinates in argument
rng. Returns NULL if no (boundary) values of the axis fall within
the range of coordinates.
Coordinates$getDirection()Retrieve the direction of the coordinates. This method is mandatory in the OGC standard for an axis.
Coordinates$getDirection()
Character string with the direction of the coordinates.
Coordinates$getUnit()Retrieve the unit of measure of the coordinates. This method is mandatory in the OGC standard for an axis.
Coordinates$getUnit()
Character string with the unit of measure of the axis.
Coordinates$getMinimumValue()Retrieve the minimum coordinate value of this set of coordinates, in units of the unit of measure of the coordinates.
Coordinates$getMinimumValue()
Negative infinity.
Coordinates$getMaximumValue()Retrieve the maximum coordinate value of this set of coordinates, in units of the unit of measure of the coordinates.
Coordinates$getMaximumValue()
Positive infinity.
Coordinates$getRangeMeaning()Retrieve the interpretation of coordinate values, either as a direct value ("EXACT") or as a wrap-around value between the minimum and maximum value of the coordinates ("WRAPAROUND").
Coordinates$getRangeMeaning()
The character string 'EXACT'.
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.
Coordinates -> CoordinatesPacked -> CoordinatesOrdinal
CoordinatesOrdinal$new()Create an instance of this class.
CoordinatesOrdinal$new(name, direction, length, low = 0L)
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.
An instance of this class.
CoordinatesOrdinal$copy()Return an exact copy of these coordinates.
CoordinatesOrdinal$copy()
A new instance of CoordinatesOrdinal.
CoordinatesOrdinal$subset()Return a subset of the coordinate values.
CoordinatesOrdinal$subset(rng)
rngThe range of indices whose values from these coordinate values to include in the result.
A new CoordinatesOrdinal instance covering the indicated
range of values.
CoordinatesOrdinal$clone()The objects of this class are cloneable with this method.
CoordinatesOrdinal$clone(deep = FALSE)
deepWhether to make a deep clone.
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.
Coordinates -> CoordinatesPacked
values(read-only) Retrieve the unpacked coordinate values.
range(read-only) Retrieve the extreme values of the coordinates.
CoordinatesPacked$new()Create a new coordinates instance for use with a coordinate system axis for regularly spaced coordinate values.
CoordinatesPacked$new(name, direction, unit, values, length, bounds = NULL)
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. 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.
An instance of this class or an error.
CoordinatesPacked$copy()Return an exact copy of these coordinates.
CoordinatesPacked$copy()
A new instance of CoordinatesPacked.
CoordinatesPacked$subset()Return coordinates spanning a smaller coordinate range.
CoordinatesPacked$subset(rng)
rngThe range of indices to include in the returned coordinates.
A new CoordinatesPacked instance covering the indicated range of
indices, including boundary values, present.
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.
Coordinates -> CoordinatesString
CoordinatesString$new()Create a new coordinates instance for use with a coordinate system axis for string-type coordinate values.
CoordinatesString$new(name, direction, unit, values)
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.
An instance of this class or an error.
CoordinatesString$copy()Return an exact copy of these coordinates.
CoordinatesString$copy()
A new instance of CoordinatesString.
CoordinatesString$subset()Return coordinates spanning a smaller coordinate range.
CoordinatesString$subset(rng)
rngThe range of indices to include in the returned coordinates.
A new CoordinatesString instance covering the indicated range of
indices.
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".
Coordinates -> CoordinatesTime
values(read-only) Retrieve the coordinate values as timestamps.
time(read-only) The CFTime instance managing the coordinates.
offsets(read-only) Retrieve the numeric offsets of the time coordinate values.
CoordinatesTime$new()Create a new coordinates instance for use with a coordinate system axis for time.
CoordinatesTime$new( name, direction, unit, epoch, calendar = "standard", values, bounds = NULL )
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, 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.
An instance of this class or an error.
CoordinatesTime$copy()Return an exact copy of these coordinates.
CoordinatesTime$copy()
A new instance of CoordinatesTime.
CoordinatesTime$slice()Retrieve the indices of the time axis falling between two extreme values.
CoordinatesTime$slice(x, rightmost.closed = FALSE)
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.
An integer vector giving the indices in the time axis between
values in x, or NULL if none of the values are valid.
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.
IdentifiedObject -> CoordinateSystem
axes(read-only) Retrieve the list of axes that make up this coordinate system.
CoordinateSystem$new()Create a new coordinate system. The CS must have at least one axis.
CoordinateSystem$new(name, axes)
nameCharacter string. Name of the coordinate system.
axesA list of instances of CoordinateSystemAxis. There must
be at least one axis in the list.
An instance of CoordinateSystem or an error.
CoordinateSystem$print()Print a summary of the coordinate system to the console.
CoordinateSystem$print(...)
...Ignored.
Self, invisibly.
CoordinateSystem$print_axes()Prints details of the axes of the coordinate system to the console. Used internally.
CoordinateSystem$print_axes(...)
...Arguments passed on to data.frame printing.
CoordinateSystem$getDimension()Retrieve the dimension of the coordinate system, the number of axes that make up the coordinate system.
CoordinateSystem$getDimension()
Integer value with the dimension of the coordinate system.
CoordinateSystem$getAxis()Retrieve an axis of the coordinate system by its ordinal number.
CoordinateSystem$getAxis(dimension)
dimensionThe dimension whose axis to retrieve. Note that this is 1-based.
The CoordinateSystemAxis that forms the dimension of the
coordinate system, or an error if the dimension argument in deficient.
CoordinateSystem$clone()The objects of this class are cloneable with this method.
CoordinateSystem$clone(deep = FALSE)
deepWhether to make a deep clone.
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.
IdentifiedObject -> CoordinateSystemAxis
abbreviationSet or retrieve the abbreviation of the axis.
coordinates(read-only) Retrieve the currently active coordinates.
length(read-only) Retrieve the length of the axis.
CoordinateSystemAxis$new()Create a new axis instance for use in a coordinate system.
CoordinateSystemAxis$new(name, abbreviation, coordinates)
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.
An instance of this class or an error.
CoordinateSystemAxis$print()Print a summary of the coordinate system axis to the console.
CoordinateSystemAxis$print(...)
...Ignored.
Self, invisible.
CoordinateSystemAxis$brief()Some details of the axis.
CoordinateSystemAxis$brief()
A 1-row data.frame with some details of the axis.
CoordinateSystemAxis$copy()Return an exact copy of this axis.
CoordinateSystemAxis$copy()
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.
CoordinateSystemAxis$subset(name = "", rng = NULL)
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.
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.
CoordinateSystemAxis$slice(rng)
rngA numeric vector whose extreme values indicate the indices of coordinates to return.
An integer vector of length 2 with the lower and higher indices
into the axis that fall within the range of coordinates in argument
rng. Returns NULL if no (boundary) values of the axis fall within
the range of coordinates.
CoordinateSystemAxis$getAbbreviation()Retrieve the abbreviation of the axis. This method is mandatory in the OGC standard.
CoordinateSystemAxis$getAbbreviation()
Character string with the abbreviation of the axis.
CoordinateSystemAxis$getDirection()Retrieve the direction of the axis. This method is mandatory in the OGC standard.
CoordinateSystemAxis$getDirection()
Character string with the direction of the axis.
CoordinateSystemAxis$getUnit()Retrieve the unit of measure of the axis. This method is mandatory in the OGC standard.
CoordinateSystemAxis$getUnit()
Character string with the unit of measure of the axis.
CoordinateSystemAxis$getMinimumValue()Retrieve the minimum coordinate value of this axis, in units of the unit of measure of the axis.
CoordinateSystemAxis$getMinimumValue()
Negative infinity.
CoordinateSystemAxis$getMaximumValue()Retrieve the maximum coordinate value of this axis, in units of the unit of measure of the axis.
CoordinateSystemAxis$getMaximumValue()
Positive infinity.
CoordinateSystemAxis$getRangeMeaning()Retrieve the minimum coordinate value of this axis, in units of the unit of measure of the axis.
CoordinateSystemAxis$getRangeMeaning()
The character string 'EXACT'.
CoordinateSystemAxis$clone()The objects of this class are cloneable with this method.
CoordinateSystemAxis$clone(deep = FALSE)
deepWhether to make a deep clone.
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.
zarr::zarr_node -> zarr::zarr_array -> geozarr_array
coordinate_system(read-only) Retrieve the coordinate system of this array.
zarr::zarr_node$absolute_path()zarr::zarr_node$append_array_attribute()zarr::zarr_node$attribute()zarr::zarr_node$delete_attribute()zarr::zarr_node$print_attributes()zarr::zarr_node$relative_path()zarr::zarr_node$save()zarr::zarr_node$set_attribute()zarr::zarr_node$walk_path()zarr::zarr_array$hierarchy_nodes()zarr::zarr_array$print()zarr::zarr_array$read()zarr::zarr_array$write()geozarr_array$new()Initialize a new GeoZarr array.
geozarr_array$new(name, metadata, parent, store, coord_sys)
nameThe name of the GeoZarr array.
metadataList with the metadata of the array.
parentThe parent zarr_group instance of this new array, can be
missing or NULL if the Zarr object should have just this array.
storeThe zarr_store instance to persist data in.
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.
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.
geozarr_array$post_open()
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.
geozarr_array$build_coordsys()
Self, invisibly.
geozarr_array$subset()This method extracts a subset of values from the GeoZarr array, with the range along each axis to extract expressed in coordinate values of the domain of each axis.
geozarr_array$subset( ..., .name = NULL, .location = NULL, .rightmost.closed = FALSE )
...One or more arguments of the form axis = range. The "axis"
part should be the name of an axis or its abbreviation X, Y, Z or
T. The "range" part is a vector of values representing coordinates
along the axis where to extract data. Axis abbreviations and names are
case-sensitive and can be specified in any order. If values for the
range per axis fall outside of the extent of the axis, the range is
clipped to the extent of the axis.
.nameThe name of the GeoZarr array to be created. If omitted, an array will be created at the root of a new in-memory Zarr store.
.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 .name must be provided. If the argument gives
the location for a new Zarr store then the location must be writable by
the calling code. As per the Zarr specification, it is recommended to
use a location that ends in ".zarr" when providing a location for a new
store. If argument .name is given then the geozarr_array will be
created in the root of the zarr store with that name. If the .name
argument is not given, a single-array Zarr store will be created. If
the location argument is not given, a zarr object is created in
memory.
.rightmost.closedOptional. Single logical value to indicate if the upper boundary of range in each axis should be included.
The range of values along each axis to be subset is expressed in
coordinates of the domain of the axis. Any axes for which no selection
is made in the ... argument are extracted in whole. Coordinates can
be specified in a variety of ways that are specific to the nature of
the axis. For numeric axes it should (resolve to) be a vector of real
values from which the range is computed. For time axes a vector of
character timestamps, POSIXct or Date values must be specified. As
with numeric values, only the two extreme values in the vector will be
used. For character axes the order in the axis will be used, with the
first and last value in the supplied range.
If the range of coordinate values for an axis in argument ... extends
the valid range of the axis, the extracted data will start at the
beginning for smaller values and extend to the end for larger values.
If the values envelope the valid range the entire axis will be
extracted in the result. If the range of coordinate values for any axis
are all either smaller or larger than the valid range of the axis then
nothing is extracted and NULL is returned.
The extracted data has the same dimensional structure as the data in
the array, with degenerate dimensions preserved. The order of the axes
in argument ... does not reorder the axes in the result.
Arguments following ... must be explicitly named, like
.rightmost.closed = TRUE, to avoid the argument being treated as an
axis name.
As an example, to extract values of a variable for Australia for the
year 2020, where the first axis in GeoZarr array x is the longitude,
the second axis is the latitude, both in degrees, and the third (and
final) axis is time, the values are extracted by x$subset(X = c(112, 154), Y = c(-9, -44), T = c("2020-01-01", "2021-01-01")). Note that
this works equally well for projected coordinate reference systems -
the key is that the specification in argument ... uses the same
domain of values as the respective axes in x use.
If the .location argument is a zarr_group, the new Zarr
geozarr_array is returned, with a subset of data from this GeoZarr
array, having the axes and attributes of this GeoZarr array. Otherwise,
the zarr object that is newly created and which contains the
geozarr_array instance, or an error if the zarr object could not be
created. If one or more of the selectors in the ... argument fall
entirely outside of the range of the axis NULL is returned.
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.
zarr::zarr_node -> zarr::zarr_group -> geozarr_group
zarr::zarr_node$absolute_path()zarr::zarr_node$append_array_attribute()zarr::zarr_node$attribute()zarr::zarr_node$delete_attribute()zarr::zarr_node$print_attributes()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$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.
geozarr_group$new(name, metadata, parent, store)
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 NULL for the root group.
storeThe zarr_store instance to persist data in.
An instance of geozarr_group.
Use this function to read or modify package options.
geozarr_options(key, value)geozarr_options(key, value)
key |
Character. A key whose value to modify. If missing, all options are returned. |
value |
The new value for the option. |
A list with all options if argument key is not provided,
nothing otherwise.
geozarr_options()geozarr_options()
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.
name(read-only) The name of the object.
IdentifiedObject$new()Create a new object.
IdentifiedObject$new(name)
nameCharacter string. Name of the object.
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.
IdentifiedObject$getName()
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.
IdentifiedObject$setAlias(alias)
aliasCharacter vector with aliases for the object.
Self, invisibly.
IdentifiedObject$getAlias()Retrieve the list of aliases for the name of the object. This method is optional in the OGC standard.
IdentifiedObject$getAlias()
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.
IdentifiedObject$setIdentifiers(id)
idCharacter vector with identifiers for the object.
Self, invisibly.
IdentifiedObject$getIdentifiers()Retrieve the list of identifiers of the object. This method is optional in the OGC standard.
IdentifiedObject$getIdentifiers()
List of identifiers for the object.
IdentifiedObject$setRemarks()Set remarks for the object.
IdentifiedObject$setRemarks(remarks)
remarksCharacter string with remarks for the object.
Self, invisibly.
IdentifiedObject$getRemarks()Retrieve the remarks of the object. This method is optional in the OGC standard.
IdentifiedObject$getRemarks()
Character string with remarks or NA if no remarks have been
set.
IdentifiedObject$clone()The objects of this class are cloneable with this method.
IdentifiedObject$clone(deep = FALSE)
deepWhether to make a deep clone.
This class implements the GeoZarr "proj" convention. In particular, the following convention is implemented here:
{
"schema_url": "https://raw.githubusercontent.com/zarr-conventions/geo-proj/refs/tags/v1/schema.json",
"spec_url": "https://github.com/zarr-conventions/geo-proj/blob/v1/README.md",
"uuid": "f17cb550-5864-4468-aeb7-f3180cfb622f",
"name": "proj",
"description": "Coordinate reference system information for geospatial data"
}
zarr::zarr_convention -> zarr_conv_proj
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.
zarr_conv_proj$new()Create a new instance of a "proj" convention agent.
zarr_conv_proj$new()
A new instance of a "proj" convention agent.
zarr_conv_proj$write()Write the data of this instance in the attributes of a Zarr object.
zarr_conv_proj$write(attributes)
attributesA list with Zarr attributes for a group or array. The
properties will be written at the root level of attributes.
The updated attributes.
This class implements the GeoZarr "spatial" convention. In particular, the following convention is implemented here:
{
"schema_url": "https://raw.githubusercontent.com/zarr-conventions/spatial/refs/tags/v1/schema.json",
"spec_url": "https://github.com/zarr-conventions/spatial/blob/v1/README.md",
"uuid": "689b58e2-cf7b-45e0-9fff-9cfc0883d6b4",
"name": "spatial",
"description": "Spatial coordinate information"
}
zarr::zarr_convention -> zarr_conv_spatial
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, ymax giving the boundary coordinates of the
data array.
transform_type(read-only) The "spatial:transform_type" attribute, a character string giving the type of coordinate transformation. The only valid value (currently) is "affine".
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.
zarr_conv_spatial$new()Create a new instance of a "spatial" convention agent.
zarr_conv_spatial$new()
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.
zarr_conv_spatial$set_coordinates(x, y, shape, registration = "pixel")
x, yCoordinates for the X and Y axes, as a numeric vector of
two values: the top-left coordinate of the top-left grid cell and the
resolution along the axis, respectively. Note that for y the
resolution must be negative.
shapeThe length of each axis x and y.
registrationGrid cell registration. "pixel" (the default) means
that the coordinates in x and y are interpreted as the UL corner of
each grid cell; "node" means that the coordinates are interpreted as
the center of each grid cell.
Self, invisibly.
zarr_conv_spatial$write()Write the data of this instance in the attributes of a Zarr object.
zarr_conv_spatial$write(attributes)
attributesA list with Zarr attributes for a group or array. The
properties will be written at the root level of attributes.
The updated attributes.
This class implements the GeoZarr "cs" (coordinate set) convention. The convention attaches a full coordinate system to a Zarr array by recording, for each dimension, the axis abbreviation and direction, one or more sets of coordinate values and their optional cell-boundary values, and, where applicable, the parametric formula and its terms needed to derive physical coordinates from stored index coordinates.
The convention is registered via the following CMO:
{
"schema_url": "https://raw.githubusercontent.com/R-CF/zarr_convention_cs/main/schema.json",
"spec_url": "https://raw.githubusercontent.com/R-CF/zarr_convention_cs/main/README.md",
"uuid": "e4dbf0b7-7a00-4ce6-b23e-484292014ab4",
"name": "cs",
"description": "Coordinate set convention for Zarr arrays"
}
The cs attribute written to the array metadata has the following
structure (simplified):
{
"cs": {
"crs": [
{
"axes": {
"<dimension_name>": {
"abbreviation": "X",
"direction": "EAST",
"coordinates": [ { "unit": "degrees",
"values": { "regular": [0.0, 0.5] } } ]
}
}
}
]
}
}
Build a convention instance, add one or more CRS objects (each covering
one or more dimension axes), then call as_list() to retrieve everything
for inclusion as the "cs" attribute in the Zarr node metadata.
zarr::zarr_convention -> zarr_convention_cs
nameOptional descriptive name for the coordinate set.
crs(read-only) The list of CRS objects accumulated so far.
zarr_convention_cs$new()Create a new instance of a "cs" convention agent.
zarr_convention_cs$new()
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).
zarr_convention_cs$add_crs(axes, name = NULL, id = NULL, geolocation = NULL)
axesA named list of axis definitions, keyed by the dimension name
that appears in the Zarr array's dimension_names metadata. If the
argument is NULL or an empty list, the call is a no-op.
nameOptional character string. Descriptive name for the CRS.
idOptional. Convention proj attributes (proj:code,
proj:wkt2, or proj:projjson) providing the formal OGC description
of the CRS.
geolocationOptional list. Geolocation grid definition for curvilinear grids. This should only be included for CRS's that represent a planar coordinate system.
Self, invisibly.
zarr_convention_cs$as_list()Retrieve the cs attributes as a list.
zarr_convention_cs$as_list()
A list with the updated attributes for this convention.
zarr_convention_cs$axis()Build an axis definition.
zarr_convention_cs$axis(coordinates, abbreviation = NULL, direction = NULL)
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").
A named list representing one axis entry.
zarr_convention_cs$coordinates()Build a coordinate-set definition for use in axis().
zarr_convention_cs$coordinates( values, name = NULL, unit = NULL, boundaries = NULL, parametric = NULL, time = NULL )
valuesA values definition produced by one of values_regular(),
values_explicit(), or values_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() or values_external().
parametricOptional parametric definition produced by
parametric().
timeOptional time definition produced by time().
A named list representing one coordinates entry.
zarr_convention_cs$values_regular()Regularly-spaced coordinate values.
zarr_convention_cs$values_regular(start, increment)
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.
A values list with a regular element.
zarr_convention_cs$values_explicit()Explicitly listed coordinate values.
zarr_convention_cs$values_explicit(values)
valuesA vector of coordinate values. May be numeric, integer, or character.
A values list with an explicit element.
zarr_convention_cs$values_external()Coordinate values stored in an external array
zarr_convention_cs$values_external(node, uri)
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.
A values list with an external element.
zarr_convention_cs$boundaries_regular()Regularly-spaced cell-boundary values.
The two values give the offset below and above the coordinate value that define the extent of each cell, in the same unit as the coordinates. Both offsets are expressed as positive magnitudes; the convention interprets "below" as the lower-valued boundary and "above" as the higher-valued boundary regardless of the sign of the axis increment.
zarr_convention_cs$boundaries_regular(below, above)
below, aboveNumeric. Positive offset from the coordinate value to the lower and upper boundary, respectively.
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.
zarr_convention_cs$time(unit, epoch, calendar = NULL)
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.
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).
zarr_convention_cs$parametric(formula, terms)
formulaCharacter string. The CF standard_name of the parametric
coordinate formula, e.g. "ocean_s_coordinate_g2".
termsA named list of formula term values. Each element must be a
values attribute object. Scalar or short constants should use
explicit coordinate values; full-length arrays should use external Zarr
arrays.
A parametric list.
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).
zarr::zarr_domain -> zarr_domain_geozarr
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.
zarr_domain_geozarr$new()
A zar_domain_geozarr object.
zarr_domain_geozarr$build()This method will create a geozarr_array for an array node
and a geozarr_group for a group node with GeoZarr conventions
declared in its attributes. Either the "spatial" or "cs" convention
has to be declared or the Zarr store has to be formatted using XArray
or NCZarr or this domain will decline to manage the node.
zarr_domain_geozarr$build(name, metadata, parent, store)
nameThe name of the node.
metadataList with the metadata of the node.
parentThe parent node of this new node. May be NULL for a root
node.
storeThe store to persist data in.
A geozarr_array or geozarr_group instance if supported,
FALSE otherwise.