hec.quality

Provides quality code info and operations

Data Quality Rules:

1. Unless the Screened bit is set, no other bits can be set.

2. Unused bits (21, 23, and 26-30) must be reset (zero).

3. The Okay, Missing, Questioned and Rejected bits are mutually
   exclusive.

4. No replacement cause or replacement method bits can be set unless
   the changed (different) bit is also set, and if the changed (different)
   bit is set, one of the cause bits and one of the replacement
   method bits must be set.

5. Replacement Cause integer is in range 0..4.

6. Replacement Method integer is in range 0..4

7. The Test Failed bits are not mutually exclusive (multiple tests can be
   marked as failed).

Bit Mappings:

       3                   2                   1
     1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0

     P - - - - - T T T T T T T T T T T M M M M C C C D R R V V V V S
     |           <---------+---------> <--+--> <-+-> | <+> <--+--> |
     |                     |              |      |   |  |     |    +------Screened Flag
     |                     |              |      |   |  |     +-----------Validity Exclusive Flags
     |                     |              |      |   |  +--------------Value Range Integer
     |                     |              |      |   +-------------------Different Flag
     |                     |              |      +---------------Replacement Cause Integer
     |                     |              +---------------------Replacement Method Integer
     |                     +-------------------------------------------Test Failed Inclusive Flags
     +-------------------------------------------------------------------Protected Flag
def changed_id(code: int) -> str:

Returns the text identifier for a valid changed code.

This code is encoded in the quality code in bit 7 of 32 as diagrammed in the bit-mapping

Arguments:
  • code (int): Must be 0 or 1
Returns:

str: One of the following identifiers:

codereturns
0ORIGINAL
1MODIFIED

def get_code_ids(code: int) -> tuple[str, ...]:

Returns a list of identifiers for the component codes in a quality code

Arguments:
  • code (int): The quality code to return the component code identifiers for
Raises:
Returns:

tuple[int, ...]: A tuple containing the following code identifiers in the order specified:

  • screened
  • validity
  • range
  • changed
  • replacement cause
  • replacement method
  • test failed
  • protection
def get_component_codes(code: int) -> tuple[int, ...]:

Returns a tuple of component codes in a quality code

Arguments:
  • code (int): The quality code to return the component codes for
Raises:
Returns:

tuple[int, ...]: A tuple containing the following component codes in the order specified:

  • screened
  • validity
  • range
  • changed
  • replacement cause
  • replacement method
  • test failed
  • protection
def normalize_quality_code(code: int) -> int:

Sets bits unused by quality codes to zero

Arguments:
  • code (int): A quality code to normalize
Returns:

int: The input quality code with the unused bits set to zero

def protection_id(code: int) -> str:

Returns the text identifier for a valid protection code.

This code is encoded in the quality code in bit 31 of 32 as diagrammed in the bit-mapping

Arguments:
  • code (int): Must be 0 or 1
Returns:

str: One of the following identifiers:

codereturns
0UNPROTECTED
1PROTECTED

def range_id(code: int) -> str:

Returns the text identifier for a valid range code.

This code is encoded in the quality code in bits 5 and 6 of 32

Arguments:
  • code (int): Must be 0, 1, 2, or 3 as diagrammed in the bit-mapping
Returns:

str: One of the following identifiers:

codereturns
0NO_RANGE
1RANGE_1
2RANGE_2
3RANGE_3

def repl_cause_id(code: int) -> str:

Returns the text identifier for a valid replacement cause code.

This code is encoded in the quality code in bits 8-10 of 32 as diagrammed in the bit-mapping

Arguments:
  • code (int): Must be 0, 1, 2, 3, or 4
Returns:

str: One of the following identifiers:

codereturns
0NONE
1AUTOMATIC
2INTERACTIVE
3MANUAL
4RESTORED

def repl_method_id(code: int) -> str:

Returns the text identifier for a valid replacement method code.

This code is encoded in the quality code in bits 11-14 of 32 as diagrammed in the bit-mapping

Arguments:
  • code (int): Must be 0, 1, 2, 3, or 4
