Bring back stats and plotting aliases

RELEASE-NOTES.md

@@ -6,7 +6,15 @@
 
 ### 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)).
++ Statistics and plotting functions that were removed in `3.11.0` were brought back, albeit with deprecation warnings if an old naming scheme is used (see [#4536](https://github.com/pymc-devs/pymc3/pull/4536)). In order to future proof your code, rename these function calls:
+  + `pm.traceplot` → `pm.plot_trace`
+  + `pm.compareplot` → `pm.plot_compare` (here you might need to rename some columns in the input according to the [`arviz.plot_compare` documentation](https://arviz-devs.github.io/arviz/api/generated/arviz.plot_compare.html))
+  + `pm.autocorrplot` → `pm.plot_autocorr`
+  + `pm.forestplot` → `pm.plot_forest`
+  + `pm.kdeplot` → `pm.plot_kde`
+  + `pm.energyplot` → `pm.plot_energy`
+  + `pm.densityplot` → `pm.plot_density`
+  + `pm.pairplot` → `pm.plot_pair`
 
 ### 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

@@ -7,17 +7,7 @@ Plots
 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."
-For plots, ``pymc3.<function>`` are now aliases
-for ArviZ functions. Thus, the links below will redirect you to
-ArviZ docs:
+"exploratory analysis of Bayesian models".
 
-- :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>`
+Functions from the `arviz.plots` module are available through ``pymc3.<function>`` or ``pymc3.plots.<function>``,
+but for their API documentation please refer to the `ArviZ documentation <https://arviz-devs.github.io/arviz/api/plots.html>`_.

docs/source/api/stats.rst

@@ -1,25 +1,13 @@
 *****
 Stats
 *****
-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."
-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
 
+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".
 
-- :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>`
+Functions from the `arviz.stats` module are available through ``pymc3.<function>`` or ``pymc3.stats.<function>``,
+but for their API documentation please refer to the `ArviZ documentation <https://arviz-devs.github.io/arviz/api/stats.html>`_.

pymc3/plots/__init__.py

@@ -1,4 +1,4 @@
-#   Copyright 2020 The PyMC Developers
+#   Copyright 2021 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.
@@ -25,7 +25,7 @@
 import arviz as az
 
 # Makes this module as identical to arviz.plots as possible
-for attr in dir(az.plots):
+for attr in az.plots.__all__:
     obj = getattr(az.plots, attr)
     if not attr.startswith("__"):
         setattr(sys.modules[__name__], attr, obj)
@@ -35,23 +35,29 @@ 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`.")
+            raise DeprecationWarning(
+                f"The `varnames` kwarg was renamed to `var_names`.", stacklevel=2
+            )
         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,
+            stacklevel=2,
         )
         return func(*args, **kwargs)
 
     return wrapped
 
 
+# Always show the DeprecationWarnings
+warnings.filterwarnings("once", category=DeprecationWarning, module="pymc3.plots")
+
+
 # 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")
@@ -66,6 +72,7 @@ def compareplot(*args, **kwargs):
         "It also applies some kwarg replacements. Nevertheless, please switch "
         f"to `pymc3.plot_compare` or `arviz.plot_compare`.",
         DeprecationWarning,
+        stacklevel=2,
     )
     if "comp_df" in kwargs:
         comp_df = kwargs["comp_df"].copy()

pymc3/stats/__init__.py

@@ -1,4 +1,4 @@
-#   Copyright 2020 The PyMC Developers
+#   Copyright 2021 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.
@@ -22,7 +22,7 @@
 
 import arviz as az
 
-for attr in dir(az.stats):
+for attr in az.stats.__all__:
     obj = getattr(az.stats, attr)
     if not attr.startswith("__"):
         setattr(sys.modules[__name__], attr, obj)