API backports and deprecation warnings (#5389)

* Backwards-compatible rename `Lognormal`→`LogNormal`

* Warn about removal of trace-continuation support

* Fixup lognormal rename

* More fixup

* Fix docstring section underlines

* Temporarily pin upper numpydoc version

Tracking issue #5401

* Temporarily pin upper numpydoc version

Tracking issue #5401

Author: michaelosthege

RELEASE-NOTES.md

@@ -5,6 +5,7 @@
 + 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)).
++ `pm.Lognormal` is now available as an alias for `pm.Lognormal` (see [#5389](https://github.com/pymc-devs/pymc/pull/5389)).
 
 ### Bugfixes
 + A hotfix is applied on import to remain compatible with NumPy 1.22 (see [#5316](https://github.com/pymc-devs/pymc/pull/5316)).

conda-envs/environment-dev-py37.yml

@@ -9,7 +9,7 @@ dependencies:
 - mkl-service
 - nbsphinx>=0.4
 - numpy=1.15
-- numpydoc>=0.9
+- numpydoc<1.2
 - pandas=0.24
 - pip
 - pre-commit>=2.8.0

conda-envs/environment-dev-py38.yml

@@ -8,7 +8,7 @@ dependencies:
 - libblas=*=*mkl
 - mkl-service
 - nbsphinx>=0.4
-- numpydoc>=0.9
+- numpydoc<1.2
 - pip
 - pre-commit>=2.8.0
 - pytest-cov>=2.5

conda-envs/environment-dev-py39.yml

@@ -8,7 +8,7 @@ dependencies:
 - libblas=*=*mkl
 - mkl-service
 - nbsphinx>=0.4
-- numpydoc>=0.9
+- numpydoc<1.2
 - pip
 - pre-commit>=2.8.0
 - pytest-cov>=2.5

conda-envs/windows-environment-dev-py38.yml

@@ -16,7 +16,7 @@ dependencies:
 # Extra stuff for dev, testing and docs build
 - ipython>=7.16
 - nbsphinx>=0.4
-- numpydoc>=0.9
+- numpydoc<1.2
 - pre-commit>=2.8.0
 - pytest-cov>=2.5
 - pytest>=3.0

pymc3/distributions/__init__.py

@@ -36,6 +36,7 @@
     Logistic,
     LogitNormal,
     Lognormal,
+    LogNormal,
     Moyal,
     Normal,
     Pareto,
@@ -120,6 +121,7 @@
     "Weibull",
     "Bound",
     "Lognormal",
+    "LogNormal",
     "HalfStudentT",
     "ChiSquared",
     "HalfNormal",

pymc3/distributions/continuous.py

@@ -62,7 +62,7 @@
     "Gamma",
     "Weibull",
     "HalfStudentT",
-    "Lognormal",
+    "LogNormal",
     "ChiSquared",
     "HalfNormal",
     "Wald",
@@ -318,7 +318,7 @@ def random(self, point=None, size=None):
         size: int, optional
 
         Raises
-        -------
+        ------
         ValueError
         """
         raise ValueError("Cannot sample from Flat distribution")
@@ -375,7 +375,7 @@ def random(self, point=None, size=None):
         size: int, optional
 
         Raises
-        -------
+        ------
         ValueError
         """
         raise ValueError("Cannot sample from HalfFlat distribution")
@@ -1710,7 +1710,7 @@ class AsymmetricLaplace(Continuous):
         Location parameter
 
     See Also:
-    --------
+    ---------
     `Reference <https://en.wikipedia.org/wiki/Asymmetric_Laplace_distribution>`_
     """
 
@@ -1778,7 +1778,7 @@ def logp(self, value):
         )
 
 
-class Lognormal(PositiveContinuous):
+class LogNormal(PositiveContinuous):
     r"""
     Log-normal log-likelihood.
 
@@ -1834,10 +1834,10 @@ class Lognormal(PositiveContinuous):
 
         # Example to show that we pass in only ``sigma`` or ``tau`` but not both.
         with pm.Model():
-            x = pm.Lognormal('x', mu=2, sigma=30)
+            x = pm.LogNormal('x', mu=2, sigma=30)
 
         with pm.Model():
-            x = pm.Lognormal('x', mu=2, tau=1/100)
+            x = pm.LogNormal('x', mu=2, tau=1/100)
     """
 
     def __init__(self, mu=0, sigma=None, tau=None, sd=None, *args, **kwargs):
@@ -1856,16 +1856,16 @@ def __init__(self, mu=0, sigma=None, tau=None, sd=None, *args, **kwargs):
         self.mode = tt.exp(self.mu - 1.0 / self.tau)
         self.variance = (tt.exp(1.0 / self.tau) - 1) * tt.exp(2 * self.mu + 1.0 / self.tau)
 
-        assert_negative_support(tau, "tau", "Lognormal")
-        assert_negative_support(sigma, "sigma", "Lognormal")
+        assert_negative_support(tau, "tau", "LogNormal")
+        assert_negative_support(sigma, "sigma", "LogNormal")
 
     def _random(self, mu, tau, size=None):
         samples = np.random.normal(size=size)
         return np.exp(mu + (tau ** -0.5) * samples)
 
     def random(self, point=None, size=None):
         """
-        Draw random values from Lognormal distribution.
+        Draw random values from LogNormal distribution.
 
         Parameters
         ----------
@@ -1885,7 +1885,7 @@ def random(self, point=None, size=None):
 
     def logp(self, value):
         """
-        Calculate log-probability of Lognormal distribution at specified value.
+        Calculate log-probability of LogNormal distribution at specified value.
 
         Parameters
         ----------
@@ -1911,7 +1911,7 @@ def _distr_parameters_for_repr(self):
 
     def logcdf(self, value):
         """
-        Compute the log of the cumulative distribution function for Lognormal distribution
+        Compute the log of the cumulative distribution function for LogNormal distribution
         at the specified value.
 
         Parameters
@@ -1935,6 +1935,9 @@ def logcdf(self, value):
         )
 
 
+Lognormal = LogNormal
+
+
 class StudentT(Continuous):
     r"""
     Student's T log-likelihood.

pymc3/distributions/timeseries.py

@@ -484,7 +484,7 @@ def random(self, point=None, size=None):
 
 
         Examples
-        -------
+        --------
         .. code-block:: python
 
             with pm.Model():

pymc3/distributions/transforms.py

@@ -64,7 +64,7 @@ def forward(self, x):
             Input tensor to be transformed.
 
         Returns
-        --------
+        -------
         tensor
             Transformed tensor.
         """
@@ -82,7 +82,7 @@ def forward_val(self, x, point):
             Test value used to draw (fix) bounds-like transformations
 
         Returns
-        --------
+        -------
         array_like
             Transformed array.
         """

pymc3/sampling.py

@@ -1388,8 +1388,11 @@ def _choose_backend(trace, chain, **kwds) -> Backend:
         A trace object for the selected chain
     """
     if isinstance(trace, BaseTrace):
+        if len(trace) > 0:
+            warnings.warn("Trace-continuation is not supported in v4.", FutureWarning)
         return trace
     if isinstance(trace, MultiTrace):
+        warnings.warn("Starting from MultiTrace objects is not supported in v4.", FutureWarning)
         return trace._straces[chain]
     if trace is None:
         return NDArray(**kwds)

requirements-dev.txt

@@ -5,7 +5,7 @@ deprecat
 h5py>=2.7
 ipython>=7.16
 nbsphinx>=0.4
-numpydoc>=0.9
+numpydoc<1.2
 pre-commit>=2.8.0
 pytest-cov>=2.5
 pytest>=3.0