Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Python API

Package version — 0.5.1. Follow the installation guide before using this reference. The release notes describe compatibility and changes since 0.4.1.

The chronozarr package writes a store, reads it and opens it in xarray. The quickstart has a first run, and Analyze a store in Python has common tasks. This page lists the functions. The docstring of chronozarr.encode lists every option of encode.

For a project that imports the library, use the local-checkout dependency in that project's environment, then run scripts with uv run python script.py. Use the same environment as your notebook kernel. The shell examples below assume the development CLI is installed; its isolated tool environment does not install the library into your project.

Write a store

import chronozarr
 
chronozarr.encode(da, "my_store", crs="EPSG:32631")

da is an xarray DataArray with dims (time, band, y, x). Its dtype is uint8, uint16, int16 or float32. Its x and y coordinates are the projected pixel centres of a grid with north up.

crs is an authority code such as EPSG:32631, or WKT2 text for a CRS with no code, such as a Lambert conformal conic or a sinusoidal grid. Without crs, encode reads da.attrs["crs"]. WKT1, PROJJSON and PROJ strings are converted to WKT2 when pyproj is installed. A store whose CRS has an EPSG code is written as spec 0.3.0 and any other as 0.4.0. convert keeps the CRS of its sources as it finds it and does not reproject unless you pass --crs for another CRS with --resampling.

The output directory must not exist, or it must be empty. The store is unsharded unless you pass shard=True.

Read a store

store = chronozarr.open_store("my_store")   # a local path or an http(s) URL
frame = store.read(t=0, lod=0)              # (band, y, x), the stored values
cell = store.read_cell(t=0, row=0, col=0, lod=0)
mask = store.read_mask(t=0, lod=0)          # None when the store has no mask
coverage = store.read_coverage(t=0, lod=0)  # None when the store has no coverage plane
physical = store.physical(t=0, lod=0)       # float32, scale and offset applied
da = store.to_xarray(lod=0, times=[0], physical=False)

t is the index of a timestep. lod is the pyramid level, and level 0 has the original resolution. row and col select a cell of the level.

read, read_cell and to_xarray return the stored values in the stored dtype. With physical=True, to_xarray returns float32 values, as physical() does. Each physical value is stored * scale + offset for its band. Invalid pixels are NaN.

to_xarray loads the requested level into memory.

store.notes lists what the store leaves out or spells otherwise and the reader read through, such as an absent levels mirror or a registration with other URLs. It is empty for a store that conforms. A store can open with notes and still fail chronozarr validate: the reader decodes what it can read as declared, and validate checks the spec's rules for writers.

store.crs is the CRS the store declares: an authority code, WKT2 text, PROJJSON, or several of them. WKT2 takes precedence over PROJJSON, which takes precedence over the code. store.crs.to_string() returns that definition, shortened to the code only when equivalence is proved; pyproj and rasterio accept the resulting text. Without pyproj, an unverified code cannot replace a stored WKT2 or PROJJSON definition. A proven disagreement produces a warning. For link --lonlat, interpreting a full definition needs the geo extra even for a geographic store; a code-only EPSG:4326 store needs no projection library. --xy remains usable without it.

Read a store that chronozarr did not write

open_store also reads a pyramid written by ndpyramid or by ESA's EOPF, or any Zarr v3 store whose root multiscales lists the levels. It finds the levels, the geometry and the CRS in the store's own metadata, and store.notes says what it had to assume: scale and offset taken as 1 and 0, no time axis (one timestep dated 1970-01-01), the fill value that marks a missing pixel, levels left out or in another order. Level 0 is the finest level whatever order the layout lists.

store = chronozarr.open_store("https://example.org/product.zarr/measurements/reflectance")
store.notes

A store of this kind never conforms: chronozarr validate reports the missing chronozarr block and says that the store decodes. chronozarr info prints its levels and notes. The JavaScript reader and the viewer still open only chronozarr stores. Spec section 9.4 has the rules.

Open a store in xarray

import xarray as xr
 
ds = xr.open_dataset("my_store", engine="chronozarr")
raw = xr.open_dataset("my_store", engine="chronozarr", physical=False)

