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 (v3.3.3). 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="#id22">Annotations</a><aclass="headerlink" href="#annotations" title="Permalink to this headline">¶</a></h1>
<li><aclass="reference internal" href="#annotating-with-text-with-box" id="id25">Annotating with Text with Box</a></li>
<li><aclass="reference internal" href="#annotating-with-arrow" id="id26">Annotating with Arrow</a></li>
<li><aclass="reference internal" href="#placing-artist-at-the-anchored-location-of-the-axes" id="id27">Placing Artist at the anchored location of the Axes</a></li>
<li><aclass="reference internal" href="#using-complex-coordinates-with-annotations" id="id28">Using Complex Coordinates with Annotations</a></li>
<spanid="annotations-tutorial"></span><h2><aclass="toc-backref" href="#id23">Basic annotation</a><aclass="headerlink" href="#basic-annotation" title="Permalink to this headline">¶</a></h2>
<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
keyword arguments like <em>horizontalalignment</em>, <em>verticalalignment</em> and
<em>fontsize</em> are passed from <aclass="reference internal" href="../../api/_as_gen/matplotlib.axes.Axes.annotate.html#matplotlib.axes.Axes.annotate" title="matplotlib.axes.Axes.annotate"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">annotate</span></code></a> to the
<pclass="caption"><spanclass="caption-text">Annotation Polar</span><aclass="headerlink" href="#id2" title="Permalink to this image">¶</a></p>
</div>
<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 Annotations</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><h2><aclass="toc-backref" href="#id24">Advanced Annotations</a><aclass="headerlink" href="#advanced-annotations" title="Permalink to this headline">¶</a></h2>
<h3><aclass="toc-backref" href="#id25">Annotating with Text with Box</a><aclass="headerlink" href="#annotating-with-text-with-box" title="Permalink to this headline">¶</a></h3>
<pclass="caption"><spanclass="caption-text">Annotate Text Arrow</span><aclass="headerlink" href="#id3" title="Permalink to this image">¶</a></p>
</div>
<p><aclass="reference internal" href="../../api/_as_gen/matplotlib.axes.Axes.text.html#matplotlib.axes.Axes.text" title="matplotlib.axes.Axes.text"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">text</span></code></a> takes a <em>bbox</em> keyword argument, which draws a box around the
<h3><aclass="toc-backref" href="#id26">Annotating with Arrow</a><aclass="headerlink" href="#annotating-with-arrow" title="Permalink to this headline">¶</a></h3>
<p><aclass="reference internal" href="../../api/_as_gen/matplotlib.axes.Axes.annotate.html#matplotlib.axes.Axes.annotate" title="matplotlib.axes.Axes.annotate"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">annotate</span></code></a> draws an arrow connecting two points in an axes:</p>
<p>This annotates a point at <em>xy</em> in the given coordinate (<em>xycoords</em>)
with the text at <em>xytext</em> given in <em>textcoords</em>. 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.axes.Axes.annotate.html#matplotlib.axes.Axes.annotate" title="matplotlib.axes.Axes.annotate"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">annotate</span></code></a> for available coordinate systems.</p>
<p>An arrow connecting <em>xy</em> to <em>xytext</em> can be optionally drawn by
specifying the <em>arrowprops</em> 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>
<pclass="caption"><spanclass="caption-text">Fancyarrow Demo</span><aclass="headerlink" href="#id8" title="Permalink to this image">¶</a></p>
</div>
<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
<pclass="caption"><spanclass="caption-text">Annotate Simple02</span><aclass="headerlink" href="#id9" title="Permalink to this image">¶</a></p>
</div>
<p>As with <aclass="reference internal" href="../../api/_as_gen/matplotlib.axes.Axes.text.html#matplotlib.axes.Axes.text" title="matplotlib.axes.Axes.text"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">text</span></code></a>, a box around the text can be drawn using the <em>bbox</em>
<h3><aclass="toc-backref" href="#id27">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></h3>
<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 <aclass="reference internal" href="../../api/offsetbox_api.html#matplotlib.offsetbox.OffsetBox" title="matplotlib.offsetbox.OffsetBox"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">OffsetBox</span></code></a> class. A few
predefined classes are available in <aclass="reference internal" href="../../api/offsetbox_api.html#module-matplotlib.offsetbox" title="matplotlib.offsetbox"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">matplotlib.offsetbox</span></code></a> and 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>
<h3><aclass="toc-backref" href="#id28">Using Complex Coordinates with Annotations</a><aclass="headerlink" href="#using-complex-coordinates-with-annotations" title="Permalink to this headline">¶</a></h3>
<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>
<li><pclass="first">An <aclass="reference internal" href="../../api/artist_api.html#matplotlib.artist.Artist" title="matplotlib.artist.Artist"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Artist</span></code></a> instance. The <em>xy</em> value (or <em>xytext</em>) is interpreted as a
fractional coordinate of the bbox (return value of <em>get_window_extent</em>) of
<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><aclass="headerlink" href="#id16" title="Permalink to this image">¶</a></p>
</div>
<p>Note that you must ensure that the extent of the coordinate artist (<em>an1</em> in
above example) is determined before <em>an2</em> gets drawn. Usually, this means
that <em>an2</em> needs to be drawn after <em>an1</em>.</p>
</li>
<li><pclass="first">A callable object that takes the renderer instance as single argument, and
returns either a <aclass="reference internal" href="../../api/transformations.html#matplotlib.transforms.Transform" title="matplotlib.transforms.Transform"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Transform</span></code></a> or a <aclass="reference internal" href="../../api/transformations.html#matplotlib.transforms.BboxBase" title="matplotlib.transforms.BboxBase"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">BboxBase</span></code></a>. The return value is then
handled as in (1), for transforms, or in (2), for bboxes. For example,</p>
<pclass="caption"><spanclass="caption-text">Annotation with Simple Coordinates 2</span><aclass="headerlink" href="#id17" title="Permalink to this image">¶</a></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-obj docutils literal notranslate"><spanclass="pre">text.OffsetFrom</span></code></a> is a helper
<pclass="caption"><spanclass="caption-text">Annotation with Simple Coordinates 3</span><aclass="headerlink" href="#id18" title="Permalink to this image">¶</a></p>
<h3><aclass="toc-backref" href="#id29">Using ConnectionPatch</a><aclass="headerlink" href="#using-connectionpatch" title="Permalink to this headline">¶</a></h3>
<p>ConnectionPatch is like an annotation without text. While <aclass="reference internal" href="../../api/_as_gen/matplotlib.axes.Axes.annotate.html#matplotlib.axes.Axes.annotate" title="matplotlib.axes.Axes.annotate"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">annotate</span></code></a>
is sufficient in most situations, ConnectionPatch is useful when you want to
<p>The above code connects point <em>xy</em> in the data coordinates of <codeclass="docutils literal notranslate"><spanclass="pre">ax1</span></code> to
point <em>xy</em> in the data coordinates of <codeclass="docutils literal notranslate"><spanclass="pre">ax2</span></code>. Here is a simple example.</p>
<pclass="caption"><spanclass="caption-text">Connect Simple01</span><aclass="headerlink" href="#id19" title="Permalink to this image">¶</a></p>
</div>
<p>Here, we added the ConnectionPatch to the <em>figure</em> (with <aclass="reference internal" href="../../api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure.add_artist" title="matplotlib.figure.Figure.add_artist"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">add_artist</span></code></a>)
rather than to either axes: this ensures that it is drawn on top of both axes,
and is also necessary if using <aclass="reference internal" href="../intermediate/constrainedlayout_guide.html"><spanclass="doc">constrained_layout</span></a> for positioning the axes.</p>
</div>
</div>
<divclass="section" id="advanced-topics">
<h2><aclass="toc-backref" href="#id30">Advanced Topics</a><aclass="headerlink" href="#advanced-topics" title="Permalink to this headline">¶</a></h2>
<h3><aclass="toc-backref" href="#id31">Zoom effect between Axes</a><aclass="headerlink" href="#zoom-effect-between-axes" title="Permalink to this headline">¶</a></h3>
<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
<pclass="caption"><spanclass="caption-text">Axes Zoom Effect</span><aclass="headerlink" href="#id20" title="Permalink to this image">¶</a></p>
</div>
</div>
<divclass="section" id="define-custom-boxstyle">
<h3><aclass="toc-backref" href="#id32">Define Custom BoxStyle</a><aclass="headerlink" href="#define-custom-boxstyle" title="Permalink to this headline">¶</a></h3>
<p>You can use a custom box style. The value for the <codeclass="docutils literal notranslate"><spanclass="pre">boxstyle</span></code> can be a