geost.read_regis_netcdf#

geost.read_regis_netcdf(nc_file: str | Path, *, data_vars: str | list[str] | None = None, bbox: tuple[float, float, float, float] | None = None, mask_nodata: bool = True, load: bool = False, **xr_kwargs) → Dataset[source]#

Read REGIS NetCDF data into GeoST compatible xarray Dataset or DataArray.

Parameters:

  • nc_file (str | Path) – Path to the REGIS netcdf file.

  • data_vars (str | list[str] | None, optional) – List of data variable names or a single data variable name specifying which data variables to return.

  • bbox (tuple[float, float, float, float] | None, optional) – Specify a bounding box (xmin, ymin, xmax, ymax) to return a selected area. The default is None. If bbox is None and the dataset is large, it is recommended to use lazy loading (load=False) and specify chunks (see examples below) to avoid memory issues.

  • mask_nodata (bool, optional) – If True, replace the -9999 nodata values in the standard REGIS dataset with NaN. The default is True.

  • load (bool, optional) – If True, the netcdf file is loaded into memory immediately. This will improve the speed of several analyses but will cause higher memory usage or memory error if the dataset is too large. Use False for lazy loading, which allows to process data that does not fit into memory. The default is False.

  • **xr_kwargs (Any) – Additional keyword arguments xarray.open_dataset. See relevant documentation for details.

Returns:

xarray Dataset instance of the netcdf file or DataArray if a single variable is selected.

Return type:

xr.Dataset | xr.DataArray

Examples

Read all model data from a local NetCDF file:

>>> import geost
>>> model = geost.read_regis_netcdf("my_netcdf_file.nc")

Read one or more data variables within a specific area from the NetCDF file and directly load the data into memory:

>>> model = geost.read_regis_netcdf(
...     "my_netcdf_file.nc", data_vars="my_var", bbox=(1, 1, 3, 3), load=True
... )
>>> model = geost.read_regis_netcdf(
...     "my_netcdf_file.nc",
...     data_vars=["my_var", "my_other_var"],
...     bbox=(1, 1, 3, 3),
...     load=True
... )

Read the entire model data but specify chunks to avoid memory issues when the dataset is large:

>>> model = geost.read_regis_netcdf(
...     "my_netcdf_file.nc",
...     chunks={"x": 100, "y": 100, "layer": -1} # -1 takes the entire "layer" dimension in a chunk
... )