Skip to content

improve docstrings of Axes.fill_between and Axes.fill_betweenx #10186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 9, 2018
Merged

improve docstrings of Axes.fill_between and Axes.fill_betweenx #10186

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 113 additions & 69 deletions lib/matplotlib/axes/_axes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4742,64 +4742,86 @@ def fill(self, *args, **kwargs):
label_namer=None)
@docstring.dedent_interpd
def fill_between(self, x, y1, y2=0, where=None, interpolate=False,
step=None,
**kwargs):
step=None, **kwargs):
"""
Make filled polygons between two curves.
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.

You may exclude some horizontal sections from filling using *where*.

By default, the edges connect the given points directly. Use *step* if
the filling should be a step function, i.e. constant in between *x*.

Create a :class:`~matplotlib.collections.PolyCollection`
filling the regions between *y1* and *y2* where
``where==True``

Parameters
----------
x : array
An N-length array of the x data
x : array (length N)
The x coordinates of the nodes defining the curves.

y1 : array
An N-length array (or scalar) of the y data
y1 : array (length N) or scalar
The y coordinates of the nodes defining the first curve.

y2 : array
An N-length array (or scalar) of the y data
y2 : array (length N) or scalar, optional, default: 0
The y coordinates of the nodes defining the second curve.

where : array, optional
If `None`, default to fill between everywhere. If not `None`,
it is an N-length numpy boolean array and the fill will
only happen over the regions where ``where==True``.
where : array of bool (length N), optional, default: None
Define *where* to exclude some horizontal regions from being
filled. The filled regions are defined by the coordinates
``x[where]``. More precisely, fill between ``x[i]`` and ``x[i+1]``
if ``where[i] and where[i+1]``. Note that this definition implies
that an isolated *True* value between two *False* values in
*where* will not result in filling. Both sides of the *True*
position remain unfilled due to the adjacent *False* values.

interpolate : bool, optional
If `True`, interpolate between the two lines to find the
precise point of intersection. Otherwise, the start and
end points of the filled region will only occur on explicit
values in the *x* array.
This option is only relvant if *where* is used and the two curves
are crossing each other.

step : {'pre', 'post', 'mid'}, optional
If not None, fill with step logic.
Semantically, *where* is often used for *y1* > *y2* or similar.
By default, the nodes of the polygon defining the filled region
will only be placed at the positions in the *x* array. Such a
polygon cannot describe the above semantics close to the
intersection. The x-sections containing the intersecion are
simply clipped.

Returns
-------
`PolyCollection`
Plotted polygon collection
Setting *interpolate* to *True* will calculate the actual
interscection point and extend the filled region up to this point.

Notes
-----
step : {'pre', 'post', 'mid'}, optional
Define *step* if the filling should be a step function,
i.e. constant in between *x*. The value determines where the
step will occur:

Additional Keyword args passed on to the
:class:`~matplotlib.collections.PolyCollection`.
- 'pre': The y value is continued constantly to the left from
every *x* position.
- 'post': The y value is continued constantly to the right from
every *x* position.
- 'mid': Steps occur in the middle between the *x* positions.

kwargs control the :class:`~matplotlib.patches.Polygon` properties:
Other Parameters
----------------
**kwargs
All other keyword arguments are passed on to `~.PolyCollection`.
They control the `~.Polygon` properties:

%(PolyCollection)s
%(PolyCollection)s

Returns
-------
`~.PolyCollection`
A `~.PolyCollection` containing the plotted polygons.

See Also
--------
fill_betweenx : Fill between two sets of x-values.

:meth:`fill_betweenx`
for filling between two sets of x-values
Notes
-----
.. [notes section required to get data note injection right]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like a bug in the data decorator...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've summarized the problem and possible solutions (of which the above is one) in #10189.


"""

if not rcParams['_internal.classic_mode']:
color_aliases = mcoll._color_aliases
kwargs = cbook.normalize_kwargs(kwargs, color_aliases)
Expand Down Expand Up @@ -4904,62 +4926,84 @@ def get_interp_point(ind):
def fill_betweenx(self, y, x1, x2=0, where=None,
step=None, interpolate=False, **kwargs):
"""
Make filled polygons between two horizontal curves.
Fill the area between two vertical curves.

The curves are defined by the points (*x1*, *y*) and (*x2*, *y*). This
creates one or multiple polygons describing the filled area.

You may exclude some vertical sections from filling using *where*.

By default, the edges connect the given points directly. Use *step* if
the filling should be a step function, i.e. constant in between *y*.

Create a :class:`~matplotlib.collections.PolyCollection`
filling the regions between *x1* and *x2* where
``where==True``

Parameters
----------
y : array
An N-length array of the y data

x1 : array
An N-length array (or scalar) of the x data
y : array (length N)
The y coordinates of the nodes defining the curves.

x2 : array, optional
An N-length array (or scalar) of the x data
x1 : array (length N) or scalar
The x coordinates of the nodes defining the first curve.

where : array, optional
If *None*, default to fill between everywhere. If not *None*,
it is a N length numpy boolean array and the fill will
only happen over the regions where ``where==True``
x2 : array (length N) or scalar, optional, default: 0
The x coordinates of the nodes defining the second curve.

step : {'pre', 'post', 'mid'}, optional
If not None, fill with step logic.
where : array of bool (length N), optional, default: None
Define *where* to exclude some vertical regions from being
filled. The filled regions are defined by the coordinates
``y[where]``. More precisely, fill between ``y[i]`` and ``y[i+1]``
if ``where[i] and where[i+1]``. Note that this definition implies
that an isolated *True* value between two *False* values in
*where* will not result in filling. Both sides of the *True*
position remain unfilled due to the adjacent *False* values.

interpolate : bool, optional
If `True`, interpolate between the two lines to find the
precise point of intersection. Otherwise, the start and
end points of the filled region will only occur on explicit
values in the *x* array.
This option is only relvant if *where* is used and the two curves
are crossing each other.

Semantically, *where* is often used for *x1* > *x2* or similar.
By default, the nodes of the polygon defining the filled region
will only be placed at the positions in the *y* array. Such a
polygon cannot describe the above semantics close to the
intersection. The y-sections containing the intersecion are
simply clipped.

Returns
-------
`PolyCollection`
Plotted polygon collection
Setting *interpolate* to *True* will calculate the actual
interscection point and extend the filled region up to this point.

Notes
-----
step : {'pre', 'post', 'mid'}, optional
Define *step* if the filling should be a step function,
i.e. constant in between *y*. The value determines where the
step will occur:

- 'pre': The y value is continued constantly below every *y*
position.
- 'post': The y value is continued constantly above every *y*
position.
- 'mid': Steps occur in the middle between the *y* positions.

keyword args passed on to the
:class:`~matplotlib.collections.PolyCollection`
Other Parameters
----------------
**kwargs
All other keyword arguments are passed on to `~.PolyCollection`.
They control the `~.Polygon` properties:

kwargs control the :class:`~matplotlib.patches.Polygon` properties:
%(PolyCollection)s

%(PolyCollection)s
Returns
-------
`~.PolyCollection`
A `~.PolyCollection` containing the plotted polygons.

See Also
--------
fill_between : Fill between two sets of y-values.

:meth:`fill_between`
for filling between two sets of y-values
Notes
-----
.. [notes section required to get data note injection right]

"""

if not rcParams['_internal.classic_mode']:
color_aliases = mcoll._color_aliases
kwargs = cbook.normalize_kwargs(kwargs, color_aliases)
Expand Down