Returns:

str: One of the following identifiers:

codereturns
0NONE
1LIN_INTERP
2EXPLICIT
3MISSING
4GRAPHICAL

def screened_id(code: int) -> str:

Returns the text identifier for a valid screened code.

This code is encoded in the quality code in bit 0 of 32 as diagrammed in the bit-mapping

Arguments:
  • code (int): Must be 0 or 1
Returns:

str: One of the following identifiers:

codereturns
0UNSCREENED
1SCREENED

def set_changed_code(code: int, changed: Union[bool, int]) -> int:

Encodes a changed code into a quality code

Arguments:
  • code (int): The quality code to encode the changed code into
  • changed (Union[bool, int]): The changed code
Returns:

int: The modified quality code

def set_protection_code(code: int, protection: Union[bool, int]) -> int:

Encodes a protection code into a quality code

Arguments:
  • code (int): The quality code to encode the protection code into
  • protection (Union[bool, int]): The protection code
Returns:

int: The modified quality code

def set_range_code(code: int, value_range: int) -> int:

Encodes a range code into a quality code

Arguments:
  • code (int): The quality code to encode the range code into
  • range (Union[bool, int]): The range code
Returns:

int: The modified quality code

def set_repl_cause_code(code: int, repl_cause: int) -> int:

Encodes a replacement cause code into a quality code

Arguments:
  • code (int): The quality code to encode the replacement cause code into
  • replacement cause (Union[bool, int]): The replacement cause code
Returns:

int: The modified quality code

def set_repl_method_code(code: int, repl_method: int) -> int:

Encodes a replacement method code into a quality code

Arguments:
  • code (int): The quality code to encode the replacement method code into
  • replacement method (Union[bool, int]): The replacement method code
Returns:

int: The modified quality code

def set_screened_code(code: int, screened: Union[bool, int]) -> int:

Encodes a screened code into a quality code

Arguments:
  • code (int): The quality code to encode the screened code into
  • screened (Union[bool, int]): The screened code
Returns:

int: The modified quality code

def set_test_failed_code(code: int, test_failed: int) -> int:

Encodes a test failed code into a quality code

Arguments:
  • code (int): The quality code to encode the test failed code into
  • test failed (Union[bool, int]): The test failed code
Returns:

int: The modified quality code

def set_validity_code(code: int, validity: int) -> int:

Encodes a validity code into a quality code

Arguments:
  • code (int): The quality code to encode the validity code into
  • validity (Union[bool, int]): The validity code
Returns:

int: The modified quality code

def test_failed_id(code: int) -> str:

Returns the text identifier for a valid failed test code.

This code is encoded in the quality code in bits 15-25 of 32 as diagrammed in the bit-mapping, but bits 21 and 23 are not used

Arguments:
  • code (int): Must be 0 or sum of 1 or more of: 1, 2, 4, 8, 16, 32, 128, 512, and 1024
  • (maximum of one ocrrence per number). Note that values 64 and 256 are not used.
Returns:

str: One or more of the following identifiers. None is always returned alone; if more that one identifier is returned, they will be concatenated with the + character into a single string.

codereturns
0NONE
1ABSOLUTE_VALUE
2CONSTANT_VALUE
4RATE_OF_CHANGE
8RELATIVE_VALUE
16DURATION_VALUE
32NEG_INCREMENT
128SKIP_LIST
512USER_DEFINED
1024DISTRIBUTION

def validity_id(code: int) -> str:

Returns the text identifier for a valid validity code.

This code is encoded in the quality code in bits 1-4 of 32 as diagrammed in the bit-mapping

Arguments:
  • code (int): Must be 0, 1, 2, 4, or 8
Returns:

str: One of the following identifiers:

codereturns
0UNKNOWN
1OKAY
2MISSING
4QUESTIONABLE
8REJECTED

@total_ordering
class Quality:

Holds a quality code and provides quality tests and operations

Quality(init_from: Any = 0)

Initializes a Quality object