The backend reads lazily. It returns physical values unless you pass physical=False. The lod argument selects the level, and the default is 0. When the store has notes, ds.attrs["chronozarr_notes"] lists them.

Include dask in the local-checkout dependency to pass chunks= and get dask arrays.

A plain Zarr reader opens a level without chronozarr and returns the stored values. See Read a store without chronozarr.

Show a store

TaskPage
Send a temporary linkShare a temporary link
Preview on your computer onlyPreview a store
Look at a store in Jupyter or VS CodeExplore a store in a notebook

Band roles and the first view

Band names are free text. The viewer chooses the bands of True color, False color, NDVI, NDWI and Water by role: red, green, blue and nir. A band has a role when:

  1. its common_name is the role (the STAC eo:bands vocabulary, spec 4.4), or
  2. it has no common_name and its name is the role (red, case ignored), or
  3. it has no common_name and its name is the Sentinel-2 band for the role (B04, B03, B02, B08).

The first rule that matches decides. Nothing else is guessed: band_1, NIR1 or b4 have no role. A product whose roles are missing is not offered.

The Dual-pol composite needs the roles copol and crosspol. Bands named VV and VH have them, or else bands named HH and HV, in any case. A name counts only as part of a pair, so VV with HV has no role. A band with the common_name copol or crosspol has that role first. --band-role does not set these two.

chronozarr bands my_store                                  # bands, roles, products
chronozarr bands my_store --band-role b4=red,b8=nir --dry-run
chronozarr bands my_store --band-role b4=red,b8=nir        # write them

bands lists each band with its common name, its role and the rule that gave it, and the products with what each one still needs. --band-role NAME=ROLE sets common_name on a local store, in place. ROLE is a STAC common name, or none to remove one. The command changes the root zarr.json and its consolidated metadata and nothing else. Data, scale, offset and units stay as they are. It refuses an unknown band, a name outside the vocabulary, and an assignment that leaves two bands with the same role. For an immutable published store, assign roles before the first upload. A later role change needs a new prefix, or a deliberate metadata update and cache purge; publish --update is only for appended timesteps.

chronozarr encode and chronozarr convert take --band-role too, so a store can carry the roles from the start. In Python, convert has band_roles={"b8": "nir"} and encode takes Band(..., common_name="nir") in bands=. A manifest that names its bands has no common names unless you give them.

The initial product, display limits and colormap are presentation. They are not stored in the store, so every other client still reads the same store. They travel in the viewer URL and in the notebook:

Parameterplayer and view argumentMeaning
ttTimestep index
pproducttrue_color, false_color, ndvi, ndwi, water, band or dual_pol
bbandBand of the single-band product
rrangeDisplay limits low,high of the single-band product, in physical units
cmcolormapColormap of the single-band product: gray (the default), viridis, magma or turbo
chronozarr link https://data.example.org/my_store --product band --band B8 --range 0,4000 --colormap viridis
# https://chronozarr.org/demo/?store=...&p=band&b=B8&r=0,4000&cm=viridis
 
chronozarr link https://data.example.org/my_store --time 71 --lonlat -64.62,-3.41 --zoom 2
# https://chronozarr.org/demo/?store=...&t=71&z=2&c=684500,9123350

--lonlat and --xy set the map centre and --zoom its zoom; Choose a date and a place explains them. link checks each value against the store and prints the URL, because the viewer ignores a value that the store cannot honor. A product needs its roles. Display limits only apply to the single-band product of a band that is not reflectance-like: an unsigned 8-bit or 16-bit band whose largest possible physical value is 10 or less is toned with fixed reflectance limits, and every other band has adjustable ones. A colormap only applies to the single-band product. --range and --colormap need --product band, unless the single band is the only product the store has, as with a store of one elevation band: link then uses it and says so on stderr. from chronozarr.view import viewer_url builds the same URL from Python and refuses an unknown colormap. It, like view, takes colormap and range without a product; the viewer then applies them if the store opens on the single band. Its zoom and center arguments take the zoom and the centre (x, y) in the store's own coordinate system, not longitude and latitude. The viewer keeps the limits you set in its address bar, so copying the address shares them.

chronozarr.add_chronozarr adds a store as a layer on a leafmap or geemap MapLibre map. Install the leafmap or geemap extra. See examples/leafmap.