hec.rating.paired_data

class PairedDataException(builtins.Exception):

Exception type for paired data operations

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

name: str

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