Bring back stats and plotting aliases

RELEASE-NOTES.md

@@ -1,12 +1,12 @@
 # Release Notes
 
-## PyMC3 vNext (TBD)
+## PyMC3 3.11.2 (TBD)
 ### Breaking Changes
 + ...
 
 ### New Features
 + `pm.math.cartesian` can now handle inputs that are themselves >1D (see [#4482](https://github.com/pymc-devs/pymc3/pull/4482)).
-+ ...
++ Statistics and plotting functions that were removed in `3.11.0` were brought back, albeit with deprecation warnings (see [#4536](https://github.com/pymc-devs/pymc3/pull/4536)).
 
 ### Maintenance
 - ⚠ Our memoization mechanism wasn't robust against hash collisions (#4506), sometimes resulting in incorrect values in, for example, posterior predictives. The `pymc3.memoize` module was removed and replaced with `cachetools`.  The `hashable` function and `WithMemoization` class were moved to `pymc3.util` (see #4525).

docs/source/api/plots.rst

@@ -8,7 +8,16 @@ Plots are delegated to the
 `ArviZ <https://arviz-devs.github.io/arviz/index.html>`_.
 library, a general purpose library for
 "exploratory analysis of Bayesian models."
-Refer to its documentation to use the plotting functions directly.
+For plots, ``pymc3.<function>`` are now aliases
+for ArviZ functions. Thus, the links below will redirect you to
+ArviZ docs:
 
-.. automodule:: pymc3.plots.posteriorplot
-   :members:
+- :func:`pymc3.traceplot <arviz:arviz.plot_trace>`
+- :func:`pymc3.plot_posterior <arviz:arviz.plot_posterior>`
+- :func:`pymc3.forestplot <arviz:arviz.plot_forest>`
+- :func:`pymc3.compareplot <arviz:arviz.plot_compare>`
+- :func:`pymc3.autocorrplot <arviz:arviz.plot_autocorr>`
+- :func:`pymc3.energyplot <arviz:arviz.plot_energy>`
+- :func:`pymc3.kdeplot <arviz:arviz.plot_kde>`
+- :func:`pymc3.densityplot <arviz:arviz.plot_density>`
+- :func:`pymc3.pairplot <arviz:arviz.plot_pair>`

docs/source/api/stats.rst

@@ -5,4 +5,21 @@ Statistics and diagnostics are delegated to the
 `ArviZ <https://arviz-devs.github.io/arviz/index.html>`_.
 library, a general purpose library for
 "exploratory analysis of Bayesian models."
-Refer to its documentation to use the diagnostics functions directly.
+For statistics and diagnostics, ``pymc3.<function>`` are now aliases
+for ArviZ functions. Thus, the links below will redirect you to
+ArviZ docs:
+
+.. currentmodule:: pymc3.stats
+
+
+- :func:`pymc3.bfmi <arviz:arviz.bfmi>`
+- :func:`pymc3.compare <arviz:arviz.compare>`
+- :func:`pymc3.ess <arviz:arviz.ess>`
+- :data:`pymc3.geweke <arviz:arviz.geweke>`
+- :func:`pymc3.hpd <arviz:arviz.hpd>`
+- :func:`pymc3.loo <arviz:arviz.loo>`
+- :func:`pymc3.mcse <arviz:arviz.mcse>`
+- :func:`pymc3.r2_score <arviz:arviz.r2_score>`
+- :func:`pymc3.rhat <arviz:arviz.rhat>`
+- :func:`pymc3.summary <arviz:arviz.summary>`
+- :func:`pymc3.waic <arviz:arviz.waic>`

pymc3/__init__.py

@@ -61,6 +61,7 @@ def __set_compiler_flags():
 from pymc3.plots import *
 from pymc3.sampling import *
 from pymc3.smc import *
+from pymc3.stats import *
 from pymc3.step_methods import *
 from pymc3.tests import test
 from pymc3.theanof import *

pymc3/plots/__init__.py

@@ -12,19 +12,108 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
-"""PyMC3 Plotting.
+"""Alias for the `plots` submodule from ArviZ.
 
-Plots are delegated to the `ArviZ <https://arviz-devs.github.io/arviz/>`_ library, a general purpose library for
-exploratory analysis of Bayesian models. For more details, see https://arviz-devs.github.io/arviz/.
-
-Only `plot_posterior_predictive_glm` is kept in the PyMC code base for now, but it will move to ArviZ once the latter adds features for regression plots.
+Plots are delegated to the ArviZ library, a general purpose library for
+"exploratory analysis of Bayesian models."
+See https://arviz-devs.github.io/arviz/ for details on plots.
 """
 import functools
 import sys
 import warnings
 
 import arviz as az
 
+# Makes this module as identical to arviz.plots as possible
+for attr in dir(az.plots):
+    obj = getattr(az.plots, attr)
+    if not attr.startswith("__"):
+        setattr(sys.modules[__name__], attr, obj)
+
+
+def map_args(func, alias: str):
+    @functools.wraps(func)
+    def wrapped(*args, **kwargs):
+        if "varnames" in kwargs:
+            raise DeprecationWarning(f"The `varnames` kwarg was renamed to `var_names`.")
+        original = func.__name__
+        warnings.warn(
+            f"The function `{alias}` from PyMC3 is just an alias for `{original}` from ArviZ. "
+            f"Please switch to `pymc3.{original}` or `arviz.{original}`.",
+            DeprecationWarning,
+        )
+        return func(*args, **kwargs)
+
+    return wrapped
+
+
+# Aliases of ArviZ functions
+autocorrplot = map_args(az.plot_autocorr, alias="autocorrplot")
+forestplot = map_args(az.plot_forest, alias="forestplot")
+kdeplot = map_args(az.plot_kde, alias="kdeplot")
+plot_posterior = map_args(az.plot_posterior, alias="plot_posterior")
+energyplot = map_args(az.plot_energy, alias="energyplot")
+densityplot = map_args(az.plot_density, alias="densityplot")
+pairplot = map_args(az.plot_pair, alias="pairplot")
+traceplot = map_args(az.plot_trace, alias="traceplot")
+
+
+# Customized with kwarg reformatting
+@functools.wraps(az.plot_compare)
+def compareplot(*args, **kwargs):
+    warnings.warn(
+        f"The function `compareplot` from PyMC3 is an alias for `plot_compare` from ArviZ. "
+        "It also applies some kwarg replacements. Nevertheless, please switch "
+        f"to `pymc3.plot_compare` or `arviz.plot_compare`.",
+        DeprecationWarning,
+    )
+    if "comp_df" in kwargs:
+        comp_df = kwargs["comp_df"].copy()
+    else:
+        args = list(args)
+        comp_df = args[0].copy()
+    if "WAIC" in comp_df.columns:
+        comp_df = comp_df.rename(
+            index=str,
+            columns={
+                "WAIC": "waic",
+                "pWAIC": "p_waic",
+                "dWAIC": "d_waic",
+                "SE": "se",
+                "dSE": "dse",
+                "var_warn": "warning",
+            },
+        )
+    elif "LOO" in comp_df.columns:
+        comp_df = comp_df.rename(
+            index=str,
+            columns={
+                "LOO": "loo",
+                "pLOO": "p_loo",
+                "dLOO": "d_loo",
+                "SE": "se",
+                "dSE": "dse",
+                "shape_warn": "warning",
+            },
+        )
+    if "comp_df" in kwargs:
+        kwargs["comp_df"] = comp_df
+    else:
+        args[0] = comp_df
+    return az.plot_compare(*args, **kwargs)
+
+
 from pymc3.plots.posteriorplot import plot_posterior_predictive_glm
 
-__all__ = ["plot_posterior_predictive_glm"]
+__all__ = tuple(az.plots.__all__) + (
+    "autocorrplot",
+    "compareplot",
+    "forestplot",
+    "kdeplot",
+    "plot_posterior",
+    "traceplot",
+    "energyplot",
+    "densityplot",
+    "pairplot",
+    "plot_posterior_predictive_glm",
+)

pymc3/stats/__init__.py

@@ -0,0 +1,31 @@
+#   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.
+
+"""Alias for the `stats` submodule from ArviZ.
+
+Diagnostics and auxiliary statistical functions are delegated to the ArviZ library, a general
+purpose library for "exploratory analysis of Bayesian models."
+See https://arviz-devs.github.io/arviz/ for details.
+"""
+import sys
+
+import arviz as az
+
+for attr in dir(az.stats):
+    obj = getattr(az.stats, attr)
+    if not attr.startswith("__"):
+        setattr(sys.modules[__name__], attr, obj)
+
+
+__all__ = tuple(az.stats.__all__)