aspire.history
==============

.. py:module:: aspire.history


Classes
-------

.. autoapisummary::

   aspire.history.History
   aspire.history.FlowHistory
   aspire.history.SMCHistory


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

.. py:class:: History

   Base class for storing history of a sampler.


   .. py:method:: save(h5_file, path='history')

      Save the history to an HDF5 file.



   .. py:method:: load(h5_file, path='history')
      :classmethod:


      Load the history from an HDF5 file.

      :param h5_file: The open HDF5 file to load from.
      :type h5_file: :py:class:`h5py.File`
      :param path: The path within the HDF5 file to load the history from.
                   Default is "history".
      :type path: :py:class:`str`, *optional*



.. py:class:: FlowHistory

   Bases: :py:obj:`History`


   Base class for storing history of a sampler.


   .. py:attribute:: training_loss
      :type:  list[float]
      :value: []



   .. py:attribute:: validation_loss
      :type:  list[float]
      :value: []



   .. py:method:: plot_loss()

      Plot the training and validation loss.



   .. py:method:: save(h5_file, path='flow_history')

      Save the history to an HDF5 file.



.. py:class:: SMCHistory

   Bases: :py:obj:`History`


   Base class for storing history of a sampler.


   .. py:attribute:: log_norm_ratio
      :type:  list[float]
      :value: []



   .. py:attribute:: log_norm_ratio_var
      :type:  list[float]
      :value: []



   .. py:attribute:: beta
      :type:  list[float]
      :value: []



   .. py:attribute:: ess
      :type:  list[float]
      :value: []



   .. py:attribute:: ess_target
      :type:  list[float]
      :value: []



   .. py:attribute:: eff_target
      :type:  list[float]
      :value: []



   .. py:attribute:: mcmc_autocorr
      :type:  list[float]
      :value: []



   .. py:attribute:: mcmc_acceptance
      :type:  list[float]
      :value: []



   .. py:attribute:: sample_history
      :type:  list[aspire.samples.SMCSamples]
      :value: []



   .. py:method:: save(h5_file, path='smc_history')

      Save the history to an HDF5 file.

      The sample history is saved as a separate group under the main history
      group, with one subgroup per iteration. The number of iterations is
      stored in the main history group to allow for loading the sample history
      correctly.

      :param h5_file: The open HDF5 file to save to.
      :type h5_file: :py:class:`h5py.File`
      :param path: The path within the HDF5 file to save the history. Default is
                   "smc_history".
      :type path: :py:class:`str`, *optional*



   .. py:method:: load(h5_file, path='smc_history')
      :classmethod:


      Load the history from an HDF5 file.

      :param h5_file: The open HDF5 file to load from.
      :type h5_file: :py:class:`h5py.File`
      :param path: The path within the HDF5 file to load the history from. Default is
                   "smc_history".
      :type path: :py:class:`str`, *optional*

      :returns: The loaded history instance.
      :rtype: :py:class:`SMCHistory`



   .. py:method:: plot_beta(ax=None)


   .. py:method:: plot_log_norm_ratio(ax=None)


   .. py:method:: plot_ess(ax=None)


   .. py:method:: plot_ess_target(ax=None)


   .. py:method:: plot_eff_target(ax=None)


   .. py:method:: plot_mcmc_acceptance(ax=None)


   .. py:method:: plot_mcmc_autocorr(ax=None)


   .. py:method:: plot(fig = None)


   .. py:method:: plot_sample_history(n_samples=None, parameters=None, ax=None, cmap = 'viridis', scatter_kwargs=None, x_axis = 'log_p_t', iterations = None)

      Plot the history of samples in the SMC sampler.

      :param n_samples: Number of samples to plot from each iteration. If None, plot all samples.
      :type n_samples: :py:class:`int`, *optional*
      :param parameters: List of parameter names to plot. If None, plot all parameters.
      :type parameters: :py:class:`list` of :py:class:`str`, *optional*
      :param ax: Axes to plot on. If None, a new figure and axes will be created.
      :type ax: :py:class:`matplotlib.axes.Axes`, *optional*
      :param cmap: Colormap to use for plotting the samples. Default is "viridis".
      :type cmap: :py:class:`str`, *optional*
      :param scatter_kwargs: Keyword arguments to pass to the scatter function. If None, no additional arguments will be passed
      :type scatter_kwargs: :py:class:`dict`, *optional*
      :param x_axis: Quantity to use for the x-axis. Supported values are
                     :code:`"log_p_t"` and :code:`"log_likelihood"`.
                     Falls back to iteration index if required fields are missing.
      :type x_axis: :py:class:`str`, *optional*



   .. py:method:: plot_quantile_bands(parameters = None, quantile_interval = (0.1, 0.9), ax=None, line_kwargs=None, band_kwargs=None)

      Plot per-parameter quantile bands vs iteration.

      :param parameters: Parameters to plot. If None, all parameters are used.
      :type parameters: :py:class:`list[str] | None`, *optional*
      :param quantile_interval: Lower/upper quantiles to plot as a band.
      :type quantile_interval: :py:class:`tuple[float`, :py:class:`float]`, *optional*
      :param ax: Axes to draw on. If None, creates a new figure.
      :type ax: :py:class:`matplotlib.axes.Axes | list[matplotlib.axes.Axes] | None`, *optional*
      :param line_kwargs: Keyword arguments for the median line.
      :type line_kwargs: :py:class:`dict | None`, *optional*
      :param band_kwargs: Keyword arguments for the quantile band fill.
      :type band_kwargs: :py:class:`dict | None`, *optional*