dcc_quantities.dcc_quantity_table

Module containing all table related classes.

It is expected for the default case to read a table from an XML to use the DccQuantityTable class. This call will return the corresponding DccFlatTable or DccLongTable instance.

DccQuantityTable 

DccQuantityTable(
    idx_quants: dict[str | int, DccQuantityType],
    value_quants: list[DccQuantityType],
    dimension_len: int | None = None,
    identifier: str | None = None,
    ref_id: str | None = None,
    ref_type: list[str] | None = None,
    name: DccLangName = None,
    date_time: datetime.datetime | None = None,
    description: DccLangDescription | None = None,
    used_methods: dict | None = None,
    used_software: dict | None = None,
    measuring_equipments: dict | None = None,
    influence_conditions: dict | None = None,
    measurement_meta_data: dict | None = None,
)

Bases: ExplicitSerializerMixin

Generic Table class for Flat- and Long-Tables.

Parameters:
  • idx_quants (dict[str | int, DccQuantityType]) –

    Mapping from a numerical index to an index quantity. These correspond to the quantities that define the dimensions of the table.

  • value_quants (list[DccQuantityType]) –

    Sequence of all DccQuantityType instances that complete the values of the table.

  • ref_type (list[str] | None, default: None ) –

    Sequence of all refTypes corresponding to the Flat- or Long-Table.

  • dimension_len (int | None, default: None ) –

    Table parameter defining the number of dimensions that compose the table. This value should match to the number of index quantities.

  • identifier (str | None, default: None ) –

    Unique identifier provided to the table. If not defined, the identifier is initialized to a unique UUID value.

  • ref_id (str | None, default: None ) –

    Identifier corresponding to the IDREFS XML attribute. This ID is only required if another element outside the table is pointing to the quantity for its use outside the table.

  • name (DccLangName, default: None ) –

    Mapping from the supported languages to the names (in those languages) that were given to the table.

  • description (DccLangDescription | None, default: None ) –

    Mapping, analogous to 'name', where each value corresponds to the same description in the specified language by the key.

units property 

units: set[DsiUnit]

Set of all distinct units (DsiUnit instance) used within the table.

shape property 

shape: tuple[int, ...]

Returns the shape of the table. This property is not available for LongTables, as they don't have a fixed shape.

all_quantities property 

all_quantities: list[DccQuantityType]

List of all quantities composing the table (index quantities as well as value quantities).

index_quantities property 

index_quantities: list[DccQuantityType]

List of only the index quantities within the table.

value_quantities property 

value_quantities: list[DccQuantityType]

List of only the value quantities within the table.

id property 

id: str

Deprecated get of unique ID (or UUID) referencing the table.

unique_id property 

unique_id: str

Unique ID (or UUID) referencing the table.

from_dcc_data classmethod 

from_dcc_data(dcc_data: dict) -> DccFlatTable | DccLongTable

Create a DccQuantityTable instance from a dictionary representation.

Automatically detects the table format (attribute or reftype) and type (flat or long) to instantiate the correct subclass.

Parameters:
  • dcc_data (dict) –

    Dictionary containing DCC table data with quantities and metadata.
Returns:
Raises:
  • RuntimeError –

    If table format cannot be determined, duplicate indices found, or missing required index dimensions.

  • ValueError –

    If unknown table format type is detected.

get_quantity_ids_by_field 

get_quantity_ids_by_field(
    field: Literal["name", "ref_type", "unit", "scalable"], key: str
) -> Optional[str | list[str]]

Get the quantity unique ID of a specific field.

Parameters:
  • field (str) –

    It corresponds to the field to match the value. It can be one of the following options:

    • 'name': Name of the quantity, in either of the languages that the quantity defined. The provided name must be an exact match.
    • 'ref_type': Value of the refType that is to be matched to find the quantity. The provided value must be an exact match to the refType.
    • 'unit': D-SI unit that defined the quantity.
    • 'scalable': D-SI units that is scallable to the target unit. E.G.: '\kilo\metre\per\hour' is scallable to '\metre\per\second'.
  • key (str) –

    The value of the previous defined field.
Returns:
  • quant_id( str | list of str ) –

    Unique quantity ID, which can be used to extract the quantity from the table as quant = table[quant_id]. When multiple quantities matching the same field value are found, a list with all the IDs is returned. If no quantity is found, None is returned.

Examples:

Assuming a table with a single quantity with the name 'Acceleration', the following code shows how to retrieve its ID, then how to obtain the quantity from the table with the ID. 

>>> table: DccQuantityTable
>>> quant_id: str = table.get_quantity_ids_by_field("name", "Acceleration")
>>> acc_quant = table[quant_id]
Assuming the same table has at least two quantities with the D-SI unit '\metre', the following code shows how to obtain the second quantity with this unit. 
>>> table: DccQuantityTable
>>> quant_ids: list[str] = table.get_quantity_ids_by_field("unit", "\\metre")
>>> dist_quant = table[quant_ids[1]]

where 

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

Conditional search among the quantities of a table.

Provided a condition, the method searches among the quantities whether the condition is met among the values. The condition can be applied either to the whole table or to a subset of quantities (defined by their UUID).

Parameters:
  • condition (Callable) –

    Callable that defines the condition to be met by all the numbers. It is recommended for this to be defined as a lambda function.

  • ref_uuid (str) –

    Reference to the target unique ID (UUID) corresponding to the quantity where the condition is to be applied. The desired UUID can be easily obtained by searching either by name, unit or ref_type through the function .get_quantity_ids_by_field.
Returns:
  • Array of booleans –

    Numpy array defined as the union of the results among all conditional searches.

Examples:

The constructor of the used table in the example has been simplified for better reading. 

>>> table = DccLongTable(
...     idx_quants=[
...         DccQuantityType(name='Frequency', data=[10.0, 12.5, 16.0, 20.0, 25.0], unit=r'\hertz', ...)
...     ],
...     ...,
... )
>>> freq_uuid = table.get_quantity_ids_by_field("name", "Frequency")
>>> table.where(lambda x, _: x >= 20, ref_uuid=freq_uuid)
array([False, False, False, True, True])

See Also

SiDataListType.where(...)

export_as_xml_structure 

export_as_xml_structure() -> str

Exports the current table as an XML string compliant with the DCC-schema.

DccLongTable 

DccLongTable(*args, **kwargs)

Bases: DccQuantityTable

Serialization of a <dcc:list> with the refType basic_{dim}IndexTable, where dim corresponds to the number of dimensions that compose the table.

shape property 

shape: None

Returns None and prints a warning, as LongTables don't have a specific shape.

DccFlatTable 

DccFlatTable(*args, **kwargs)

Bases: DccQuantityTable

Serialization of a <dcc:list> with the refType basic_{dim}IndexFlatTable, where dim corresponds to the number of dimensions that compose the table.