pywatershed.parameters.StarfitParameters

pywatershed.parameters.StarfitParameters#

class pywatershed.parameters.StarfitParameters(dims, coords, data_vars, metadata, encoding={})[source]#

Starfit parameter class.

This parameter class provides STARFIT parameters to for modeling. This class does NOT calculate the parameters from inputs (e.g. as ISTARF-CONUS did using ResOpsUS), it simply provides the format for the model to get the the parameter data.

The data supplied can come from whatever means. The method from_istarf_conus_grand uses existing ISTARF-CONUS and GRanD data to create a parameter object for the user.

References:

ISTARF-CONUS (Inferred Storage Targets and Release Functions - Continental US): Sean W.D. Turner, Jennie Clarice Steyaert, Laura Condon, Nathalie Voisin, Water storage and release policies for all large reservoirs of conterminous United States, Journal of Hydrology, Volume 603, Part A, 2021, 126843, ISSN 0022-1694, https://doi.org/10.1016/j.jhydrol.2021.126843. https://zenodo.org/records/4602277

GRanD (Global Reservoir and Dam) database: Lehner, Bernhard, Catherine Reidy Liermann, Carmen Revenga, Charles Vörösmarty, Balazs Fekete, Philippe Crouzet, Petra Döll et al. “High‐ resolution mapping of the world’s reservoirs and dams for sustainable river‐flow management.” Frontiers in Ecology and the Environment 9, no. 9 (2011): 494-502. https://ln.sync.com/dl/bd47eb6b0/anhxaikr-62pmrgtq-k44xf84f-pyz4atkm/view/default/447819520013

ResOpsUS: Steyaert, Jennie C., Laura E. Condon, Sean WD Turner, and Nathalie Voisin. “ResOpsUS, a dataset of historical reservoir operations in the contiguous United States.” Scientific Data 9, no. 1 (2022): 34. https://zenodo.org/records/6612040

Parameters:

  • parameter_dict (dict) –

    Parameters dictionary with either structure:

    • param: value

    • process: {param: value … }

    where the later is a parameter dictionary grouped by process. The keys for process should be either the class itself, class.name, or type(class.__name__).

  • parameter_dimensions_dict (dict) – Parameters dimensions dictionary with a structure mirroring the parameter dict as described above but with shape tuples in place of parameter value data.

Returns:

StarfitParameters – StarfitParameters object

__init__(dims, coords, data_vars, metadata, encoding={})[source]#

Methods

__init__(dims, coords, data_vars, metadata)

drop_var(var_names)

Drop variables

from_dict(dict_in[, copy])

Return this class from a passed dictionary.

from_ds(ds)

Get this class from a dataset (nc4 or xarray).

from_istarf_conus_grand(grand_file[, ...])

Build parameter object from istarf-conus and the GRanD v1.3 sources.

from_netcdf(resops_domain, istarf_conus, ...)

TODO: what are the netcdf parameter files? describe their format

get_dim_values([keys])

Get the values of the dimensions by keys.

get_param_values([keys])

Get the values of the parameters (coords or data_vars) by keys

merge(*args[, copy, del_global_src])

Merge Parameter classes

rename_dim(name_maps[, in_place])

Rename dimensions.

rename_var(name_maps[, in_place])

Rename variables.

subset(keys[, copy, keep_global, ...])

Subset a DatasetDict to keys in data_vars or coordinates

subset_on_coord(coord_name, where)

Subset DatasetDict to a np.where along a named coordinate in-place

to_dd([copy])

Export Parameters to a DatasetDict (for editing).

to_nc4_ds(filename)

Export Parameters to a netcdf4 dataset

to_netcdf(filename[, use_xr])

Write parameters to a netcdf file

to_xr_dd()

Export to an xarray DatasetDict (xr.Dataset.to_dict()).

to_xr_ds()

Export Parameters to an xarray dataset

validate()

Check that a DatasetDict is internally consistent.

Attributes

coords

Return the coordinates

data

dims, coords, data_vars, metadata, encoding

data_vars

Return the data_vars.

dimensions

Get the dimensions from the parameters

dims

Return the dimensions

encoding

Return the encoding

metadata

Return the metadata

parameters

spatial_coord_names

Return the spatial coordinate names.

variables

Return coords and data_vars together
property coords: dict#

Return the coordinates

property data: dict#

dims, coords, data_vars, metadata, encoding

Parameters:

copy – boolean if a deepcopy is desired

Returns:

A dict of dicts containing all the data

Type:

Return a dict of dicts

property data_vars: dict#

Return the data_vars.

property dimensions: dict#

Get the dimensions from the parameters

Returns:

dimensions in the PRMS parameter dictionary

property dims: dict#

Return the dimensions

drop_var(var_names)#

Drop variables

property encoding: dict#

Return the encoding

classmethod from_dict(dict_in, copy=False)#

Return this class from a passed dictionary.

Parameters:

  • dict_in (dict) – A dictionary from which to create an instance of this class

  • copy (bool, optional) – If True, the passed dictionary will be deep copied. Default is False.

Returns:

