hec.parameter

Provides parameter info and operations

Comprises the classes:

Base Parameter Definitions The tab separated variable file resources/base_parameters.tsv in this module's installation provides the following information about base parameters.

Field No.ContentTypeNotes
1Base Parameter IdentifierStringRequired
2Long NameStringRequired
3DescriptionStringRequired
4Default English UnitStringRequired
5Default SI UnitStringRequired
6Parameter is Accumuatable Over TimeBooleanRequired
7Integrated Base ParameterStringOptional. Base Parameter of integrating the base parameter in Field 1 over time
8Differentiated Base ParameterStringOptional. Base Parameter of differentiating the base parameter in Field 1 with respect to time
9English Differentiation Conversion FactorNumericRequired if Field 8 is present. Factor to convert:
  • From standard English unit of dividing the base parameter in Field 1 by a number of seconds
  • To the standard English unit of the base parameter in Field 8
10SI Differentiation Conversion FactorNumericRequired if Field 8 is present. Factor to convert:
  • From standard SI unit of dividing the base parameter in Field 1 by a number of seconds
  • To the standard SI unit of the base parameter in Field 8
def get_compatible_parameters(unitspec: Union[str, pint.registry.Unit]) -> list[str]:

Returns a list of base parameter names that are compatible with the specified unit

Arguments:
  • unit Union[str, Unit]): The unit to get the compatible parameters for
Returns:

list[str]: The list of compatible base parameter names

class ParameterException(builtins.Exception):

Exception specific to Parameter operations

class Parameter:

Holds info (name and unit) for a parameter.

See base_parameter_definitions for information on base parameters and their conversions.

Parameter(name: str, unit_or_system: Optional[str] = None)

Initializer

Arguments:
  • name (str): The full parmeter name
  • unit_or_system (Optional[str]):
    • If EN or None, the default English unit for the base parameter will be assigned
    • if SI, the default Système International unit for the base parameter will be assigned
    • Otherwise the specified unit will be assigned
Raises:
  • ParameterException: If the parameter name does not contain a valid base parameter name, or if the specified unit is not valid for the parameter
  • KeyError: If the specified unit is not a valid unit name, alias or Pint unit definition
@staticmethod
def accumulatable_base_parameters(context: str = 'CWMS') -> List[str]:

Returns a list of base parameter names that can be accumulated over time for the specified context

See base_parameter_definitions for information on base parameters and their conversions.

Arguments:
  • context (str): The context for the base parameter names. Currently only "CWMS" is supported. Defaults to "CWMS"
Raises:
  • ParameterException: If an invalid context is specified
Returns:

List[str]: A sorted list of names of base parameter that can be integrated over time for the context

base_parameter: str

The actual base parameter used. Will be same as basename unless the parameter was created using a parameter alias

Operations:

Read Only

@staticmethod
def base_parameters(context: str = 'CWMS') -> List[str]:

Returns a list of valid base parameter names for the specified context

See base_parameter_definitions for information on base parameters and their conversions.

Arguments:
  • context (str): The context for the base parameter names. Currently only "CWMS" is supported. Defaults to "CWMS"
Raises:
  • ParameterException: If an invalid context is specified
Returns:

List[str]: A sorted list of valid base parameter names for the context

basename: str

The name of the parameter as specified up to any initial '-' character

Operations:

Read Only

@staticmethod
def differentiable_base_parameters(context: str = 'CWMS') -> List[str]:

Returns a list of base parameter names that can be differentiated with respect to time for the specified context

See base_parameter_definitions for information on base parameters and their conversions.

Arguments:
  • context (str): The context for the base parameter names. Currently only "CWMS" is supported. Defaults to "CWMS"
Raises:
  • ParameterException: If an invalid context is specified
Returns:

List[str]: A sorted list of names of base parameter that can be differentiated with respect to time for the context

@staticmethod
def differentiation_info(base_parameter: str, context: str = 'CWMS') -> dict[str, typing.Any]:

Returns differentiation information for a base parameter name

See base_parameter_definitions for information on base parameters and their conversions.

Arguments:
  • base_parameter (str): The base parameter to get the information for.
  • context (str): The context for the base parameter names. Currently only "CWMS" is supported. Defaults to "CWMS"
Returns:

dict: A dictionary with the following content: { "base_parameter": , "EN" : , "SI" : , }

