hec.rating

Sub-module to provide rating capabilities to hec module

Quick links to Constants:

Quick links to Classes:

Ratings - Individual Rating Objects
Class	Exception	Description
AbstractRating	AbstractRatingException	Abstract base class for all rating types
SimpleRating	SimpleRatingException	Abstract base class for `ExpressionRating` and `TableRating` objects, which both use the `<simple-rating>` xml element
TableRating	TableRatingException	Ratings that use tables of lookup values
Rating Sets - Time Series of Rating Objects
Class	Exception	Description
AbstractRatingSet	AbstractRatingSetException	Abstract base class for all rating set types
LocalRatingSet	LocalRatingSetException	Rating sets that perform all operations in local code
ReferenceRatingSet	ReferenceRatingSetException	Rating sets that perform all operations in the CWMS database by sending/receiving data on each operation
Other Rating Info
Class	Exception	Description
PairedData	PairedDataException	HEC-DSS-style paired data objects
RatingSpecification	RatingSpecificationException	Location ID, template ID, time-based lookup methods and rounding parameter specifications for rating sets
RatingTemplate	RatingTemplateException	Parameter names, parameter lookup behaviors for ratings

class AbstractRating(abc.ABC):

Abstract class for all rating classes;

Specifies required methods for sub-classes, holds information and implements code common one or more sub-classes.

AbstractRating( specification: RatingSpecification, effective_time: Union[datetime.datetime, hec.HecTime, str])

Initializer for AbstractRating objects.

Arguments:

specification (Any): A RatingSpecification object to initialize from. This is typed as Any to avoid circular import dependencies.
effective_time (Union[datetime, HecTime, str]): The effective date/time of the rating

Raises:

TypeError: if specification is not a RatingSpecification object.

valid_rating_tags = ['simple-rating', 'usgs-stream-rating', 'virtual-rating', 'transitional-rating']

effective_time: datetime.datetime

The effective date/time of the rating

Operations:

Read/Write

active: bool

Whether the rating is marked as active

Operations:

Read/Write

@staticmethod

def convert_units(values: Sequence[float], from_unit: str, to_unit: str) -> Sequence[float]:

Converts a tuple or list of value from/to the specified units

Arguments:

values (Sequence[float]): The values to convert
from_unit (str): The unit to convert from
to_unit (str): The unit to convert to

Returns:

Sequence[float]: The converted values

create_time: Optional[datetime.datetime]

The creation date/time of the rating, if any

Operations:

Read/Write

default_data_units: Optional[list[str]]

The default data units, if any.

The default data units are used if the rate or reverse_rate methods are called without any specified units.

Operations:

Read/Write

default_data_vertical_datum: Optional[str]

The default vertical datum for rating Elev parameter values.

If not None, Elev parameter values will be converted to the default vertical datum before (input values) or after (output values) the rating is performed.

If None, the native vertical datum will be used.

When setting, must be None, NGVD-29, NAVD-99, or OTHER.

Operations:

Read/Write

description: Optional[str]

The description of the rating object, if any.

Operations:

Read/Write

@staticmethod

@abstractmethod

def from_xml( xml_str: str, specification: Optional[RatingSpecification] = None) -> AbstractRating:

Creates a rating object from an XML instance

Arguments:

xml_str (str): The XML instance to create the rating from

Raises:

AbstractRatingException: if no subclass of AbstractRating has a registered from_xml()
method that is compatible with the specified XML instance

Returns:

AbstractRating: The rating created from the XML instance

has_elev_param: bool

Whether the rating has "Elev" as the base parameter for one of the indpendent parameters or the dependent parameter

Operations:

Read-Only

def make_datum_offsets(self, vertical_datum: str) -> list[typing.Optional[float]]:

Creates a list of offsets (in rating units) from the specified vertical datum to the rating native vertical datum plus the offset for from the rating native vertical datum to the specified vertical datum.

All offsets except the last one are for independent parameter values in the same position. The last offset is for the dependent parameter value (hence the difference in offset direction).

In any postion, the offset will be None if: * The parameter at that position is not an elevation parameter * The offset is zero

Arguments:

vertical_datum (str): The specified vertical datum

Returns:

list[Optional[float]]: The list of offsets.

def make_reverse_datum_offsets(self, vertical_datum: str) -> list[typing.Optional[float]]:

Creates a list of two vertical datum offsets (in rating units). The first is from the specified vertical datum to the rating native vertical datum; the second from the rating native vertical datum to the specified datum.

The first offset will be None if the base parameter of the rating dependent parameter is not "Elev" or the offset is zero. The secons offset will be None if the base parameter of the (single) rating independent parameter is not "Elev" or the offset is zero.

Arguments:

vertical_datum (str): The specified vertical datum

Returns:

list[Optional[float]]: The list of offsets.

def make_reverse_unit_conversions( self, unit_list: list[str]) -> list[typing.Optional[typing.Callable[[float], float]]]:

Creates a list of unit conversion functions (each optionally None for the identity function) for converting the dependent parameter values to rating units and the independent parameter value to specified unit

Arguments:

unit_list (list[str]): The list of [dependent parameter unit, independent parameter unit].

Returns:

list[Optional[Callable[[float], float]]]: The list of unit conversions. The first is for converting from the rating independent parameter unit to the specified unit. The second one is for converting the specified unit to the rating dependent parameter unit.

@staticmethod

def make_unit_conversion(from_unit: str, to_unit: str) -> Optional[Callable[[float], float]]:

Creates a function that converts a value from/to specified units

Arguments:

from_unit (str): The unit to convert from
to_unit (str): The unit to conver to

Returns:

Optional[Callable[[float],float]]: The conversion function or None for the identity conversion

