dacapo.experiments.training_stats
=================================

.. py:module:: dacapo.experiments.training_stats


Attributes
----------

.. autoapisummary::

   dacapo.experiments.training_stats.logger


Classes
-------

.. autoapisummary::

   dacapo.experiments.training_stats.TrainingStats


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

.. py:data:: logger

.. py:class:: TrainingStats

   A class used to represent Training Statistics. It contains a list of training
   iteration statistics. It also provides methods to add new iteration stats,
   delete stats after a specified iteration, get the number of iterations trained
   for, and convert the stats to a xarray data array.

   .. attribute:: iteration_stats

      List[TrainingIterationStats]
      an ordered list of training stats.

   .. method:: add_iteration_stats(iteration_stats

      TrainingIterationStats) -> None:
      Add a new set of iterations stats to the existing list of iteration
      stats.

   .. method:: delete_after(iteration

      int) -> None:
      Deletes training stats after a specified iteration number.

   .. method:: trained_until() -> int

      
      Gets the number of iterations that the model has been trained for.

   .. method:: to_xarray() -> xr.DataArray

      
      Converts the iteration statistics to a xarray data array.

   .. note::

      The iteration stats list is structured as follows:
      - The outer list contains the stats for each iteration.
      - The inner list contains the stats for each training iteration.


   .. py:attribute:: iteration_stats
      :type:  List[dacapo.experiments.training_iteration_stats.TrainingIterationStats]


   .. py:method:: add_iteration_stats(iteration_stats: dacapo.experiments.training_iteration_stats.TrainingIterationStats) -> None

      Add a new iteration stats to the current iteration stats.

      :param iteration_stats: a new iteration stats object.
      :type iteration_stats: TrainingIterationStats

      :raises assert: if the new iteration stats do not follow the order of existing iteration stats.

      .. rubric:: Examples

      >>> training_stats = TrainingStats()
      >>> training_stats.add_iteration_stats(TrainingIterationStats(0, 0.1))
      >>> training_stats.add_iteration_stats(TrainingIterationStats(1, 0.2))
      >>> training_stats.add_iteration_stats(TrainingIterationStats(2, 0.3))
      >>> training_stats.iteration_stats
      [TrainingIterationStats(iteration=0, loss=0.1),
       TrainingIterationStats(iteration=1, loss=0.2),
       TrainingIterationStats(iteration=2, loss=0.3)]

      .. note::

         The iteration stats list is structured as follows:
         - The outer list contains the stats for each iteration.
         - The inner list contains the stats for each training iteration.



   .. py:method:: delete_after(iteration: int) -> None

      Deletes training stats after a specified iteration.

      :param iteration: the iteration after which the stats are to be deleted.
      :type iteration: int

      :raises assert: if the iteration number is less than the maximum iteration number.

      .. rubric:: Examples

      >>> training_stats = TrainingStats()
      >>> training_stats.add_iteration_stats(TrainingIterationStats(0, 0.1))
      >>> training_stats.add_iteration_stats(TrainingIterationStats(1, 0.2))
      >>> training_stats.add_iteration_stats(TrainingIterationStats(2, 0.3))
      >>> training_stats.delete_after(1)
      >>> training_stats.iteration_stats
      [TrainingIterationStats(iteration=0, loss=0.1)]

      .. note::

         The iteration stats list is structured as follows:
         - The outer list contains the stats for each iteration.
         - The inner list contains the stats for each training iteration.



   .. py:method:: trained_until() -> int

      The number of iterations trained for (the maximum iteration plus one).
      Returns zero if no iterations trained yet.

      :returns: number of iterations that the model has been trained for.
      :rtype: int

      :raises assert: if the iteration stats list is empty.

      .. rubric:: Examples

      >>> training_stats = TrainingStats()
      >>> training_stats.add_iteration_stats(TrainingIterationStats(0, 0.1))
      >>> training_stats.add_iteration_stats(TrainingIterationStats(1, 0.2))
      >>> training_stats.add_iteration_stats(TrainingIterationStats(2, 0.3))
      >>> training_stats.trained_until()
      3

      .. note::

         The iteration stats list is structured as follows:
         - The outer list contains the stats for each iteration.
         - The inner list contains the stats for each training iteration.



   .. py:method:: to_xarray() -> xarray.DataArray

      Converts the iteration stats to a data array format easily manipulatable.

      :returns: xarray DataArray of iteration losses.
      :rtype: xr.DataArray

      :raises assert: if the iteration stats list is empty.

      .. rubric:: Examples

      >>> training_stats = TrainingStats()
      >>> training_stats.add_iteration_stats(TrainingIterationStats(0, 0.1))
      >>> training_stats.add_iteration_stats(TrainingIterationStats(1, 0.2))
      >>> training_stats.add_iteration_stats(TrainingIterationStats(2, 0.3))
      >>> training_stats.to_xarray()
      <xarray.DataArray (iterations: 3)>
      array([0.1, 0.2, 0.3])
      Coordinates:
        * iterations  (iterations) int64 0 1 2

      .. note::

         The iteration stats list is structured as follows:
         - The outer list contains the stats for each iteration.
         - The inner list contains the stats for each training iteration.