DOC: add example for plotting asymmetrical error bars (pandas-dev#41035)

Author: mortada

doc/source/user_guide/visualization.rst

@@ -1458,25 +1458,23 @@ Horizontal and vertical error bars can be supplied to the ``xerr`` and ``yerr``
 * As a ``str`` indicating which of the columns of plotting :class:`DataFrame` contain the error values.
 * As raw values (``list``, ``tuple``, or ``np.ndarray``). Must be the same length as the plotting :class:`DataFrame`/:class:`Series`.
 
-Asymmetrical error bars are also supported, however raw error values must be provided in this case. For a ``N`` length :class:`Series`, a ``2xN`` array should be provided indicating lower and upper (or left and right) errors. For a ``MxN`` :class:`DataFrame`, asymmetrical errors should be in a ``Mx2xN`` array.
-
 Here is an example of one way to easily plot group means with standard deviations from the raw data.
 
 .. ipython:: python
 
    # Generate the data
    ix3 = pd.MultiIndex.from_arrays(
        [
-           ["a", "a", "a", "a", "b", "b", "b", "b"],
-           ["foo", "foo", "bar", "bar", "foo", "foo", "bar", "bar"],
+           ["a", "a", "a", "a", "a", "b", "b", "b", "b", "b"],
+           ["foo", "foo", "foo", "bar", "bar", "foo", "foo", "bar", "bar", "bar"],
        ],
        names=["letter", "word"],
    )
 
    df3 = pd.DataFrame(
        {
-           "data1": [3, 2, 4, 3, 2, 4, 3, 2],
-           "data2": [6, 5, 7, 5, 4, 5, 6, 5],
+           "data1": [9, 3, 2, 4, 3, 2, 4, 6, 3, 2],
+           "data2": [9, 6, 5, 7, 5, 4, 5, 6, 5, 1],
        },
        index=ix3,
    )
@@ -1499,6 +1497,28 @@ Here is an example of one way to easily plot group means with standard deviation
 
    plt.close("all")
 
+Asymmetrical error bars are also supported, however raw error values must be provided in this case. For a ``N`` length :class:`Series`, a ``2xN`` array should be provided indicating lower and upper (or left and right) errors. For a ``MxN`` :class:`DataFrame`, asymmetrical errors should be in a ``Mx2xN`` array.
+
+Here is an example of one way to plot the min/max range using asymmetrical error bars.
+
+.. ipython:: python
+
+   mins = gp3.min()
+   maxs = gp3.max()
+
+   # errors should be positive, and defined in the order of lower, upper
+   errors = [[means[c] - mins[c], maxs[c] - means[c]] for c in df3.columns]
+
+   # Plot
+   fig, ax = plt.subplots()
+   @savefig errorbar_asymmetrical_example.png
+   means.plot.bar(yerr=errors, ax=ax, capsize=4, rot=0);
+
+.. ipython:: python
+   :suppress:
+
+   plt.close("all")
+
 .. _visualization.table:
 
 Plotting tables