Add rope to plots arguments guide (#2210)

* Add a rope example Add a rope example of forest plots using ropes to the plot's arguments guide * Add link in rope argument Add the "Plots’ arguments guide" link to the rope argument in forest and posterior plots. * Update forestplot.py remove the forest plot with ropes examples from the `plot_forest()` documentation * Update plots_arguments_guide.md Correct the data set in the plot's guide example * Update rope's description Update rope's description * add examples of rope behaviour * update rope docstrings --------- Co-authored-by: Oriol (ZBook) <[email protected]>
arviz-devs · Jul 11, 2023 · 7fb2257 · 7fb2257
1 parent 37540cd
commit 7fb2257
Show file tree

Hide file tree

Showing 3 changed files with 61 additions and 22 deletions.
diff --git a/arviz/plots/forestplot.py b/arviz/plots/forestplot.py
@@ -85,10 +85,9 @@ def plot_forest(
     hdi_prob : float, default 0.94
         Plots highest posterior density interval for chosen percentage of density.
         See :ref:`this section <common_ hdi_prob>` for usage examples.
-    rope : tuple or dictionary of tuples
-        Lower and upper values of the Region of Practical Equivalence. If a list with one interval
-        only is provided, the ROPE will be displayed across the y-axis. If more than one
-        interval is provided the length of the list should match the number of variables.
+    rope : list, tuple or dictionary of {str : tuples or lists}, optional
+        A dictionary of tuples with the lower and upper values of the Region Of Practical
+        Equivalence. See :ref:`this section <common_rope>` for usage examples.
     quartiles : bool, default True
         Flag for plotting the interquartile range, in addition to the ``hdi_prob`` intervals.
     r_hat : bool, default False
@@ -182,20 +181,6 @@ def plot_forest(
         >>>                            figsize=(9, 7))
         >>> axes[0].set_title('Estimated theta for 8 schools models')
 
-    Forestplot with ropes
-
-    .. plot::
-        :context: close-figs
-
-        >>> rope = {'theta': [{'school': 'Choate', 'rope': (2, 4)}], 'mu': [{'rope': (-2, 2)}]}
-        >>> axes = az.plot_forest(non_centered_data,
-        >>>                            rope=rope,
-        >>>                            var_names='~tau',
-        >>>                            combined=True,
-        >>>                            figsize=(9, 7))
-        >>> axes[0].set_title('Estimated theta for 8 schools model')
-
-
     Ridgeplot
 
     .. plot::

diff --git a/arviz/plots/posteriorplot.py b/arviz/plots/posteriorplot.py
@@ -38,7 +38,7 @@ def plot_posterior(
     show=None,
     **kwargs
 ):
-    """Plot Posterior densities in the style of John K. Kruschke's book.
+    r"""Plot Posterior densities in the style of John K. Kruschke's book.
 
     Parameters
     ----------
@@ -83,9 +83,9 @@ def plot_posterior(
         Defaults to 'auto' i.e. it falls back to default set in rcParams.
     group: str, optional
         Specifies which InferenceData group should be plotted. Defaults to 'posterior'.
-    rope: tuple or dictionary of tuples
-        Lower and upper values of the Region Of Practical Equivalence. If a list is provided, its
-        length should match the number of variables.
+    rope : list, tuple or dictionary of {str: tuples or lists}, optional
+        A dictionary of tuples with the lower and upper values of the Region Of Practical
+        Equivalence. See :ref:`this section <common_rope>` for usage examples.
     ref_val: float or dictionary of floats
         display the percentage below and above the values in ref_val. Must be None (default),
         a constant, a list or a dictionary like see an example below. If a list is provided, its

diff --git a/doc/source/user_guide/plots_arguments_guide.md b/doc/source/user_guide/plots_arguments_guide.md
@@ -304,6 +304,60 @@ Matplotlib {doc}`mpl:tutorials/colors/colors` tutorial.
 Module {mod}`bokeh.colors`
 :::
 
+(common_rope)=
+## `rope`
+
+The rope argument is used to indicate the lower and upper limits of the Region Of Practical
+Equivalence (ROPE). These limits can be expressed in two ways, depending on whether
+the ROPE is common between all variables or not:
+
+1. A single list. If a single list of two floats is given as `rope` argument,
+   these two provided values will be used as limits of the ROPE in all plotted variables.
+2. A dictionary of lists.
+
+Example of using a single list as `rope`
+
+```{code-cell} ipython3
+az.plot_forest(non_centered_eight, var_names="~theta_t", rope=[-1, 2]);
+```
+
+An example of using a dictionary as `rope` to highlight the ROPE for a single variable:
+
+```{code-cell} ipython3
+rope = {'mu': [{"rope": (4, 5)}]}
+
+az.plot_forest(non_centered_eight, rope=rope, var_names='~theta_t', combined=True);
+```
+
+An example of using a dictionary as `rope` to highlight different ROPEs for different variables:
+
+```{code-cell} ipython3
+rope = {
+    "mu": [{"rope": (4, 5)}],
+    "theta": [
+        {"school": "Choate",    "rope": (0, 3)},
+        {"school": "Phillips Andover", "rope": (10, 14)},
+        {"school": "Hotchkiss", "rope": (3, 9)},
+        {"school": "St. Paul's", "rope": (3, 8)},
+    ]
+}
+
+az.plot_forest(non_centered_eight, rope=rope, var_names="~theta_t", combined=True);
+```
+
+Moreover, for multidimensional variables, it is easy to share a common ROPE for all its components
+with a different one for other variables:
+
+```{code-cell} ipython3
+rope = {
+    "mu": [{"rope": (4, 5)}],
+    "theta": [{"rope": (0, 3)}],
+    "tau": [{"rope": (0, 1)}],
+}
+
+az.plot_forest(non_centered_eight, rope=rope, var_names="~theta_t", combined=True);
+```
+
 (common_legend)=
 ## `legend`