def make_unit_conversions( self, unit_list: list[str]) -> list[typing.Optional[typing.Callable[[float], float]]]:

Creates a list of unit conversion functions (each optionally None for the identity function) for converting independent parameter values to rating units and the dependent parameter value to specified unit

Arguments:

unit_list (list[str]): The list of independent parameter units plus the dependent parameter unit.

Returns:

list[Optional[Callable[[float], float]]]: The list of unit conversions. All but the last one are for converting the specified unit to the rating unit for the independent parameter at that position. The last one is for converting from the rating dependent parameter unit to the specified unit.

office: Optional[str]

The rating's specification's office, if any

Operations:

Read-Only

def populate_xml_element(self, rating_elem: lxml.etree._Element) -> lxml.etree._Element:

The info common to all ratings as an lxml.etree.Element object

Operations:

Read-Only

def rate( self, input: Union[list[list[float]], hec.TimeSeries, Sequence[hec.TimeSeries]], *, units: Optional[str] = None, vertical_datum: Optional[str] = None, round: bool = False) -> Union[list[float], hec.TimeSeries]:

Rates independent parameter values and returns dependent parameter values.

Arguments:

input (Union[list[list[float]], TimeSeries, Sequence[TimeSeries]]): The input parameter values.
- If specified as a list of lists of floats:
  - The list must be of the same length as the number of independent parameters of the rating.
  - Each list of values must have the same times and be of the same length
  - The times parameter is used, if specified
  - The units, if specified, is the unit of each independent and dependent parameter.
  - A list of floats is returned
- If specified as a TimeSeries:
  - The rating must have a single independent parameter
  - The times parameter is not used and will cause an exception if specified
  - The units parameter, if specified, is the unit of the rated time series
  - A time series is returned
- If specified as a list of TimeSeries:
  - The list must be of the same length as the number of independent parameters of the rating.
  - The times parameter is not used and will cause an exception if specified
  - The units parameter, if specified, is the unit of the rated time series
  - A time series is returned
units (Optional[str], must be passed by name): Defaults to None.
- If input is a list of list of floats, this specifies units of the independent parameter values and the rated values. A comma-delimited string of independent value units concatendated with a semicolon and the dependent parameter unit. Defaults to None. If not specified or None, the rating's default data units are used, if specified. If the rating has no default data units, the rating units are used.
- If specified as a TimeSeries or list of TimeSeries, this specifies the unit of the rated time series. If not specified or None, rating's default data unit for the dependent parameter, if any, is used. Otherwise, the dependent parameter's default unit will be used.
vertical_datum (Optional[str], must be passed by name): Defaults to None.
- If input is a list of list of floats, this specifies the vertical datum of any input elevation value and the desired vertical datum of any output elevation values. If None, or not specified, the location's native vertical datum is used.
- If specified as a TimeSeries or list of TimeSeries, this specifies the desired vertical datum for any output elevation values. Any input elevation values will be in the vertical datum of the input time series.
round (bool, optional, must be passed by name): Whether to use the rating's specification's dependent rounding specification . Defaults to False.

Returns:

Union[list[float], TimeSeries]: The dependent parameter values as described in input above

rating_units: list[str]

The native units of the rating, one for each independent parameter, plus the dependent parameter

Operations:

Read-Only

def reverse_rate( self, input: Union[list[float], hec.TimeSeries], *, units: Optional[str] = None, vertical_datum: Optional[str] = None, round: bool = False) -> Union[list[float], hec.TimeSeries]:

Rates dependent parameter values and returns independent parameter values.

Arguments:

input (Union[list[float], TimeSeries]): The input parameter values.
- If specified as a lists of floats:
  - The times parameter is used, if specified
  - The units, if specified, is the unit of each independent and dependent parameter.
  - A list of floats is returned
- If specified as a TimeSeries:
  - The rating must have a single independent parameter
  - The times parameter is not used and will cause an exception if specified
  - The units parameter, if specified, is the unit of the rated time series
  - A time series is returned
units (Optional[str], optional, must be passed by name): Defaults to None.
- If input is a list of list of floats, this specifies units of the independent parameter values and the rated values. A comma-delimited string of independent value units concatendated with a semicolon and the dependent parameter unit. Defaults to None. If not specified or None, the rating's default data units are used, if specified. If the rating has no default data units, the rating units are used.
- If specified as a TimeSeries or list of TimeSeries, this specifies the unit of the rated time series. If not specified or None, rating's default data unit for the dependent parameter, if any, is used. Otherwise, the dependent parameter's default unit will be used.
round (bool, optional, must be passed by name): Whether to use the rating's specification's dependent rounding specification . Defaults to False.

Returns:

Union[list[float], TimeSeries]: The dependent parameter values as described in input above

specification: RatingSpecification

A copy of the rating's specification

Operations:

Read-Only

specification_id: str

The rating's specification identifer

Operations:

Read-Only

A copy of the rating's template

Operations:

Read-Only

template_id: str

The rating's template identifer

Operations:

Read-Only

def to_xml(self, indent: str = ' ', prepend: str = '') -> str:

Returns a formatted xml representation of the rating.

For unformatted xml use etree.tostring(<template_obj>.xml_element)

Arguments:

indent (str, optional): The string to use for each level of indentation. Defaults to " ".
prepend (Optional[str], optional): A string to prepend to each line. Defaults to None.

Returns:

str: The formatted xml

transition_start_time: Optional[datetime.datetime]

The date/time of beginning of transition from the previous rating, if any

Operations:

Read/Write

vertical_datum_info: Optional[hec.parameter.ElevParameter._VerticalDatumInfo]

