pywatershed.Parameters#

class pywatershed.Parameters(dims=None, coords=None, data_vars=None, metadata=None, encoding=None, validate=True, copy=True)[source]#

Parameter base class

This is a subclass of DatasetDict() where data are read-only by design. Parameters has all the same methods as DatasetDict plus several new ones that map to DatasetDict as follows:

  • parameters: dd.variables (dd.coords + dd.data)

  • get_param_values: get values from dd.variables

  • get_dim_values: get values from dd.dims

Parameters:

  • dims (Optional[dict]) – A dictionary of pairs of dim_names: dim_len where dim_len is an integer value.

  • coords (Optional[dict]) – A dictionary of pairs of coord_names: coord_data where coord_data is an np.ndarray.

  • data_vars (Optional[dict]) – A dictionary of pairs of var_names: var_data where coord_data is an np.ndarray.

  • metadata (Optional[dict]) –

    For all names in coords and data_vars, metadata entries with the required fields:

    • dims: tuple of names in dim,

    • attrs: dictionary whose values may be strings, ints, floats

    The metadata argument may also contain a special global key paired with a dictionary of global metadata of arbitrary name and values of string, integer, or float types.

  • encoding (Optional[dict]) – The encoding attributes to/from file when reading/writing.

  • validate (bool) – A bool that defaults to True, enforcing the consistency of the supplied dictionaries.

See also

pywatershed.base.DatasetDict

Examples

See DatasetDict() for more examples.

>>> from pprint import pprint
>>> import numpy as np
>>> import pywatershed as pws
>>> nreach = 3
>>> params = pws.parameters.PrmsParameters(
...     dims={
...         "nsegment": nreach,
...     },
...     coords={
...         "nsegment": np.array(range(nreach)),
...     },
...     data_vars={
...         "tosegment": np.array(
...             [2, 3, 0]
...         ),  # one-based index, 0 is outflow
...         "seg_length": np.ones(nreach) * 1.0e3,
...     },
...     metadata={
...         "nsegment": {"dims": ["nsegment"]},
...         "tosegment": {"dims": ["nsegment"]},
...         "seg_length": {"dims": ["nsegment"]},
...     },
...     validate=True,
... )
>>> params
<pywatershed.parameters.prms_parameters.PrmsParameters object at 0x105781390>
>>> params.dims
mappingproxy({'nsegment': 3})
>>> params.coords
mappingproxy({'nsegment': array([0, 1, 2])})
>>> pprint(params.data)
{'coords': mappingproxy({'nsegment': array([0, 1, 2])}),
 'data_vars': mappingproxy({'seg_length': array([1000., 1000., 1000.]),
                            'tosegment': array([2, 3, 0])}),
 'dims': mappingproxy({'nsegment': 3}),
 'encoding': mappingproxy({}),
 'metadata': mappingproxy({'global': mappingproxy({}),
                           'nsegment': mappingproxy({'dims': ['nsegment']}),
                           'seg_length': mappingproxy({'dims': ['nsegment']}),
                           'tosegment': mappingproxy({'dims': ['nsegment']})})}
>>> pprint(params.metadata)
mappingproxy({'global': mappingproxy({}),
              'nsegment': mappingproxy({'dims': ['nsegment']}),
              'seg_length': mappingproxy({'dims': ['nsegment']}),
              'tosegment': mappingproxy({'dims': ['nsegment']})})
>>> xrds = params.to_xr_ds()
>>> xrds
<xarray.Dataset>
Dimensions:     (nsegment: 3)
Coordinates:
  * nsegment    (nsegment) int64 0 1 2
Data variables:
    tosegment   (nsegment) int64 2 3 0
    seg_length  (nsegment) float64 1e+03 1e+03 1e+03
__init__(dims=None, coords=None, data_vars=None, metadata=None, encoding=None, validate=True, copy=True)[source]#

Methods

__init__([dims, coords, data_vars, ...])

drop_var(var_names)

Drop variables

from_dict(dict_in[, copy])

Return this class from a passed dictionary. :type dict_in: :param dict_in: a dictionary from which to create an instance of this class :type copy: :param copy: boolean if the passed dictionary should be deep copied.

from_ds(ds)

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

from_netcdf(nc_file[, use_xr, encoding])

Load this class from a netcdf file.

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.

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 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. :type dict_in: :param dict_in: a dictionary from which to create an instance of this

class

Parameters:

copy – boolean if the passed dictionary should be deep copied

Returns:

A object of this class.

classmethod from_ds(ds)#

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

classmethod from_netcdf(nc_file, use_xr=False, encoding=False)#

Load this class from a netcdf file.

Return type:

DatasetDict

get_dim_values(keys=None)[source]#

Get the values of the dimensions by keys.

Return type:

Union[dict, ndarray]

get_param_values(keys=None)[source]#

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)[source]#

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 (Optional[bool]) – bool retain the global metadata in the subset

  • keep_global_encoding (Optional[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)[source]#

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)[source]#

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()[source]#

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