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]>

Author: asael697

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::

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

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`