dcc_quantities.si_data.si_data_type

Module supporting the 'SiDataList' classes.

SiDataListType 

SiDataListType(
    data: Sequence,
    unit: str | DsiUnit,
    label: str | None = None,
    date_time: list[datetime] | None = None,
    _unc_info: dict | None = None,
)

Bases: BasicSiType, ABC

Base class of all SI types.

The class is not configured to be initialized directly. Instead, one of its subclasses should be used for initializing any instance. Alternatively, any subclass is automatically initialized if the classmethod .from_dcc_data(...) is invoked.

Subclasses

Base class of all SI types.

Parameters:
  • data (Numpy Array) –

    Quantity data array, defined as values defined their uncertainties. The provided data should match one of the following formats:

    1. Iterable of 2 same-length arrays: ([value0, value1, ...], [unc0, unc1, ...])
    2. Iterable of length N, where each item contains the value and uncertainty:
      [(val0, unc0), (val1, unc1), ...]
    3. Dictionaries with the keys 'value' and 'unc' with iterables with the values and uncertainties.
    4. Iterable of length N, where each item contains the value of the element (no uncertainties).
  • unit (DsiUnit) –

    D-SI unit that corresponds to the quantity data; unit for every single value of the data array.

  • label (str, default: None ) –

    String value to be used as an identifier of the data. This is usually represented as a character or a symbol to be correlated in mathematical equations.

  • date_time (list[datetime] | None, default: None ) –

    Timestamp in which the values where measured.

values property 

values: np.ndarray[float]

Returns a NumPy array of just the numerical values extracted from the data.

uncertainties property 

uncertainties: np.ndarray[float]

Returns a NumPy array of just the uncertainties extracted from the data.

If the data does not present any uncertainty whatsoever, the returned value is an array with the same length as the data, where each item is np.nan.

from_dcc_data classmethod 

from_dcc_data(dcc_data: dict) -> SiRealList | SiComplexList

Initialization of the class based on the parsed extracted DCC data.

Parameters:
  • dcc_data (dict) –

    Extracted DCC data, containing the correct DCC tag pointing to the data of the quantity.
Returns:

get_scale_factor 

get_scale_factor(other: SiDataListType | DsiUnit) -> float

Returns the scale of the current unit to a different one.

where 

where(
    condition: Callable[[np.ndarray[float], np.ndarray[float]], np.ndarray[bool]],
) -> np.ndarray[bool]

Conditional search within the data.

Provided a condition, the function searches for all places where that condition is met or not, providing back an array (same length as the data) defining if each element meets the condition. The condition is only considered either the real values or the uncertainties based on the check_uncertainties parameter.

The function is based on numpy.where, but differs in the return type.

Parameters:
  • condition (Callable[[np.ndarray[float], np.ndarray[float]], np.ndarray[bool]]) –

    Callable that defines the condition to be met by all the numbers. It is recommended for this to be defined as a lambda function. The condition must accept two inputs in this order:

    • The array of all values (represented as x in the example below).
    • The array of all uncertainties (represented as u in the example below).
Returns:
  • Array of booleans –

    Array with the same length as the data, where the i-th element defines whether the condition is met for the same index element of the original data.

Examples:

>>> values = SiRealList(data=[(1, 0.1), (2, 0.2), (3, 0.3), (4, 0.4), (5, 0.5)], ...)
>>> values.where(lambda x, _ : x % 2 == 0)  # Uncertainties are ignored
array([False, True, False, True, False])
>>> values.where(lambda x, u : (x > 3) & (u < 0.5))  # 'AND' logical operation
array([False, False, False, True, False])
>>> values.where(lambda _, u : u > 0.2)  # Values are ignored
array([False, False, True, True, True])
Note that the logical operations among both arrays must be identified with the bit operators (&, | and ^), at the same time that each result must be encapsulated in parentheses.

SiRealList 

SiRealList(*args, origin_type: SiOriginType = SiOriginType.XML_REAL_LIST, **kwargs)

Bases: SiDataListType

Class to contain all the data with real values.

