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
<divid="unreleased-message"> You are reading an old version of the documentation (v2.2.5). For the latest version see <ahref="https://matplotlib.org/stable/tutorials/text/annotations.html">https://matplotlib.org/stable/tutorials/text/annotations.html</a></div>
<li><aclass="reference internal" href="#annotating-with-text-with-box">Annotating with Text with Box</a></li>
<li><aclass="reference internal" href="#annotating-with-arrow">Annotating with Arrow</a></li>
<li><aclass="reference internal" href="#placing-artist-at-the-anchored-location-of-the-axes">Placing Artist at the anchored location of the Axes</a></li>
<li><aclass="reference internal" href="#using-complex-coordinates-with-annotations">Using Complex Coordinates with Annotations</a></li>
<pclass="last">Click <aclass="reference internal" href="#sphx-glr-download-tutorials-text-annotations-py"><spanclass="std std-ref">here</span></a> to download the full example code</p>
<spanid="sphx-glr-tutorials-text-annotations-py"></span><h1><aclass="toc-backref" href="#id23">Annotations</a><aclass="headerlink" href="#annotations" title="Permalink to this headline">¶</a></h1>
<li><aclass="reference internal" href="#annotating-with-text-with-box" id="id26">Annotating with Text with Box</a></li>
<li><aclass="reference internal" href="#annotating-with-arrow" id="id27">Annotating with Arrow</a></li>
<li><aclass="reference internal" href="#placing-artist-at-the-anchored-location-of-the-axes" id="id28">Placing Artist at the anchored location of the Axes</a></li>
<li><aclass="reference internal" href="#using-complex-coordinates-with-annotations" id="id29">Using Complex Coordinates with Annotations</a></li>
<spanid="annotations-tutorial"></span><h1><aclass="toc-backref" href="#id24">Basic annotation</a><aclass="headerlink" href="#basic-annotation" title="Permalink to this headline">¶</a></h1>
<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-func docutils literal notranslate"><spanclass="pre">text()</span></code></a> will place text
at an arbitrary position on the Axes. A common use case of text is to
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,y)</span></code> tuples.</p>
<p>In this 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 -- you can specify the coordinate
system of <codeclass="docutils literal notranslate"><spanclass="pre">xy</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">xytext</span></code> with one of the following strings for
<codeclass="docutils literal notranslate"><spanclass="pre">xycoords</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">textcoords</span></code> (default is 'data')</p>
<tableborder="1" class="docutils">
<colgroup>
<colwidth="28%" />
<colwidth="72%" />
</colgroup>
<theadvalign="bottom">
<trclass="row-odd"><thclass="head">argument</th>
<thclass="head">coordinate system</th>
</tr>
</thead>
<tbodyvalign="top">
<trclass="row-even"><td>'figure points'</td>
<td>points from the lower left corner of the figure</td>
</tr>
<trclass="row-odd"><td>'figure pixels'</td>
<td>pixels from the lower left corner of the figure</td>
</tr>
<trclass="row-even"><td>'figure fraction'</td>
<td>0,0 is lower left of figure and 1,1 is upper right</td>
</tr>
<trclass="row-odd"><td>'axes points'</td>
<td>points from lower left corner of axes</td>
</tr>
<trclass="row-even"><td>'axes pixels'</td>
<td>pixels from lower left corner of axes</td>
</tr>
<trclass="row-odd"><td>'axes fraction'</td>
<td>0,0 is lower left of axes and 1,1 is upper right</td>
</tr>
<trclass="row-even"><td>'data'</td>
<td>use the axes data coordinate system</td>
</tr>
</tbody>
</table>
<p>For example to place the text coordinates in fractional axes
keyword args like <codeclass="docutils literal notranslate"><spanclass="pre">horizontalalignment</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">verticalalignment</span></code> and
<codeclass="docutils literal notranslate"><spanclass="pre">fontsize</span></code> are passed from <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">annotate</span></code> to the
<p>For more on all the wild and wonderful things you can do with
annotations, including fancy arrows, see <aclass="reference internal" href="#plotting-guide-annotation"><spanclass="std std-ref">Advanced Annotation</span></a>
and <aclass="reference internal" href="../../gallery/text_labels_and_annotations/annotation_demo.html"><spanclass="doc">Annotating Plots</span></a>.</p>
<p>Do not proceed unless you have already read <aclass="reference internal" href="#annotations-tutorial"><spanclass="std std-ref">Basic annotation</span></a>,
<spanid="plotting-guide-annotation"></span><h1><aclass="toc-backref" href="#id25">Advanced Annotation</a><aclass="headerlink" href="#advanced-annotation" title="Permalink to this headline">¶</a></h1>
<h2><aclass="toc-backref" href="#id26">Annotating with Text with Box</a><aclass="headerlink" href="#annotating-with-text-with-box" title="Permalink to this headline">¶</a></h2>
<h2><aclass="toc-backref" href="#id27">Annotating with Arrow</a><aclass="headerlink" href="#annotating-with-arrow" title="Permalink to this headline">¶</a></h2>
<p>The <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.annotate.html#matplotlib.pyplot.annotate" title="matplotlib.pyplot.annotate"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">annotate()</span></code></a> function in the pyplot module
(or annotate method of the Axes class) is used to draw an arrow
<p>This annotates a point at <codeclass="docutils literal notranslate"><spanclass="pre">xy</span></code> in the given coordinate (<codeclass="docutils literal notranslate"><spanclass="pre">xycoords</span></code>)
with the text at <codeclass="docutils literal notranslate"><spanclass="pre">xytext</span></code> given in <codeclass="docutils literal notranslate"><spanclass="pre">textcoords</span></code>. Often, the
annotated point is specified in the <em>data</em> coordinate and the annotating
text in <em>offset points</em>.
See <aclass="reference internal" href="../../api/_as_gen/matplotlib.pyplot.annotate.html#matplotlib.pyplot.annotate" title="matplotlib.pyplot.annotate"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">annotate()</span></code></a> for available coordinate systems.</p>
<p>An arrow connecting two points (xy & xytext) can be optionally drawn by
specifying the <codeclass="docutils literal notranslate"><spanclass="pre">arrowprops</span></code> argument. To draw only an arrow, use
<p>Note that "3" in <codeclass="docutils literal notranslate"><spanclass="pre">angle3</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">arc3</span></code> is meant to indicate that the
resulting path is a quadratic spline segment (three control
points). As will be discussed below, some arrow style options can only
be used when the connecting path is a quadratic spline.</p>
<p>The behavior of each connection style is (limitedly) demonstrated in the
example below. (Warning : The behavior of the <codeclass="docutils literal notranslate"><spanclass="pre">bar</span></code> style is currently not
well defined, it may be changed in the future).</p>
<p>Some arrowstyles only work with connection styles that generate a
quadratic-spline segment. They are <codeclass="docutils literal notranslate"><spanclass="pre">fancy</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">simple</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">wedge</span></code>.
For these arrow styles, you must use the "angle3" or "arc3" connection
style.</p>
<p>If the annotation string is given, the patchA is set to the bbox patch
<h2><aclass="toc-backref" href="#id28">Placing Artist at the anchored location of the Axes</a><aclass="headerlink" href="#placing-artist-at-the-anchored-location-of-the-axes" title="Permalink to this headline">¶</a></h2>
<p>There are classes of artists that can be placed at an anchored location
in the Axes. A common example is the legend. This type of artist can
be created by using the OffsetBox class. A few predefined classes are
available in <codeclass="docutils literal notranslate"><spanclass="pre">mpl_toolkits.axes_grid1.anchored_artists</span></code> others in
<spanclass="n">el</span><spanclass="o">=</span><spanclass="n">Ellipse</span><spanclass="p">((</span><spanclass="mi">0</span><spanclass="p">,</span><spanclass="mi">0</span><spanclass="p">),</span><spanclass="n">width</span><spanclass="o">=</span><spanclass="mf">0.1</span><spanclass="p">,</span><spanclass="n">height</span><spanclass="o">=</span><spanclass="mf">0.4</span><spanclass="p">,</span><spanclass="n">angle</span><spanclass="o">=</span><spanclass="mi">30</span><spanclass="p">)</span><spanclass="c1"># in data coordinates!</span>
<h2><aclass="toc-backref" href="#id29">Using Complex Coordinates with Annotations</a><aclass="headerlink" href="#using-complex-coordinates-with-annotations" title="Permalink to this headline">¶</a></h2>
<p>The Annotation in matplotlib supports several types of coordinates as
described in <aclass="reference internal" href="#annotations-tutorial"><spanclass="std std-ref">Basic annotation</span></a>. For an advanced user who wants
more control, it supports a few other options.</p>
<spanclass="n">an2</span><spanclass="o">=</span><spanclass="n">ax</span><spanclass="o">.</span><spanclass="n">annotate</span><spanclass="p">(</span><spanclass="s2">"Test 2"</span><spanclass="p">,</span><spanclass="n">xy</span><spanclass="o">=</span><spanclass="p">(</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="mf">0.5</span><spanclass="p">),</span><spanclass="n">xycoords</span><spanclass="o">=</span><spanclass="n">an1</span><spanclass="p">,</span><spanclass="c1"># (1,0.5) of the an1's bbox</span>
<pclass="caption"><spanclass="caption-text">Annotation with Simple Coordinates</span></p>
</div>
<p>Note that it is your responsibility that the extent of the
coordinate artist (<em>an1</em> in above example) is determined before <em>an2</em>
gets drawn. In most cases, it means that <em>an2</em> needs to be drawn
later than <em>an1</em>.</p>
</li>
<li><pclass="first">A callable object that returns an instance of either
<aclass="reference internal" href="../../api/transformations.html#matplotlib.transforms.BboxBase" title="matplotlib.transforms.BboxBase"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">BboxBase</span></code></a> or
<aclass="reference internal" href="../../api/transformations.html#matplotlib.transforms.Transform" title="matplotlib.transforms.Transform"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">Transform</span></code></a>. If a transform is
returned, it is the same as 1 and if a bbox is returned, it is the same
as 2. The callable object should take a single argument of the
renderer instance. For example, the following two commands give
<pclass="caption"><spanclass="caption-text">Annotation with Simple Coordinates 2</span></p>
</div>
</li>
<li><pclass="first">Sometimes, you want your annotation with some "offset points", not from the
annotated point but from some other point.
<aclass="reference internal" href="../../api/text_api.html#matplotlib.text.OffsetFrom" title="matplotlib.text.OffsetFrom"><codeclass="xref py py-class docutils literal notranslate"><spanclass="pre">OffsetFrom</span></code></a> is a helper class for such cases.</p>
<h2><aclass="toc-backref" href="#id30">Using ConnectionPatch</a><aclass="headerlink" href="#using-connectionpatch" title="Permalink to this headline">¶</a></h2>
<p>The ConnectionPatch is like an annotation without text. While the annotate
function is recommended in most situations, the ConnectionPatch is useful when
<h2><aclass="toc-backref" href="#id32">Zoom effect between Axes</a><aclass="headerlink" href="#zoom-effect-between-axes" title="Permalink to this headline">¶</a></h2>
<p><codeclass="docutils literal notranslate"><spanclass="pre">mpl_toolkits.axes_grid1.inset_locator</span></code> defines some patch classes useful
for interconnecting two axes. Understanding the code requires some
knowledge of how mpl's transform works. But, utilizing it will be
<h2><aclass="toc-backref" href="#id33">Define Custom BoxStyle</a><aclass="headerlink" href="#define-custom-boxstyle" title="Permalink to this headline">¶</a></h2>
<p>You can use a custom box style. The value for the <codeclass="docutils literal notranslate"><spanclass="pre">boxstyle</span></code> can be a