You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
<spanid="sphx-glr-tutorials-pyplot-py"></span><spanid="id1"></span><h1>Pyplot tutorial<aclass="headerlink" href="#pyplot-tutorial" title="Link to this heading">#</a></h1>
<p>An introduction to the pyplot interface. Please also see
<aclass="reference internal" href="../users/explain/quick_start.html#quick-start"><spanclass="std std-ref">Quick start guide</span></a> for an overview of how Matplotlib
works and <aclass="reference internal" href="../users/explain/figure/api_interfaces.html#api-interfaces"><spanclass="std std-ref">Matplotlib Application Interfaces (APIs)</span></a> for an explanation of the trade-offs between the
supported user APIs.</p>
<sectionid="introduction-to-pyplot">
<h2>Introduction to pyplot<aclass="headerlink" href="#introduction-to-pyplot" title="Link to this heading">#</a></h2>
<p><aclass="reference internal" href="../api/pyplot_summary.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">matplotlib.pyplot</span></code></a> is a collection of functions that make matplotlib
work like MATLAB. Each <codeclass="docutils literal notranslate"><spanclass="pre">pyplot</span></code> function makes some change to a figure:
e.g., creates a figure, creates a plotting area in a figure, plots some lines
in a plotting area, decorates the plot with labels, etc.</p>
<p>In <aclass="reference internal" href="../api/pyplot_summary.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">matplotlib.pyplot</span></code></a> various states are preserved
across function calls, so that it keeps track of things like
the current figure and plotting area, and the plotting
functions are directed to the current Axes (please note that we use uppercase
Axes to refer to the <aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Axes</span></code></a> concept, which is a central
<aclass="reference internal" href="../users/explain/quick_start.html#figure-parts"><spanclass="std std-ref">part of a figure</span></a>
and not only the plural of <em>axis</em>).</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>The implicit pyplot API is generally less verbose but also not as flexible as the
explicit API. Most of the function calls you see here can also be called
as methods from an <codeclass="docutils literal notranslate"><spanclass="pre">Axes</span></code> object. We recommend browsing the tutorials
and examples to see how this works. See <aclass="reference internal" href="../users/explain/figure/api_interfaces.html#api-interfaces"><spanclass="std std-ref">Matplotlib Application Interfaces (APIs)</span></a> for an
explanation of the trade-off of the supported user APIs.</p>
</div>
<p>Generating visualizations with pyplot is very quick:</p>
<imgsrc="../_images/sphx_glr_pyplot_001.png" srcset="../_images/sphx_glr_pyplot_001.png, ../_images/sphx_glr_pyplot_001_2_00x.png 2.00x" alt="pyplot" class = "sphx-glr-single-img"/><p>You may be wondering why the x-axis ranges from 0-3 and the y-axis
from 1-4. If you provide a single list or array to
<aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">plot</span></code></a>, matplotlib assumes it is a
sequence of y values, and automatically generates the x values for
you. Since python ranges start with 0, the default x vector has the
same length as y but starts with 0; therefore, the x data are
<p><aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">plot</span></code></a> is a versatile function, and will take an arbitrary number of
arguments. For example, to plot x versus y, you can write:</p>
<imgsrc="../_images/sphx_glr_pyplot_003.png" srcset="../_images/sphx_glr_pyplot_003.png, ../_images/sphx_glr_pyplot_003_2_00x.png 2.00x" alt="pyplot" class = "sphx-glr-single-img"/><p>See the <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">plot</span></code></a> documentation for a complete
list of line styles and format strings. The
<aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.axis.html#matplotlib.pyplot.axis" title="matplotlib.pyplot.axis"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">axis</span></code></a> function in the example above takes a
list of <codeclass="docutils literal notranslate"><spanclass="pre">[xmin,</span><spanclass="pre">xmax,</span><spanclass="pre">ymin,</span><spanclass="pre">ymax]</span></code> and specifies the viewport of the
Axes.</p>
<p>If matplotlib were limited to working with lists, it would be fairly
useless for numeric processing. Generally, you will use <aclass="reference external" href="https://numpy.org/">numpy</a> arrays. In fact, all sequences are
converted to numpy arrays internally. The example below illustrates
plotting several lines with different format styles in one function call
<imgsrc="../_images/sphx_glr_pyplot_004.png" srcset="../_images/sphx_glr_pyplot_004.png, ../_images/sphx_glr_pyplot_004_2_00x.png 2.00x" alt="pyplot" class = "sphx-glr-single-img"/></section>
</section>
<sectionid="plotting-with-keyword-strings">
<spanid="plotting-with-keywords"></span><h2>Plotting with keyword strings<aclass="headerlink" href="#plotting-with-keyword-strings" title="Link to this heading">#</a></h2>
<p>There are some instances where you have data in a format that lets you
access particular variables with strings. For example, with <aclass="reference external" href="https://numpy.org/doc/stable/user/basics.rec.html#structured-arrays">structured arrays</a>
<imgsrc="../_images/sphx_glr_pyplot_005.png" srcset="../_images/sphx_glr_pyplot_005.png, ../_images/sphx_glr_pyplot_005_2_00x.png 2.00x" alt="pyplot" class = "sphx-glr-single-img"/></section>
<sectionid="plotting-with-categorical-variables">
<spanid="plotting-with-categorical-vars"></span><h2>Plotting with categorical variables<aclass="headerlink" href="#plotting-with-categorical-variables" title="Link to this heading">#</a></h2>
<p>It is also possible to create a plot using categorical variables.
Matplotlib allows you to pass categorical variables directly to
<imgsrc="../_images/sphx_glr_pyplot_006.png" srcset="../_images/sphx_glr_pyplot_006.png, ../_images/sphx_glr_pyplot_006_2_00x.png 2.00x" alt="Categorical Plotting" class = "sphx-glr-single-img"/></section>
<sectionid="controlling-line-properties">
<spanid="id2"></span><h2>Controlling line properties<aclass="headerlink" href="#controlling-line-properties" title="Link to this heading">#</a></h2>
<p>Lines have many attributes that you can set: linewidth, dash style,
antialiased, etc; see <aclass="reference internal" href="../api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.lines.Line2D</span></code></a>. There are
<li><p>Use the setter methods of a <codeclass="docutils literal notranslate"><spanclass="pre">Line2D</span></code> instance. <codeclass="docutils literal notranslate"><spanclass="pre">plot</span></code> returns a list
of <codeclass="docutils literal notranslate"><spanclass="pre">Line2D</span></code> objects; e.g., <codeclass="docutils literal notranslate"><spanclass="pre">line1,</span><spanclass="pre">line2</span><spanclass="pre">=</span><spanclass="pre">plot(x1,</span><spanclass="pre">y1,</span><spanclass="pre">x2,</span><spanclass="pre">y2)</span></code>. In the code
below we will suppose that we have only
one line so that the list returned is of length 1. We use tuple unpacking with
<codeclass="docutils literal notranslate"><spanclass="pre">line,</span></code> to get the first element of that list:</p>
<p>Here are the available <aclass="reference internal" href="../api/_as_gen/matplotlib.lines.Line2D.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Line2D</span></code></a> properties.</p>
<p>To get a list of settable line properties, call the
<aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.setp.html#matplotlib.pyplot.setp" title="matplotlib.pyplot.setp"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">setp</span></code></a> function with a line or lines as argument</p>
<spanid="multiple-figs-axes"></span><h2>Working with multiple figures and Axes<aclass="headerlink" href="#working-with-multiple-figures-and-axes" title="Link to this heading">#</a></h2>
<p>MATLAB, and <aclass="reference internal" href="../api/pyplot_summary.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">pyplot</span></code></a>, have the concept of the current figure
and the current Axes. All plotting functions apply to the current
Axes. The function <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.gca.html#matplotlib.pyplot.gca" title="matplotlib.pyplot.gca"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">gca</span></code></a> returns the current Axes (a
<aclass="reference internal" href="../api/_as_gen/matplotlib.axes.Axes.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.axes.Axes</span></code></a> instance), and <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.gcf.html#matplotlib.pyplot.gcf" title="matplotlib.pyplot.gcf"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">gcf</span></code></a> returns the current
figure (a <aclass="reference internal" href="../api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.figure.Figure</span></code></a> instance). Normally, you don't have to
worry about this, because it is all taken care of behind the scenes. Below
<imgsrc="../_images/sphx_glr_pyplot_007.png" srcset="../_images/sphx_glr_pyplot_007.png, ../_images/sphx_glr_pyplot_007_2_00x.png 2.00x" alt="pyplot" class = "sphx-glr-single-img"/><p>The <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.figure.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">figure</span></code></a> call here is optional because a figure will be created
if none exists, just as an Axes will be created (equivalent to an explicit
<codeclass="docutils literal notranslate"><spanclass="pre">subplot()</span></code> call) if none exists.
<spanclass="pre">numcols,</span><spanclass="pre">plot_number</span></code> where <codeclass="docutils literal notranslate"><spanclass="pre">plot_number</span></code> ranges from 1 to
<codeclass="docutils literal notranslate"><spanclass="pre">numrows*numcols</span></code>. The commas in the <codeclass="docutils literal notranslate"><spanclass="pre">subplot</span></code> call are
optional if <codeclass="docutils literal notranslate"><spanclass="pre">numrows*numcols<10</span></code>. So <codeclass="docutils literal notranslate"><spanclass="pre">subplot(211)</span></code> is identical
to <codeclass="docutils literal notranslate"><spanclass="pre">subplot(2,</span><spanclass="pre">1,</span><spanclass="pre">1)</span></code>.</p>
<p>You can create an arbitrary number of subplots
and Axes. If you want to place an Axes manually, i.e., not on a
which allows you to specify the location as <codeclass="docutils literal notranslate"><spanclass="pre">axes([left,</span><spanclass="pre">bottom,</span>
<spanclass="pre">width,</span><spanclass="pre">height])</span></code> where all values are in fractional (0 to 1)
coordinates. See <aclass="reference internal" href="../gallery/subplots_axes_and_figures/axes_demo.html"><spanclass="doc">Axes Demo</span></a> for an example of
placing Axes manually and <aclass="reference internal" href="../gallery/subplots_axes_and_figures/subplot.html"><spanclass="doc">Multiple subplots</span></a> for an
example with lots of subplots.</p>
<p>You can create multiple figures by using multiple
<aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.figure.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">figure</span></code></a> calls with an increasing figure
number. Of course, each figure can contain as many Axes and subplots
<ahref="../api/_as_gen/matplotlib.pyplot.figure.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure" class="sphx-glr-backref-module-matplotlib-pyplot sphx-glr-backref-type-py-function"><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">figure</span></a><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">)</span><spanclass="c1"># the first figure</span>
<ahref="../api/_as_gen/matplotlib.pyplot.subplot.html#matplotlib.pyplot.subplot" title="matplotlib.pyplot.subplot" class="sphx-glr-backref-module-matplotlib-pyplot sphx-glr-backref-type-py-function"><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">subplot</span></a><spanclass="p">(</span><spanclass="mi">211</span><spanclass="p">)</span><spanclass="c1"># the first subplot in the first figure</span>
<ahref="../api/_as_gen/matplotlib.pyplot.subplot.html#matplotlib.pyplot.subplot" title="matplotlib.pyplot.subplot" class="sphx-glr-backref-module-matplotlib-pyplot sphx-glr-backref-type-py-function"><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">subplot</span></a><spanclass="p">(</span><spanclass="mi">212</span><spanclass="p">)</span><spanclass="c1"># the second subplot in the first figure</span>
<ahref="../api/_as_gen/matplotlib.pyplot.figure.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure" class="sphx-glr-backref-module-matplotlib-pyplot sphx-glr-backref-type-py-function"><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">figure</span></a><spanclass="p">(</span><spanclass="mi">2</span><spanclass="p">)</span><spanclass="c1"># a second figure</span>
<ahref="../api/_as_gen/matplotlib.pyplot.plot.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot" class="sphx-glr-backref-module-matplotlib-pyplot sphx-glr-backref-type-py-function"><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">plot</span></a><spanclass="p">([</span><spanclass="mi">4</span><spanclass="p">,</span><spanclass="mi">5</span><spanclass="p">,</span><spanclass="mi">6</span><spanclass="p">])</span><spanclass="c1"># creates a subplot() by default</span>
<ahref="../api/_as_gen/matplotlib.pyplot.figure.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure" class="sphx-glr-backref-module-matplotlib-pyplot sphx-glr-backref-type-py-function"><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">figure</span></a><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">)</span><spanclass="c1"># first figure current;</span>
<spanclass="c1"># subplot(212) still current</span>
<ahref="../api/_as_gen/matplotlib.pyplot.subplot.html#matplotlib.pyplot.subplot" title="matplotlib.pyplot.subplot" class="sphx-glr-backref-module-matplotlib-pyplot sphx-glr-backref-type-py-function"><spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">subplot</span></a><spanclass="p">(</span><spanclass="mi">211</span><spanclass="p">)</span><spanclass="c1"># make subplot(211) in the first figure</span>
<p>You can clear the current figure with <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.clf.html#matplotlib.pyplot.clf" title="matplotlib.pyplot.clf"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">clf</span></code></a>
and the current Axes with <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.cla.html#matplotlib.pyplot.cla" title="matplotlib.pyplot.cla"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">cla</span></code></a>. If you find
it annoying that states (specifically the current image, figure and Axes)
are being maintained for you behind the scenes, don't despair: this is just a thin
stateful wrapper around an object-oriented API, which you can use
instead (see <aclass="reference internal" href="artists.html#artists-tutorial"><spanclass="std std-ref">Artist tutorial</span></a>)</p>
<p>If you are making lots of figures, you need to be aware of one
more thing: the memory required for a figure is not completely
released until the figure is explicitly closed with
<aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.close.html#matplotlib.pyplot.close" title="matplotlib.pyplot.close"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">close</span></code></a>. Deleting all references to the
figure, and/or using the window manager to kill the window in which
the figure appears on the screen, is not enough, because pyplot
<spanid="id3"></span><h2>Working with text<aclass="headerlink" href="#working-with-text" title="Link to this heading">#</a></h2>
<p><aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.text.html#matplotlib.pyplot.text" title="matplotlib.pyplot.text"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">text</span></code></a> can be used to add text in an arbitrary location, and
<aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.xlabel.html#matplotlib.pyplot.xlabel" title="matplotlib.pyplot.xlabel"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">xlabel</span></code></a>, <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.ylabel.html#matplotlib.pyplot.ylabel" title="matplotlib.pyplot.ylabel"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">ylabel</span></code></a> and <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.title.html#matplotlib.pyplot.title" title="matplotlib.pyplot.title"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">title</span></code></a> are used to add
text in the indicated locations (see <aclass="reference internal" href="../users/explain/text/text_intro.html#text-intro"><spanclass="std std-ref">Text in Matplotlib</span></a> for a
<imgsrc="../_images/sphx_glr_pyplot_008.png" srcset="../_images/sphx_glr_pyplot_008.png, ../_images/sphx_glr_pyplot_008_2_00x.png 2.00x" alt="Histogram of IQ" class = "sphx-glr-single-img"/><p>All of the <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.text.html#matplotlib.pyplot.text" title="matplotlib.pyplot.text"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">text</span></code></a> functions return a <aclass="reference internal" href="../api/text_api.html#matplotlib.text.Text" title="matplotlib.text.Text"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">matplotlib.text.Text</span></code></a>
instance. Just as with lines above, you can customize the properties by
passing keyword arguments into the text functions or using <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.setp.html#matplotlib.pyplot.setp" title="matplotlib.pyplot.setp"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">setp</span></code></a>:</p>
<p>These properties are covered in more detail in <aclass="reference internal" href="../users/explain/text/text_props.html#text-props"><spanclass="std std-ref">Text properties and layout</span></a>.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">r</span></code> preceding the title string is important -- it signifies
that the string is a <em>raw</em> string and not to treat backslashes as
python escapes. matplotlib has a built-in TeX expression parser and
layout engine, and ships its own math fonts -- for details see
<aclass="reference internal" href="../users/explain/text/mathtext.html#mathtext"><spanclass="std std-ref">Writing mathematical expressions</span></a>. Thus, you can use mathematical text across
platforms without requiring a TeX installation. For those who have LaTeX
and dvipng installed, you can also use LaTeX to format your text and
incorporate the output directly into your display figures or saved
postscript -- see <aclass="reference internal" href="../users/explain/text/usetex.html#usetex"><spanclass="std std-ref">Text rendering with LaTeX</span></a>.</p>
</section>
<sectionid="annotating-text">
<h3>Annotating text<aclass="headerlink" href="#annotating-text" title="Link to this heading">#</a></h3>
<p>The uses of the basic <aclass="reference internal" href="../api/_as_gen/matplotlib.pyplot.text.html#matplotlib.pyplot.text" title="matplotlib.pyplot.text"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">text</span></code></a> function above
place text at an arbitrary position on the Axes. A common use for
text is to annotate some feature of the plot, and the
functionality to make annotations easy. In an annotation, there are
two points to consider: the location being annotated represented by
the argument <codeclass="docutils literal notranslate"><spanclass="pre">xy</span></code> and the location of the text <codeclass="docutils literal notranslate"><spanclass="pre">xytext</span></code>. Both of
these arguments are <codeclass="docutils literal notranslate"><spanclass="pre">(x,</span><spanclass="pre">y)</span></code> tuples.</p>
<imgsrc="../_images/sphx_glr_pyplot_009.png" srcset="../_images/sphx_glr_pyplot_009.png, ../_images/sphx_glr_pyplot_009_2_00x.png 2.00x" alt="pyplot" class = "sphx-glr-single-img"/><p>In this basic example, both the <codeclass="docutils literal notranslate"><spanclass="pre">xy</span></code> (arrow tip) and <codeclass="docutils literal notranslate"><spanclass="pre">xytext</span></code>
locations (text location) are in data coordinates. There are a
variety of other coordinate systems one can choose -- see
<aclass="reference internal" href="../users/explain/text/annotations.html#annotations-tutorial"><spanclass="std std-ref">Basic annotation</span></a> and <aclass="reference internal" href="../users/explain/text/annotations.html#plotting-guide-annotation"><spanclass="std std-ref">Advanced annotation</span></a> for
<h2>Logarithmic and other nonlinear axes<aclass="headerlink" href="#logarithmic-and-other-nonlinear-axes" title="Link to this heading">#</a></h2>
<p><aclass="reference internal" href="../api/pyplot_summary.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">matplotlib.pyplot</span></code></a> supports not only linear axis scales, but also
logarithmic and logit scales. This is commonly used if data spans many orders
of magnitude. Changing the scale of an axis is easy:</p>