The DCC schema defines the following tags as those that can hold real values:

  • 'si:real'
  • 'si:constant'
  • 'si:realListXMLList'

from_si_real classmethod 

from_si_real(si_data: dict, relative_uncertainties: dict | None) -> SiRealList

Specified constructor for the tag 'si:real'.

Parameters:
  • si_data (dict) –

    Extracted DCC data relative to the SI class.

  • relative_uncertainties (dict | None) –

    Optional dictionary for the relative uncertainties.

from_si_constant classmethod 

from_si_constant(si_data: dict, relative_uncertainties: dict | None) -> SiRealList

Specified constructor for the tag 'si:constant'.

Parameters:
  • si_data (dict) –

    Extracted DCC data relative to the SI class.

  • relative_uncertainties (dict | None) –

    Optional dictionary for the relative uncertainties.

from_si_xml_list classmethod 

from_si_xml_list(si_data: dict, relative_uncertainties: dict | None) -> SiRealList

Specified constructor for the tag 'si:realListXMLList'.

Parameters:
  • si_data (dict) –

    Extracted DCC data relative to the SI class.

  • relative_uncertainties (dict | None) –

    Optional dictionary for the relative uncertainties.

SiComplexList 

SiComplexList(*args, **kwargs)

Bases: SiDataListType

Class to contain data with complex values.

The DCC schema defines the tag 'si:complex' for these type of values.

Warning

This class is still not supported. Creating an SiComplexList instance will raise a NotImplementedError.

Built-in Operators

Length: len(obj)

Number of elements (values with uncertainties) defining the quantity data array.

Get item: obj[index]

Allows accessing quantity data array by a numeric index. The return value is an instance of SiDataListType (which keeps all other data from the original class) of length 1.

Comparator: ==

Checking whether all values are mathematically indistinguishable.

The == operator will check whether the values (stored at the quantity data array) have the same values as the ones being compared. 'Having the same values' is being defined as:

  • Both sequences have the same length.
  • For each item in the sequence, the real value is the same (considering scaling).
  • For each item in the sequence, the uncertainty value is the same (considering scaling).

Only when all conditions above are true, it will be considered that the current SiDataListType instance has the same value as the 'other' instance.

Math operators

Each SiDataListType instance can perform math operations (through built-in operators like +, *, /, etc.) providing as a result a new SiDataListType instance. This instance presents the updated values with uncertainty and recalculated D-SI unit.

Supported Math

  • Sum SiDataListType + other and other + SiDataListType
  • Subtraction SiDataListType - other and other - SiDataListType
  • Multiplication SiDataListType * other and other * SiDataListType
  • Division SiDataListType / other and other / SiDataListType
  • Power SiDataListType ** other
  • Value comparison SiDataListType == other
  • Negation -SiDataListType

Note

New SiDataListType instances are created without a label. Make sure to update the label of any new instance.

Tip

Consider performing all the math directly with DccQuantityType instances.

Addition: +

Subtraction: -

Performs the addition/subtraction of the current data with other, using the + or the - operator.

Only the data of the instance is modified. Other parameters (like the label) are kept as the one from the original instance at the left of the operator. Different units and scale factors are also considered for operations with multiple SiDataListTypes.

Tip

Only quantity data with the same D-SI unit can be added or subtracted.

Negation: -obj

Negation of the data from the instance.

Examples 

Initial:
    data = [1, 2, 3, 4]
Negated:
    data = [-1, -2, -3, -4]

Initial:
    data = [1, -2, 3, -4]
Negated:
    data = [-1, 2, -3, 4]

Multiplication: *

Multiplication of an SiDataListType with other value, which can be a scalar or other SiDataListType instance. The result data has updated quantity data array and D-SI unit.

Power: **

Support the operation of an SiDataListType powered to a target. The power operator is supported only for:

  • The target being a scalar.
  • The target being another quantity with adimensional D-SI units.

Warning

The instance SiComplexList to support complex values is not yet implemented. Any result with complex values will raise a NotImplementedError. These results most likely are produced by a negative value powered to a fraction.