hec.rating.abstract_rating_set

class AbstractRatingSetException(hec.shared.RatingException):

Base exception for all rating exceptions

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

The RatingSpecification of the rating set

Operations:

Read-Only

template: hec.rating.RatingTemplate

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