Deprecation of testval→initval and related start kwarg

Author: michaelosthege

RELEASE-NOTES.md

@@ -3,6 +3,8 @@
 ## PyMC 3.11.5 (TBD)
 ### Backports
 + The `pm.logp(rv, x)` syntax is now available and recommended to make your model code `v4`-ready. Note that this backport is just an alias and much less capable than what's available with `pymc >=4` (see [#5083](https://github.com/pymc-devs/pymc/pulls/5083)).
++ The `pm.Distribution(testval=...)` kwarg was deprecated and will be replaced by `pm.Distribution(initval=...)`in `pymc >=4` (see [#5226](https://github.com/pymc-devs/pymc/pulls/5226)).
++ The `pm.sample(start=...)` kwarg was deprecated and will be replaced by `pm.sample(initvals=...)`in `pymc >=4` (see [#5226](https://github.com/pymc-devs/pymc/pulls/5226)).
 
 ## PyMC3 3.11.4 (20 August 2021)
 

pymc3/distributions/distribution.py

@@ -24,6 +24,8 @@
 
 import dill
 
+from deprecat.sphinx import deprecat
+
 if TYPE_CHECKING:
     from typing import Optional, Callable
 
@@ -67,6 +69,7 @@
 )  # type: contextvars.ContextVar[Optional[Callable]]
 
 PLATFORM = sys.platform
+UNSET = object()
 
 
 class _Unpickling:
@@ -130,15 +133,54 @@ def dist(cls, *args, **kwargs):
         dist.__init__(*args, **kwargs)
         return dist
 
+    @deprecat(
+        deprecated_args={
+            "testval": dict(version="3.11.5", reason="replaced by `initval` in PyMC 4.0.0"),
+        }
+    )
     def __init__(
-        self, shape, dtype, testval=None, defaults=(), transform=None, broadcastable=None, dims=None
+        self,
+        shape,
+        dtype,
+        initval=None,
+        defaults=(),
+        transform=None,
+        broadcastable=None,
+        dims=None,
+        *,
+        testval=UNSET,
     ):
+        """Creates a PyMC distribution object.
+
+        Parameters
+        ----------
+        shape : tuple
+            Output shape of the RV.
+            Forwarded to the Theano TensorType of this RV.
+        dtype
+            Forwarded to the Theano TensorType of this RV.
+        initval : np.ndarray
+            Initial value for this RV.
+            In PyMC 4.0.0 this will no longer assign test values to the tensors.
+        defaults : tuple
+        transform : pm.Transform
+        broadcastable : tuple
+            Forwarded to the Theano TensorType of this RV.
+        dims : tuple
+            Ignored.
+        testval : np.ndarray
+            The old way of specifying initial values assigning test-values.
+        """
+        # Handle deprecated kwargs
+        if testval is not UNSET:
+            initval = testval
+
         self.shape = np.atleast_1d(shape)
         if False in (np.floor(self.shape) == self.shape):
             raise TypeError("Expected int elements in shape")
         self.dtype = dtype
         self.type = TensorType(self.dtype, self.shape, broadcastable)
-        self.testval = testval
+        self.testval = initval
         self.defaults = defaults
         self.transform = transform
 
@@ -288,7 +330,7 @@ def __init__(
         **kwargs,
     ):
         super().__init__(
-            shape=shape, dtype=dtype, testval=testval, defaults=defaults, *args, **kwargs
+            shape=shape, dtype=dtype, initval=testval, defaults=defaults, *args, **kwargs
         )
         self.parent_dist = parent_dist
 
@@ -353,16 +395,22 @@ class DensityDist(Distribution):
 
     """
 
+    @deprecat(
+        deprecated_args={
+            "testval": dict(version="3.11.5", reason="replaced by `initval` in PyMC 4.0.0"),
+        }
+    )
     def __init__(
         self,
         logp,
         shape=(),
         dtype=None,
-        testval=0,
+        initval=0,
         random=None,
         wrap_random_with_dist_shape=True,
         check_shape_in_random=True,
         *args,
+        testval=UNSET,
         **kwargs,
     ):
         """
@@ -379,8 +427,8 @@ def __init__(
             a value here.
         dtype: None, str (Optional)
             The dtype of the distribution.
-        testval: number or array (Optional)
-            The ``testval`` of the RV's tensor that follow the ``DensityDist``
+        initval: number or array (Optional)
+            The ``initval`` of the RV's tensor that follow the ``DensityDist``
             distribution.
         random: None or callable (Optional)
             If ``None``, no random method is attached to the ``DensityDist``
@@ -403,6 +451,8 @@ def __init__(
             If ``True``, the shape of the random samples generate in the
             ``random`` method is checked with the expected return shape. This
             test is only performed if ``wrap_random_with_dist_shape is False``.
+        testval : np.ndarray
+            The old way of specifying initial values assigning test-values.
         args, kwargs: (Optional)
             These are passed to the parent class' ``__init__``.
 
@@ -525,9 +575,13 @@ def __init__(
                 assert prior.shape == (10, 100, 3)
 
         """
+        # Handle deprecated kwargs
+        if testval is not UNSET:
+            initval = testval
+
         if dtype is None:
             dtype = theano.config.floatX
-        super().__init__(shape, dtype, testval, *args, **kwargs)
+        super().__init__(shape, dtype, initval, *args, **kwargs)
         self.logp = logp
         if type(self.logp) == types.MethodType:
             if PLATFORM != "linux":

pymc3/sampling.py

@@ -23,7 +23,7 @@
 
 from collections import defaultdict
 from copy import copy, deepcopy
-from typing import Any, Dict, Iterable, List, Optional, Set, Union, cast
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Set, Union, cast
 
 import arviz
 import numpy as np
@@ -32,6 +32,7 @@
 import xarray
 
 from arviz import InferenceData
+from deprecat.sphinx import deprecat
 from fastprogress.fastprogress import progress_bar
 
 import pymc3 as pm
@@ -232,12 +233,18 @@ def _print_step_hierarchy(s: Step, level=0) -> None:
         _log.info(">" * level + f"{s.__class__.__name__}: [{varnames}]")
 
 
+@deprecat(
+    deprecated_args={
+        "start": dict(version="3.11.5", reason="renamed to `initvals` in PyMC v4.0.0"),
+        "pickle_backend": dict(version="3.11.5", reason="removed in PyMC v4.0.0"),
+    }
+)
 def sample(
     draws=1000,
     step=None,
     init="auto",
     n_init=200000,
-    start=None,
+    initvals: Optional[Union[PointType, Sequence[Optional[PointType]]]] = None,
     trace=None,
     chain_idx=0,
     chains=None,
@@ -251,6 +258,7 @@ def sample(
     callback=None,
     jitter_max_retries=10,
     *,
+    start=None,
     return_inferencedata=None,
     idata_kwargs: dict = None,
     mp_ctx=None,
@@ -294,11 +302,10 @@ def sample(
         users.
     n_init : int
         Number of iterations of initializer. Only works for 'ADVI' init methods.
-    start : dict, or array of dict
-        Starting point in parameter space (or partial point)
-        Defaults to ``trace.point(-1))`` if there is a trace provided and model.test_point if not
-        (defaults to empty dict). Initialization methods for NUTS (see ``init`` keyword) can
-        overwrite the default.
+    initvals : optional, dict, array of dict
+        Dict or list of dicts with initial values to use instead of the defaults.
+        The keys should be names of transformed random variables.
+        Initialization methods for NUTS (see ``init`` keyword) can overwrite the default.
     trace : backend, list, or MultiTrace
         This should be a backend instance, a list of variables to track, or a MultiTrace object
         with past values. If a MultiTrace object is given, it must contain samples for the chain
@@ -339,6 +346,11 @@ def sample(
         Maximum number of repeated attempts (per chain) at creating an initial matrix with uniform jitter
         that yields a finite probability. This applies to ``jitter+adapt_diag`` and ``jitter+adapt_full``
         init methods.
+    start : dict, or array of dict
+        Starting point in parameter space (or partial point)
+        Defaults to ``trace.point(-1))`` if there is a trace provided and model.test_point if not
+        (defaults to empty dict). Initialization methods for NUTS (see ``init`` keyword) can
+        overwrite the default.
     return_inferencedata : bool, default=False
         Whether to return the trace as an :class:`arviz:arviz.InferenceData` (True) object or a `MultiTrace` (False)
         Defaults to `False`, but we'll switch to `True` in an upcoming release.
@@ -422,6 +434,10 @@ def sample(
             mean     sd  hdi_3%  hdi_97%
         p  0.609  0.047   0.528    0.699
     """
+    # Handle deprecated/forwards-compatible kwargs
+    if initvals is not None:
+        start = initvals
+
     model = modelcontext(model)
     start = deepcopy(start)
     if start is None: