Skip to content

Commit f18f92d

Browse files
ksundenksunden
committed
Update docs for v3.10.1
1 parent 93b2ed9 commit f18f92d

File tree

10,353 files changed

+3110734
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

10,353 files changed

+3110734
-3
lines changed

Diff for: ‎3.10.1/Matplotlib.pdf

54.8 MB
Binary file not shown.

Diff for: ‎3.10.1/_downloads/0017d0c84e03d6c5e463e23d8e570671/line_collection.ipynb

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"\n# Plot multiple lines using a LineCollection\n\nMatplotlib can efficiently draw multiple lines at once using a `~.LineCollection`.\n"
8+
]
9+
},
10+
{
11+
"cell_type": "code",
12+
"execution_count": null,
13+
"metadata": {
14+
"collapsed": false
15+
},
16+
"outputs": [],
17+
"source": [
18+
"import matplotlib.pyplot as plt\nimport numpy as np\n\nfrom matplotlib.collections import LineCollection\n\ncolors = [\"indigo\", \"blue\", \"green\", \"yellow\", \"orange\", \"red\"]\n\n# create a list of half-circles with varying radii\ntheta = np.linspace(0, np.pi, 36)\nradii = np.linspace(4, 5, num=len(colors))\narcs = [np.column_stack([r * np.cos(theta), r * np.sin(theta)]) for r in radii]\n\nfig, ax = plt.subplots(figsize=(6.4, 3.2))\n# set axes limits manually because Collections do not take part in autoscaling\nax.set_xlim(-6, 6)\nax.set_ylim(0, 6)\nax.set_aspect(\"equal\") # to make the arcs look circular\n\n# create a LineCollection with the half-circles\n# its properties can be set per line by passing a sequence (here used for *colors*)\n# or they can be set for all lines by passing a scalar (here used for *linewidths*)\nline_collection = LineCollection(arcs, colors=colors, linewidths=4)\nax.add_collection(line_collection)\n\nplt.show()"
19+
]
20+
},
21+
{
22+
"cell_type": "markdown",
23+
"metadata": {},
24+
"source": [
25+
"Instead of passing a list of colors (``colors=colors``), we can alternatively use\ncolormapping. The lines are then color-coded based on an additional array of values\npassed to the *array* parameter. In the below example, we color the lines based on\ntheir radius by passing ``array=radii``.\n\n"
26+
]
27+
},
28+
{
29+
"cell_type": "code",
30+
"execution_count": null,
31+
"metadata": {
32+
"collapsed": false
33+
},
34+
"outputs": [],
35+
"source": [
36+
"num_arcs = 15\ntheta = np.linspace(0, np.pi, 36)\nradii = np.linspace(4, 5.5, num=num_arcs)\narcs = [np.column_stack([r * np.cos(theta), r * np.sin(theta)]) for r in radii]\n\nfig, ax = plt.subplots(figsize=(6.4, 3))\n# set axes limits manually because Collections do not take part in autoscaling\nax.set_xlim(-6, 6)\nax.set_ylim(0, 6)\nax.set_aspect(\"equal\") # to make the arcs look circular\n\n# create a LineCollection with the half-circles and color mapping\nline_collection = LineCollection(arcs, array=radii, cmap=\"rainbow\")\nax.add_collection(line_collection)\n\nfig.colorbar(line_collection, label=\"Radius\")\nax.set_title(\"Line Collection with mapped colors\")\n\nplt.show()"
37+
]
38+
},
39+
{
40+
"cell_type": "markdown",
41+
"metadata": {},
42+
"source": [
43+
".. admonition:: References\n\n The use of the following functions, methods, classes and modules is shown\n in this example:\n\n - `matplotlib.collections.LineCollection`\n - `matplotlib.collections.Collection.set_array`\n - `matplotlib.axes.Axes.add_collection`\n - `matplotlib.figure.Figure.colorbar` / `matplotlib.pyplot.colorbar`\n\n"
44+
]
45+
}
46+
],
47+
"metadata": {
48+
"kernelspec": {
49+
"display_name": "Python 3",
50+
"language": "python",
51+
"name": "python3"
52+
},
53+
"language_info": {
54+
"codemirror_mode": {
55+
"name": "ipython",
56+
"version": 3
57+
},
58+
"file_extension": ".py",
59+
"mimetype": "text/x-python",
60+
"name": "python",
61+
"nbconvert_exporter": "python",
62+
"pygments_lexer": "ipython3",
63+
"version": "3.13.2"
64+
}
65+
},
66+
"nbformat": 4,
67+
"nbformat_minor": 0
68+
}

