sequince.steps.resampling
=========================

.. py:module:: sequince.steps.resampling


Attributes
----------

.. autoapisummary::

   sequince.steps.resampling.logger


Classes
-------

.. autoapisummary::

   sequince.steps.resampling.ResamplingOutput
   sequince.steps.resampling.ResamplingStep
   sequince.steps.resampling.MultinomialResampling
   sequince.steps.resampling.StratifiedResampling
   sequince.steps.resampling.SystematicResampling


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

.. py:data:: logger

.. py:class:: ResamplingOutput

   Bases: :py:obj:`collections.abc.Mapping`\ [\ :py:obj:`str`\ , :py:obj:`Any`\ ]


   Fixed-structure resampling output with a static scheme label.


   .. py:attribute:: ess
      :type:  float | sequince.typing.Array


   .. py:attribute:: resampled
      :type:  bool | sequince.typing.Array


   .. py:attribute:: ancestors
      :type:  sequince.typing.Array


   .. py:attribute:: resampling_scheme
      :type:  str


.. py:class:: ResamplingStep(*, ess_threshold = 0.5, always_resample = False, n_samples = None, resample_at_end = True)

   Bases: :py:obj:`sequince.steps.base.SMCStep`


   Base class for resampling steps with an optional ESS trigger.

   :param ess_threshold: Resample when the effective sample size (ESS) ratio falls below this
                         threshold.  If ``None`` (default) resampling is never triggered based on
                         ESS.
   :param always_resample: When ``True`` always resample regardless of ESS (overrides
                           ``ess_threshold``).
   :param n_samples: Number of particles to draw when resampling. If ``None``, draw the same
                     number as are present in the input state.
   :param resample_at_end: If ``True`` (default) will always resample when the inverse
                           temperature β reaches 1.0, regardless of ESS. If ``False``, the final
                           resampling may be skipped if ``always_resample`` is ``False`` and the
                           ESS ratio is above ``ess_threshold``.


   .. py:attribute:: resampling_scheme
      :type:  ClassVar[str]
      :value: 'unknown'



   .. py:method:: apply(state, context, rng)


   .. py:method:: initialize_functional_metadata(state, metadata)

      Initialize fixed-shape resampling metadata.



   .. py:method:: apply_functional(state, context, random_state)

      Resample while explicitly threading RNG state.

      The initial compiled subset requires unconditional resampling.  A
      traced ESS threshold needs a conditional RNG transition and is not
      supported yet.



.. py:class:: MultinomialResampling(*, ess_threshold = 0.5, always_resample = False, n_samples = None, resample_at_end = True)

   Bases: :py:obj:`ResamplingStep`


   Draw ancestors with replacement according to the weights.


   .. py:attribute:: resampling_scheme
      :value: 'multinomial'



.. py:class:: StratifiedResampling(*, ess_threshold = 0.5, always_resample = False, n_samples = None, resample_at_end = True)

   Bases: :py:obj:`ResamplingStep`


   Stratified resampling for reduced variance.


   .. py:attribute:: resampling_scheme
      :value: 'stratified'



.. py:class:: SystematicResampling(*, ess_threshold = 0.5, always_resample = False, n_samples = None, resample_at_end = True)

   Bases: :py:obj:`ResamplingStep`


   Systematic resampling for reduced variance.


   .. py:attribute:: resampling_scheme
      :value: 'systematic'