jexplore.backends.default
=========================

.. py:module:: jexplore.backends.default

.. autoapi-nested-parse::

   Ths module defines the default version of a Jexplore
   backend for storing data in memory and on disk.



Attributes
----------

.. autoapisummary::

   jexplore.backends.default.DEFAULTBKND_CONFIG
   jexplore.backends.default.logger


Classes
-------

.. autoapisummary::

   jexplore.backends.default.DefaultBackend


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

.. py:data:: DEFAULTBKND_CONFIG

   Default backend config parameters

.. py:data:: logger

   logger instance

.. py:class:: DefaultBackend[Tepoch: jexplore.sampling.Epoch](burn = 0, **config)

   Default backend dumping samples on disk per epoch.

   :param burn: number of samples to burn (these will not be registered by the
                backend)
   :param \**config: backend configuration options.


   .. py:attribute:: burn
      :type:  int

      burned samples


   .. py:method:: ingest(epoch, eind=-1)

      loads and store one epoch in the backend.

      :param epoch: the epoch to be loaded. Can be an epoch
      instance, a dictionnary or the path to a
      backend file.

      :param eind: if `epoch` is the path to a backend file this
      is the index of the epoch. Same syntax that
      :py:attr:`jexplore.backend.default.DefaultBackend.read_epoch`

      :return: the backend object.



   .. py:method:: ingest_dict(epoch, copy = True)

      Loads and store one epoch dictionnary in the
      backend.

      :param epoch: the epoch dictionnary
      :param copy: if true the dictionary is copied before storing

      :return: the backend object



   .. py:method:: get(ind = -1)

      Loads an epoch from registry.

      :param ind: index of the epoch in the registry.

      :return: epoch data as a dictionnary.



   .. py:method:: set_burn(burn)

      Sets the number of samples to be burned and removes stored
      samples if necessary.

      :param burn: number of burned samples



   .. py:method:: update()

      This implements the storing logic of this backend. It parses
      the registry of the ingested epochs and implements storing policies
      according to the configuration paremeters.



   .. py:method:: flatten_samples(samples)
      :staticmethod:


      Flatten a (chain, dim, nsamples) chain into a (n. all samples, dim) format.

      :param samples: the samples dictionnary

      :return: flatten samples dictionnary



   .. py:method:: get_samples(burn = 0, thin = 1, pars = None, mask = Ellipsis, flatten = False)

      Get the samples from the backend.

      :param burn: number of initial samples to discart. This is added
                   on top of the backend instance `burn` parameter.
      :param thin: thinning factor.
      :param pars: list of names of the sample parameters to be returned.
                   Default: only "p".
      :param mask: mask (boolean mask or list of index) for the chains to be
                   retrieved.
      :param flatten: returns flattened samples with shape (n. samples, dim).

      :return: a dictionnary which keys are the parameters names and values
               the returned chains. None if no samples could be retrieved.



   .. py:method:: get_stats(epochs = None, fname = None)

      Returns a dictionnary of epoch stats. Optionnally save the dictionnary to a
      h5 file.

      :param epochs: list of epochs. If None (default) all non burned epochs are
                     considered.
      :param fname: if not None, the epochs stats are saved to file.

      :return: the stats of the selected epochs.



   .. py:method:: clean()

      Clean up all epochs data from backend



   .. py:method:: read_epoch(fn, iepoch = -1)
      :classmethod:


      Loads an epoch from a backend `h5` file.

      :param fn: file name
      :param iepoch: index of the epoch in the file. Note that this is
                     the overall index in the backend that created the
                     file. If it is a negative integer `-i` it takes
                     the `-ith` epoch from the last (ordered by their
                     epoch index). E.g if `iepoch` is -1 it takes the
                     last epoch.

      :return: epoch data as a dictionnary.



   .. py:method:: load(iepoch = -1, eclass = None, pars = None)

      Loads an epoch from a backend `h5` file.

      :param iepoch: index of the epoch in the file. Note that this is
                     the overall index in the backend that created the
                     file. If it is a negative integer `-i` it takes
                     the `-ith` epoch from the last (ordered by their
                     epoch index). E.g if `iepoch` is -1 it takes the
                     last epoch.

      :param eclass: epoch class.
      :param pars: samples parameters to be loaded. Default: all.

      :return: the loaded epoch.



   .. py:method:: load_epoch(fn, iepoch = -1, eclass = None, pars = None)
      :staticmethod:


      Loads an epoch from a backend `h5` file.

      :param fn: file name
      :param iepoch: index of the epoch in the file. Note that this is
                     the overall index in the backend that created the
                     file. If it is a negative integer `-i` it takes
                     the `-ith` epoch from the last (ordered by their
                     epoch index). E.g if `iepoch` is -1 it takes the
                     last epoch.

      :param eclass: epoch class.
      :param pars: samples parameters to be loaded. Default: all.

      :return: the loaded epoch.



   .. py:method:: reset()

      Remove all existing files