def get_compatible_units(self) -> list[str]:

Returns the list of unit names compatible with this parameter's unit

Returns:

list[str]: The list of compatible unit names

@staticmethod
def integrable_base_parameters(context: str = 'CWMS') -> List[str]:

Returns a list of base parameter names that can be integrated over time for the specified context

See base_parameter_definitions for information on base parameters and their conversions.

Arguments:
  • context (str): The context for the base parameter names. Currently only "CWMS" is supported. Defaults to "CWMS"
Raises:
  • ParameterException: If an invalid context is specified
Returns:

List[str]: A sorted list of names of base parameter that can be integrated over time for the context

def ito(self, unit_or_system: str) -> Parameter:

Assigns a unit to this parameter.

Identical to calling .to(unit_or_system, in_place=True)

Arguments:
  • unit_or_system (str):
    • If EN, the default English unit for the base parameter will be assigned
    • if SI, the default Système International unit for the base parameter will be assigned
    • Otherwise the specified unit will be assigned
Raises:
  • ParameterException: If the specified unit is not valid for the parameter
Returns:

Parameter: The converted object

name: str

The full name of the parameter as specified

Operations:

Read Only

subname: Optional[str]

The name of the parameter as specified after any initial '-' character

Operations:

Read Only

def to( self, unit_or_system: str, in_place: bool = False) -> Parameter:

Assigns a unit to this parameter or a copy of this parameter

Arguments:
  • unit_or_system (str):
    • If EN, the default English unit for the base parameter will be assigned
    • if SI, the default Système International unit for the base parameter will be assigned
    • Otherwise the specified unit will be assigned
  • in_place (bool, optional): Specifies whether to modify and return this object (True) or a copy of this object (False). Defaults to False.
Raises:
  • ParameterException: If the specified unit is not valid for the parameter
Returns:

Parameter: The converted object (self if in_place == True, otherwise a converted copy)

unit: pint.registry.Unit

The unit assigned to the parameter

Operations:

Read Only

unit_name: str

The unit name assigned to the parameter

Operations:

Read Only

class ElevParameter(Parameter):

Holds info (name and vertical datum information) for an elevation parameter

ElevParameter( name: str, vertical_datum_info: Union[str, dict[str, Any], NoneType] = None)

Initializes the ElevParameter object

Arguments:
  • name (str): The full parameter name
  • vertical_datum_info (Union[str, dict[str, Any]]): The vertical datum info as an xml string or dictionary
Raises:
def clone(self) -> ElevParameter:

Returns a copy of this object

Returns:

ElevParameter: The copy

current_datum: Optional[str]

The current datum of this object

Operations:

Read/Write

elevation: Optional[hec.UnitQuantity]

The elevation of this object in the current datum and unit

Operations:

Read Only

def get_offset_to(self, target_datum: str) -> Optional[hec.UnitQuantity]:

Returns the offset from the current vertical datum to the specified target datum in the current unit.

Arguments:
  • target_datum (str): The target datum
Raises:
Returns:

Optional[UnitQuantity]: The offset from the current datum to the target datum or None if the current and target datums are the same.

def ito( self, unit_or_system_or_datum: Union[str, pint.registry.Unit]) -> ElevParameter:

Converts this object to the specified unit or vertical datum and returns it.

