Fix docs for sphynx

Author: stefanradev93

bayesflow/amortizers.py

@@ -36,9 +36,9 @@ class AmortizedTarget(ABC):
     """An abstract interface for an amortized learned distribution. Children should
     implement the following public methods:
 
-    - compute_loss(self, input_dict, **kwargs)
-    - sample(input_dict, **kwargs)
-    - log_prob(input_dict, **kwargs)
+    1. ``compute_loss(self, input_dict, **kwargs)``
+    2. ``sample(input_dict, **kwargs)``
+    3. ``log_prob(input_dict, **kwargs)``
     """
 
     @abstractmethod
@@ -77,6 +77,8 @@ class AmortizedPosterior(tf.keras.Model, AmortizedTarget):
     [3] Jaini, P., Kobyzev, I., Yu, Y., & Brubaker, M. (2020, November).
     Tails of lipschitz triangular flows.
     In International Conference on Machine Learning (pp. 4673-4681). PMLR.
+
+    Serves as in interface for learning ``p(parameters | data, context).``
     """
 
     def __init__(self, inference_net, summary_net=None, latent_dist=None, latent_is_dynamic=False, 
@@ -410,7 +412,7 @@ def _determine_summary_loss(self, loss_fun):
 
 class AmortizedLikelihood(tf.keras.Model, AmortizedTarget):
     """An interface for a surrogate model of a simulator, or an implicit likelihood
-    ``p(params | data, context).''
+    ``p(data | parameters, context).``
     """
 
     def __init__(self, surrogate_net, latent_dist=None, **kwargs):
@@ -471,7 +473,7 @@ def call_loop(self, input_list, **kwargs):
         -------
         net_out or (net_out, summary_out) : tuple of tf.Tensor
             the outputs of ``inference_net(theta, summary_net(x, c_s), c_d)``, usually a latent variable and
-            log(det(Jacobian)), that is a tuple ``(z, log_det_J).
+            log(det(Jacobian)), that is a tuple ``(z, log_det_J)``.
         """
 
         outputs = []

bayesflow/inference_networks.py

@@ -178,8 +178,8 @@ def forward(self, targets, condition, **kwargs):
 
     @tf.function
     def inverse(self, z, condition, **kwargs):
-        """Performs a reverse pass through the chain. Assumes only used
-        in inference mode, so **kwargs contains `training=False`."""
+        """Performs a reverse pass through the chain. Assumes that it is only used
+        in inference mode, so ``**kwargs`` contains ``training=False``."""
 
         # Add noise to target if using SoftFlow, use explicitly
         # not in call(), since methods are public

bayesflow/mcmc.py

@@ -27,31 +27,31 @@
 
 class MCMCSurrogateLikelihood:
     """An interface to provide likelihood evaluation and gradient estimation of a pre-trained
-    `AmortizedLikelihood` instance, which can be used in tandem with (HMC)-MCMC, as implemented,
-    for instance, in `PyMC3`.
+    ``AmortizedLikelihood`` instance, which can be used in tandem with (HMC)-MCMC, as implemented,
+    for instance, in ``PyMC3``.
     """
 
     @tf.function
     def __init__(self, amortized_likelihood, configurator=None, likelihood_postprocessor=None,
                  grad_postprocessor=None):
-        """Creates in instance of the surrogate likelihood using a pre-trained `AmortizedLikelihood` instance.
+        """Creates in instance of the surrogate likelihood using a pre-trained ``AmortizedLikelihood`` instance.
 
         Parameters
         ----------
         amortized_likelihood       : bayesflow.amortized_inference.AmortizedLikelihood
             A pre-trained (invertible) inference network which processes the outputs of the generative model.
         configurator               : callable, optional, default: None
-            A function that takes the input to the `log_likelihood` and `log_likelihood_grad`
+            A function that takes the input to the ``log_likelihood`` and ``log_likelihood_grad``
             calls and converts them to a dictionary containing the following mandatory keys,
             if DEFAULT_KEYS unchanged:
-                `observables` - the variables over which a condition density is learned (i.e., the observables)
-                `conditions`  - the conditioning variables that the directly passed to the inference network
+                ``observables`` - the variables over which a condition density is learned (i.e., the observables)
+                ``conditions``  - the conditioning variables that the directly passed to the inference network
             default: Return the first parameter - has to be a dicitionary with the mentioned characteristics
         likelihood_postprocessor  : callable, optional, default: None
             A function that takes the likelihood for each observable as an input. Can be used for aggregation
             default: sum all likelihood values and return a single value.
         grad_postprocessor        : callable, optional, default: None
