small edits in documentation and messages (#4921)

Author: stestoll

pymc3/sampling.py

@@ -381,7 +381,8 @@ def sample(
           work better for problematic posteriors
         * max_treedepth : The maximum depth of the trajectory tree
         * step_scale : float, default 0.25
-          The initial guess for the step size scaled down by :math:`1/n**(1/4)`
+          The initial guess for the step size scaled down by :math:`1/n**(1/4)`,
+          where n is the dimensionality of the parameter space
 
     If your model uses multiple step methods, aka a Compound Step, then you have
     two ways to address arguments to each step method:

pymc3/step_methods/arraystep.py

@@ -33,7 +33,7 @@
 
 @unique
 class Competence(IntEnum):
-    """Enum for charaterizing competence classes of step methods.
+    """Enum for characterizing competence classes of step methods.
     Values include:
     0: INCOMPATIBLE
     1: COMPATIBLE

pymc3/step_methods/hmc/base_hmc.py

@@ -66,12 +66,15 @@ def __init__(
 
         Parameters
         ----------
-        vars: list of Aesara variables
-        scaling: array_like, ndim = {1,2}
+        vars: list, default=None
+            List of Aesara variables. If None, all continuous RVs from the
+            model are included.
+        scaling: array_like, ndim={1,2}
             Scaling for momentum distribution. 1d arrays interpreted matrix
             diagonal.
         step_scale: float, default=0.25
-            Size of steps to take, automatically scaled down by 1/n**(1/4)
+            Size of steps to take, automatically scaled down by 1/n**(1/4),
+            where n is the dimensionality of the parameter space
         is_cov: bool, default=False
             Treat scaling as a covariance matrix/vector if True, else treat
             it as a precision matrix/vector
@@ -134,9 +137,9 @@ def __init__(
 
     @abstractmethod
     def _hamiltonian_step(self, start, p0, step_size):
-        """Compute one hamiltonian trajectory and return the next state.
+        """Compute one Hamiltonian trajectory and return the next state.
 
-        Subclasses must overwrite this method and return a `HMCStepData`.
+        Subclasses must overwrite this abstract method and return an `HMCStepData` object.
         """
 
     def astep(self, q0):

pymc3/step_methods/hmc/hmc.py

@@ -59,15 +59,19 @@ def __init__(self, vars=None, path_length=2.0, max_steps=1024, **kwargs):
 
         Parameters
         ----------
-        vars: list of Aesara variables
+        vars: list, default=None
+            List of Aesara variables. If None, all continuous RVs from the
+            model are included.
         path_length: float, default=2
-            total length to travel
+            Total length to travel
         step_rand: function float -> float, default=unif
-            A function which takes the step size and returns an new one used to
-            randomize the step size at each iteration.
+            A function which takes the step size and returns a new one used to
+            randomize the step size at each iteration. The default draws a random
+            new step size from a uniform distribution with +-15% of the given one.
+            If set to None, no randomization is done.
         step_scale: float, default=0.25
-            Initial size of steps to take, automatically scaled down
-            by 1/n**(1/4).
+            Initial size of steps to take, automatically scaled down by 1/n**(1/4)
+            where n is the dimensionality of the parameter space
         scaling: array_like, ndim = {1,2}
             The inverse mass, or precision matrix. One dimensional arrays are
             interpreted as diagonal matrices. If `is_cov` is set to True,
@@ -133,7 +137,10 @@ def _hamiltonian_step(self, start, p0, step_size):
                 energy_change = -np.inf
             if np.abs(energy_change) > self.Emax:
                 div_info = DivergenceInfo(
-                    "Divergence encountered, large integration error.", None, last, state
+                    f"Divergence encountered, energy change larger than {self.Emax}.",
+                    None,
+                    last,
+                    state,
                 )
 
         accept_stat = min(1, np.exp(energy_change))

pymc3/step_methods/hmc/nuts.py

@@ -114,7 +114,9 @@ def __init__(self, vars=None, max_treedepth=10, early_max_treedepth=8, **kwargs)
 
         Parameters
         ----------
-        vars: list of Aesara variables, default all continuous vars
+        vars: list, default=None
+            List of Aesara variables. If None, all continuous RVs from the
+            model are included.
         Emax: float, default 1000
             Maximum energy change allowed during leapfrog steps. Larger
             deviations will abort the integration.
@@ -357,7 +359,7 @@ def _single_step(self, left, epsilon):
                 )
                 return tree, None, False
             else:
-                error_msg = "Energy change in leapfrog step is too large: %s." % energy_change
+                error_msg = f"Energy change in leapfrog step is too large: {energy_change}."
                 error = None
         tree = Subtree(None, None, None, None, -np.inf, -np.inf, 1)
         divergance_info = DivergenceInfo(error_msg, error, left, right)