<divid="unreleased-message"> You are reading an old version of the documentation (v1.2.1). For the latest version see <ahref="/stable/">https://matplotlib.org/stable/</a></div>
<spanid="id1"></span><h1>Pyplot tutorial<aclass="headerlink" href="#pyplot-tutorial" title="Permalink to this headline">¶</a></h1>
<p><aclass="reference internal" href="../api/pyplot_api.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><ttclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib.pyplot</span></tt></a> is a collection of command style functions
that make matplotlib work like MATLAB.
Each <ttclass="docutils literal"><spanclass="pre">pyplot</span></tt> function makes
some change to a figure: eg, create a figure, create a plotting area
in a figure, plot some lines in a plotting area, decorate the plot
with labels, etc.... <aclass="reference internal" href="../api/pyplot_api.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><ttclass="xref py py-mod docutils literal"><spanclass="pre">matplotlib.pyplot</span></tt></a> is stateful, in that it
keeps track of the current figure and plotting area, and the plotting
<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 the
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><ttclass="xref py py-func docutils literal"><spanclass="pre">plot()</span></tt></a> command, 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. Hence the x data are
<p><aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><ttclass="xref py py-func docutils literal"><spanclass="pre">plot()</span></tt></a> is a versatile command, and will take
an arbitrary number of arguments. For example, to plot x versus y,
<p>See the <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.plot" title="matplotlib.pyplot.plot"><ttclass="xref py py-func docutils literal"><spanclass="pre">plot()</span></tt></a> documentation for a complete
list of line styles and format strings. The
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.axis" title="matplotlib.pyplot.axis"><ttclass="xref py py-func docutils literal"><spanclass="pre">axis()</span></tt></a> command in the example above takes a
list of <ttclass="docutils literal"><spanclass="pre">[xmin,</span><spanclass="pre">xmax,</span><spanclass="pre">ymin,</span><spanclass="pre">ymax]</span></tt> 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="http://numpy.scipy.org">numpy</a> arrays. In fact, all sequences are
converted to numpy arrays internally. The example below illustrates a
plotting several lines with different format styles in one command
<spanid="id2"></span><h2>Controlling line properties<aclass="headerlink" href="#controlling-line-properties" title="Permalink to this headline">¶</a></h2>
<p>Lines have many attributes that you can set: linewidth, dash style,
antialiased, etc; see <aclass="reference internal" href="../api/artist_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><ttclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.lines.Line2D</span></tt></a>. There are
<li><pclass="first">Use the setter methods of the <ttclass="docutils literal"><spanclass="pre">Line2D</span></tt> instance. <ttclass="docutils literal"><spanclass="pre">plot</span></tt> returns a list
of lines; eg <ttclass="docutils literal"><spanclass="pre">line1,</span><spanclass="pre">line2</span><spanclass="pre">=</span><spanclass="pre">plot(x1,y1,x2,x2)</span></tt>. Below I have only
one line so it is a list of length 1. I use tuple unpacking in the
<ttclass="docutils literal"><spanclass="pre">line,</span><spanclass="pre">=</span><spanclass="pre">plot(x,</span><spanclass="pre">y,</span><spanclass="pre">'o')</span></tt> to get the first element of the list:</p>
<spanclass="n">line</span><spanclass="o">.</span><spanclass="n">set_antialiased</span><spanclass="p">(</span><spanclass="bp">False</span><spanclass="p">)</span><spanclass="c"># turn off antialising</span>
</pre></div>
</div>
</li>
<li><pclass="first">Use the <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.setp" title="matplotlib.pyplot.setp"><ttclass="xref py py-func docutils literal"><spanclass="pre">setp()</span></tt></a> command. The example below
uses a MATLAB-style command to set multiple properties
on a list of lines. <ttclass="docutils literal"><spanclass="pre">setp</span></tt> works transparently with a list of objects
or a single object. You can either use python keyword arguments or
<p>Here are the available <aclass="reference internal" href="../api/artist_api.html#matplotlib.lines.Line2D" title="matplotlib.lines.Line2D"><ttclass="xref py py-class docutils literal"><spanclass="pre">Line2D</span></tt></a> properties.</p>
<tableborder="1" class="docutils">
<colgroup>
<colwidth="31%" />
<colwidth="69%" />
</colgroup>
<theadvalign="bottom">
<trclass="row-odd"><thclass="head">Property</th>
<thclass="head">Value Type</th>
</tr>
</thead>
<tbodyvalign="top">
<trclass="row-even"><td>alpha</td>
<td>float</td>
</tr>
<trclass="row-odd"><td>animated</td>
<td>[True | False]</td>
</tr>
<trclass="row-even"><td>antialiased or aa</td>
<td>[True | False]</td>
</tr>
<trclass="row-odd"><td>clip_box</td>
<td>a matplotlib.transform.Bbox instance</td>
</tr>
<trclass="row-even"><td>clip_on</td>
<td>[True | False]</td>
</tr>
<trclass="row-odd"><td>clip_path</td>
<td>a Path instance and a Transform instance, a Patch</td>
<p>To get a list of settable line properties, call the
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.setp" title="matplotlib.pyplot.setp"><ttclass="xref py py-func docutils literal"><spanclass="pre">setp()</span></tt></a> function with a line or lines
<spanid="multiple-figs-axes"></span><h2>Working with multiple figures and axes<aclass="headerlink" href="#working-with-multiple-figures-and-axes" title="Permalink to this headline">¶</a></h2>
<p>MATLAB, and <aclass="reference internal" href="../api/pyplot_api.html#module-matplotlib.pyplot" title="matplotlib.pyplot"><ttclass="xref py py-mod docutils literal"><spanclass="pre">pyplot</span></tt></a>, have the concept of the current
figure and the current axes. All plotting commands apply to the
current axes. The function <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.gca" title="matplotlib.pyplot.gca"><ttclass="xref py py-func docutils literal"><spanclass="pre">gca()</span></tt></a> returns the
current axes (a <aclass="reference internal" href="../api/axes_api.html#matplotlib.axes.Axes" title="matplotlib.axes.Axes"><ttclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.axes.Axes</span></tt></a> instance), and
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.gcf" title="matplotlib.pyplot.gcf"><ttclass="xref py py-func docutils literal"><spanclass="pre">gcf()</span></tt></a> returns the current figure
(<aclass="reference internal" href="../api/figure_api.html#matplotlib.figure.Figure" title="matplotlib.figure.Figure"><ttclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.figure.Figure</span></tt></a> instance). Normally, you don’t have
to worry about this, because it is all taken care of behind the
scenes. Below is a script to create two subplots.</p>
<p>The <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure"><ttclass="xref py py-func docutils literal"><spanclass="pre">figure()</span></tt></a> command here is optional because
<ttclass="docutils literal"><spanclass="pre">figure(1)</span></tt> will be created by default, just as a <ttclass="docutils literal"><spanclass="pre">subplot(111)</span></tt>
will be created by default if you don’t manually specify an axes. The
<spanclass="pre">numcols,</span><spanclass="pre">fignum</span></tt> where <ttclass="docutils literal"><spanclass="pre">fignum</span></tt> ranges from 1 to
<ttclass="docutils literal"><spanclass="pre">numrows*numcols</span></tt>. The commas in the <ttclass="docutils literal"><spanclass="pre">subplot</span></tt> command are
optional if <ttclass="docutils literal"><spanclass="pre">numrows*numcols<10</span></tt>. So <ttclass="docutils literal"><spanclass="pre">subplot(211)</span></tt> is identical
to <ttclass="docutils literal"><spanclass="pre">subplot(2,1,1)</span></tt>. You can create an arbitrary number of subplots
and axes. If you want to place an axes manually, ie, not on a
rectangular grid, use the <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.axes" title="matplotlib.pyplot.axes"><ttclass="xref py py-func docutils literal"><spanclass="pre">axes()</span></tt></a> command,
which allows you to specify the location as <ttclass="docutils literal"><spanclass="pre">axes([left,</span><spanclass="pre">bottom,</span>
<spanclass="pre">width,</span><spanclass="pre">height])</span></tt> where all values are in fractional (0 to 1)
coordinates. See <aclass="reference internal" href="../examples/pylab_examples/axes_demo.html#pylab-examples-axes-demo"><em>pylab_examples example code: axes_demo.py</em></a> for an example of
placing axes manually and <aclass="reference internal" href="../examples/pylab_examples/line_styles.html#pylab-examples-line-styles"><em>pylab_examples example code: line_styles.py</em></a> for an
example with lots-o-subplots.</p>
<p>You can create multiple figures by using multiple
<aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.figure" title="matplotlib.pyplot.figure"><ttclass="xref py py-func docutils literal"><spanclass="pre">figure()</span></tt></a> calls with an increasing figure
number. Of course, each figure can contain as many axes and subplots
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">figure</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">)</span><spanclass="c"># the first figure</span>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">subplot</span><spanclass="p">(</span><spanclass="mi">211</span><spanclass="p">)</span><spanclass="c"># the first subplot in the first figure</span>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">subplot</span><spanclass="p">(</span><spanclass="mi">212</span><spanclass="p">)</span><spanclass="c"># the second subplot in the first figure</span>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">figure</span><spanclass="p">(</span><spanclass="mi">2</span><spanclass="p">)</span><spanclass="c"># a second figure</span>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">plot</span><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="c"># creates a subplot(111) by default</span>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">figure</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">)</span><spanclass="c"># figure 1 current; subplot(212) still current</span>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">subplot</span><spanclass="p">(</span><spanclass="mi">211</span><spanclass="p">)</span><spanclass="c"># make subplot(211) in figure1 current</span>
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">title</span><spanclass="p">(</span><spanclass="s">'Easy as 1,2,3'</span><spanclass="p">)</span><spanclass="c"># subplot 211 title</span>
</pre></div>
</div>
<p>You can clear the current figure with <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.clf" title="matplotlib.pyplot.clf"><ttclass="xref py py-func docutils literal"><spanclass="pre">clf()</span></tt></a>
and the current axes with <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.cla" title="matplotlib.pyplot.cla"><ttclass="xref py py-func docutils literal"><spanclass="pre">cla()</span></tt></a>. If you find
this statefulness, annoying, 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#artist-tutorial"><em>Artist tutorial</em></a>)</p>
<p>If you are making a long sequence 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/pyplot_api.html#matplotlib.pyplot.close" title="matplotlib.pyplot.close"><ttclass="xref py py-func docutils literal"><spanclass="pre">close()</span></tt></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="Permalink to this headline">¶</a></h2>
<p>The <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.text" title="matplotlib.pyplot.text"><ttclass="xref py py-func docutils literal"><spanclass="pre">text()</span></tt></a> command can be used to add text in
an arbitrary location, and the <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.xlabel" title="matplotlib.pyplot.xlabel"><ttclass="xref py py-func docutils literal"><spanclass="pre">xlabel()</span></tt></a>,
<spanclass="n">plt</span><spanclass="o">.</span><spanclass="n">title</span><spanclass="p">(</span><spanclass="s">'Histogram of IQ'</span><spanclass="p">)</span>
<p>All of the <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.text" title="matplotlib.pyplot.text"><ttclass="xref py py-func docutils literal"><spanclass="pre">text()</span></tt></a> commands return an
<aclass="reference internal" href="../api/artist_api.html#matplotlib.text.Text" title="matplotlib.text.Text"><ttclass="xref py py-class docutils literal"><spanclass="pre">matplotlib.text.Text</span></tt></a> instance. Just as with with lines
above, you can customize the properties by passing keyword arguments
into the text functions or using <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.setp" title="matplotlib.pyplot.setp"><ttclass="xref py py-func docutils literal"><spanclass="pre">setp()</span></tt></a>:</p>
<p>These properties are covered in more detail in <aclass="reference internal" href="text_props.html#text-properties"><em>Text properties and layout</em></a>.</p>
<h3>Using mathematical expressions in text<aclass="headerlink" href="#using-mathematical-expressions-in-text" title="Permalink to this headline">¶</a></h3>
<p>matplotlib accepts TeX equation expressions in any text expression.
For example to write the expression <imgsrc="../_images/mathmpl/math-4cd9a23707.png" style="position: relative; bottom: -7px"/> in the title,
you can write a TeX expression surrounded by dollar signs:</p>
<p>The <ttclass="docutils literal"><spanclass="pre">r</span></tt> preceeding the title string is important – it signifies
that the string is a <em>raw</em> string and not to treate backslashes and
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="mathtext.html#mathtext-tutorial"><em>Writing mathematical expressions</em></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="usetex.html#usetex-tutorial"><em>Text rendering With LaTeX</em></a>.</p>
</div>
<divclass="section" id="annotating-text">
<h3>Annotating text<aclass="headerlink" href="#annotating-text" title="Permalink to this headline">¶</a></h3>
<p>The uses of the basic <aclass="reference internal" href="../api/pyplot_api.html#matplotlib.pyplot.text" title="matplotlib.pyplot.text"><ttclass="xref py py-func docutils literal"><spanclass="pre">text()</span></tt></a> command above
place text at an arbitrary position on the Axes. A common use case of
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 <ttclass="docutils literal"><spanclass="pre">xy</span></tt> and the location of the text <ttclass="docutils literal"><spanclass="pre">xytext</span></tt>. Both of
these arguments are <ttclass="docutils literal"><spanclass="pre">(x,y)</span></tt> tuples.</p>
<p>In this basic example, both the <ttclass="docutils literal"><spanclass="pre">xy</span></tt> (arrow tip) and <ttclass="docutils literal"><spanclass="pre">xytext</span></tt>
locations (text location) are in data coordinates. There are a
variety of other coordinate systems one can choose – see
<aclass="reference internal" href="annotations_intro.html#annotations-tutorial"><em>Annotating text</em></a> and <aclass="reference internal" href="annotations_guide.html#plotting-guide-annotation"><em>Annotating Axes</em></a> for
details. More examples can be found in
<aclass="reference internal" href="../examples/pylab_examples/annotation_demo.html#pylab-examples-annotation-demo"><em>pylab_examples example code: annotation_demo.py</em></a>.</p>