[Bug]: matplotlib.axes.Axes.fill_between() doesn't work correctly when parameter x is not sorted

[fantauzzi]

Bug summary

When calling Axes.fill_between(x, y1, y2, where, interpolate, step, *, data, **)
with argument x whose items are not in ascending or descending order, the method colors the required area in a wrong way.

Code for reproduction

import matplotlib.pyplot as plt
import numpy as np
plt.ioff()

x = np.arange(0.0, 2, 0.01)
y1 = np.sin(2 * np.pi * x)

# Shuffle the content of x and y1 in a coordinated way
shuffle_me = list(zip(x, y1))
np.random.shuffle(shuffle_me)
x = np.array([item for item, _ in shuffle_me])
y1 = np.array([item for _, item in shuffle_me])
# This makes a bad plot
_, ax = plt.subplots()
ax.fill_between(x, y1)

# Sort the content of x and y1 in a coordinated way, such that x is in ascending order
y1 = y1[x.argsort()]
x = np.sort(x)
# This makes a good plot
_, ax = plt.subplots()
ax.fill_between(x, y1)

plt.pause(0)

Actual outcome

Expected outcome

Additional information

The issue is systematic.

Operating system

Ubuntu 20.04

Matplotlib Version

3.5.2

Matplotlib Backend

TkAgg

Python version

3.8.10

Jupyter version

N/A

Installation

pip

[jklymak]

Why do you say this is a "wrong way"?

[timhoffm]

The behavior is intended. I think it's also reasonably clear from the description:
https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.fill_between.html#matplotlib.axes.Axes.fill_between

Fill the area between two horizontal curves.

The curves are defined by the points (x, y1) and (x, y2). This creates one or multiple polygons describing the filled area.

[fantauzzi]

The behavior is intended. I think it's also reasonably clear from the description: https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.fill_between.html#matplotlib.axes.Axes.fill_between

Fill the area between two horizontal curves.
The curves are defined by the points (x, y1) and (x, y2). This creates one or multiple polygons describing the filled area.

I fail to see how the behavior is clear from that description. But I now see the behavior is consistent with that of plt.plot(x, y1).
In my view, given the behavior is as intended, the documentation could make it more obvious.

[jklymak]

At some level we have to assume the convention is understood that we will plot (x[1], y[1]) after (x[0], y[0]). I'm not sure it makes sense for us to litter the docs explaining that arrays have a defined order. Are you used to a different convention?

[fantauzzi]

At some level we have to assume the convention is understood that we will plot (x[1], y[1]) after (x[0], y[0]). I'm not sure it makes sense for us to litter the docs explaining that arrays have a defined order. Are you used to a different convention?

No.