Diff for: ‎3.10.1/_downloads/0058fbe25cf21cd7c40fb5bd22f92895/axes_units.ipynb

+266
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"\n\n# Plotting dates and strings\n\nThe most basic way to use Matplotlib plotting methods is to pass coordinates in\nas numerical numpy arrays. For example, ``plot(x, y)`` will work if ``x`` and\n``y`` are numpy arrays of floats (or integers). Plotting methods will also\nwork if `numpy.asarray` will convert ``x`` and ``y`` to an array of floating\npoint numbers; e.g. ``x`` could be a python list.\n\nMatplotlib also has the ability to convert other data types if a \"unit\nconverter\" exists for the data type. Matplotlib has two built-in converters,\none for dates and the other for lists of strings. Other downstream libraries\nhave their own converters to handle their data types.\n\nThe method to add converters to Matplotlib is described in `matplotlib.units`.\nHere we briefly overview the built-in date and string converters.\n\n## Date conversion\n\nIf ``x`` and/or ``y`` are a list of `datetime` or an array of\n`numpy.datetime64`, Matplotlib has a built-in converter that will convert the\ndatetime to a float, and add tick locators and formatters to the axis that are\nappropriate for dates. See `matplotlib.dates`.\n\nIn the following example, the x-axis gains a converter that converts from\n`numpy.datetime64` to float, and a locator that put ticks at the beginning of\nthe month, and a formatter that label the ticks appropriately:\n"
8+
]
9+
},
10+
{
11+
"cell_type": "code",
12+
"execution_count": null,
13+
"metadata": {
14+
"collapsed": false
15+
},
16+
"outputs": [],
17+
"source": [
18+
"import numpy as np\n\nimport matplotlib.dates as mdates\nimport matplotlib.units as munits\n\nimport matplotlib.pyplot as plt\n\nfig, ax = plt.subplots(figsize=(5.4, 2), layout='constrained')\ntime = np.arange('1980-01-01', '1980-06-25', dtype='datetime64[D]')\nx = np.arange(len(time))\nax.plot(time, x)"
19+
]
20+
},
21+
{
22+
"cell_type": "markdown",
23+
"metadata": {},
24+
"source": [
25+
"Note that if we try to plot a float on the x-axis, it will be plotted in\nunits of days since the \"epoch\" for the converter, in this case 1970-01-01\n(see `date-format`). So when we plot the value 0, the ticks start at\n1970-01-01. (The locator also now chooses every two years for a tick instead\nof every month):\n\n"
26+
]
27+
},
28+
{
29+
"cell_type": "code",
30+
"execution_count": null,
31+
"metadata": {
32+
"collapsed": false
33+
},
34+
"outputs": [],
35+
"source": [
36+
"fig, ax = plt.subplots(figsize=(5.4, 2), layout='constrained')\ntime = np.arange('1980-01-01', '1980-06-25', dtype='datetime64[D]')\nx = np.arange(len(time))\nax.plot(time, x)\n# 0 gets labeled as 1970-01-01\nax.plot(0, 0, 'd')\nax.text(0, 0, ' Float x=0', rotation=45)"
37+
]
38+
},
39+
{
40+
"cell_type": "markdown",
41+
"metadata": {},
42+
"source": [
43+
"We can customize the locator and the formatter; see `date-locators` and\n`date-formatters` for a complete list, and\n`date_formatters_locators` for examples of them in use. Here we locate\nby every second month, and format just with the month's 3-letter name using\n``\"%b\"`` (see `~datetime.datetime.strftime` for format codes):\n\n"
44+
]
45+
},
46+
{
47+
"cell_type": "code",
48+
"execution_count": null,
49+
"metadata": {
50+
"collapsed": false
51+
},
52+
"outputs": [],
53+
"source": [
54+
"fig, ax = plt.subplots(figsize=(5.4, 2), layout='constrained')\ntime = np.arange('1980-01-01', '1980-06-25', dtype='datetime64[D]')\nx = np.arange(len(time))\nax.plot(time, x)\nax.xaxis.set_major_locator(mdates.MonthLocator(bymonth=np.arange(1, 13, 2)))\nax.xaxis.set_major_formatter(mdates.DateFormatter('%b'))\nax.set_xlabel('1980')"
55+
]
56+
},
57+
{
58+
"cell_type": "markdown",
59+
"metadata": {},
60+
"source": [
61+
"The default locator is the `~.dates.AutoDateLocator`, and the default\nFormatter `~.dates.AutoDateFormatter`. There are also \"concise\" formatter\nand locators that give a more compact labelling, and can be set via rcParams.\nNote how instead of the redundant \"Jan\" label at the start of the year,\n\"1980\" is used instead. See `date_concise_formatter` for more examples.\n\n"
62+
]
63+
},
64+
{
65+
"cell_type": "code",
66+
"execution_count": null,
67+
"metadata": {
68+
"collapsed": false
69+
},
70+
"outputs": [],
71+
"source": [
72+
"plt.rcParams['date.converter'] = 'concise'\n\nfig, ax = plt.subplots(figsize=(5.4, 2), layout='constrained')\ntime = np.arange('1980-01-01', '1980-06-25', dtype='datetime64[D]')\nx = np.arange(len(time))\nax.plot(time, x)"
73+
]
74+
},
75+
{
76+
"cell_type": "markdown",
77+
"metadata": {},
78+
"source": [
79+
"We can set the limits on the axis either by passing the appropriate dates as\nlimits, or by passing a floating-point value in the proper units of days\nsince the epoch. If we need it, we can get this value from\n`~.dates.date2num`.\n\n"
80+
]
81+
},
82+
{
83+
"cell_type": "code",
84+
"execution_count": null,
85+
"metadata": {
86+
"collapsed": false
87+
},
88+
"outputs": [],
89+
"source": [
90+
"fig, axs = plt.subplots(2, 1, figsize=(5.4, 3), layout='constrained')\nfor ax in axs.flat:\n time = np.arange('1980-01-01', '1980-06-25', dtype='datetime64[D]')\n x = np.arange(len(time))\n ax.plot(time, x)\n\n# set xlim using datetime64:\naxs[0].set_xlim(np.datetime64('1980-02-01'), np.datetime64('1980-04-01'))\n\n# set xlim using floats:\n# Note can get from mdates.date2num(np.datetime64('1980-02-01'))\naxs[1].set_xlim(3683, 3683+60)"
91+
]
92+
},
93+
{
94+
"cell_type": "markdown",
95+
"metadata": {},
96+
"source": [
97+
"## String conversion: categorical plots\n\nSometimes we want to label categories on an axis rather than numbers.\nMatplotlib allows this using a \"categorical\" converter (see\n`~.matplotlib.category`).\n\n"
98+
]
99+
},
100+
{
101+
"cell_type": "code",
102+
"execution_count": null,
103+
"metadata": {
104+
"collapsed": false
105+
},
106+
"outputs": [],
107+
"source": [
108+
"data = {'apple': 10, 'orange': 15, 'lemon': 5, 'lime': 20}\nnames = list(data.keys())\nvalues = list(data.values())\n\nfig, axs = plt.subplots(1, 3, figsize=(7, 3), sharey=True, layout='constrained')\naxs[0].bar(names, values)\naxs[1].scatter(names, values)\naxs[2].plot(names, values)\nfig.suptitle('Categorical Plotting')"
109+
]
110+
},
111+
{
112+
"cell_type": "markdown",
113+
"metadata": {},
114+
"source": [
115+
"Note that the \"categories\" are plotted in the order that they are first\nspecified and that subsequent plotting in a different order will not affect\nthe original order. Further, new additions will be added on the end (see\n\"pear\" below):\n\n"
116+
]
117+
},
118+
{
119+
"cell_type": "code",
120+
"execution_count": null,
121+
"metadata": {
122+
"collapsed": false
123+
},
124+
"outputs": [],
125+
"source": [
126+
"fig, ax = plt.subplots(figsize=(5, 3), layout='constrained')\nax.bar(names, values)\n\n# plot in a different order:\nax.scatter(['lemon', 'apple'], [7, 12])\n\n# add a new category, \"pear\", and put the other categories in a different order:\nax.plot(['pear', 'orange', 'apple', 'lemon'], [13, 10, 7, 12], color='C1')"
127+
]
128+
},
129+
{
130+
"cell_type": "markdown",
131+
"metadata": {},
132+
"source": [
133+
"Note that when using ``plot`` like in the above, the order of the plotting is\nmapped onto the original order of the data, so the new line goes in the order\nspecified.\n\nThe category converter maps from categories to integers, starting at zero. So\ndata can also be manually added to the axis using a float. Note that if a\nfloat is passed in that does not have a \"category\" associated with it, the\ndata point can still be plotted, but a tick will not be created. In the\nfollowing, we plot data at 4.0 and 2.5, but no tick is added there because\nthose are not categories.\n\n"
134+
]
135+
},
136+
{
137+
"cell_type": "code",
138+
"execution_count": null,
139+
"metadata": {
140+
"collapsed": false
141+
},
142+
"outputs": [],
143+
"source": [
144+
"fig, ax = plt.subplots(figsize=(5, 3), layout='constrained')\nax.bar(names, values)\n# arguments for styling the labels below:\nargs = {'rotation': 70, 'color': 'C1',\n 'bbox': {'color': 'white', 'alpha': .7, 'boxstyle': 'round'}}\n\n\n# 0 gets labeled as \"apple\"\nax.plot(0, 2, 'd', color='C1')\nax.text(0, 3, 'Float x=0', **args)\n\n# 2 gets labeled as \"lemon\"\nax.plot(2, 2, 'd', color='C1')\nax.text(2, 3, 'Float x=2', **args)\n\n# 4 doesn't get a label\nax.plot(4, 2, 'd', color='C1')\nax.text(4, 3, 'Float x=4', **args)\n\n# 2.5 doesn't get a label\nax.plot(2.5, 2, 'd', color='C1')\nax.text(2.5, 3, 'Float x=2.5', **args)"
145+
]
146+
},
147+
{
148+
"cell_type": "markdown",
149+
"metadata": {},
150+
"source": [
151+
"Setting the limits for a category axis can be done by specifying the\ncategories, or by specifying floating point numbers:\n\n"
152+
]
153+
},
154+
{
155+
"cell_type": "code",
156+
"execution_count": null,
157+
"metadata": {
158+
"collapsed": false
159+
},
160+
"outputs": [],
161+
"source": [
162+
"fig, axs = plt.subplots(2, 1, figsize=(5, 5), layout='constrained')\nax = axs[0]\nax.bar(names, values)\nax.set_xlim('orange', 'lemon')\nax.set_xlabel('limits set with categories')\nax = axs[1]\nax.bar(names, values)\nax.set_xlim(0.5, 2.5)\nax.set_xlabel('limits set with floats')"
163+
]
164+
},
165+
{
166+
"cell_type": "markdown",
167+
"metadata": {},
168+
"source": [
169+
"The category axes are helpful for some plot types, but can lead to confusion\nif data is read in as a list of strings, even if it is meant to be a list of\nfloats or dates. This sometimes happens when reading comma-separated value\n(CSV) files. The categorical locator and formatter will put a tick at every\nstring value and label each one as well:\n\n"
170+
]
171+
},
172+
{
173+
"cell_type": "code",
174+
"execution_count": null,
175+
"metadata": {
176+
"collapsed": false
177+
},
178+
"outputs": [],
179+
"source": [
180+
"fig, ax = plt.subplots(figsize=(5.4, 2.5), layout='constrained')\nx = [str(xx) for xx in np.arange(100)] # list of strings\nax.plot(x, np.arange(100))\nax.set_xlabel('x is list of strings')"
181+
]
182+
},
183+
{
184+
"cell_type": "markdown",
185+
"metadata": {},
186+
"source": [
187+
"If this is not desired, then simply convert the data to floats before plotting:\n\n"
188+
]
189+
},
190+
{
191+
"cell_type": "code",
192+
"execution_count": null,
193+
"metadata": {
194+
"collapsed": false
195+
},
196+
"outputs": [],
197+
"source": [
198+
"fig, ax = plt.subplots(figsize=(5.4, 2.5), layout='constrained')\nx = np.asarray(x, dtype='float') # array of float.\nax.plot(x, np.arange(100))\nax.set_xlabel('x is array of floats')"
199+
]
200+
},
201+
{
202+
"cell_type": "markdown",
203+
"metadata": {},
204+
"source": [
205+
"## Determine converter, formatter, and locator on an axis\n\nSometimes it is helpful to be able to debug what Matplotlib is using to\nconvert the incoming data. We can do that by querying the ``converter``\nproperty on the axis. We can also query the formatters and locators using\n`~.axis.Axis.get_major_locator` and `~.axis.Axis.get_major_formatter`.\n\nNote that by default the converter is *None*.\n\n"
206+
]
207+
},
208+
{
209+
"cell_type": "code",
210+
"execution_count": null,
211+
"metadata": {
212+
"collapsed": false
213+
},
214+
"outputs": [],
215+
"source": [
216+
"fig, axs = plt.subplots(3, 1, figsize=(6.4, 7), layout='constrained')\nx = np.arange(100)\nax = axs[0]\nax.plot(x, x)\nlabel = f'Converter: {ax.xaxis.get_converter()}\\n '\nlabel += f'Locator: {ax.xaxis.get_major_locator()}\\n'\nlabel += f'Formatter: {ax.xaxis.get_major_formatter()}\\n'\nax.set_xlabel(label)\n\nax = axs[1]\ntime = np.arange('1980-01-01', '1980-06-25', dtype='datetime64[D]')\nx = np.arange(len(time))\nax.plot(time, x)\nlabel = f'Converter: {ax.xaxis.get_converter()}\\n '\nlabel += f'Locator: {ax.xaxis.get_major_locator()}\\n'\nlabel += f'Formatter: {ax.xaxis.get_major_formatter()}\\n'\nax.set_xlabel(label)\n\nax = axs[2]\ndata = {'apple': 10, 'orange': 15, 'lemon': 5, 'lime': 20}\nnames = list(data.keys())\nvalues = list(data.values())\nax.plot(names, values)\nlabel = f'Converter: {ax.xaxis.get_converter()}\\n '\nlabel += f'Locator: {ax.xaxis.get_major_locator()}\\n'\nlabel += f'Formatter: {ax.xaxis.get_major_formatter()}\\n'\nax.set_xlabel(label)"
217+
]
218+
},
219+
{
220+
"cell_type": "markdown",
221+
"metadata": {},
222+
"source": [
223+
"## More about \"unit\" support\n\nThe support for dates and categories is part of \"units\" support that is built\ninto Matplotlib. This is described at `.matplotlib.units` and in the\n`basic_units` example.\n\nUnit support works by querying the type of data passed to the plotting\nfunction and dispatching to the first converter in a list that accepts that\ntype of data. So below, if ``x`` has ``datetime`` objects in it, the\nconverter will be ``_SwitchableDateConverter``; if it has has strings in it,\nit will be sent to the ``StrCategoryConverter``.\n\n"
224+
]
225+
},
226+
{
227+
"cell_type": "code",
228+
"execution_count": null,
229+
"metadata": {
230+
"collapsed": false
231+
},
232+
"outputs": [],
233+
"source": [
234+
"for k, v in munits.registry.items():\n print(f\"type: {k};\\n converter: {type(v)}\")"
235+
]
236+
},
237+
{
238+
"cell_type": "markdown",
239+
"metadata": {},
240+
"source": [
241+
"There are a number of downstream libraries that provide their own converters\nwith locators and formatters. Physical unit support is provided by\n[astropy](https://www.astropy.org), [pint](https://pint.readthedocs.io), and\n[unyt](https://unyt.readthedocs.io), among others.\n\nHigh level libraries like [pandas](https://pandas.pydata.org) and\n[nc-time-axis](https://nc-time-axis.readthedocs.io) (and thus\n[xarray](https://docs.xarray.dev)) provide their own datetime support.\nThis support can sometimes be incompatible with Matplotlib native datetime\nsupport, so care should be taken when using Matplotlib locators and\nformatters if these libraries are being used.\n\n"
242+
]
243+
}
244+
],
245+
"metadata": {
246+
"kernelspec": {
247+
"display_name": "Python 3",
248+
"language": "python",
249+
"name": "python3"
250+
},
251+
"language_info": {
252+
"codemirror_mode": {
253+
"name": "ipython",
254+
"version": 3
255+
},
256+
"file_extension": ".py",
257+
"mimetype": "text/x-python",
258+
"name": "python",
259+
"nbconvert_exporter": "python",
260+
"pygments_lexer": "ipython3",
261+
"version": "3.13.2"
262+
}
263+
},
264+
"nbformat": 4,
265+
"nbformat_minor": 0
266+
}