-            A function that takes the gradient for each value in `conditions` as returned by the preprocessor
+            A function that takes the gradient for each value in ``conditions`` as returned by the preprocessor
             default: Leave the values unchanged.
         """
 
@@ -84,15 +84,16 @@ def log_likelihood(self, *args, **kwargs):
 
         Parameters
         ----------
-        The parameters as expected by `configurator`. For the default configurator,
+        The parameters as expected by ``configurator``. For the default configurator,
         the first parameter has to be a dictionary containing the following mandatory keys,
         if DEFAULT_KEYS unchanged:
-            `observables` - the variables over which a condition density is learned (i.e., the observables)
-            `conditions`  - the conditioning variables that the directly passed to the inference network
+            ``observables`` - the variables over which a condition density is learned (i.e., the observables)
+            ``conditions``  - the conditioning variables that the directly passed to the inference network
+
         Returns
         -------
-        out :
-            The output as returned by `likelihood_postprocessor`. For the default postprocessor,
+        out : np.ndarray
+            The output as returned by ``likelihood_postprocessor``. For the default postprocessor,
             this is the total log-likelihood given by the sum of all log-likelihood values.
         """
 
@@ -103,21 +104,22 @@ def log_likelihood(self, *args, **kwargs):
 
     def log_likelihood_grad(self, *args, **kwargs):
         """Calculates the gradient of the surrogate likelihood with respect to
-        every parameter in `conditions`.
+        every parameter in ``conditions``.
 
         Parameters
         ----------
-        The parameters as expected by `configurator`. For the default configurator,
+        The parameters as expected by ``configurator``. For the default configurator,
         the first parameter has to be a dictionary containing the following mandatory keys,
-        if DEFAULT_KEYS unchanged:
-            `observables` - the variables over which a condition density is learned (i.e., the observables)
-            `conditions`  - the conditioning variables that the directly passed to the inference network
+        if ``DEFAULT_KEYS`` unchanged:
+            ``observables`` - the variables over which a condition density is learned (i.e., the observables)
+            ``conditions``  - the conditioning variables that the directly passed to the inference network
+
         Returns
         -------
-        out :
-            The output as returned by `grad_postprocessor`. For the default postprocessor,
-            this is an array containing the derivative with respect to each value in `conditions`
-            as returned by `configurator`.
+        out : np.ndarray
+            The output as returned by ``grad_postprocessor``. For the default postprocessor,
+            this is an array containing the derivative with respect to each value in ``conditions``
+            as returned by ``configurator``.
         """
 
         input_dict = self.configurator(*args, **kwargs)
@@ -130,14 +132,14 @@ def log_likelihood_grad(self, *args, **kwargs):
 
     @tf.function
     def _log_likelihood_grad(self, input_dict, **kwargs):
-        """Calculates the gradient with respect to every parameter contained in `input_dict`.
+        """Calculates the gradient with respect to every parameter contained in ``input_dict``.
 
         Parameters
         ----------
         input_dict : dict
             Input dictionary containing the following mandatory keys, if DEFAULT_KEYS unchanged:
-                `observables` - tf.constant: the variables over which a condition density is learned (i.e., the observables)
-                `conditions`  - tf.Variable: the conditioning variables that the directly passed to the inference network
+                ``observables`` - tf.constant: the variables over which a condition density is learned (i.e., the observables)
+                ``conditions``  - tf.Variable: the conditioning variables that the directly passed to the inference network
 
         Returns
         -------
@@ -155,7 +157,7 @@ class _LogLikGrad(at.Op):
     """Custom log-likelihood operator, based on:
     https://www.pymc.io/projects/examples/en/latest/case_studies/blackbox_external_likelihood_numpy.html#aesara-op-with-grad
 
-    This Op will execute the `log_lik_grad` function, supplying the gradient
+    This Op will execute the ``log_lik_grad`` function, supplying the gradient
     for the custom surrogate likelihood function.
     """
 
@@ -169,7 +171,7 @@ def __init__(self, log_lik_grad, observables, default_type=np.float64):
         ----------
         log_lik_grad  : callable
             The object that provides the gradient of the log-likelihood.
-        observables   : tf.constant, the shape depends on `log_lik_grad`.
+        observables   : tf.constant, the shape depends on ``log_lik_grad``.
             The variables over which a condition density is learned (i.e., the observables).
         default_type  : np.dtype, optional, default: np.float64
             The default float type to use for the gradient vectors.
@@ -180,15 +182,15 @@ def __init__(self, log_lik_grad, observables, default_type=np.float64):
         self.default_type = default_type
 
     def perform(self, node, inputs, outputs):
-        """Computes gradients with respect to `inputs` (corresponding to the parameters of a model).
+        """Computes gradients with respect to ``inputs`` (corresponding to the parameters of a model).
 
         Parameters
         ----------