The vertical datum info of the rating's specification's location, if any

Operations:

Read-Only

vertical_datum_json: Optional[str]

The vertical datum info of the rating's specification's location, if any, as a JSON object

Operations:

Read-Only

vertical_datum_xml: Optional[str]

The vertical datum info of the rating's specification's location, if any, as an XML instance

Operations:

Read-Only

xml_element: lxml.etree._Element

The rating as an lxml.etree.Element object

Operations:

Read-Only

@abstractmethod

def xml_tag_name(self) -> str:

The XML tag name for this rating type

Oprations:

Read-Only

class AbstractRatingSet(abc.ABC):

Abstract class for all rating set classes.

Specifies required methods for sub-classes, holds information and implements code common one or more sub-classes.

AbstractRatingSet(specification: Any, **kwargs: Any)

Initializer for AbstractRatingSet objects.

Arguments:

specification (Any): A RatingSpecification object to initialize from. This is typed as Any to avoid circular import dependencies.

Raises:

TypeError: if specification is not a RatingSpecification object.

default_data_time: Optional[datetime.datetime]

The default data time of the rating set.

If not None, the default data time is used to rate values that don't otherwise have times specified.

If None, the current time is used as the default data time

Operations:

Read/Write

default_data_units: Optional[list[str]]

The units to use for independent and dependent parameter values when no units are specified for rate.

If None and no data units are specified, the rating methods will raise an exception.

Operations:

Read/Write

default_data_vertical_datum: Optional[str]

The default vertical datum for rating Elev parameter values.

If not None, Elev parameter values will be converted to the default vertical datum before (input values) or after (output values) the rating is performed.

If None, the native vertical datum will be used.

When setting, must be None, NGVD-29, NAVD-99, or OTHER.

Operations:

Read/Write

def rate( self, input: Union[list[float], list[list[float]], hec.TimeSeries, Sequence[hec.TimeSeries]], *, times: Union[datetime.datetime, list[datetime.datetime], NoneType] = None, units: Optional[str] = None, vertical_datum: Optional[str] = None, rating_time: Optional[datetime.datetime] = None, round: bool = False) -> Any:

Rates independent parameter values and returns dependent parameter values.

The times of the values are used in conjuction with the effective times of the individual ratings and rating set specification lookup methods to determine which ratings in the rating set are used - and the manner in which they are used - to compute the rated values.

Arguments:

input (Union[list[float], list[list[float]]): The input (independnent parameter(s)) values.
- If specified as a float or a list of floats (for rating a single input value set using a single- or multi-independent-parameter rating set):
  - The list must be of the same length as the number of independent parameters of the rating set.
  - The times parameter is used, if specified
  - The units, if specified, is the unit of each independent and dependent parameter.
  - A single float is returned
- If specified as a list of lists of floats (for rating a list of input value sets using a single- or multi-independent-parameter rating set):
  - The list must be of the same length as the number of independent parameters of the rating set.
  - Each list of values must have the same times and be of the same length
  - The times parameter is used, if specified
  - The units, if specified, is the unit of each independent and dependent parameter.
  - A list of floats is returned
- If specified as a TimeSeries (for rating a single time series using a single-independent-parameter rating set):
  - The rating set must have a single independent parameter
  - The times parameter is not used and will cause an exception if specified
  - The units parameter, if specified, is the unit of the rated time series
  - A time series is returned
- If specified as a list of TimeSeries (for rating a list of time series using a multi-independent-parameter rating set):
  - The list must be of the same length as the number of independent parameters of the rating set.
  - The times parameter is not used and will cause an exception if specified
  - The units parameter, if specified, is the unit of the rated time series
  - A time series is returned
times (Optional[Union[datetime, list[datetime]]], must be passed by name): The date/times of the independent parameter values. Defaults to None.
- If specified and not None:
  - Specifying a datetime object is the same as specifying that datetime object in a list of length 1.
  - If shorter than the independent parameter value list(s), the last time will be used for the remainging values.
  - If longer than the independent parameter values list(s), the beginning portion of the list will be used.
- If None or not specified:
  - If the rating set's default data time is not None, that time is used for each value
  - If the rating set's default data time is None, the current time is used for each value
units (Optional[str], must be passed by name): Defaults to None.
- If input is a list of floats or a list of list of floats:
  - Specifies units of the independent parameter values and the rated values as comma-delimited string of independent value units concatendated with a semicolon and the dependent parameter unit (e.g., "ft;ac-ft", "unit,ft,ft;cfs").
  - If not specified or None:
    - The rating's default data units, if any, are used
    - If the rating has no default data units, an exception is raised.
- If input is a TimeSeries or list of TimeSeries:
  - Specifies the unit of the rated (dependent parameter) time series.
  - If not specified or None:
    - The rating's default data units, if any, are used
    - If the rating has no default data units, an exception is raised.
vertical_datum (Optional[str], must be passed by name): Defaults to None.
- If input is a list of floats or a list of list of floats, this specifies:
  - Specifies:
    - The vertical datum of any input (independent parameter) elevation values
    - The desired vertical datum of any rated (dependent parameter) elevation values.
  - If None, or not specified, the location's native vertical datum is used.
- If input is a TimeSeries or list of TimeSeries:
  - Specifies only the desired vertical datum for any rated (dependent parameter) elevation values.
  - Any input (independent parameter) elevation values will be in the vertical datum of the input time series.
  - If None, or not specified, the location's native vertical datum is used.
rating_time (Optional[datetime], must be passed by name): The maximum effective time and creation time for the rating set to use to perform the rating. Defaults to None. Causes the rating to be performed as if the current date/time were the specified time (no ratings with effective times or creation times later than this time will be used).
round (bool, optional, must be passed by name): Whether to use the rating set's specification's dependent rounding specification . Defaults to False.

Returns:

Any: The dependent parameter value(s) as described in input above

def reverse_rate( self, input: Union[float, list[float], hec.TimeSeries], *, times: Union[datetime.datetime, list[datetime.datetime], NoneType] = None, units: Optional[str] = None, vertical_datum: Optional[str] = None, rating_time: Optional[datetime.datetime] = None, round: bool = False) -> Any:

Rates dependent parameter values and returns independent parameter values.

May only be used on rating sets with a single independent parameter.

Important Note
Unlike single-independent-parameter ratings, two-dimensional (time and parameter value) rating sets are not generally invertible. That is, if you rate value `x` at time `t` using a rating set to generate value `y`, using the same rating set to reverse rate value `y` at time `t` will generally not result in `x`.

Arguments:

input (Union[float, list[float], TimeSeries]): The input (dependent parameter) value(s).
- If specified as a float (for reverse rating a single dependent parameter value using a single-independent-parameter rating set):
  - The times parameter is used, if specified
  - The units, if specified, is the unit of each independent and dependent parameter.
  - A float is returned
- If specified as a lists of floats (for reverse rating a multiple dependent parameter values using a single-independent-parameter rating set):
  - The times parameter is used, if specified
  - The units, if specified, is the unit of the independent and dependent parameters as shown below.
  - A list of floats is returned
- If specified as a TimeSeries (for reverse rating a dependent parameter time series using a single-independent-parameter rating set):
  - The times parameter is not used and will cause an exception if specified
  - The units parameter, if specified, is the unit of the reverse rated time series
  - A time series is returned
times (Optional[list[datetime]], must be passed by name): The date/times of the independent parameter value(s). Defaults to None.
- If specified and not None:
  - Specifying a datetime object is the same as specifying that datetime object in a list of length 1.
  - If shorter than the independent parameter value list(s), the last time will be used for the remainging values.
  - If longer than the independent parameter values list(s), the beginning portion of the list will be used.
- If None or not specified:
  - If the rating set's default data time is not None, that time is used for each value
  - If the rating set's default data time is None, the current time is used for each value
units (Optional[str], must be passed by name): Defaults to None.
- If input is a list of floats:
  - Specifies units of the independent parameter value and the dependent parameter values as the independent value units concatendated with a semicolon and the dependent parameter unit (e.g., "ft;ac-ft").
  - If not specified or None:
    - The rating's default data units, if any, are used
    - If the rating has no default data units, an exception is raised.
- If input is a TimeSeries:
  - Specifies the unit of the reverse rated (independent parameter) time series.
  - If not specified or None:
    - The rating's default data units, if any, are used
    - If the rating has no default data units, an exception is raised.
vertical_datum (Optional[str], must be passed by name): Defaults to None.
- If input is a list of list of floats, this specifies:
  - Specifies:
    - The vertical datum of any input (dependent parameter) elevation value
    - The desired vertical datum of any reverse rated (independent parameter) elevation values.
  - If None, or not specified, the location's native vertical datum is used.
- If input is a TimeSeries:
  - Specifies only the desired vertical datum for any reverse rated (independent parameter) elevation values.
  - Any input (dependent parameter) elevation values will be in the vertical datum of the input time series.
  - If None, or not specified, the location's native vertical datum is used.
rating_time (Optional[datetime], must be passed by name): The maximum effective time and creation time for the rating set to use to perform the reverse rating. Defaults to None. Causes the reverse rating to be performed as if the current date/time were the specified time (no ratings with effective times or creation times later than this time will be used).
round (bool, optional, must be passed by name): Whether to use the rating set's specification's dependent rounding specification . Defaults to False.

Returns:

Any: The dependent parameter value(s) as described in input above

specification: RatingSpecification

The RatingSpecification of the rating set

Operations:

Read-Only

The RatingTemplate of the rating set

Operations:

Read-Only

vertical_datum_info: Optional[hec.parameter.ElevParameter._VerticalDatumInfo]

The vertical datum info of the rating set's specification's location, if any

Operations:

Read-Only

vertical_datum_json: Optional[str]

The vertical datum info of the rating set's specification's location, if any, as a JSON object

Operations:

Read-Only

vertical_datum_xml: Optional[str]

The vertical datum info of the rating set's specification's location, if any, as an XML instance

Operations:

Read-Only

class LocalRatingSet(hec.rating.AbstractRatingSet):

A sub-class of AbstractRatingSet that performs all ratings in local code

@classmethod

def from_xml( cls, xml_str: str, datastore: Optional[hec.AbstractDataStore] = None) -> LocalRatingSet:

Creates a LocalRatingSet object from an XML instance

Arguments:

xml_str (str): The XML instance
datastore (Optional[AbstractDataStore]): The AbstractDataStore object to retrieve rating points from if the XML includes table ratings without rating points (used in lazy loading). Defaults to None. Not needed if the XML has no table ratings or all table ratings have rating points specified for all effective times.

Raises:

Returns:

LocalRatingSet: The constructed LocalRatingSet object

ratings: dict[datetime.datetime, AbstractRating]

The set of ratings in this rating set

Operations:

Read-Only

def to_xml(self, indent: str = ' ', prepend: str = '') -> str:

Returns a formatted xml representation of the rating set.

Arguments:

indent (str, optional): The string to use for each level of indentation. Defaults to " ".
prepend (Optional[str], optional): A string to prepend to each line. Defaults to None.

Returns:

str: The formatted xml

Inherited Members

AbstractRatingSet: AbstractRatingSet; default_data_time; default_data_units; default_data_vertical_datum; rate; reverse_rate; specification; template; vertical_datum_info; vertical_datum_json; vertical_datum_xml

class LocalRatingSetException(hec.rating.abstract_rating_set.AbstractRatingSetException):

Exception class for LocalRatingSet objects

class LookupMethod(enum.Enum):

An enumeration.

NULL = <LookupMethod.NULL: (1, 'Return null if between values or outside range')>

ERROR = <LookupMethod.ERROR: (2, 'Raise an exception if between values or outside range')>

LINEAR = <LookupMethod.LINEAR: (3, 'Linear interpolation or extrapolation of independent and dependent values')>

LOGARITHMIC = <LookupMethod.LOGARITHMIC: (4, 'Logarithmic interpolation or extrapolation of independent and dependent values')>

LINLOG = <LookupMethod.LINLOG: (5, 'Linear interpolation/extrapoloation of independent values, Logarithmic of dependent values')>

LOGLIN = <LookupMethod.LOGLIN: (6, 'Logarithmic interpolation/extrapoloation of independent values, Linear of dependent values')>

PREVIOUS = <LookupMethod.PREVIOUS: (7, 'Return the value that is lower in position')>

NEXT = <LookupMethod.NEXT: (8, 'Return the value that is higher in position')>

NEAREST = <LookupMethod.NEAREST: (9, 'Return the value that is nearest in position')>

LOWER = <LookupMethod.LOWER: (10, 'Return the value that is lower in magnitude')>

HIGHER = <LookupMethod.HIGHER: (11, 'Return the value that is higher in magnitude')>

CLOSEST = <LookupMethod.CLOSEST: (12, 'Return the value that is closest in magnitude')>

@classmethod

def get(cls, key: Union[str, int]) -> LookupMethod:

class PairedData:

Class for directly using HEC-DSS Paired Data records for rating operations.

Unlike the HEC Rating API, PairedData objects support multiple dependent parameters for a single independent parameter

Multiple dependent parameters may be specified:

In the parameter portion of the name (e.g., HEC-DSS C pathname part):
- Example: C part = 'Elev-Area-Stor' with no labels specifies 'Elev' as the independent parameter, and 'Area' and 'Stor' as the dependent parameters.
In the labels field of the PaireData object:
- Example: C part = 'Stage-Currency' with labels of 'residential', 'agricultural', 'industrial', and 'municipal' specifies 'Stage' as the independent parameter, 'Currency' as the dependent parameter (as in a stage-damage curve) and the labels as the dependent sub-parameters
If labels are present and are all string representations of increasing numeric values, in addition to being able to perform a rating using the label keyword argument, the rating can be used as a rating with two independent parameters and one dependent parameter. The first indpendent parameter corresponds to the normal independent parameter of the rating and the second independent parameter corresponds to the numeric labels. Reverse ratings cannot be performed when using the PairedData object in this manner.

When calling the rate or reverse_rate methods of a PairedData object that has more than one dependent parameter or sub-parameter, the label keyword argument must be provided to specify the dependent parameter or sub-parameter to use

Unlike the Java hec.hecmath.PairedDataMath class, PairedData objects support linear and logarithmic interpolation of both independent and dependent parameters separately instead of requiring the same method on both parameters. However, PairedData object do not currently suppport the probability or percent axis type nor the horizontal axis selection that hec.HecMath.PairedDataMath and the hec.io.PairedDataContainer objects use for plotting control.

PairedData objects are serialized to/from HEC-DSS files using the hec.DssDataStore class

PairedData(init_from: Union[hecdss.paired_data.PairedData, str])

Initializer

Arguments:

init_from (Union[hecdss.PairedData, str]): Either a hecdss.PairedData object or a JSON string.
- hecdss.PairedData: A paired data record from an HEC-DSS file as retrieved by hecdss.get()
- str: A JSON string of the same format as produced by the json property. The string must contain a JSON object with the following members:
  - name (string, required): The object's name. If this is a valid HEC-DSS paired data pathname, the parameters will be parsed from the C pathname part unless parameters is specified.
  - ind_unit (string, required): The unit of the independent parameter values
  - ind_log (boolean, optional): Whether to interpolate the independent parameter values logarithmically. Defaults to false.
  - dep_unit (string, required): The unit of the independent parameter values
  - dep_log (boolean, optional): Whether to interpolate the dependent parameter values logarithmically. Defaults to false.
  - parameters (array of strings, optional): The independent (first string) and dependent (subsequent strings)parameter names. If not specified, parameters are taken from the name member, if possible.
  - labels (array of strings, optional): The dependent sub-parameters or second independent parameter values, depending on usage.
  - values (array of array of numbers, required): The independent (first array) and dependent (subsequend arrays) parameter values.

def copy(self) -> PairedData:

Returns a copy of this object

Returns:

PairedData: the copy

data: pandas.core.frame.DataFrame

Returns the internal pandas DataFrame object (not a copy)

Operations:

Read-Only

dep_log: bool

Returns whether the dependent parameter is interpolated logarithmically

Operations:

Read-Only

dep_unit: str

Returns the dependent parameter unit

Operations:

Read-Only

dep_values: Sequence[Sequence[float]]

Returns the dependent parameter values

Operations:

Read-Only

ind_log: bool

Returns whether the independent parameter is interpolated logarithmically

Operations:

Read-Only

ind_unit: str

Returns the independent parameter unit

Operations:

Read-Only

ind_values: Sequence[float]

Returns the independent parameter values

Operations:

Read-Only

json: str

Returns a string containing a JSON representation of the object

Operations:

Read-Only

labels: Optional[Sequence[str]]

Returns the object's labels, if any

Operations:

Read-Only

Returns the object's name

Operations:

Read-Only

parameters: Sequence[str]

Returns the object's parameters

Operations:

Read-Only

def rate(self, to_rate: Any, label: Optional[str] = None) -> Any:

Rates a single value, list of values, list of value sets, time series, or time series set.

Arguments:

to_rate (Any): The item(s) to be rated
- float: returns a single dependent value for a single independent value
- sequence of floats: returns a list of dependent values for a sequence of single independent values
- TimeSeries object: returns a TimeSeries of dependent values for a single TimeSeries of independent values
- sequence of two-value sequences of floats: returns a list of dependent values for a sequence of indepentent value sets
- sequence of two TimeSeries: returns a TimeSeries of dependent values for set of two independent value time series
label (Optional[str], optional): Specifies which dependent parameter or sub-parameter to use to rate single independent values. Must be specified when rating a single independent parameter with a multi-dependent parameter PairedData object. Must be one of the object's dependent parameters or sub-parameters. Defaults to None.

Returns:

Any: The rated value(s)

def reverse_rate(self, to_rate: Any, label: Optional[str] = None) -> Any:

Reverse rates a single value, list of values, or time series

Arguments:

to_rate (Any): The item(s) to be reverse rated
- float: returns an independent value for a dependent value
- sequence of floats: returns a list of independent values for a sequence of dependent values
- TimeSeries object: returns a TimeSeries of independent values for a TimeSeries of dependent values
label (Optional[str], optional): Specifies which dependent parameter or sub-parameter to use to reverse rate dependent values. Must be specified when reverse rating a single dependent parameter with a multi-dependent parameter PairedData object. Must be one of the object's dependent parameters or sub-parameters. Defaults to None.

Returns:

Any: The reverse rated value(s)

@staticmethod

def transform( values1: Sequence[float], values2: Sequence[float]) -> Sequence[Sequence[float]]:

Transforms two list of indpendent values (1st and 2nd independent values) to a list of value sets suitable for use in the rate method

Arguments:

values1 (Sequence[float]): The values for the 1st independent parameter
values2 (Sequence[float]): The vaules for the 2nd independent parameter

Raises:

ValueError: An list of value sets with each value set containing a value from the 1st and 2nd independent parameters

Returns:

list[list[float]]: _description_

values: Sequence[Sequence[float]]

Returns the object's values (indpendent and dependent)

Operations:

Read-Only

class PairedDataException(builtins.Exception):

Exception type for paired data operations

class RatingSpecification:

Holds the following information about ratings and rating sets;

rating idendifier, comprised of
- location identifier
- template identifier
  - independent parameters
  - dependent parameter
  - template version
- specification version
source agency
lookup methods for multiple effective dates in rating sets
- method for value times within the range of effective dates
- method for value times before the earliest effective date
- method for value times after the latest effective date
rounding specifications
- one for each independent parameter
- one for the dependent parameter
whether the specification is active (should be used)
whether the ratings with this specification should be automatically updated from the source agency
whether automatically updated ratings should be set to active
whether automatically updated ratings should have any rating extension migrated to the new rating
a description of the rating specification

RatingSpecification(name: str, **kwargs: Any)

Initializer for RatingSpecification objects

Arguments:

name (str): The rating specification identifier
location (Optional[Location], must be passed by name): A Location object for the specification. Defaults to None. If specified, the location name must match the location portion of the rating specification identifier
template (Optional[RatingTemplate], must be passed by name): A RatingTemplate object for the specification. Defaults to None. If specified, the rating template identifier must match the template portion of the rating specification identifier.
office (Optional[str], must be passed by name): The office for the rating specification. Defaults to None. If specified, overrides any office in the location and template parameters.
agency (Optional[str], must be passed by name): The agency that generates the ratings for this specification. Defaults to None.
lookup (Optional[list[str]], must be passed by value): Methods for time-based lookups using effective dates in rating sets with this specification. Defaults to None. If specified, must be an array of three strings, in the following order
- method for value times within the range of effective dates
- method for value times before the earliest effective date
- method for value times after the latest effective date
  If not specified, lookup methods of ['LINEAR', 'NEXT', 'PREVIOUS'] will be used.
rounding (Optional[list[str]], must be passed by name): Rounding specifications. Defaults to None. If specified:
- must be the length of the number of independent parameters plus 1
- all but the last item are applied to the independent parameters in position order
- the last item is applied to the dependent parameter
- each item must be a valid rounding specification
  If not specified, the rounding specification of 4444444449 is used for all parameters
active (Optional[bool], must be passed by name): Whether ratings and rating sets using this specification are active (should be used). Defaults to True.
auto_update (Optional[bool], must be passed by name): Whether ratings and rating sets using this specification are active (should be used). Defaults to False.
auto_activate (Optional[bool], must be passed by name): Whether automatically updated ratings should be set to active. Defaults to False.
auto_update_migration (Optional[bool], must be passed by name): Whether automatically updated ratings should have any rating extension migrated to the new rating. Defaults to False.
description (Optional[str], must be passed by name): A description for the rating specification. Defaults to None.

Raises:

ValueError: if the name parameter is not a properly-formed rating specification identifier
TypeError: if one of the named parameters has an unexpected type
RatingSpecificationException: if one of the named parameters is inconsistent with the rating specification identifier

active: bool

Whether ratings using this specification are active (should be used)

Operations:

Read/Write

agency: Optional[str]

The agency responsible for generating ratings using this specification

Operations:

Read/Write

auto_update: bool

Whether the ratings with this specification should be automatically updated from the source agency

Operations:

Read/Write

auto_activate: bool

Whether automatically updated ratings should be set to active

Operations:

Read/Write

auto_migrate_extension: bool

Whether automatically updated ratings should have any rating extension migrated to the new rating

Operations:

Read/Write

def copy(self) -> RatingSpecification:

Creates and returns a copy of this specificaiton

Returns:

RatingSpecification: The copy

description: Optional[str]

The description of the rating specification

Operations:

Read/Write

@staticmethod

def from_xml(xml: str) -> RatingSpecification:

Generates a RatingSpecification object from an XML string representation

Arguments:

xml (str): The XML string representation

Raises:

RatingSpecificationException: if there is an error in the XML string

Returns:

RatingSpecification: The generated RatingSpecification object

location: hec.Location

The location object of the specification

Operations:

Read/Write

lookup: list[str]

The lookup methods of the specification

Operations:

Read/Write

The specification identifier

Operations:

Read-Only

rounding: list[str]

The rounding specifications of the specification

Operations:

Read/Write

The RatingTemplate of the specification

Operations:

Read/Write

def to_xml(self, indent: str = ' ', prepend: str = '') -> str:

Returns a formatted xml representation of the rating specification.

For unformatted xml use etree.tostring(<specification_obj>.xml_element)

Arguments:

indent (str, optional): The string to use for each level of indentation. Defaults to " ".
prepend (Optional[str], optional): A string to prepend to each line. Defaults to None.

Returns:

str: The formatted xml

version: str

The version string of the specification

Operations:

Read/Write

xml_element: lxml.etree._Element

The rating specification as an lxml.etree.Element object

Operations:

Read-Only

class RatingSpecificationException(hec.shared.RatingException):

Base exception for all rating exceptions

class RatingTemplate:

Holds independent and dependent parameter names, independent parameter lookup methods, and version string for all associated ratings.

Ratings are associated by using a rating identifier that includes the template identifier.

RatingTemplate(name: str, **kwargs: Any)

Initializes the RatingTemplate object

Arguments:

name (str): The rating template identifier
lookup_methods (Optional[ tuple[LookupMethod, LookupMethod, LookupMethod] ]): _description_. Defaults to None.

Raises:

ValueError: _description_

def copy(self) -> RatingTemplate:

Returns a copy of the rating template

Returns:

RatingTemplate: The copy

dep_param: str

The depdendent parameter

Operations:

Read/Write

description: Optional[str]

The rating template description

Operations:

Read/Write

@staticmethod

def from_xml(xml: str) -> RatingTemplate:

Generates a RatingTemplate object from an XML string representation

Arguments:

xml (str): The XML string representation

Raises:

RatingTemplateException: if there is an error in the XML string

Returns:

RatingTemplate: The generated RatingTemplate object

ind_param_count: int

The number of independent parameters

Operations:

Read-Only

ind_params: list[str]

The indepdendent parameters as a list of strings

Operations:

Read-Only

lookup: list[list[str]]

The rating independent parameter lookup behaviors in in-range, out-range-low, out-range-high order as a list of lists of strings (one list for each independent parameter)

Operations:

Read/Write

The rating template identifier

Operations:

Read-Only

office: Optional[str]

The rating template office

Operations:

Read/Write

def to_xml(self, indent: str = ' ', prepend: Optional[str] = None) -> str:

Returns a formatted xml representation of the rating template.

For unformatted xml use etree.tostring(<template_obj>.xml_element)

Arguments:

indent (str, optional): The string to use for each level of indentation. Defaults to " ".
prepend (Optional[str], optional): A string to prepend to each line. Defaults to None.

Returns:

str: The formatted xml

version: str

The rating template version

Operations:

Read/Write

xml_element: lxml.etree._Element

The rating template as an lxml.etree.Element object

Operations:

Read-Only

class RatingTemplate.IndParameter:

Associates lookup methods with an independent parameter for a RatingTemplate object

RatingTemplate.IndParameter( name: str, lookup_methods: Optional[tuple[LookupMethod, LookupMethod, LookupMethod]] = None)

Initializes the IndParameter object

Arguments:

name (str): The associated independent parameter name
lookup_methods (Optional[ tuple[ LookupMethod, LookupMethod, LookupMethod ] ]): The lookup methods associated with the independent parameter. Defaults to None. If specified, the lookup methods are in the order of in-range, out-of-range-low, out-of-range-high. If not specified, the default methods of [ LINEAR, NEXT, PREVIOUS ] are used.

Raises:

ValueError: if the name is not a valid Parameter name

The independent parameter name

Operations:

Read-Only

in_range_method: str

The in-range lookup behavior for the independent parameter

Operations:

Read-Only

out_range_low_method: str

The out-of-range-low lookup behavior for the independent parameter

Operations:

Read-Only

out_range_high_method: str

The out-of-range-low lookup behavior for the independent parameter

Operations:

Read-Only

class RatingTemplateException(hec.shared.RatingException):

Exception for rating templates

class ReferenceRatingSet(hec.rating.AbstractRatingSet):

A sub-class of AbstractRatingSet that performs all ratings in the CWMS database

ReferenceRatingSet(specification: Any, **kwargs: Any)

Initializer for ReferenceRatingSet objects.

Arguments:

specification (Any): A RatingSpecification object to initialize from. This is typed as Any to avoid circular import dependencies.
datastore (CwmsDataStore, must be passed by name): The CwmsDataStore object used to perform the ratings in the database.

Raises:

TypeError: if specification is not a RatingSpecification object.

@staticmethod

def from_xml( xml: str, datastore: hec.AbstractDataStore) -> ReferenceRatingSet:

Creates a ReferenceRatingSet object from an XML instance

Arguments:

xml_str (str): The XML instance
datastore (Optional[AbstractDataStore]): The AbstractDataStore object for the database where the ratings are performed.

Returns:

ReferenceRatingSet: The ReferenceRatingSet object

Inherited Members

AbstractRatingSet: default_data_time; default_data_units; default_data_vertical_datum; rate; reverse_rate; specification; template; vertical_datum_info; vertical_datum_json; vertical_datum_xml

class TableRating(hec.rating.SimpleRating):

Implements lookup-based ratings

TableRating( specification: RatingSpecification, effective_time: Union[datetime.datetime, hec.HecTime, str])

Initializer for AbstractRating objects.

Arguments:

specification (Any): A RatingSpecification object to initialize from. This is typed as Any to avoid circular import dependencies.
effective_time (Union[datetime, HecTime, str]): The effective date/time of the rating

Raises:

TypeError: if specification is not a RatingSpecification object.

@staticmethod

def from_element( root: lxml.etree._Element, specification: Optional[RatingSpecification]) -> SimpleRating:

Creates a TableRating from a XML element and rating spec

Arguments:

root (etree._Element): The element
specification (Optional[RatingSpecification]): The rating specification.
- If specified: If specification vertical datum info is None, it will be created from any vertical datum info in the XML
- If not specified: The rating spec for the rating will be constructed from the XML

Raises:

AbstractRatingException: If there is any invalid XML in the portion common to all ratings
TableRatingException: If there is any invalid XML in the elements

Returns:

SimpleRating: The created rating

has_rating_points: bool

Whether the table rating has rating points

Concrete (non-reference) rating sets (see LocalRatingSet) may be initailized in a manner in which the included TableRating objects are initialized with or without data points.

This is controlled by specifying 'EAGER' or 'LAZY' as the loading method. A TableRating object in LocalRatingSet loaded with LAZY loading keeps a reference to the datastore from which it was loaded in order to retrieve rating points on the first use of the rating.

Operations:

Read/Write

@staticmethod

def interpolate_or_select( x: float, x0: float, x1: float, y0: float, y1: float, lookup: str) -> float:

Performs dependent value interpolation, extrapolation, or selection based on specified behavior

Arguments:

x (float): The independent value
x0 (float): The nearest independent value <= x in a sorted list
x1 (float): The nearest independent value >= x in a sorted list
y0 (float): The dependent value corresponding to x0
y1 (float): The dependent value corresponding to x1
lookup (str): The computation or selection behavior to use. See LookupMethod

Returns:

float: The interpolated, extrapolated, or selected dependent value

def populate_rating_points(self) -> None:

def rate_value( self, ind_value: list[float], lo_key: list[float] = [], hi_key: list[float] = []) -> float:

Rates a single independent parameter value set

The value set is expected to be in the native units and vertical datum of the rating. To specify units, vertical datum or rounding use rate_values, nesting ind_value in a list and extracting the result from the returned list.

Arguments:

ind_value (list[float]): The list of values (one for each independent parameter) that comprises the input value set
lo_key (list[float], optional): Do not set; only used internally on recursion. Defaults to [].
hi_key (list[float], optional): Do not set; only used internally on recursion. Defaults to [].

Returns:

float: The rated (dependent parameter) value

def reverse_rate_value(self, dep_value: float) -> float:

Reverse rates a single dependent parameter value

The dependent parameter value is expected to be in the native unit and vertical datum of the rating. To specify units, vertical datum or rounding use reverse_rate_values, putting dep_value in a list and extracting the result from the returned list.

Arguments:

dep_value (float): The dependent parameter value to reverse rate

Returns:

float: The rated (independent parameter) value

xml_element: lxml.etree._Element

The rating as an lxml.etree.Element object

Operations:

Read-Only

def xml_tag_name(self) -> str:

The XML tag name for this rating type

Oprations:

Read-Only

Inherited Members

SimpleRating: from_xml
AbstractRating: valid_rating_tags; effective_time; active; convert_units; create_time; default_data_units; default_data_vertical_datum; description; has_elev_param; make_datum_offsets; make_reverse_datum_offsets; make_reverse_unit_conversions; make_unit_conversion; make_unit_conversions; office; populate_xml_element; rate; rating_units; reverse_rate; specification; specification_id; template; template_id; to_xml; transition_start_time; vertical_datum_info; vertical_datum_json; vertical_datum_xml

class TableRatingException(hec.rating.simple_rating.SimpleRatingException):

Exception class for TableRating objects

class SimpleRating(hec.rating.AbstractRating):

Provides common for definitions and code for TableRating and ExpressionRating classes, both of which are represented in XML using the tag.

@staticmethod

def from_xml( xml_str: str, specification: Optional[RatingSpecification] = None) -> AbstractRating:

Creates a rating object from an XML instance

Arguments:

xml_str (str): The XML instance to create the rating from

Raises:

AbstractRatingException: if no subclass of AbstractRating has a registered from_xml()
method that is compatible with the specified XML instance

Returns:

AbstractRating: The rating created from the XML instance

xml_element: lxml.etree._Element

The rating as an lxml.etree.Element object

Operations:

Read-Only

def xml_tag_name(self) -> str:

The XML tag name for this rating type

Oprations:

Read-Only

Inherited Members

AbstractRating: valid_rating_tags; effective_time; active; convert_units; create_time; default_data_units; default_data_vertical_datum; description; has_elev_param; make_datum_offsets; make_reverse_datum_offsets; make_reverse_unit_conversions; make_unit_conversion; make_unit_conversions; office; populate_xml_element; rate; rating_units; reverse_rate; specification; specification_id; template; template_id; to_xml; transition_start_time; vertical_datum_info; vertical_datum_json; vertical_datum_xml