Arguments:
  • init_from (Any, optional): The object to initialize from. Defaults to 0.
    • Not specified: the quality code is set to 0
    • Integer: the quality code is set to the integer
    • String: the quality code is set from the unique beginning of one of the following (case insensitive):
      • "Unscreened": the quality code is 0 (Unscreened)
      • "Unknown" or "Indeterminate": the quality code is 1 (Screened Indeterminate)
      • "Okay": the quality code is 3 (Screened Okay)
      • "Missing": the quality code is 5 (Screened Missing)
      • "Questionable": the quality code is 9 (Screened Questionable)
      • "Rejected": the quality code is 17 (Screened Rejected)
    • Quality: the quality code is set to the other object's quality code
    • List or tuple: the quality code is set from the list of component identifiers.
      The zero value can be set for any of the component by setting its identifier to None.
      The sequence must have a mininum length of 8, in this order:
      • screened identifier
      • validity identifier
      • range identifier
      • changed identifier
      • replacement cause identifier
      • replacement method identifier
      • test failed identifier (may be multiple identifiers concatenated with + character)
      • protected identifier
def add_test_failed(self, value: Union[int, str]) -> Quality:

Adds a failed test to the test failed component of this object from a code or identifier and returns the modified object

Arguments:
  • value (Union[int, str]): The test failed component code or identifier of the failed test to be added
Returns:

Quality: The modified object

changed: int

The changed component code of the quality code

Operations:

Read-Write

changed_id: str

The changed component identifier of the quality code

Operations:

Read-Write

code: int

The internal quality code as a signed or unsigned integer depending on the default setting.

See

Operations:

Read Only

protection: int

The protection component code of the quality code

Operations:

Read-Write

protection_id: str

The protection component identifier of the quality code

Operations:

Read-Write

range: int

The range component code of the quality code

Operations:

Read-Write

range_id: str

The range component identifier of the quality code

Operations:

Read-Write

def remove_test_failed(self, value: Union[int, str]) -> Quality:

Removes a failed test from the test failed component of this object from a code or identifier and returns the modified object

Arguments:
  • value (Union[int, str]): The test failed component code or identifier of the failed test to be removed
Returns:

Quality: The modified object

repl_cause: int

The replacement cause component code of the quality code

Operations:

Read-Write

repl_cause_id: str

The replacement cause component identifier of the quality code

Operations:

Read-Write

repl_method: int

The replacement method component code of the quality code

Operations:

Read-Write

repl_method_id: str

The replacement method component identifier of the quality code

Operations:

Read-Write

score: int

A score to compare qualities by:

ScreenedValidity CodeScore
UNSCREENEDUNKNOWN1
SCREENEDMISSING0
SCREENEDREJECTED0
SCREENEDUNKNOWN2
SCREENEDQUESTIONABLE3
SCREENEDOKAY4
Operations:

Read Only

screened: int

The screened component code of the quality code

Operations:

Read-Write

screened_id: str

The screened component identifier of the quality code

Operations:

Read-Write

def set_changed(self, value: Union[int, str]) -> Quality:

Sets the changed component of this object from a code or identifier and returns the modified object.

Using this method instead of setting the changed or changed_id properties allows chained operations.

Arguments:
  • value (Union[int, str]): The changed component code or identifier
Returns:

Quality: The modified object

def set_protection(self, value: Union[int, str]) -> Quality:

Sets the protection component of this object from a code or identifier and returns the modified object.

Using this method instead of setting the protection or protection_id properties allows chained operations.

Arguments:
  • value (Union[int, str]): The protection component code or identifier
Returns:

Quality: The modified object

def set_range(self, value: Union[int, str]) -> Quality:

Sets the range component of this object from a code or identifier and returns the modified object.

Using this method instead of setting the range or range_id properties allows chained operations.

Arguments:
  • value (Union[int, str]): The range component code or identifier
Returns:

Quality: The modified object

def set_repl_cause(self, value: Union[int, str]) -> Quality:

Sets the replacement cause component of this object from a code or identifier and returns the modified object.

