hec.rating.abstract_rating

class AbstractRatingException(hec.shared.RatingException):

Exception class for AbstractRating objects

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: hec.rating.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:
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[hec.rating.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: hec.rating.RatingSpecification

A copy of the rating's specification

Operations:

Read-Only

specification_id: str

The rating's specification identifer

Operations:

Read-Only

template: hec.rating.RatingTemplate

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