fix docstrings for censored and timeseries (#6638)

Author: alporter08

docs/source/conf.py

@@ -76,6 +76,7 @@
     "SMC_kernel": ":ref:`SMC Kernel <smc_kernels>`",
     "PyTensor_Op": ":class:`PyTensor Op <pytensor.graph.op.Op>`",
     "tensor_like": ":term:`tensor_like`",
+    "unnamed_distribution": ":term:`unnamed_distribution`",
     "numpy_Generator": ":class:`~numpy.random.Generator`",
     "Distribution": ":ref:`Distribution <api_distributions>`",
 }

docs/source/glossary.md

@@ -132,5 +132,26 @@ tensor_like
 
   pt.as_tensor_variable([[1, 2.0], [0, 0]])
   ```
+unnamed_distribution
+    PyMC distributions can be initialized directly (e.g. `pm.Normal`) or using the `.dist` classmethod (e.g. `pm.Normal.dist`). Distributions initialized with the 1st method are registered as model parameters and thus, need to be given a name and be initialized within a model context. "unnamed_distributions" are distributions initialized with the 2nd method. These are standalone distributions, they are not parameters in any model and can be used to draw samples from a distribution by itself or as parameters to other distributions like mixtures or censored.
+
+    "unnamed_distributions" can be used outside the model context. For example:
+
+    ```{jupyter-execute}
+    import pymc as pm
+
+    unnamed_dist = pm.Normal.dist(mu=1, sigma=2)
+    pm.draw(unnamed_dist, draws=10)
+    ```
+
+    Trying to initialize a named distribution outside a model context raises a `TypeError`:
+
+    ```{jupyter-execute}
+    :raises: TypeError
+
+    import pymc as pm
+
+    pm.Normal("variable")
+    ```
 
 :::::

pymc/distributions/censored.py

@@ -52,15 +52,15 @@ class Censored(Distribution):
 
     Parameters
     ----------
-    dist: unnamed distribution
-        Univariate distribution created via the `.dist()` API, which will be censored.
+    dist : unnamed_distribution
+        Univariate distribution which will be censored.
         This distribution must have a logcdf method implemented for sampling.
 
         .. warning:: dist will be cloned, rendering it independent of the one passed as input.
 
-    lower: float or None
+    lower : float or None
         Lower (left) censoring point. If `None` the distribution will not be left censored
-    upper: float or None
+    upper : float or None
         Upper (right) censoring point. If `None`, the distribution will not be right censored.
 
     Warnings

pymc/distributions/timeseries.py

@@ -277,7 +277,7 @@ class GaussianRandomWalk(PredefinedRandomWalk):
         innovation drift
     sigma : tensor_like of float, default 1
         sigma > 0, innovation standard deviation.
-    init_dist : Distribution
+    init_dist : unnamed_distribution
         Unnamed univariate distribution of the initial value. Unnamed refers to distributions
         created with the ``.dist()`` API.
 
@@ -317,19 +317,18 @@ class MvGaussianRandomWalk(PredefinedRandomWalk):
 
     Parameters
     ----------
-    mu: tensor_like of float
+    mu : tensor_like of float
         innovation drift
-    cov: tensor_like of float
+    cov : tensor_like of float
         pos def matrix, innovation covariance matrix
-    tau: tensor_like of float
+    tau : tensor_like of float
         pos def matrix, inverse covariance matrix
-    chol: tensor_like of float
+    chol : tensor_like of float
         Cholesky decomposition of covariance matrix
     lower : bool, default=True
         Whether the cholesky fatcor is given as a lower triangular matrix.
-    init_dist: distribution
-        Unnamed multivariate distribution of the initial value. Unnamed refers to distributions
-         created with the ``.dist()`` API.
+    init_dist : unnamed_distribution
+        Unnamed multivariate distribution of the initial value.
 
          .. warning:: init_dist will be cloned, rendering them independent of the ones passed as input.
 
@@ -370,21 +369,20 @@ class MvStudentTRandomWalk(PredefinedRandomWalk):
 
     Parameters
     ----------
-    nu: int
+    nu : int
         degrees of freedom
-    mu: tensor_like of float
+    mu : tensor_like of float
         innovation drift
-    scale: tensor_like of float
+    scale : tensor_like of float
         pos def matrix, innovation covariance matrix
-    tau: tensor_like of float
+    tau : tensor_like of float
         pos def matrix, inverse covariance matrix
-    chol: tensor_like of float
+    chol : tensor_like of float
         Cholesky decomposition of covariance matrix
     lower : bool, default=True
         Whether the cholesky fatcor is given as a lower triangular matrix.
-    init_dist: distribution
-        Unnamed multivariate distribution of the initial value. Unnamed refers to distributions
-         created with the ``.dist()`` API.
+    init_dist : unnamed_distribution
+        Unnamed multivariate distribution of the initial value.
 
          .. warning:: init_dist will be cloned, rendering them independent of the ones passed as input.
 
@@ -471,9 +469,8 @@ class AR(Distribution):
     constant : bool, default False
         Whether the first element of rho should be used as a constant term in the AR
         process.
-    init_dist : unnamed distribution, optional
-        Scalar or vector distribution for initial values. Unnamed refers to distributions
-        created with the ``.dist()`` API. Distributions should have shape (*shape[:-1], ar_order).
+    init_dist : unnamed_distribution, optional
+        Scalar or vector distribution for initial values. Distributions should have shape (*shape[:-1], ar_order).
         If not, it will be automatically resized. Defaults to pm.Normal.dist(0, 100, shape=...).
 
         .. warning:: init_dist will be cloned, rendering it independent of the one passed as input.
@@ -755,13 +752,13 @@ class GARCH11(Distribution):
 
     Parameters
     ----------
-    omega: tensor
+    omega : tensor_like of float
         omega > 0, mean variance
-    alpha_1: tensor
+    alpha_1 : tensor_like of float
         alpha_1 >= 0, autoregressive term coefficient
-    beta_1: tensor
+    beta_1 : tensor_like of float
         beta_1 >= 0, alpha_1 + beta_1 < 1, moving average term coefficient
-    initial_vol: tensor
+    initial_vol : tensor_like of float
         initial_vol >= 0, initial volatility, sigma_0
     """
 
@@ -922,9 +919,8 @@ class EulerMaruyama(Distribution):
         function returning the drift and diffusion coefficients of SDE
     sde_pars : tuple
         parameters of the SDE, passed as ``*args`` to ``sde_fn``
-    init_dist : unnamed distribution, optional
-        Scalar distribution for initial values. Unnamed refers to distributions created with
-        the ``.dist()`` API. Distributions should have shape (*shape[:-1]).
+    init_dist : unnamed_distribution, optional
+        Scalar distribution for initial values. Distributions should have shape (*shape[:-1]).
         If not, it will be automatically resized. Defaults to pm.Normal.dist(0, 100, shape=...).
 
         .. warning:: init_dist will be cloned, rendering it independent of the one passed as input.