8000 Merge pull request #18834 from QuLogic/artist-link · matplotlib/matplotlib@d3916e7 · GitHub
[go: up one dir, main page]
Skip to content

Commit d3916e7

Browse files
tacaswelltacaswell
authored
Merge pull request #18834 from QuLogic/artist-link
DOC: Add cross-references to Artist tutorial
2 parents 74d6145 + 599f4a4 commit d3916e7

File tree

2 files changed

+99
-92
lines changed

2 files changed

+99
-92
lines changed

‎doc/api/axis_api.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ Axis Label
7777
Axis.set_label_coords
7878
Axis.set_label_position
7979
Axis.set_label_text
80+
Axis.get_label
8081
Axis.get_label_position
8182
Axis.get_label_text
8283

‎tutorials/intermediate/artists.py

Lines changed: 98 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,12 @@
55
66
Using Artist objects to render on the canvas.
77
8-
There are three layers to the matplotlib API.
8+
There are three layers to the Matplotlib API.
99
1010
* the :class:`matplotlib.backend_bases.FigureCanvas` is the area onto which
1111
the figure is drawn
12-
* the :class:`matplotlib.backend_bases.Renderer` is
13-
the object which knows how to draw on the
14-
:class:`~matplotlib.backend_bases.Figu 10000 reCanvas`
12+
* the :class:`matplotlib.backend_bases.Renderer` is the object which knows how
13+
to draw on the :class:`~matplotlib.backend_bases.FigureCanvas`
1514
* and the :class:`matplotlib.artist.Artist` is the object that knows how to use
1615
a renderer to paint onto the canvas.
1716
@@ -47,7 +46,7 @@
4746
ax = fig.add_subplot(2, 1, 1) # two rows, one column, first plot
4847
4948
The :class:`~matplotlib.axes.Axes` is probably the most important
50-
class in the matplotlib API, and the one you will be working with most
49+
class in the Matplotlib API, and the one you will be working with most
5150
of the time. This is because the ``Axes`` is the plotting area into
5251
which most of the objects go, and the ``Axes`` has many special helper
5352
methods (:meth:`~matplotlib.axes.Axes.plot`,
@@ -83,8 +82,8 @@ class in the matplotlib API, and the one you will be working with most
8382
``fig.add_subplot`` call above (remember ``Subplot`` is just a
8483
subclass of ``Axes``) and when you call ``ax.plot``, it creates a
8584
``Line2D`` instance and adds it to the :attr:`Axes.lines
86-
<matplotlib.axes.Axes.lines>` list. In the interactive `ipython
87-
<http://ipython.org/>`_ session below, you can see that the
85+
<matplotlib.axes.Axes.lines>` list. In the interactive `IPython
86+
<https://ipython.org/>`_ session below, you can see that the
8887
``Axes.lines`` list is length one and contains the same line that was
8988
returned by the ``line, = ax.plot...`` call:
9089
@@ -170,7 +169,7 @@ class in the matplotlib API, and the one you will be working with most
170169
# ========== =================================================================
171170
# alpha The transparency - a scalar from 0-1
172171
# animated A boolean that is used to facilitate animated drawing
173-
# axes The axes that the Artist lives in, possibly None
172+
# axes The Axes that the Artist lives in, possibly None
174173
# clip_box The bounding box that clips the Artist
175174
# clip_on Whether clipping is enabled
176175
# clip_path The path the artist is clipped to
@@ -183,7 +182,7 @@ class in the matplotlib API, and the one you will be working with most
183182
# visible A boolean whether the artist should be drawn
184183
# zorder A number which determines the drawing order
185184
# rasterized Boolean; Turns vectors into raster graphics (for compression &
186-
# eps transparency)
185+
# EPS transparency)
187186
# ========== =================================================================
188187
#
189188
# Each of the properties is accessed with an old-fashioned setter or
@@ -307,33 +306,33 @@ class in the matplotlib API, and the one you will be working with most
307306
# In [160]: print(fig.axes)
308307
# [<AxesSubplot:>, <matplotlib.axes._axes.Axes object at 0x7f0768702be0>]
309308
#
310-
# Because the figure maintains the concept of the "current axes" (see
309+
# Because the figure maintains the concept of the "current Axes" (see
311310
# :meth:`Figure.gca <matplotlib.figure.Figure.gca>` and
312311
# :meth:`Figure.sca <matplotlib.figure.Figure.sca>`) to support the
313-
# pylab/pyplot state machine, you should not insert or remove axes
314-
# directly from the axes list, but rather use the
312+
# pylab/pyplot state machine, you should not insert or remove Axes
313+
# directly from the Axes list, but rather use the
315314
# :meth:`~matplotlib.figure.Figure.add_subplot` and
316315
# :meth:`~matplotlib.figure.Figure.add_axes` methods to insert, and the
317316
# :meth:`~matplotlib.figure.Figure.delaxes` method to delete. You are
318-
# free however, to iterate over the list of axes or index into it to get
317+
# free however, to iterate over the list of Axes or index into it to get
319318
# access to ``Axes`` instances you want to customize. Here is an
320-
# example which turns all the axes grids on::
319+
# example which turns all the Axes grids on::
321320
#
322321
# for ax in fig.axes:
323322
# ax.grid(True)
324323
#
325324
#
326-
# The figure also has its own text, lines, patches and images, which you
327-
# can use to add primitives directly. The default coordinate system for
328-
# the ``Figure`` will simply be in pixels (which is not usually what you
329-
# want) but you can control this by setting the transform property of
330-
# the ``Artist`` you are adding to the figure.
325+
# The figure also has its own ``images``, ``lines``, ``patches`` and ``text``
326+
# attributes, which you can use to add primitives directly. When doing so, the
327+
# default coordinate system for the ``Figure`` will simply be in pixels (which
328+
# is not usually what you want). If you instead use Figure-level methods to add
329+
# Artists (e.g., using `.Figure.text` to add text), then the default coordinate
330+
# system will be "figure coordinates" where (0, 0) is the bottom-left of the
331+
# figure and (1, 1) is the top-right of the figure.
331332
#
332-
# .. TODO: Is that still true?
333-
#
334-
# More useful is "figure coordinates" where (0, 0) is the bottom-left of
335-
# the figure and (1, 1) is the top-right of the figure which you can
336-
# obtain by setting the ``Artist`` transform to :attr:`fig.transFigure
333+
# As with all ``Artist``\s, you can control this coordinate system by setting
334+
# the transform property. You can explicitly use "figure coordinates" by
335+
# setting the ``Artist`` transform to :attr:`fig.transFigure
337336
# <matplotlib.figure.Figure.transFigure>`:
338337

339338
import< F438 /span> matplotlib.lines as lines
@@ -347,23 +346,22 @@ class in the matplotlib API, and the one you will be working with most
347346
plt.show()
348347

349348
###############################################################################
350-
# Here is a summary of the Artists the figure contains
351-
#
352-
# .. TODO: Add xrefs to this table
349+
# Here is a summary of the Artists the Figure contains
353350
#
354351
# ================ ============================================================
355352
# Figure attribute Description
356353
# ================ ============================================================
357-
# axes A list of Axes instances (includes Subplot)
358-
# patch The Rectangle background
359-
# images A list of FigureImage patches -
354+
# axes A list of `~.axes.Axes` instances (includes Subplot)
355+
# patch The `.Rectangle` background
356+
# images A list of `.FigureImage` patches -
360357
# useful for raw pixel display
361-
# legends A list of Figure Legend instances
362-
# (different from Axes.legends)
363-
# lines A list of Figure Line2D instances
364-
# (rarely used, see Axes.lines)
365-
# patches A list of Figure patches (rarely used, see Axes.patches)
366-
# texts A list Figure Text instances
358+
# legends A list of Figure `.Legend` instances
359+
# (different from ``Axes.legends``)
360+
# lines A list of Figure `.Line2D` instances
361+
# (rarely used, see ``Axes.lines``)
362+
# patches A list of Figure `.Patch`\s
363+
# (rarely used, see ``Axes.patches``)
364+
# texts A list Figure `.Text` instances
367365
# ================ ============================================================
368366
#
369367
# .. _axes-container:
@@ -538,20 +536,21 @@ class in the matplotlib API, and the one you will be working with most
538536
# below summarizes a small sampling of them, the kinds of ``Artist`` they
539537
# create, and where they store them
540538
#
541-
# ============================== ==================== =======================
542-
# Helper method Artist Container
543-
# ============================== ==================== =======================
544-
# ax.annotate - text annotations Annotate ax.texts
545-
# ax.bar - bar charts Rectangle ax.patches
546-
# ax.errorbar - error bar plots Line2D and Rectangle ax.lines and ax.patches
547-
# ax.fill - shared area Polygon ax.patches
548-
# ax.hist - histograms Rectangle ax.patches
549-
# ax.imshow - image data AxesImage ax.images
550-
# ax.legend - axes legends Legend ax.legends
551-
# ax.plot - xy plots Line2D ax.lines
552-
# ax.scatter - scatter charts PolygonCollection ax.collections
553-
# ax.text - text Text ax.texts
554-
# ============================== ==================== =======================
539+
# ========================================= ================= ===============
540+
# Axes helper method Artist Container
541+
# ========================================= ================= ===============
542+
# `~.axes.Axes.annotate` - text annotations `.Annotation` ax.texts
543+
# `~.axes.Axes.bar` - bar charts `.Rectangle` ax.patches
544+
# `~.axes.Axes.errorbar` - error bar plots `.Line2D` and ax.lines and
545+
# `.Rectangle` ax.patches
546+
# `~.axes.Axes.fill` - shared area `.Polygon` ax.patches
547+
# `~.axes.Axes.hist` - histograms `.Rectangle` ax.patches
548+
# `~.axes.Axes.imshow` - image data `.AxesImage` ax.images
549+
# `~.axes.Axes.legend` - Axes legends `.Legend` ax.legends
550+
# `~.axes.Axes.plot` - xy plots `.Line2D` ax.lines
551+
# `~.axes.Axes.scatter` - scatter charts `.PolyCollection` ax.collections
552+
# `~.axes.Axes.text` - text `.Text` ax.texts
553+
# ========================================= ================= ===============
555554
#
556555
#
557556
# In addition to all of these ``Artists``, the ``Axes`` contains two
@@ -572,20 +571,20 @@ class in the matplotlib API, and the one you will be working with most
572571
#
573572
# Below is a summary of the Artists that the Axes contains
574573
#
575-
# ============== ======================================
574+
# ============== =========================================
576575
# Axes attribute Description
577-
# ============== ======================================
578-
# artists A list of Artist instances
579-
# patch Rectangle instance for Axes background
580-
# collections A list of Collection instances
581-
# images A list of AxesImage
582-
# legends A list of Legend instances
583-
# lines A list of Line2D instances
584-
# patches A list of Patch instances
585-
# texts A list of Text instances
586-
# xaxis matplotlib.axis.XAxis instance
587-
# yaxis matplotlib.axis.YAxis instance
588-
# ============== ======================================
576+
# ============== =========================================
577+
# artists A list of `.Artist` instances
578+
# patch `.Rectangle` instance for Axes background
579+
# collections A list of `.Collection` instances
580+
# images A list of `.AxesImage`
581+
# legends A list of `.Legend` instances
582+
# lines A list of `.Line2D` instances
583+
# patches A list of `.Patch` instances
584+
# texts A list of `.Text` instances
585+
# xaxis A `matplotlib.axis.XAxis` instance
586+
# yaxis A `matplotlib.axis.YAxis` instance
587+
# ============== =========================================
589588
#
590589
# .. _axis-container:
591590
#
@@ -640,28 +639,35 @@ class in the matplotlib API, and the one you will be working with most
640639
# (these have corresponding setters where useful, such as
641640
# :meth:`~matplotlib.axis.Axis.set_major_formatter`.)
642641
#
643-
# ==================== =====================================================
644-
# Accessor method Description
645-
# ==================== =====================================================
646-
# get_scale The scale of the axis, e.g., 'log' or 'linear'
647-
# get_view_interval The interval instance of the axis view limits
648-
# get_data_interval The interval instance of the axis data limits
649-
# get_gridlines A list of grid lines for the Axis
650-
# get_label The axis label - a Text instance
651-
# get_ticklabels A list of Text instances - keyword minor=True|False
652-
# get_ticklines A list of Line2D instances - keyword minor=True|False
653-
# get_ticklocs A list of Tick locations - keyword minor=True|False
654-
# get_major_locator The `.ticker.Locator` instance for major ticks
655-
# get_major_formatter The `.ticker.Formatter` instance for major ticks
656-
# get_minor_locator The `.ticker.Locator` instance for minor ticks
657-
# get_minor_formatter The `.ticker.Formatter` instance for minor ticks
658-
# get_major_ticks A list of Tick instances for major ticks
659-
# get_minor_ticks A list of Tick instances for minor ticks
660-
# grid Turn the grid on or off for the major or minor ticks
661-
# ==================== =====================================================
642+
# ============================= ==============================================
643+
# Axis accessor method Description
644+
# ============================= ==============================================
645+
# `~.Axis.get_scale` The scale of the Axis, e.g., 'log' or 'linear'
646+
# `~.Axis.get_view_interval` The interval instance of the Axis view limits
647+
# `~.Axis.get_data_interval` The interval instance of the Axis data limits
648+
# `~.Axis.get_gridlines` A list of grid lines for the Axis
649+
# `~.Axis.get_label` The Axis label - a `.Text` instance
650+
# `~.Axis.get_offset_text` The Axis offset text - a `.Text` instance
651+
# `~.Axis.get_ticklabels` A list of `.Text` instances -
652+
# keyword minor=True|False
653+
# `~.Axis.get_ticklines` A list of `.Line2D` instances -
654+
# keyword minor=True|False
655+
# `~.Axis.get_ticklocs` A list of Tick locations -
656+
# keyword minor=True|False
657+
# `~.Axis.get_major_locator` The `.ticker.Locator` instance for major ticks
658+
# `~.Axis.get_major_formatter` The `.ticker.Formatter` instance for major
659+
# ticks
660+
# `~.Axis.get_minor_locator` The `.ticker.Locator` instance for minor ticks
661+
# `~.Axis.get_minor_formatter` The `.ticker.Formatter` instance for minor
662+
# ticks
663+
# `~.axis.Axis.get_major_ticks` A list of `.Tick` instances for major ticks
664+
# `~.axis.Axis.get_minor_ticks` A list of `.Tick` instances for minor ticks
665+
# `~.Axis.grid` Turn the grid on or off for the major or minor
666+
# ticks
667+
# ============================= ==============================================
662668
#
663669
# Here is an example, not recommended for its beauty, which customizes
664-
# the axes and tick properties
670+
# the Axes and Tick properties.
665671

666672
# plt.figure creates a matplotlib.figure.Figure instance
667673
fig = plt.figure()
@@ -701,15 +707,15 @@ class in the matplotlib API, and the one you will be working with most
701707
# and lower ticks. Each of these is accessible directly as an attribute
702708
# of the ``Tick``.
703709
#
704-
# ============== ==========================================================
705-
# Tick attribute Description
706-
# ============== ==========================================================
707-
# tick1line Line2D instance
708-
# tick2line Line2D instance
709-
# gridline Line2D instance
710-
# label1 Text instance
711-
# label2 Text instance
712-
# ============== ==========================================================
710+
# ============== ==========================================================
711+
# Tick attribute Description
712+
# ============== ==========================================================
713+
# tick1line A `.Line2D` instance
714+
# tick2line A `.Line2D` instance
715+
# gridline A `.Line2D` instance
716+
# label1 A `.Text` instance
717+
# label2 A `.Text` instance
718+
# ============== ==========================================================
713719
#
714720
# Here is an example which sets the formatter for the right side ticks with
715721
# dollar signs and colors them green on the right side of the yaxis.

0 commit comments

Comments
 (0)
0