Reference

Generated from the package docstrings.

write_mdim_vrt

write_mdim_vrt(ds: 'xr.Dataset', sources: 'Sequence[Any]', path: 'str | Path',
    *, composition: 'Composition', concat_dim: 'str | None' = None, crs: 'str | None' = None, sizes: 'Sequence[int] | None' = None, block_size: 'Sequence[int] | Mapping[str, Sequence[int]] | None' = None, coord_mode: 'CoordMode | Mapping[str, CoordMode]' = 'auto', inline_threshold: 'int' = 10000, require_crs: 'bool' = False, variables: 'Sequence[str] | None' = None) -> 'Path'

Emit a GDAL multidim VRT from an xarray Dataset.

Every data variable becomes an <Array> in one VRT (OISST-style files with sst/anom/err/ice give one VRT with four arrays). Each source file is expected to hold every variable; variables that lack the composition dim (static fields such as a land mask) are read from the first source.

Parameters

ds

The Dataset whose shape / dims / coords / data-vars describe the desired virtual composition.

sources

list[str | Path | dict]. Dict form: {"path": ..., "size": N, "array": "/name"}; with several variables use "arrays": {var: "/name", ...} instead of "array" for any renames (variables not listed default to their own name).

path

Output .vrt path.

composition

"stack" | "concat". ("mosaic" is reserved and raises NotImplementedError.)

concat_dim

Required for stack (new dim name) and concat (existing dim name).

crs

WKT string. If omitted, we look at ds[dv].attrs["crs_wkt"] / ds[dv].rio.crs / CF grid_mapping; if still absent the writer emits no <SRS> and warns. Pass require_crs=True to make that an error.

sizes

Convenience shortcut for concat: list[int] of per-source sizes along concat_dim. If not given, we try (in order): per-source size in dict-form sources, ds.chunks[concat_dim] when the number of chunks matches the number of sources, then opening each source to read .sizes[concat_dim].

block_size

Sequence matching array dim order, or dict keyed by data-var name. None falls back to the dask chunks, then to encoding["preferred_chunks"] / encoding["chunksizes"].

coord_mode

"auto" (default) | "inline" | "source" or dict per coord.

inline_threshold

In auto mode, coords with size <= threshold go inline.

variables

Subset of ds.data_vars to write, in order. Default: all data vars except CF grid_mapping containers (their content is carried by <SRS>).

require_crs

When True, raise VrtWriterError if no CRS can be determined. Default False (warn-and-omit); matches the reality of ocean NetCDFs and other CRS-less sources.

from_stac

from_stac(items: 'str | Path | Iterable[Mapping[str, Any]]', path: 'str | Path',
    *, assets: 'Sequence[str] | None' = None, dim: 'str' = 'time', crs: 'str | None' = None, block_size: 'Sequence[int] | Mapping[str, Sequence[int]] | None' = None) -> 'Path'

Write a multidim VRT stacking STAC items along dim.

Parameters

items

A stac-geoparquet file (path or URL; needs pyarrow), or an iterable of STAC item dicts (pystac.Item.to_dict() works). Both the flat geoparquet layout and the nested "properties" layout are read.

path

Output .vrt path.

assets

Asset keys to write, one array each, in this order. Default: every asset with raster:bands, in first-seen order.

dim

Name of the stack dimension (one position per distinct datetime).

crs

WKT override. Default: from the items’ projection fields, turned into WKT with pyproj (or GDAL’s osr) when only an EPSG code is given, so the axis mapping can be computed.

block_size

Optional <BlockSize>; the catalogue does not record it.

Raises

VrtWriterError

Items on different grids, duplicate datetimes, a band description that changes between items, or no usable CRS.

encode_datetime_coord

encode_datetime_coord(da: 'xr.DataArray',
    *, unit: "Literal['seconds', 'minutes', 'hours', 'days']" = 'days', since: 'str' = '1970-01-01') -> 'xr.DataArray'

Convert a datetime64 coord DataArray to numeric + CF units attr.

Handy pre-step when you have a datetime64[ns] time coord and want to feed it to the writer (which refuses datetime dtypes per v0 policy).

VrtWriterError

Raised when the writer’s rules are violated.

Subclasses ValueError so that naive except-clauses still catch it; specific enough that callers can except VrtWriterError to distinguish rule violations from generic bad input.

Accessor

import xvrt.accessor registers Dataset.vrt.write_mdim(path, sources=..., ...), which forwards its arguments to write_mdim_vrt.