Add documentation for the pyro.infer.predictive.MHResampler weighed s…

…amples resampler.

pyro/infer/predictive.py

@@ -453,8 +453,30 @@ def forward(self, *args, **kwargs):
 
 
 class MHResampler(torch.nn.Module):
-    """
-    Resampler for weighed samples that is based on the Metropolis-Hastings algorithm.
+    r"""
+    Resampler for weighed samples that generates equally weighed samples from the distribution
+    specified by the weighed samples ``sampler``.
+
+    The resampling is based on the Metropolis-Hastings algorithm.
+    Given an initial sample :math:`x` subsequent samples are generated by:
+
+    -   Sampling from the ``guide`` a new sample candidate :math:`x'` with probability :math:`g(x')`.
+    -   Calculate an acceptance probability
+        :math:`A(x', x) = \min\left(1, \frac{P(x')}{P(x)} \frac{g(x)}{g(x')}\right)`
+        with :math:`P` being the ``model``.
+    -   With probability :math:`A(x', x)` accept the new sample candidate :math:`x'`
+        as the next sample, otherwise set the current sample :math:`x` as the next sample.
+
+    The above is the Metropolis-Hastings algorithm with the new sample candidate
+    proposal distribution being equal to the ``guide`` and independent of the
+    current sample such that :math:`g(x')=g(x' \mid x)`.
+
+    In case the ``guide`` perfectly tracks the ``model`` this sampler will do nothing
+    as the acceptance probability :math:`A(x', x)` will always be one.
+
+    :param callable sampler: When called returns :class:`WeighedPredictiveResults`.
+    :param slice source_samples_slice: Select source samples for storage (default is `slice(0)`, i.e. none).
+    :param slice stored_samples_slice: Select output samples for storage (default is `slice(0)`, i.e. none).
     """
 
     def __init__(
@@ -475,6 +497,7 @@ def __init__(
     def forward(self, *args, **kwargs):
         """
         Perform single resampling step.
+        Returns :class:`WeighedPredictiveResults`
         """
         with torch.no_grad():
             new_samples = self.sampler(*args, **kwargs)