plaid.containers.utils
======================

.. py:module:: plaid.containers.utils

.. autoapi-nested-parse::

   Utility functions for PLAID containers.



Functions
---------

.. autoapisummary::

   plaid.containers.utils.get_sample_ids
   plaid.containers.utils.get_number_of_samples
   plaid.containers.utils.get_feature_type_and_details_from
   plaid.containers.utils.check_features_type_homogeneity
   plaid.containers.utils.check_features_size_homogeneity
   plaid.containers.utils.has_duplicates_feature_ids


Module Contents
---------------

.. py:function:: get_sample_ids(savedir: Union[str, pathlib.Path]) -> list[int]

   Return list of sample ids from a dataset on disk.

   :param savedir: The path to the directory where sample files are stored.
   :type savedir: Union[str,Path]

   :returns: List of sample ids.
   :rtype: list[int]


.. py:function:: get_number_of_samples(savedir: Union[str, pathlib.Path]) -> int

   Return number of samples in a dataset on disk.

   :param savedir: The path to the directory where sample files are stored.
   :type savedir: Union[str,Path]

   :returns: number of samples.
   :rtype: int


.. py:function:: get_feature_type_and_details_from(feature_identifier: plaid.containers.feature_identifier.FeatureIdentifier) -> tuple[str, plaid.containers.feature_identifier.FeatureIdentifier]

   Extract and validate the feature type and its associated metadata from a feature identifier.

   This utility function ensures that the `feature_identifier` dictionary contains a valid
   "type" key (e.g., "scalar", "field", "node") and returns the type along
   with the remaining identifier keys, which are specific to the feature type.

   :param feature_identifier: A dictionary with a "type" key, and
                              other keys (some optional) depending on the feature type. For example:
                              - {"type": "scalar", "name": "Mach"}
                              - {"type": "field", "name": "pressure"}
                              - {"type": "field", "name": "pressure", "time":0.}
                              - {"type": "nodes", "base_name": "Base_2_2"}
   :type feature_identifier: dict

   :returns:

             A tuple `(feature_type, feature_details)` where:
                 - `feature_type` is the value of the "type" key (e.g., "scalar").
                 - `feature_details` is a dictionary of the remaining keys.
   :rtype: tuple[str, dict]

   :raises AssertionError: - If "type" is missing.
       - If the type is not in `AUTHORIZED_FEATURE_TYPES`.
       - If any unexpected keys are present for the given type.


.. py:function:: check_features_type_homogeneity(feature_identifiers: list[plaid.containers.feature_identifier.FeatureIdentifier]) -> None

   Check type homogeneity of features, for tabular conversion.

   :param feature_identifiers: dict with a "type" key, and
                               other keys (some optional) depending on the feature type. For example:
                               - {"type": "scalar", "name": "Mach"}
                               - {"type": "field", "name": "pressure"}
   :type feature_identifiers: list[dict]

   :raises AssertionError: if types are not consistent


.. py:function:: check_features_size_homogeneity(feature_identifiers: list[plaid.containers.feature_identifier.FeatureIdentifier], features: dict[int, list[plaid.types.Feature]]) -> int

   Check size homogeneity of features, for tabular conversion.

   Size homogeneity is check through samples for each feature, and through features for each sample.
   To be converted to tabular data, each sample must have the same number of features and each feature
   must have the same dimension

   :param feature_identifiers: dict with a "type" key, and
                               other keys (some optional) depending on the feature type. For example:
                               - {"type": "scalar", "name": "Mach"}
                               - {"type": "field", "name": "pressure"}
   :type feature_identifiers: list[dict]
   :param features: dict with sample index as keys and one or more features as values.
   :type features: dict

   :returns: the common feature dimension
   :rtype: int

   :raises AssertionError: if sizes are not consistent


.. py:function:: has_duplicates_feature_ids(feature_identifiers: list[plaid.containers.feature_identifier.FeatureIdentifier])

   Check whether a list of feature identifier contains duplicates.

   :param feature_identifiers: A list of dictionaries representing feature identifiers.
   :type feature_identifiers: list[FeatureIdentifier]

   :returns: True if a duplicate is found in the list, False otherwise.
   :rtype: bool