Identical to calling .to(unit_or_system_or_datum, in_place=True

Arguments:
  • unit_or_system_or_datum (Union[str, Unit]): The unit, unit_system, or vertical datum to convert to. If unit system ("EN" or "SI"), the default Elev unit for that system is used.
Returns:

ElevParameter: The converted object, whether this object of a copy of it

native_datum: Optional[str]

The native datum of this object

Operations:

Read Only

navd88_offset: Optional[hec.UnitQuantity]

The offset from the native datum of this object to NGVD-29, in the current unit, or None if
* the native vertical datum is NGVD-29 * the native vertical datum is not NGVD-29, but the object does not have such an offset

Operations:

Read Only

navd88_offset_is_estimate: Optional[bool]

Whether the offset from the native vertical datum to NGVD-29 is an estimate (e.g, VERTCON) or None if the native vertical datum is NGVD-29 or the object does not have such and offset

Operations:

Read Only

ngvd29_offset: Optional[hec.UnitQuantity]

The offset from the native datum of this object to NGVD-29, in the current unit, or None if
* the native vertical datum is NGVD-29 * the native vertical datum is not NGVD-29, but the object does not have such an offset

Operations:

Read Only

ngvd29_offset_is_estimate: Optional[bool]

Whether the offset from the native vertical datum to NGVD-29 is an estimate (e.g, VERTCON) or None if the native vertical datum is NGVD-29 or the object does not have such and offset

Operations:

Read Only

def to( self, unit_or_system_or_datum: Union[str, pint.registry.Unit], in_place: bool = False) -> ElevParameter:

Converts either this object or a copy of it to the specified unit or vertical datum and returns it

Arguments:
  • unit_or_system_or_datum (Union[str, Unit]): The unit, unit_system, or vertical datum to convert to. If unit system ("EN" or "SI"), the default Elev unit for that system is used.
  • in_place (bool, optional): If True, this object is converted and returned, otherwise a copy is converted and returned. Defaults to False.
Returns:

ElevParameter: The converted object, whether this object of a copy of it

unit: pint.registry.Unit

The unit of this object

Operations:

Read Only

unit_name: str

The unit name of this object

Operations:

Read Only

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

The VerticalDatumInfo object of this parameter

Operations:

Read Only

vertical_datum_info_dict: Optional[dict[str, Any]]

The VerticalDatumInfo object of this parameter as a dictionary

Operations:

Read Only

vertical_datum_info_xml: Optional[str]

The VerticalDatumInfo object of this parameter as an xml string

Operations:

Read Only

Inherited Members
Parameter
accumulatable_base_parameters
base_parameter
base_parameters
basename
differentiable_base_parameters
differentiation_info
get_compatible_units
integrable_base_parameters
name
subname
class ElevParameter.VerticalDatumException(ParameterException):

Exception specific to vertical datum operations

class ParameterTypeException(builtins.Exception):

Exception specific to ParameterType operations

class ParameterType:

Holds info about parameter types.

Parameter types have 3 separate contexts, RAW, CWMS, and DSS. There's not much use for the RAW context except for providing a bridge between the CWMS and DSS contexts. Users would normally work in either the CWMS or DSS context.

The contexts of already-instantiated objects can also be set.

Parameter type names in the different contexts are:

RAWCWMSDSS
TotalTotalPER-CUM
MaximumMaxPER-MAX
MinimumMinPER-MIN
ConstantConstCONST
AverageAvePER-AVER
InstantaneousInstINST-CUM (for Precip or Count)
INST-VAL (for others)
ParameterType(param_type: str, context: Optional[str] = None)

Initializes a ParameterType object

Arguments:
  • param_type (str): The name of the parameter type
Raises:
  • ParameterTypeException: If param_type is not one of the values listed in the table above (context-insensitive)
context: str

The context of this object

Operations:

Read Only

def get_cwms_name(self) -> str:

Returns the name of the parameter time for the CWMS context

Returns:

str: The CWMS context name

def get_dss_name(self, is_precip: bool = False) -> str:

Returns the name of the parameter time for the DSS context

Arguments:
  • is_precip (bool, optional): Whether the parameter type is for a precipitation parameter. This matters only for the Instantaneous parameter type (CWMS=Inst). Defaults to False.
    • False: INST-CUM
    • True : INST-VAL
Returns:

str: The DSS context name

def get_raw_name(self) -> str:

Returns the name of the parameter time for the RAW context

Returns:

str: The RAW context name

name: str

The context-specific name of the object

Operations:

Read Only

@staticmethod
def parameter_type_names(context: str) -> List[str]:

Returns a list of valid parameter type names for the context.

Arguments:
  • context (str): The context for the parameter type names. Currently only "RAW", "CWMS", "DSS", and "ALL" are supported.
  • If "RAW", the parameter types for all contexts are returned
Raises:
  • ParameterTypeException: If an invlid context is specified
Returns:

List[str]: A sorted list of valid parameter type names for the context

def set_context(self, context: str) -> None:

Sets the context for this object

Arguments:
  • context (str): The context - must be one of RAW, CWMS, or DSS
Raises:
  • ParameterTypeException: If the specified context isn't one of the valid values
@classmethod
def set_default_context(cls, context: str) -> None:

Sets the default context for new ParameterType objects

Arguments:
  • context (str): The default context (RAW, CWMS, or DSS)
Raises:
  • ParameterTypeException: If an invalid context is specified