Add plot_forest and tests (arviz-devs#34)

* some improvements to PlotCollection

* add classmethod tests

* add more tests

* add divergences to plot_trace

* extend tests

* add divergence data to test_plots

* add plot_forest draft

For everything to work, the following features were added to:
* support for "__variable__" in aesthetics
* default values for common aesthetics
* support for dict of datatree input -> multiple models aligned within the same plot

* add labels to plot_forest

still some backend elements missing for bokeh

* further improvements to plot_forest

* invert y aes to preserve order top-down

* improvements to aes_map defaults and shading

* attempt support for InferenceData inputs

* plot_dist support for multiple models and docs

* update dependencies

* add more tests

* raise error on wrong use of combined

* better support for aesthetics in labels elements

Author: OriolAbril

.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10", "3.11"]
+        python-version: ["3.10", "3.11", "3.12"]
       fail-fast: false
     steps:
       - uses: actions/checkout@v3

README.md

@@ -1,5 +1,7 @@
 # arviz-plots
 
+[![Run tests](https://github.com/arviz-devs/arviz-plots/actions/workflows/test.yml/badge.svg)](https://github.com/arviz-devs/arviz-plots/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/arviz-devs/arviz-plots/graph/badge.svg?token=1VIPLXCOJQ)](https://codecov.io/gh/arviz-devs/arviz-plots)
 [![Powered by NumFOCUS](https://img.shields.io/badge/powered%20by-NumFOCUS-orange.svg?style=flat&colorA=E1523D&colorB=007D8A)](https://numfocus.org)
 
 ArviZ plotting elements and static battery included plots

docs/source/api/backend/interface.template.rst

@@ -26,6 +26,8 @@ Plot appeareance
    title
    ylabel
    xlabel
+   xticks
+   yticks
    ticks_size
    remove_ticks
    remove_axis

docs/source/api/plots.rst

@@ -16,5 +16,6 @@ A complementary introduction and guide to ``plot_...`` functions is available at
    :toctree: generated/
 
    plot_dist
+   plot_forest
    plot_trace
    plot_trace_dist

docs/source/api/visuals.rst

@@ -22,6 +22,7 @@ Data and axis annotating elements
 .. autosummary::
    :toctree: generated/
 
+   annotate_label
    point_estimate_text
    labelled_title
    labelled_y

docs/source/conf.py

@@ -36,6 +36,7 @@
     "sphinx_copybutton",
     "sphinx_design",
     "jupyter_sphinx",
+    "matplotlib.sphinxext.plot_directive",
 ]
 
 templates_path = ["_templates"]
@@ -67,11 +68,19 @@
 
 # -- Options for extensions
 
+plot_include_source = True
+plot_formats = [("png", 90)]
+plot_html_show_formats = False
+plot_html_show_source_link = False
+
 extlinks = {
     "issue": ("https://github.com/arviz-devs/arviz-base/issues/%s", "GH#%s"),
     "pull": ("https://github.com/arviz-devs/arviz-base/pull/%s", "PR#%s"),
 }
 
+copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: "
+copybutton_prompt_is_regexp = True
+
 nb_execution_mode = "auto"
 nb_execution_excludepatterns = ["*.ipynb"]
 nb_kernel_rgx_aliases = {".*": "python3"}
@@ -85,12 +94,13 @@
 
 numpydoc_show_class_members = False
 numpydoc_xref_param_type = True
-numpydoc_xref_ignore = {"of", "or", "optional", "scalar"}
+numpydoc_xref_ignore = {"of", "or", "optional", "scalar", "default"}
 singulars = ("int", "list", "dict", "float")
 numpydoc_xref_aliases = {
     "DataArray": ":class:`xarray.DataArray`",
     "Dataset": ":class:`xarray.Dataset`",
     "DataTree": ":class:`datatree.DataTree`",
+    "mapping": ":term:`python:mapping`",
     **{f"{singular}s": f":any:`{singular}s <{singular}>`" for singular in singulars},
 }
 

pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "flit_core.buildapi"
 [project]
 name = "arviz-plots"
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = {file = "LICENSE"}
 authors = [
     {name = "ArviZ team", email = "[email protected]"}
@@ -20,9 +20,9 @@ classifiers = [
     "Operating System :: OS Independent",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
 ]
 dynamic = ["version", "description"]
 dependencies = [
@@ -45,7 +45,8 @@ test = [
     "pytest",
     "pytest-cov",
     "matplotlib",
-    "bokeh"
+    "bokeh",
+    "h5netcdf",
 ]
 doc = [
     "furo",
@@ -110,6 +111,7 @@ disallow_untyped_defs = true
 # ignore_missing_imports = true
 
 [tool.pytest.ini_options]
+filterwarnings = ["error"]
 testpaths = [
     "tests",
 ]

src/arviz_plots/backend/__init__.py

@@ -12,6 +12,7 @@
 to any type of the plotting backend or even custom objects, but all instances
 of the same placeholder must use the same type (whatever that is).
 """
+import numpy as np
 
 error = NotImplementedError(
     "The `arviz_plots.backend` module itself is for reference only. "
@@ -20,6 +21,22 @@
 )
 
 
+# generation of default values for aesthetics
+def get_default_aes(aes_key, n, kwargs):
+    """Generate `n` default values for a given aesthetics keyword."""
+    if aes_key not in kwargs:
+        if aes_key in {"x", "y"}:
+            return np.arange(n)
+        if aes_key == "alpha":
+            return np.linspace(0.2, 0.7, n)
+        return [None] * n
+    aes_vals = kwargs[aes_key]
+    n_aes_vals = len(aes_vals)
+    if n_aes_vals >= n:
+        return aes_vals[:n]
+    return np.tile(aes_vals, (n // n_aes_vals) + 1)[:n]
+
+
 # object creation and i/o
 def show(chart):
     """Show this :term:`chart`.
@@ -39,6 +56,8 @@ def create_plotting_grid(
     sharex=False,
     sharey=False,
     polar=False,
+    width_ratios=None,
+    plot_hspace=None,
     subplot_kws=None,
     **kwargs,
 ):
@@ -56,6 +75,8 @@ def create_plotting_grid(
         Flags that indicate the axis limits between the different plots should
         be shared.
     polar : bool, default False
+    width_ratios : array_like of shape (cols,), optional
+    plot_hspace : float, optional
     subplot_kws, **kwargs : mapping, optional
         Arguments passed downstream to the plotting backend.
 
@@ -114,9 +135,10 @@ def scatter(
     target : plot type
     size : float or array-like of float
     marker : any
+        The character ``|`` must be a valid marker as it is the default for rug plots.
     alpha : float
     color : any
-        Set both facecolor and edgecolor simultaneously.
+        Set both facecolor and edgecolor simultaneously but without overriding them if present.
     facecolor : any
         Color of the marker filling.
     edgecolor : any
@@ -145,6 +167,11 @@ def text(
     raise error
 
 
+def fill_between_y(x, y_bottom, y_top, target, **artist_kws):
+    """Fill the region between y_bottom and y_top."""
+    raise error
+
+
 # general plot appeareance
 def title(string, target, *, size=None, color=None, **artist_kws):
     """Interface to adding a title to a plot."""
@@ -161,6 +188,32 @@ def xlabel(string, target, *, size=None, color=None, **artist_kws):
     raise error
 
 
+def xticks(ticks, labels, traget, **artist_kws):
+    """Interface to setting ticks and tick labels of the x axis.
+
+    Parameters
+    ----------
+    ticks : array_like
+    labels : array_like or None
+        Labels for the provided `ticks`. Must accept ``None`` as a way
+        to set only ticks and leave their default labels.
+    """
+    raise error
+
+
+def yticks(ticks, labels, traget, **artist_kws):
+    """Interface to setting ticks and tick labels of the y axis.
+
+    Parameters
+    ----------
+    ticks : array_like
+    labels : array_like or None
+        Labels for the provided `ticks`. Must accept ``None`` as a way
+        to set only ticks and leave their default labels.
+    """
+    raise error
+
+
 def ticks_size(value, target):
     """Interface to setting ticks size."""
     raise error