read#

hydromodpy.read(sim, var, *, time=None, layer=None, sel=None, bbox=None)[source]#

Read a variable from a simulation Run with storage-kind auto-dispatch.

Single entry point for reads on a Run. The return type follows one rule: :rtype: Any

  • Zarr field -> xr.DataArray (lazy); when time is an int, the eager np.ndarray of that single timestep instead.

  • timeseries -> pd.Series.

  • geographic feature -> gpd.GeoDataFrame.

To read by reference (id / unique prefix / name) instead of a Run, use cat.read(ref, var) on a hydromodpy.catalog.Catalog.

Parameters#

sim

A Run (e.g. cat.latest() or cat[ref]).

var

Variable name, resolved against the field registry, then the DuckDB timeseries table, then the geographic features.

time

Timestep index (int) or slice for Zarr fields. None loads every persisted timestep lazily.

layer

Optional layer index for three-dimensional fields.

sel

Optional selectors forwarded to the reader: {"station": ...} for timeseries, {"period": ...} for a time window.

bbox

Optional (xmin, ymin, xmax, ymax) in the simulation CRS; restricts Zarr fields to faces whose centroid lies in the box.

Returns#

xarray.DataArray or numpy.ndarray or pandas.Series or geopandas.GeoDataFrame

See the rule above.

Raises#

TypeError

If sim is not a Run instance.

hydromodpy.results.errors.FieldNotFoundError

If var could not be resolved by any backend.

Examples#

>>> import hydromodpy as hmp
>>> cat = hmp.open("~/ws/projects/naizin")  
>>> run = cat.latest()  
>>> da = hmp.read(run, "head")  # lazy DataArray  
>>> arr = hmp.read(run, "head", time=-1, layer=0)  # ndarray  
>>> ts = hmp.read(run, "discharge", sel={"station": "outlet"})  
>>> gdf = hmp.read(run, "watershed_polygon")
param sim:

type sim:

Any

param var:

type var:

str

param time:

type time:

int | slice | None

param layer:

type layer:

int | None

param sel:

type sel:

dict | None

param bbox:

type bbox:

tuple[float, float, float, float] | None

Parameters:
Return type:

Any

On this page