hmp.read#

Read a variable from a simulation with auto-dispatch across Zarr fields, DuckDB timeseries, and GeoParquet geographic features.

Signature#

hmp.read(sim, var, *, time=None, layer=None, sel=None, bbox=None) -> Any

Reference#

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:

sim (Any)
var (str)
time (int | slice | None)
layer (int | None)
sel (dict | None)
bbox (tuple[float, float, float, float] | None)

Return type:

Any

Example#

import hydromodpy as hmp

catalog = hmp.open("~/hmp_workspace")
run = catalog.latest()

da = hmp.read(run, "head")                       # xr.DataArray, lazy
arr = hmp.read(run, "head", time=-1, layer=0)    # np.ndarray, eager
ts = hmp.read(run, "discharge", sel={"station": "outlet"})
gdf = hmp.read(run, "watershed_polygon")         # geographic feature