-        node      : The symbolic `aesara.graph.basic.Apply` node that represents this computation.
+        node      : The symbolic ``aesara.graph.basic.Apply`` node that represents this computation.
         inputs    : Immutable sequence of non-symbolic/numeric inputs. These are the values of each
-                    `Variable` in `node.inputs`.
+                    ``Variable`` in ``node.inputs``.
         outputs   : List of mutable single-element lists (do not change the length of these lists).
-                    Each sub-list corresponds to value of each `Variable` in `node.outputs`.
+                    Each sub-list corresponds to value of each ``Variable`` in ``node.outputs``.
                     The primary purpose of this method is to set the values of these sub-lists.
         """
 
@@ -208,28 +210,28 @@ class PyMCSurrogateLikelihood(at.Op, MCMCSurrogateLikelihood):
 
     def __init__(self, amortized_likelihood, observables, configurator=None, likelihood_postprocessor=None,
                  grad_postprocessor=None, default_pymc_type=np.float64, default_tf_type=np.float32):
-        """A custom surrogate likelihood function for integration with `PyMC3`, to be used with pymc.Potential
+        """A custom surrogate likelihood function for integration with ``PyMC3``, to be used with pymc.Potential
 
         Parameters
         ----------
         amortized_likelihood      : bayesflow.amortized_inference.AmortizedLikelihood
             A pre-trained (invertible) inference network which processes the outputs of the generative model.
         observables               :
             The "observed" data that will be passed to the configurator.
-            For the default `configurator`, an np.array of shape (N, x_dim).
+            For the default ``configurator``, an np.array of shape (N, x_dim).
         configurator              : callable, optional, default None
             A function that takes the input to the log_likelihood and log_likelihood_grad
             calls and converts it to a dictionary containing the following mandatory keys,
             if DEFAULT_KEYS unchanged:
-                `observables` - the variables over which a condition density is learned (i.e., the observables)
-                `conditions`  - the conditioning variables that the directly passed to the inference network
-            default behavior: convert `observables` to shape (1, N, x_dim),
+                ``observables`` - the variables over which a condition density is learned (i.e., the observables)
+                ``conditions``  - the conditioning variables that the directly passed to the inference network
+            default behavior: convert ``observables`` to shape (1, N, x_dim),
                 expand parameters of shape (cond_dim) to shape (1, N, cond_dim)
         likelihood_postprocessor  : callable, optional, default: None
             A function that takes the likelihood for each observable, can be used for aggregation
             default behavior: sum all likelihoods and return a single value
         grad_postprocessor        : callable, optional, default: None
-            A function that takes the gradient for each value in `conditions` as returned by the preprocessor
+            A function that takes the gradient for each value in ``conditions`` as returned by the preprocessor
             default behavior: Reduce shape from (1, N, cond_dim) to (cond_dim) by summing the corresponding values
         default_pymc_type         : np.dtype, optional, default: np.float64
             The default float type to use for numpy arrays as required by PyMC.
@@ -265,15 +267,15 @@ def _default_grad_postprocessor(self, grads):
         return tf.reduce_sum(grads[0], axis=0)
 
     def perform(self, node, inputs, outputs):
-        """Computes the log-likelihood of `inputs` (typically the parameter vector of a model).
+        """Computes the log-likelihood of ``inputs`` (typically the parameter vector of a model).
         
         Parameters
         ----------
-        node      : The symbolic `aesara.graph.basic.Apply` node that represents this computation.
+        node      : The symbolic ``aesara.graph.basic.Apply`` node that represents this computation.
         inputs    : Immutable sequence of non-symbolic/numeric inputs. These are the values of each
-                    `Variable` in `node.inputs`.
+                    ``Variable`` in ``node.inputs``.
         outputs   : List of mutable single-element lists (do not change the length of these lists).
-                    Each sub-list corresponds to value of each `Variable` in `node.outputs`.
+                    Each sub-list corresponds to value of each ``Variable`` in ``node.outputs``.
                     The primary purpose of this method is to set the values of these sub-lists.
         """
 
@@ -282,7 +284,7 @@ def perform(self, node, inputs, outputs):
         outputs[0][0] = np.array(logl, dtype=self.default_pymc_type)
 
     def grad(self, inputs, output_grads):
-        """Aggregates gradients with respect to `inputs` (typically the parameter vector)
+        """Aggregates gradients with respect to ``inputs`` (typically the parameter vector)
         
         Parameters
         ----------
@@ -291,7 +293,7 @@ def grad(self, inputs, output_grads):
 
         Returns
         -------
-        grads         : The gradients with respect to each `Variable` in `inputs`.
+        grads         : The gradients with respect to each ``Variable`` in ``inputs``.
         """
 
         # the method that calculates the gradients - it actually returns the