Diff for: ‎3.10.1/_downloads/008c73d5ac1c4af82c0b90fde922ebb9/stairs.py

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
"""
2+
==============
3+
stairs(values)
4+
==============
5+
Draw a stepwise constant function as a line or a filled plot.
6+
7+
See `~matplotlib.axes.Axes.stairs` when plotting :math:`y` between
8+
:math:`(x_i, x_{i+1})`. For plotting :math:`y` at :math:`x`, see
9+
`~matplotlib.axes.Axes.step`.
10+
11+
.. redirect-from:: /plot_types/basic/step
12+
"""
13+
import matplotlib.pyplot as plt
14+
import numpy as np
15+
16+
plt.style.use('_mpl-gallery')
17+
18+
# make data
19+
y = [4.8, 5.5, 3.5, 4.6, 6.5, 6.6, 2.6, 3.0]
20+
21+
# plot
22+
fig, ax = plt.subplots()
23+
24+
ax.stairs(y, linewidth=2.5)
25+
26+
ax.set(xlim=(0, 8), xticks=np.arange(1, 8),
27+
ylim=(0, 8), yticks=np.arange(1, 8))
28+
29+
plt.show()

Diff for: ‎3.10.1/_downloads/008dacd6028779838d22c9578023d145/api_interfaces-7.2x.png

56 KB
Loading

Diff for: ‎3.10.1/_downloads/00aacc25eb4ed2eaffa3c821d5562b6d/whats_new_3-6-0-5.py

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
x = np.linspace(1., 3., 10)
2+
y = x**3
3+
4+
fig, ax = plt.subplots()
5+
ax.plot(x, y, linestyle='--', color='orange', gapcolor='blue',
6+
linewidth=3, label='a striped line')
7+
ax.legend()

Diff for: ‎3.10.1/_downloads/00acb51f759431356d920d5a71341b06/whats_new_3-6-0-7.png

9.53 KB
Loading

Diff for: ‎3.10.1/_downloads/00c5504fb7c2dac95f97dfc7fb5df3a0/angles_on_bracket_arrows.zip

6.27 KB
Binary file not shown.

0 commit comments

Comments
 (0)