Remove initval from dist API and add dedicated test suite

Closes #4893

Author: michaelosthege

.github/workflows/pytest.yml

@@ -30,6 +30,7 @@ jobs:
         # → pytest will run only these files
           - |
             --ignore=pymc3/tests/test_distributions_timeseries.py
+            --ignore=pymc3/tests/test_initvals.py
             --ignore=pymc3/tests/test_mixture.py
             --ignore=pymc3/tests/test_model_graph.py
             --ignore=pymc3/tests/test_modelcontext.py
@@ -60,7 +61,9 @@ jobs:
             --ignore=pymc3/tests/test_distributions_random.py
             --ignore=pymc3/tests/test_idata_conversion.py
 
-          - pymc3/tests/test_distributions.py
+          - |
+            pymc3/tests/test_initvals.py
+            pymc3/tests/test_distributions.py
 
           - |
             pymc3/tests/test_modelcontext.py
@@ -153,6 +156,7 @@ jobs:
         floatx: [float32, float64]
         test-subset:
           - |
+            pymc3/tests/test_initvals.py
             pymc3/tests/test_distributions_random.py
             pymc3/tests/test_distributions_timeseries.py
           - |

pymc3/distributions/continuous.py

@@ -361,11 +361,9 @@ class Flat(Continuous):
     rv_op = flat
 
     @classmethod
-    def dist(cls, *, size=None, initval=None, **kwargs):
-        if initval is None:
-            initval = np.full(size, floatX(0.0))
+    def dist(cls, *, size=None, **kwargs):
         res = super().dist([], size=size, **kwargs)
-        res.tag.test_value = initval
+        res.tag.test_value = np.full(size, floatX(0.0))
         return res
 
     def logp(value):
@@ -425,11 +423,9 @@ class HalfFlat(PositiveContinuous):
     rv_op = halfflat
 
     @classmethod
-    def dist(cls, *, size=None, initval=None, **kwargs):
-        if initval is None:
-            initval = np.full(size, floatX(1.0))
+    def dist(cls, *, size=None, **kwargs):
         res = super().dist([], size=size, **kwargs)
-        res.tag.test_value = initval
+        res.tag.test_value = np.full(size, floatX(1.0))
         return res
 
     def logp(value):

pymc3/distributions/distribution.py

@@ -202,9 +202,9 @@ def __new__(
             )
         dims = convert_dims(dims)
 
-        # Create the RV without specifying initval, because the initval may have a shape
-        # that only matches after replicating with a size implied by dims (see below).
-        rv_out = cls.dist(*args, rng=rng, initval=None, **kwargs)
+        # Create the RV without dims information, because that's not something tracked at the Aesara level.
+        # If necessary we'll later replicate to a different size implied by already known dims.
+        rv_out = cls.dist(*args, rng=rng, **kwargs)
         ndim_actual = rv_out.ndim
         resize_shape = None
 
@@ -242,7 +242,6 @@ def dist(
         *,
         shape: Optional[Shape] = None,
         size: Optional[Size] = None,
-        initval=None,
         **kwargs,
     ) -> RandomVariable:
         """Creates a RandomVariable corresponding to the `cls` distribution.
@@ -258,25 +257,27 @@ def dist(
             all the dimensions that the RV would get if no shape/size/dims were passed at all.
         size : int, tuple, Variable, optional
             For creating the RV like in Aesara/NumPy.
-        initival : optional
-            Test value to be attached to the output RV.
-            Must match its shape exactly.
 
         Returns
         -------
         rv : RandomVariable
             The created RV.
         """
         if "testval" in kwargs:
-            initval = kwargs.pop("testval")
+            kwargs.pop("testval")
             warnings.warn(
-                "The `testval` argument is deprecated. "
-                "Use `initval` to set initial values for a `Model`; "
-                "otherwise, set test values on Aesara parameters explicitly "
-                "when attempting to use Aesara's test value debugging features.",
+                "The `.dist(testval=...)` argument is deprecated and has no effect. "
+                "Initial values for sampling/optimization can be specified with `initval` in a modelcontext. "
+                "For using Aesara's test value features, you must assign the `.tag.test_value` yourself.",
                 DeprecationWarning,
                 stacklevel=2,
             )
+        if "initval" in kwargs:
+            raise TypeError(
+                "Unexpected keyword argument `initval`. "
+                "This argument is not available for the `.dist()` API."
+            )
+
         if "dims" in kwargs:
             raise NotImplementedError("The use of a `.dist(dims=...)` API is not supported.")
         if shape is not None and size is not None:

pymc3/tests/test_initvals.py

@@ -0,0 +1,48 @@
+#   Copyright 2020 The PyMC Developers
+#
+#   Licensed under the Apache License, Version 2.0 (the "License");
+#   you may not use this file except in compliance with the License.
+#   You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+#   Unless required by applicable law or agreed to in writing, software
+#   distributed under the License is distributed on an "AS IS" BASIS,
+#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#   See the License for the specific language governing permissions and
+#   limitations under the License.
+import pytest
+
+import pymc3 as pm
+
+
+def transform_fwd(rv, expected_untransformed):
+    return rv.tag.value_var.tag.transform.forward(rv, expected_untransformed).eval()
+
+
+class TestInitvalAssignment:
+    def test_dist_warnings_and_errors(self):
+        with pytest.warns(DeprecationWarning, match="argument is deprecated and has no effect"):
+            rv = pm.Exponential.dist(lam=1, testval=0.5)
+        assert not hasattr(rv.tag, "test_value")
+
+        with pytest.raises(TypeError, match="Unexpected keyword argument `initval`."):
+            pm.Normal.dist(1, 2, initval=None)
+        pass
+
+    def test_new_warnings(self):
+        with pm.Model() as pmodel:
+            with pytest.warns(DeprecationWarning, match="`testval` argument is deprecated"):
+                rv = pm.Uniform("u", 0, 1, testval=0.75)
+                assert pmodel.initial_values[rv.tag.value_var] == transform_fwd(rv, 0.75)
+        pass
+
+
+class TestSpecialDistributions:
+    def test_automatically_assigned_test_values(self):
+        # ...because they don't have random number generators.
+        rv = pm.Flat.dist()
+        assert hasattr(rv.tag, "test_value")
+        rv = pm.HalfFlat.dist()
+        assert hasattr(rv.tag, "test_value")
+        pass