Interactive Matplotlib Tutorial

1 00 Introduction to OO Matplotlib

1.1 Parts of a Figure

./anatomy.pdf

https://matplotlib.org/tutorials/introductory/usage.html#parts-of-a-figure

1.2 Parts of a Figure

Figure

Everything you see, top level container

Axes

One set coordinates, many Axes per Figure

Axis

The spines, ticks, and labels on the Axes

Artist

everything you see

1.3 Matplotlib Layers

Renderer

Internal, handles final `on screen’ or `on disk’ version

Canvas

Manages a Figure and and a Renderer

Transforms

between coord systems {`data’, `axes’, `figure’, `screen’}

Artists

`middle layer’, given a Renderer can draw self

Axes and Figure methods

create Artists and add to draw-tree

pyplot

create Artists and add to draw-tree

\hline

UI events

mouse/keyboard events

1.4 pyplot

• pyplot is intentionally very close to MATLAB ploting API
  • pro: easy for people switching from MATLAB
  • pro: pyplot is much terser
  • con: makes some interesting design choices
  • con: has buckets of global state
• Everything in pyplot implemented in terms of 00
  • ?? plt.FOO can be good way to look up how to do something

1.5 Axes and Figure methods

These classes manage:

• manage the draw tree (hold that thought)
• manage figure size, dpi, axes layout, view limits, axis scales
• namespace for plotting functions
  • ax.plot
  • ax.hist
  • ax.imshow
  • …

https://matplotlib.org/api/axes_api.html

1.6 Aritsts

• Everything that you see in the figure is an Artist (because it draws on the Canvas)
  • text, marks, images, spines, background patches
• responsible for translating internal state → Renderer method calls
• can be mutated and re-drawn
  • obj.set_* and obj.get_* methods

1.7 draw via visitor pattern

class Canvas:
    def draw(self):
        render = self.get_renderer()
        self.figure.draw(renderer)

class Figure:
    def draw(self, renderer):
        self.patch.draw(renderer)
        for artist in self.get_children():
            artist.draw(renderer)

class Line2D:
    def draw(self, renderer):
        renderer.draw_path(self.verticies, ...)

1.8 Tansforms and coordinate systems

----------------------------------------+-----------------------------------+

Coords

Transformation object

Description

----------------------------------------+-----------------------------------+

“data”	ax.transData	The coordinate system for the data,
		controlled by xlim and ylim.

----------------------------------------+-----------------------------------+

“axes”	ax.transAxes	The coordinate system of the
		Axes; (0, 0) is bottom left of
		and (1, 1) is top right

----------------------------------------+-----------------------------------+

“figure”	fig.transFigure	The coordinate system of the
		Figure; (0, 0) is bottom left
		and (1, 1) is top right.

----------------------------------------+-----------------------------------+

“display”	IdentityTransform()	The pixel coordinate system of the
		display; (0, 0) is bottom left
		and (width, height) is top right
		in pixels.

----------------------------------------+-----------------------------------+

https://matplotlib.org/tutorials/advanced/transforms_tutorial.html

1.9 Canvas

• holds a Figure instance
• knows how to make a Renderer instance at correct size and DPI on demand
• for GUI backends typically uses multiple inheritance and is the native GUI widget

https://matplotlib.org/gallery/index.html#embedding-matplotlib-in-graphical-user-interfaces

1.10 Renderer

• Takes low-level data and renders to output
• Typically should not have to know this exists

Minimal set of methods (may have other methods for optimizations)

class Renderer:
    def draw_path(self, ...):
        ...
    def draw_image(self, ...):
        ...
    def draw_text(self, ...):
        ...
    def get_text_width_height_descent(self, ...):
        ...

1.11 UI events

• if you have used the pan / zoom tools or the ‘g’, ‘l’, ‘k’, etc keys in mpl, you have used the mpl event framework
• events has always been in mpl (Event class came into codebase on Tue Dec 28 2004 as a refactoring of existing functionality

1.12 UI events on Canvas

---------------------------------------------------------------+

Event name

Description

---------------------------------------------------------------+

`button_press_event’	mouse button is pressed
`button_release_event’	mouse button is released
`draw_event’	canvas draw (but before screen update)
`key_press_event’	key is pressed
`key_release_event’	key is released
`motion_notify_event’	mouse motion
`pick_event’	an object in the canvas is selected
`resize_event’	figure canvas is resized
`scroll_event’	mouse scroll wheel is rolled
`figure_enter_event’	mouse enters a new figure
`figure_leave_event’	mouse leaves a figure
`axes_enter_event’	mouse enters a new axes
`axes_leave_event’	mouse leaves an axes

---------------------------------------------------------------+

• cid = canvas.mpl_connect(event_name, callback)
• canvas.mpl_disconnect(cid)

2 01 Installation

2.1 installation

git clone \
    https://github.com/tacaswell/interactive_mpl_tutorial
cd interactive_mpl_tutorial
conda env create -f environment.yml
source activate mpl-tutorial    # linux / OSX
activate mpl-tutorial           # windows

To run examples:

ipython --matplotlib=qt5

In [N]: %run -i 00-explore.py