8000 Merge pull request #20309 from QuLogic/example-kwargs · matplotlib/matplotlib@401aa2f · GitHub
[go: up one dir, main page]
Skip to content

Commit 401aa2f

Browse files
timhoffmtimhoffm
authored
Merge pull request #20309 from QuLogic/example-kwargs
DOC: Spell out args/kwargs in examples/tutorials
2 parents 81436da + 203f8a0 commit 401aa2f

File tree

27 files changed

+97
-99
lines changed

27 files changed

+97
-99
lines changed

‎examples/images_contours_and_fields/contourf_demo.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,10 +41,10 @@
4141
fig1, ax2 = plt.subplots(constrained_layout=True)
4242
CS = ax2.contourf(X, Y, Z, 10, cmap=plt.cm.bone, origin=origin)
4343

44-
# Note that in the following, we explicitly pass in a subset of
45-
# the contour levels used for the filled contours. Alternatively,
46-
# We could pass in additional levels to provide extra resolution,
47-
# or leave out the levels kwarg to use all of the original levels.
44+
# Note that in the following, we explicitly pass in a subset of the contour
45+
# levels used for the filled contours. Alternatively, we could pass in
46+
# additional levels to provide extra resolution, or leave out the *levels*
47+
# keyword argument to use all of the original levels.
4848

4949
CS2 = ax2.contour(CS, levels=CS.levels[::2], colors='r', origin=origin)
5050

‎examples/images_contours_and_fields/tripcolor_demo.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@
113113
# object if the same triangulation was to be used more than once to save
114114
# duplicated calculations.
115115
# Can specify one color value per face rather than one per point by using the
116-
# facecolors kwarg.
116+
# *facecolors* keyword argument.
117117

118118
fig3, ax3 = plt.subplots()
119119
ax3.set_aspect('equal')