Using this method instead of setting the repl_cause or repl_cause_id properties allows chained operations.

Arguments:
  • value (Union[int, str]): The replacement cause component code or identifier
Returns:

Quality: The modified object

def set_repl_method(self, value: Union[int, str]) -> Quality:

Sets the replacement method component of this object from a code or identifier and returns the modified object.

Using this method instead of setting the repl_method or repl_method_id properties allows chained operations.

Arguments:
  • value (Union[int, str]): The replacement method component code or identifier
Returns:

Quality: The modified object

def set_screened(self, value: Union[int, str]) -> Quality:

Sets the screened component of this object from a code or identifier and returns the modified object.

Using this method instead of setting the screened or screened_id properties allows chained operations.

Arguments:
  • value (Union[int, str]): The screened component code or identifier
Returns:

Quality: The modified object

def set_test_failed(self, value: Union[int, str]) -> Quality:

Sets the test failed component of this object from a code or identifier and returns the modified object.

Using this method instead of setting the test_failed or test_failed_id properties allows chained operations.

Arguments:
  • value (Union[int, str]): The test failed component code or identifier
Returns:

Quality: The modified object

def set_validity(self, value: Union[int, str]) -> Quality:

Sets the validity component of this object from a code or identifier and returns the modified object.

Using this method instead of setting the validity or validity_id properties allows chained operations.

Arguments:
  • value (Union[int, str]): The validity component code or identifier
Returns:

Quality: The modified object

@classmethod
def set_return_signed_codes(cls, state: bool = True) -> None:

Sets the type (signed or unsigned of the code property)

Arguments:
  • state (bool, optional): Sets default type to signed if true, otherwise unsigned. Defaults to True.
@classmethod
def set_return_unsigned_codes(cls, state: bool = True) -> None:

Sets the type (signed or unsigned of the code property)

Arguments:
  • state (bool, optional): Sets default type to unsigned if true, otherwise signed. Defaults to True.
signed: int

The internal quality code as a signed integer.

Operations:

Read Only

symbol: str

The text symbol of the quality.

The symbol will be one or two characters, with the first character being:

  • ~: Not screened
  • u or 'U': Screened, validity is unknown
  • o or O: Screened, validity is okay
  • m or M: Screened, validity is missing
  • q or Q: Screened, validity is questioned
  • r or R: Screened, validity is rejected

If a screened quality has the protection bit set, the first chanacter will be uppercase; if not, it will be lowercase.

A second character of + signifies that the quality has additional information about one or more of the following:

  • value range
  • value replacement cause and method
  • test(s) failed

This property is used when the quality is used in a string context (e.g., print(q))

Operations:

Read Only

test_failed: int

The test failed component code of the quality code

Operations:

Read-Write

test_failed_id: str

The test failed component identifier of the quality code

Operations:

Read-Write

text: str

The text description of the quality.

A space separated list of words specifying the state of the following, in order:

  • Screened: ("Unscreened" or "Screened")
  • Validity: ("Unknown", "Okay", "Missing", "Questionable", or "Rejected")
  • Range: ("No_range", "Range_1", "Range_2", or "Range_3")
  • Changed: ("Original" or "Modified")
  • Replacement Cause: ("None", "Automatic", "Interactive", "Manual", "Restored")
  • Replacement Method: ("None", "Lin_Interp", "Explicit", "Missing", "Graphical")
  • Test Failed: ("None" or one or more of the following concatenated with "+"):
    • "Absolute_Value"
    • "Constant_Value"
    • "Rate_Of_Change"
    • "Relative_Value"
    • "Duration_Value"
    • "Neg_Increment"
    • "Skip_List"
    • "User_Defined"
    • "Distribution"
  • Protection: ("Unprotected" or "Protected")
Operations:

Read Only

unsigned: int

The internal quality code as an unsigned integer.

Operations:

Read Only

validity: int

The validity component code of the quality code

Operations:

Read-Write

validity_id: str

The validity component identifier of the quality code

Operations:

Read-Write

class QualityException(builtins.Exception):

Common base class for all non-exit exceptions.