DatasetDict – An object of this class.

classmethod from_ds(ds)#

Get this class from a dataset (nc4 or xarray).

static from_istarf_conus_grand(grand_file, istarf_file=None, files_directory=PosixPath('.'), grand_ids=None)[source]#

Build parameter object from istarf-conus and the GRanD v1.3 sources.

This returns the parameters for the STARFIT method. The parameters are in the original units of the method.

Note that this method returns nan for the fields of start_time, end_time, and initial_storage. The user can edit the parameter set if she would like to change these with the following basic steps (outlined in an example notebook) export the parameters to and xarray data set via params.to_xr_ds(), then edit params using xarray, finally instantiate a parameter object from the xarray dataset using params = StarfitParameters.from_ds(param_ds). The units of initial_storage supplied should match the units of flow input to Starfit.

Parameters:

Examples

Read the full ISTART-CONUS dataset, identify the “big sandy” reservoir by name to get its grand_id, then subset the parameters to this grand_id. This requires downloading the GRanD and ISTARF-CONUS datasets in advance and specifying the paths to those files.

>>> import pywatershed as pws
>>> grand_file = (
...     your_data_dir / "GRanD_Version_1_3/GRanD_reservoirs_v1_3.dbf"
... )
>>> istarf_file = your_data_dir / "ISTARF-CONUS.csv"
>>> sf_params = (
...     pws.parameters.StarfitParameters.from_istarf_conus_grand(
...         grand_file=grand_file, istarf_file=istarf_file
...     )
... )
>>> grand_names = sf_params.parameters["GRanD_NAME"].tolist()
>>> # where is Big Sandy?
>>> big_sandy_index = [
...     ii
...     for ii, nn in enumerate(grand_names)
...     if "big sandy" in str(nn).lower()
... ][0]
>>> big_sandy_grand_id = sf_params.parameters["grand_id"][
...     big_sandy_index
... ]
>>> # get a parameter set with just the big sandy dike
>>> sf_params = (
...     pws.parameters.StarfitParameters.from_istarf_conus_grand(
...         grand_file=grand_file,
...         istarf_file=istarf_file,
...         grand_ids=[big_sandy_grand_id],
...     )
... )
static from_netcdf(resops_domain, istarf_conus, grand_dams, grand_ids=None, param_names=None)[source]#

TODO: what are the netcdf parameter files? describe their format

Return type:

dict

get_dim_values(keys=None)#

Get the values of the dimensions by keys.

Return type:

Union[dict, ndarray]

get_param_values(keys=None)#

Get the values of the parameters (coords or data_vars) by keys

Return type:

Union[dict, ndarray]

Also see:

subset() method is a Parameter object is desired.

classmethod merge(*args, copy=True, del_global_src=True)#

Merge Parameter classes

Parameters:

  • *args – several Parameters objects as individual objects.

  • copy – bool if the args should be copied?

  • del_golbal_src – bool delete the file source attribute to avoid meaningless merge conflicts?

property metadata: dict#

Return the metadata

property parameters: dict#
rename_dim(name_maps, in_place=True)#

Rename dimensions.

rename_var(name_maps, in_place=True)#

Rename variables.

property spatial_coord_names: dict#

Return the spatial coordinate names. :param None:

Returns:

Dictionary of spatial coordinates with names.

subset(keys, copy=False, keep_global=False, keep_global_metadata=None, keep_global_encoding=None, strict=False)#

Subset a DatasetDict to keys in data_vars or coordinates

Parameters:

  • keys (Iterable) – Iterable to subset on

  • copy (bool) – bool to copy the input or edit it

  • keep_global (bool) – bool that sets both keep_global_metadata and keep_global_encoding

  • keep_global_metadata (bool) – bool retain the global metadata in the subset

  • keep_global_encoding (bool) – bool retain the global encoding in the subset

Return type:

DatasetDict

Returns:

A subset Parameter object on the passed keys.

subset_on_coord(coord_name, where)#

Subset DatasetDict to a np.where along a named coordinate in-place

Parameters:

  • coord_name (str) – string name of a coordinate

  • where (ndarray) – the result of an np.where along that coordinate (or likewise constructed)

Return type:

None

Returns:

None

to_dd(copy=True)#

Export Parameters to a DatasetDict (for editing).

Parameters can NOT be edited, but DatasetDicts can. To convert back pws.Parameters(**dataset_dict.data).

Parameters:

copy – return a copy or a reference?

Return type:

DatasetDict

to_nc4_ds(filename)#

Export Parameters to a netcdf4 dataset

Parameters:

filename (Union[str, Path]) – a file to write to as nc4 is not in memory

Return type:

None

to_netcdf(filename, use_xr=False)#

Write parameters to a netcdf file

Return type:

None

to_xr_dd()#

Export to an xarray DatasetDict (xr.Dataset.to_dict()).

Return type:

dict

to_xr_ds()#

Export Parameters to an xarray dataset

Return type:

Dataset

validate()#

Check that a DatasetDict is internally consistent.

Return type:

None

Returns:

None

property variables: dict#

Return coords and data_vars together