‎examples/lines_bars_and_markers/filled_step.py

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,6 @@ def filled_hist(ax, edges, values, bottoms=None, orientation='v',
2020
"""
2121
Draw a histogram as a stepped patch.
2222
23-
Extra kwargs are passed through to `fill_between`
24-
2523
Parameters
2624
----------
2725
ax : Axes
@@ -41,6 +39,9 @@ def filled_hist(ax, edges, values, bottoms=None, orientation='v',
4139
Orientation of the histogram. 'v' (default) has
4240
the bars increasing in the positive y-direction.
4341
42+
**kwargs
43+
Extra keyword arguments are passed through to `.fill_between`.
44+
4445
Returns
4546
-------
4647
ret : PolyCollection
@@ -103,11 +104,11 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None,
103104
104105
If not given and stacked data is an array defaults to 'default set {n}'
105106
106-
If stacked_data is a mapping, and labels is None, default to the keys
107-
(which may come out in a random order).
107+
If *stacked_data* is a mapping, and *labels* is None, default to the
108+
keys.
108109
109-
If stacked_data is a mapping and labels is given then only
110-
the columns listed by be plotted.
110+
If *stacked_data* is a mapping and *labels* is given then only the
111+
columns listed will be plotted.
111112
112113
plot_func : callable, optional
113114
Function to call to draw the histogram must have signature:
@@ -116,9 +117,9 @@ def stack_hist(ax, stacked_data, sty_cycle, bottoms=None,
116117
label=label, **kwargs)
117118
118119
plot_kwargs : dict, optional
119-
Any extra kwargs to pass through to the plotting function. This
120-
will be the same for all calls to the plotting function and will
121-
over-ride the values in cycle.
120+
Any extra keyword arguments to pass through to the plotting function.
121+
This will be the same for all calls to the plotting function and will
122+
override the values in *sty_cycle*.
122123
123124
Returns
124125
-------

‎examples/lines_bars_and_markers/gradient_bar.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ def gradient_image(ax, extent, direction=0.3, cmap_range=(0, 1), **kwargs):
3434
extent
3535
The extent of the image as (xmin, xmax, ymin, ymax).
3636
By default, this is in Axes coordinates but may be
37-
changed using the *transform* kwarg.
37+
changed using the *transform* keyword argument.
3838
direction : float
3939
The direction of the gradient. This is a number in
4040
range 0 (=vertical) to 1 (=horizontal).

‎examples/shapes_and_collections/collections.py

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,10 @@
33
Line, Poly and RegularPoly Collection with autoscaling
44
=========================================================
55
6-
For the first two subplots, we will use spirals. Their
7-
size will be set in plot units, not data units. Their positions
8-
will be set in data units by using the "offsets" and "transOffset"
9-
kwargs of the `~.collections.LineCollection` and
10-
`~.collections.PolyCollection`.
6+
For the first two subplots, we will use spirals. Their size will be set in
7+
plot units, not data units. Their positions will be set in data units by using
8+
the *offsets* and *transOffset* keyword arguments of the `.LineCollection` and
9+
`.PolyCollection`.
1110
1211
The third subplot will make regular polygons, with the same
1312
type of scaling and positioning as in the first two.
@@ -60,7 +59,7 @@
6059
# but it is good enough to generate a plot that you can use
6160
# as a starting point. If you know beforehand the range of
6261
# x and y that you want to show, it is better to set them
63-
# explicitly, leave out the autolim kwarg (or set it to False),
62+
# explicitly, leave out the *autolim* keyword argument (or set it to False),
6463
# and omit the 'ax1.autoscale_view()' call below.
6564

6665
# Make a transform for the line segments such that their size is

‎examples/specialty_plots/topographic_hillshading.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
In most cases, hillshading is used purely for visual purposes, and *dx*/*dy*
1414
can be safely ignored. In that case, you can tweak *vert_exag* (vertical
1515
exaggeration) by trial and error to give the desired visual effect. However,
16-
this example demonstrates how to use the *dx* and *dy* kwargs to ensure that
17-
the *vert_exag* parameter is the true vertical exaggeration.
16+
this example demonstrates how to use the *dx* and *dy* keyword arguments to
17+
ensure that the *vert_exag* parameter is the true vertical exaggeration.
1818
"""
1919
import numpy as np
2020
import matplotlib.pyplot as plt

‎examples/statistics/boxplot.py

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,15 @@
33
Artist customization in box plots
44
=================================
55
6-
This example demonstrates how to use the various kwargs
7-
to fully customize box plots. The first figure demonstrates
8-
how to remove and add individual components (note that the
9-
mean is the only value not shown by default). The second
10-
figure demonstrates how the styles of the artists can
11-
be customized. It also demonstrates how to set the limit
12-
of the whiskers to specific percentiles (lower right axes)
13-
14-
A good general reference on boxplots and their history can be found
15-
here: http://vita.had.co.nz/papers/boxplots.pdf
6+
This example demonstrates how to use the various keyword arguments to fully
7+
customize box plots. The first figure demonstrates how to remove and add
8+
individual components (note that the mean is the only value not shown by
9+
default). The second figure demonstrates how the styles of the artists can be
10+
customized. It also demonstrates how to set the limit of the whiskers to
11+
specific percentiles (lower right axes)
12+
13+
A good general reference on boxplots and their history can be found here:
14+
https://vita.had.co.nz/papers/boxplots.pdf
1615
1716
"""
1817

‎examples/statistics/confidence_ellipse.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ def get_correlated_dataset(n, dependency, mu, scale):
190190
# Using the keyword arguments
191191
# """""""""""""""""""""""""""
192192
#
193-
# Use the kwargs specified for matplotlib.patches.Patch in order
193+
# Use the keyword arguments specified for `matplotlib.patches.Patch` in order
194194
# to have the ellipse rendered in different ways.
195195

196196
fig, ax_kwargs = plt.subplots(figsize=(6, 6))
@@ -210,7 +210,7 @@ def get_correlated_dataset(n, dependency, mu, scale):
210210

211211
ax_kwargs.scatter(x, y, s=0.5)
212212
ax_kwargs.scatter(mu[0], mu[1], c='red', s=3)
213-
ax_kwargs.set_title('Using kwargs')
213+
ax_kwargs.set_title('Using keyword arguments')
214214

215215
fig.subplots_adjust(hspace=0.25)
216216
plt.show()

‎examples/statistics/customized_violin.py

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,11 @@
33
Violin plot customization
44
=========================
55
6-
This example demonstrates how to fully customize violin plots.
7-
The first plot shows the default style by providing only
8-
the data. The second plot first limits what matplotlib draws
9-
with additional kwargs. Then a simplified representation of
10-
a box plot is drawn on top. Lastly, the styles of the artists
11-
of the violins are modified.
6+
This example demonstrates how to fully customize violin plots. The first plot
7+
shows the default style by providing only the data. The second plot first
8+
limits what Matplotlib draws with additional keyword arguments. Then a
9+
simplified representation of a box plot is drawn on top. Lastly, the styles of
10+
the artists of the violins are modified.
1211
1312
For more information on violin plots, the scikit-learn docs have a great
1413
section: https://scikit-learn.org/stable/modules/density.html

‎examples/statistics/errorbars_and_boxes.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,9 @@
1212
1. an `~.axes.Axes` object is passed directly to the function
1313
2. the function operates on the ``Axes`` methods directly, not through
1414
the ``pyplot`` interface
15-
3. plotting kwargs that could be abbreviated are spelled out for
16-
better code readability in the future (for example we use
17-
``facecolor`` instead of ``fc``)
15+
3. plotting keyword arguments that could be abbreviated are spelled out for
16+
better code readability in the future (for example we use *facecolor*
17+
instead of *fc*)
1818
4. the artists returned by the ``Axes`` plotting methods are then
1919
returned by the function so that, if desired, their styles
2020
can be modified later outside of the function (they are not

‎examples/statistics/hist.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232

3333
fig, axs = plt.subplots(1, 2, sharey=True, tight_layout=True)
3434

35-
# We can set the number of bins with the `bins` kwarg
35+
# We can set the number of bins with the *bins* keyword argument.
3636
axs[0].hist(x, bins=n_bins)
3737
axs[1].hist(y, bins=n_bins)
3838

‎examples/statistics/histogram_cumulative.py

Lines changed: 7 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,13 @@
77
step function in order to visualize the empirical cumulative
88
distribution function (CDF) of a sample. We also show the theoretical CDF.
99
10-
A couple of other options to the ``hist`` function are demonstrated.
11-
Namely, we use the ``normed`` parameter to normalize the histogram and
12-
a couple of different options to the ``cumulative`` parameter.
13-
The ``normed`` parameter takes a boolean value. When ``True``, the bin
14-
heights are scaled such that the total area of the histogram is 1. The
15-
``cumulative`` kwarg is a little more nuanced. Like ``normed``, you
16-
can pass it True or False, but you can also pass it -1 to reverse the
17-
distribution.
10+
A couple of other options to the ``hist`` function are demonstrated. Namely, we
11+
use the *normed* parameter to normalize the histogram and a couple of different
12+
options to the *cumulative* parameter. The *normed* parameter takes a boolean
13+
value. When ``True``, the bin heights are scaled such that the total area of
14+
the histogram is 1. The *cumulative* keyword argument is a little more nuanced.
15+
Like *normed*, you can pass it True or False, but you can also pass it -1 to
16+
reverse the distribution.
1817
1918
Since we're showing a normalized and cumulative histogram, these curves
2019
are effectively the cumulative distribution functions (CDFs) of the

‎examples/subplots_axes_and_figures/secondary_axis.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
axes with only one axis visible via `.axes.Axes.secondary_xaxis` and
99
`.axes.Axes.secondary_yaxis`. This secondary axis can have a different scale
1010
than the main axis by providing both a forward and an inverse conversion
11-
function in a tuple to the ``functions`` kwarg:
11+
function in a tuple to the *functions* keyword argument:
1212
"""
1313

1414
import matplotlib.pyplot as plt
@@ -87,9 +87,9 @@ def one_over(x):
8787
# nominal plot limits.
8888
#
8989
# In the specific case of the numpy linear interpolation, `numpy.interp`,
90-
# this condition can be arbitrarily enforced by providing optional kwargs
91-
# *left*, *right* such that values outside the data range are mapped
92-
# well outside the plot limits.
90+
# this condition can be arbitrarily enforced by providing optional keyword
91+
# arguments *left*, *right* such that values outside the data range are
92+
# mapped well outside the plot limits.
9393

9494
fig, ax = plt.subplots(constrained_layout=True)
9595
xdata = np.arange(1, 11, 0.4)

‎examples/text_labels_and_annotations/annotation_demo.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@
107107
# In the example below, the *xy* point is in native coordinates (*xycoords*
108108
# defaults to 'data'). For a polar axes, this is in (theta, radius) space.
109109
# The text in the example is placed in the fractional figure coordinate system.
110-
# Text keyword args like horizontal and vertical alignment are respected.
110+
# Text keyword arguments like horizontal and vertical alignment are respected.
111111

112112
fig, ax = plt.subplots(subplot_kw=dict(projection='polar'), figsize=(3, 3))
113113
r = np.arange(0, 1, 0.001)

‎examples/text_labels_and_annotations/fonts_demo.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
66
Set font properties using setters.
77
8-
See :doc:`fonts_demo_kw` to achieve the same effect using kwargs.
8+
See :doc:`fonts_demo_kw` to achieve the same effect using keyword arguments.
99
"""
1010

1111
from matplotlib.font_manager import FontProperties

‎examples/text_labels_and_annotations/fonts_demo_kw.py

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
"""
2-
===================
3-
Fonts demo (kwargs)
4-
===================
2+
==============================
3+
Fonts demo (keyword arguments)
4+
==============================
55
6-
Set font properties using kwargs.
6+
Set font properties using keyword arguments.
77
88
See :doc:`fonts_demo` to achieve the same effect using setters.
99
"""

‎examples/text_labels_and_annotations/titles_demo.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,8 @@
3838
plt.show()
3939

4040
###########################################################################
41-
# Automatic positioning can be turned off by manually specifying the
42-
# *y* kwarg for the title or setting :rc:`axes.titley` in the rcParams.
41+
# Automatic positioning can be turned off by manually specifying the *y*
42+
# keyword argument for the title or setting :rc:`axes.titley` in the rcParams.
4343

4444
fig, axs = plt.subplots(1, 2, constrained_layout=True)
4545

‎examples/ticks_and_spines/custom_ticker1.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717

1818

1919
def millions(x, pos):
20-
"""The two args are the value and tick position."""
20+
"""The two arguments are the value and tick position."""
2121
return '${:1.1f}M'.format(x*1e-6)
2222

2323
fig, ax = plt.subplots()

‎examples/ticks_and_spines/date_concise_formatter.py

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@
101101
# limits are mostly hours, we label Feb 4 00:00 as simply "Feb-4".
102102
#
103103
# Note that these format lists can also be passed to `.ConciseDateFormatter`
104-
# as optional kwargs.
104+
# as optional keyword arguments.
105105
#
106106
# Here we modify the labels to be "day month year", instead of the ISO
107107
# "year month day":
@@ -142,8 +142,8 @@
142142
# Registering a converter with localization
143143
# =========================================
144144
#
145-
# `.ConciseDateFormatter` doesn't have rcParams entries, but localization
146-
# can be accomplished by passing kwargs to `.ConciseDateConverter` and
145+
# `.ConciseDateFormatter` doesn't have rcParams entries, but localization can
146+
# be accomplished by passing keyword arguments to `.ConciseDateConverter` and
147147
# registering the datatypes you will use with the units registry:
148148

149149
import datetime

‎examples/units/basic_units.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,8 +79,8 @@ def __call__(self, *args):
7979
arg_units = [self.unit]
8080
for a in args:
8181
if hasattr(a, 'get_unit') and not hasattr(a, 'convert_to'):
82-
# if this arg has a unit type but no conversion ability,
83-
# this operation is prohibited
82+
# If this argument has a unit type but no conversion ability,
83+
# this operation is prohibited.
8484
return NotImplemented
8585

8686
if hasattr(a, 'convert_to'):

‎tutorials/intermediate/constrainedlayout_guide.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,8 @@ def example_plot(ax, fontsize=12, hide_labels=False):
7979
# To prevent this, the location of axes needs to be adjusted. For
8080
# subplots, this can be done by adjusting the subplot params
8181
# (:ref:`howto-subplots-adjust`). However, specifying your figure with the
82-
# ``constrained_layout=True`` kwarg will do the adjusting automatically.
82+
# ``constrained_layout=True`` keyword argument will do the adjusting
83+
# automatically.
8384

8485
fig, ax = plt.subplots(constrained_layout=True)
8586
example_plot(ax, fontsize=24)
@@ -112,7 +113,7 @@ def example_plot(ax, fontsize=12, hide_labels=False):
112113
#
113114
# .. note::
114115
#
115-
# For the `~.axes.Axes.pcolormesh` kwargs (``pc_kwargs``) we use a
116+
# For the `~.axes.Axes.pcolormesh` keyword arguments (``pc_kwargs``) we use a
116117
# dictionary. Below we will assign one colorbar to a number of axes each
117118
# containing a `~.cm.ScalarMappable`; specifying the norm and colormap
118119
# ensures the colorbar is accurate for all the axes.

‎tutorials/intermediate/imshow_extent.py

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,18 @@
22
*origin* and *extent* in `~.Axes.imshow`
33
========================================
44
5-
:meth:`~.Axes.imshow` allows you to render an image (either a 2D array
6-
which will be color-mapped (based on *norm* and *cmap*) or a 3D RGB(A)
7-
array which will be used as-is) to a rectangular region in data space.
8-
The orientation of the image in the final rendering is controlled by
9-
the *origin* and *extent* kwargs (and attributes on the resulting
10-
`.AxesImage` instance) and the data limits of the axes.
11-
12-
The *extent* kwarg controls the bounding box in data coordinates that
13-
the image will fill specified as ``(left, right, bottom, top)`` in
14-
**data coordinates**, the *origin* kwarg controls how the image fills
15-
that bounding box, and the orientation in the final rendered image is
16-
also affected by the axes limits.
5+
:meth:`~.Axes.imshow` allows you to render an image (either a 2D array which
6+
will be color-mapped (based on *norm* and *cmap*) or a 3D RGB(A) array which
7+
will be used as-is) to a rectangular region in data space. The orientation of
8+
the image in the final rendering is controlled by the *origin* and *extent*
9+
keyword arguments (and attributes on the resulting `.AxesImage` instance) and
10+
the data limits of the axes.
11+
12+
The *extent* keyword arguments controls the bounding box in data coordinates
13+
that the image will fill specified as ``(left, right, bottom, top)`` in **data
14+
coordinates**, the *origin* keyword argument controls how the image fills that
15+
bounding box, and the orientation in the final rendered image is also affected
16+
by the axes limits.
1717
1818
.. hint:: Most of the code below is used for adding labels and informative
1919
text to the plots. The described effects of *origin* and *extent* can be

0 commit comments

Comments
 (0)
0