piel.analysis.metrics
=====================

.. py:module:: piel.analysis.metrics


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/piel/analysis/metrics/join/index
   /autoapi/piel/analysis/metrics/metadata/index
   /autoapi/piel/analysis/metrics/statistics/index
   /autoapi/piel/analysis/metrics/units/index


Functions
---------

.. autoapisummary::

   piel.analysis.metrics.aggregate_scalar_metrics_collection
   piel.analysis.metrics.rename_metrics_collection
   piel.analysis.metrics.convert_scalar_metric_unit
   piel.analysis.metrics.convert_metric_collection_units_per_metric
   piel.analysis.metrics.convert_metric_collection_per_unit
   piel.analysis.metrics.concatenate_metrics_collection


Package Contents
----------------

.. py:function:: aggregate_scalar_metrics_collection(metrics_collection: piel.types.ScalarMetricCollection) -> piel.types.ScalarMetric

   Aggregates a ScalarMetricCollection into a single ScalarMetrics instance.

   The aggregation is performed as follows:
   - mean: Weighted mean based on count.
   - min: Minimum of all min values.
   - max: Maximum of all max values.
   - standard_deviation: Combined standard deviation considering individual means and counts.
   - count: Sum of all counts.
   - unit: Must be consistent across all ScalarMetrics.

   :param metrics_collection: A ScalarMetricsCollection instances to aggregate.
   :type metrics_collection: ScalarMetricCollection

   :returns: A single ScalarMetrics instance representing the aggregated metrics.
   :rtype: ScalarMetric

   :raises ValueError: If the input list is empty or units are inconsistent.


.. py:function:: rename_metrics_collection(collection: piel.types.ScalarMetricCollection, new_names: list[str]) -> piel.types.ScalarMetricCollection

   Renames each metric in the provided ScalarMetricCollection with the corresponding name from new_names.

   :param collection: The original metric collection.
   :type collection: ScalarMetricCollection
   :param new_names: A list of new names for the metrics.
   :type new_names: List[str]

   :returns: A new metric collection with renamed metrics.
   :rtype: ScalarMetricCollection

   :raises ValueError: If the number of new names does not match the number of metrics.


.. py:function:: convert_scalar_metric_unit(metric: piel.types.ScalarMetric, target_unit: piel.types.Unit) -> piel.types.ScalarMetric

   Converts the units of a single ScalarMetrics instance to the target unit.

   :param metric: The original scalar metric.
   :type metric: ScalarMetric
   :param target_unit: The target unit to convert to.
   :type target_unit: Unit

   :returns: A new ScalarMetrics instance with converted values and updated unit.
   :rtype: ScalarMetric

   :raises ValueError: If the original unit and target unit have different 'datum'.


.. py:function:: convert_metric_collection_units_per_metric(collection: piel.types.ScalarMetricCollection, target_units: dict[str, piel.types.Unit]) -> piel.types.ScalarMetricCollection

   Converts the units of metrics in a ScalarMetricCollection to the target units.

   :param collection: The original metric collection.
   :type collection: ScalarMetricCollection
   :param target_units:
                        - If a dictionary is provided, keys should be metrics names and values are the target Units.
   :type target_units: dict[str, Unit]

   :returns: A new ScalarMetricCollection with converted metrics.
   :rtype: ScalarMetricCollection

   :raises ValueError: If target_units is a dict and a metric name is missing,
       or if any unit conversion is invalid.


.. py:function:: convert_metric_collection_per_unit(collection: piel.types.ScalarMetricCollection, target_units: dict[str, piel.types.Unit]) -> piel.types.ScalarMetricCollection

   Converts the units of metrics in a ScalarMetricCollection based on unit names.

   :param collection: The original metric collection.
   :type collection: ScalarMetricCollection
   :param target_units:
   :type target_units: dict[str, Unit]

   :returns: A new ScalarMetricCollection with converted metrics.
   :rtype: ScalarMetricCollection

   :raises ValueError: If target_units is a dict and a metric's unit name is missing,
       or if any unit conversion is invalid.


.. py:function:: concatenate_metrics_collection(metrics_collection_list: list[piel.types.ScalarMetricCollection], **kwargs) -> piel.types.ScalarMetricCollection

   Concatenates multiple ScalarMetricCollection instances into a single ScalarMetricCollection.

   :param metrics_collection_list: List of ScalarMetricCollection instances to concatenate.
   :type metrics_collection_list: List[ScalarMetricCollection]

   :returns: A new ScalarMetricCollection containing all metrics from the input collections.
   :rtype: ScalarMetricCollection

   :raises ValueError: If the input list is empty.