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

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


Functions
---------

.. autoapisummary::

   piel.analysis.metrics.units.convert_scalar_metric_unit
   piel.analysis.metrics.units.convert_metric_collection_units_per_metric
   piel.analysis.metrics.units.convert_metric_collection_per_unit


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

.. 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.