mplcursors Documentation Release 0.4

Antony Lee

Dec 09, 2020

CONTENTS

1 Installation 3

2 Basic example 5

3 Activation by environment variable7

4 Default UI 9

5 Customization 11

6 Selection indices 13

7 Complex plots 15

8 Animations 17

9 Users 19

10 Indices and tables 21 10.1 The mplcursors API...... 21 10.2 mplcursors examples...... 25

Python Module Index 43

Index 45

i ii mplcursors Documentation, Release 0.4

mplcursors provides interactive data selection cursors for Matplotlib. It is inspired from mpldatacursor, with a much simplified API. mplcursors requires Python 3, and Matplotlib3.1.

CONTENTS 1 mplcursors Documentation, Release 0.4

2 CONTENTS CHAPTER ONE

INSTALLATION

Pick one among:

$ pip install mplcursors # from PyPI $ pip install git+https://github.com/anntzer/mplcursors # from Github

3 mplcursors Documentation, Release 0.4

4 Chapter 1. Installation CHAPTER TWO

BASIC EXAMPLE

Basic examples work similarly to mpldatacursor: import matplotlib.pyplot as plt import numpy as np import mplcursors data= np.outer(range(10), range(1,5)) fig, ax= plt.subplots() lines= ax.plot(data) ax.set_title("Click somewhere on a line.\nRight-click to deselect.\n" "Annotations can be dragged.") mplcursors.cursor(lines) # or just mplcursors.cursor() plt.show()

5 mplcursors Documentation, Release 0.4

The cursor convenience function makes a collection of artists selectable. Specifically, its first argument can either be a list of artists or axes (in which case all artists in each of the axes become selectable); or one can just pass no argument, in which case all artists in all figures become selectable. Other arguments (which are all keyword-only) allow for basic customization of the Cursor’s behavior; please refer to that class’ documentation.

6 Chapter 2. Basic example CHAPTER THREE

ACTIVATION BY ENVIRONMENT VARIABLE

It is possible to use mplcursors without modifying any source code: setting the MPLCURSORS environment vari- able to a JSON-encoded dict will patch Figure.draw to automatically call cursor (with the passed keyword arguments, if any) after the figure is drawn for the first time (more precisely, after the first draw that includes a se- lectable artist). Typical settings include:

$ MPLCURSORS={} python foo.py and:

$ MPLCURSORS='{"hover": 1}' python foo.py

Note that this will only work if mplcursors has been installed, not if it is simply added to the PYTHONPATH. Note that this will not pick up artists added to the figure after the first draw, e.g. through interactive callbacks.

7 mplcursors Documentation, Release 0.4

8 Chapter 3. Activation by environment variable CHAPTER FOUR

DEFAULT UI

• A left click on a line (a point, for plots where the data points are not connected) creates a draggable annotation there. Only one annotation is displayed (per Cursor instance), except if the multiple keyword argument was set. • A right click on an existing annotation will remove it. • Clicks do not trigger annotations if the zoom or pan tool are active. It is possible to bypass this by double- clicking instead. • For annotations pointing to lines or images, Shift-Left and Shift-Right move the cursor “left” or “right” by one data point. For annotations pointing to images, Shift-Up and Shift-Down are likewise available. • v toggles the visibility of the existing annotation(s). • e toggles whether the Cursor is active at all (if not, no event other than re-activation is propagated). These bindings are all customizable via Cursor’s bindings keyword argument. Note that the keyboard bindings are only active if the canvas has the keyboard input focus.

9 mplcursors Documentation, Release 0.4

10 Chapter 4. Default UI CHAPTER FIVE

CUSTOMIZATION

Instead of providing a host of keyword arguments in Cursor’s constructor, mplcursors represents selections as Selection objects (essentially, namedtuples) and lets you hook into their addition and removal. Specifically, a Selection has the following fields: • artist: the selected artist, • target: the point picked within the artist; if a point is picked on a Line2D, the index of the point is available as the target.index sub-attribute (for more details, see Selection indices). • dist: the distance from the point clicked to the target (mostly used to decide which artist to select). • annotation: a Matplotlib Annotation object. • extras: an additional list of artists, that will be removed whenever the main annotation is deselected. For certain classes of artists, additional information about the picked point is available in the target.index sub- attribute: • For Line2Ds, it contains the index of the selected point (see Selection indices for more details, especially regarding step plots). • For AxesImages, it contains the (y, x) indices of the selected point (such that data[y, x] in that order is the value at that point; note that this means that the indices are not in the same order as the target coordinates!). • For Containers, it contains the index of the selected sub-artist. • For LineCollections and PathCollections, it contains a pair: the index of the selected line, and the index within the line, as defined above. Thus, in order to customize, e.g., the annotation text, one can call:

lines= ax.plot(range(3), range(3),"o") labels=["a","b","c"] cursor= mplcursors.cursor(lines) cursor.connect( "add", lambda sel: sel.annotation.set_text(labels[sel.target.index]))

Whenever a point is selected (resp. deselected), the "add" (resp. "remove") event is triggered and the registered callbacks are executed, with the Selection as only argument. Here, the only callback updates the text of the annotation to a per-point label. (cursor.connect("add") can also be used as a decorator to register a callback, see below for an example.) For an example using pandas’ DataFrames, see Extracting data and labels from a DataFrame. For additional examples of customization of the position and appearance of the annotation, see Display a bar’s height and name on top of it upon hovering and Changing properties of the popup.

11 mplcursors Documentation, Release 0.4

Note: When the callback is fired, the position of the annotating text is temporarily set to (nan, nan). This allows us to track whether a callback explicitly sets this position, and, if none does, automatically compute a suitable position. Likewise, if the text alignment is not explicitly set but the position is, then a suitable alignment will be automatically computed.

Callbacks can also be used to make additional changes to the figure when a selection occurs. For example, the following snippet (extracted from Linked artists) ensures that whenever an artist is selected, another artist that has been “paired” with it (via the pairs map) also gets selected:

@cursor.connect("add") def on_add(sel): sel.extras.append(cursor.add_highlight(pairs[sel.artist]))

Note that the paired artist will also get de-highlighted when the “first” artist is deselected. In order to set the status bar text from a callback, it may be helpful to clear it during “normal” mouse motion, e.g.: fig.canvas.mpl_connect( "motion_notify_event", lambda event: fig.canvas.toolbar.set_message("")) cursor= mplcursors.cursor(hover= True) cursor.connect( "add", lambda sel: fig.canvas.toolbar.set_message( sel.annotation.get_text().replace("\n",";")))

12 Chapter 5. Customization CHAPTER SIX

SELECTION INDICES

When picking a point on a “normal” line, the target index has an integer part equal to the index of segment it is on, and a fractional part that indicates where the point is within that segment. For step plots (i.e., created by plt.step or plt.plot(..., drawstyle="steps-..."), we return a spe- cial Index object, with attributes int (the segment index), x (how far the point has advanced in the x direction) and y (how far the point has advanced in the y direction). See Step plots for an example. On polar plots, lines can be either drawn with a “straight” connection between two points (in screen space), or “curved” (i.e., using linear interpolation in data space). In the first case, the fractional part of the index is defined as for cartesian plots. In the second case, the index in computed first on the interpolated path, then divided by the interpolation factor (i.e., pretending that each interpolated segment advances the same index by the same amount).

13 mplcursors Documentation, Release 0.4

14 Chapter 6. Selection indices CHAPTER SEVEN

COMPLEX PLOTS

Some complex plots, such as contour plots, may be partially supported, or not at all. Typically, it is because they do not subclass Artist, and thus appear to cursor as a collection of independent artists (each contour level, in the case of contour plots). It is usually possible, again, to hook the "add" signal to provide additional information in the annotation text. See Contour plots for an example.

15 mplcursors Documentation, Release 0.4

16 Chapter 7. Complex plots CHAPTER EIGHT

ANIMATIONS

Matplotlib’s animation blitting mode assumes that the animation object is entirely in charge of deciding what artists to draw and when. In particular, this means that the animated property is set on certain artists. As a result, when mplcursors tries to blit an animation on top of the image, the animated artists will not be drawn, and disappear. More importantly, it also means that once an annotation is added, mplcursors cannot remove it (as it needs to know what artists to redraw to restore the original state). As a workaround, either switch off blitting, or unset the animated property on the relevant artists before using a cursor. (The only other fix I can envision is to walk the entire tree of artists, record their visibility status, and try to later restore them; but this would fail for ArtistAnimations which themselves fiddle with artist visibility).

17 mplcursors Documentation, Release 0.4

18 Chapter 8. Animations CHAPTER NINE

USERS

Some users of mplcursors (please let me know if you find this package useful!): • reliability: A Python library for reliability engineering. • RepoDash: Performance metrics for Github repositories. • topplot: Munge top logs in to graphs.

19 mplcursors Documentation, Release 0.4

20 Chapter 9. Users CHAPTER TEN

INDICES AND TABLES

• genindex • modindex • search

10.1 The mplcursors API

mplcursors.Cursor(artists, *[, multiple, . . . ]) A cursor for selecting Matplotlib artists. mplcursors.cursor([pickables]) Create a Cursor for a list of artists, containers, and axes. mplcursors.Selection(artist, target, dist, . . . ) mplcursors.compute_pick(artist, event) Find whether artist has been picked by event. mplcursors.get_ann_text(artist, target, . . . ) Compute an annotating text for a Selection (passed unpacked). mplcursors.make_highlight(artist, target, . . . ) Create a highlight for a Selection.

class mplcursors.Cursor(artists, *, multiple=False, highlight=False, hover=False, bind- ings=None, annotation_kwargs=None, annotation_positions=None, highlight_kwargs=None) Bases: object A cursor for selecting Matplotlib artists. bindings See the bindings keyword argument to the constructor. Type dict annotation_kwargs See the annotation_kwargs keyword argument to the constructor. Type dict

21 mplcursors Documentation, Release 0.4

annotation_positions See the annotation_positions keyword argument to the constructor. Type dict highlight_kwargs See the highlight_kwargs keyword argument to the constructor. Type dict __init__(artists, *, multiple=False, highlight=False, hover=False, bindings=None, annota- tion_kwargs=None, annotation_positions=None, highlight_kwargs=None) Construct a cursor. Parameters • artists (List[Artist]) – A list of artists that can be selected by this cursor. • multiple (bool, default: False) – Whether multiple artists can be “on” at the same time. • highlight (bool, default: False) – Whether to also highlight the selected artist. If so, “highlighter” artists will be placed as the first item in the extras attribute of the Selection. • hover (HoverMode, default: False) – Whether to select artists upon hovering instead of by clicking. (Hovering over an artist while a button is pressed will not trigger a selection; right clicking on an annotation will still remove it.) Possible values are – False, alias HoverMode.NoHover: hovering is inactive. – True, alias HoverMode.Persistent: hovering is active; annotations remain in place even after the mouse moves away from the artist (until another artist is selected, if multiple is False. – 2, alias HoverMode.Transient: hovering is active; annotations are removed as soon as the mouse moves away from the artist. • bindings (dict, optional) – A mapping of actions to button and keybindings. Valid keys are:

’select’ mouse button to select an artist (default: 1) ’deselect’ mouse button to deselect an artist (default: 3) ’left’ move to the previous point in the selected path, or to the left in the selected image (default: shift+left) ’right’ move to the next point in the selected path, or to the right in the selected image (default: shift+right) ’up’ move up in the selected image (default: shift+up) ’down’ move down in the selected image (default: shift+down) ’tog- toggle whether the cursor is active (default: e) gle_enabled’ ’tog- toggle default cursor visibility and apply it to all cursors (default: v) gle_visible’

Missing entries will be set to the defaults. In order to not assign any binding to an action, set it to None. Modifier keys (or other event properties) can be set for mouse button bindings by passing them as e.g. {"button": 1, "key": "control"}. • annotation_kwargs (dict, default: {}) – Keyword argments passed to the annotate call.

22 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

• annotation_positions (List[dict], optional) – List of positions tried by the annotation positioning algorithm. The default is to try four positions, 15 points to the NW, NE, SE, and SW from the selected point; annotations that stay within the axes are preferred. • highlight_kwargs (dict, default: {}) – Keyword arguments used to create a highlighted artist. property artists The tuple of selectable artists. property enabled Whether clicks are registered for picking and unpicking events. property selections The tuple of current Selections. property visible Whether selections are visible by default. Setting this property also updates the visibility status of current selections. add_selection(pi) Create an annotation for a Selection and register it. Returns a new Selection, that has been registered by the Cursor, with the added annotation set in the annotation field and, if applicable, the highlighting artist in the extras field. Emits the "add" event with the new Selection as argument. When the event is emitted, the position of the annotation is temporarily set to (nan, nan); if this position is not explicitly set by a callback, then a suitable position will be automatically computed. Likewise, if the text alignment is not explicitly set but the position is, then a suitable alignment will be automatically computed. add_highlight(artist, *args, **kwargs) Create, add, and return a highlighting artist. This method is should be called with an “unpacked” Selection, possibly with some fields set to None. It is up to the caller to register the artist with the proper Selection (by calling sel.extras.append on the result of this method) in order to ensure cleanup upon deselection. connect(event, func=None) Connect a callback to a Cursor event; return the callback. Two events can be connected to: • callbacks connected to the "add" event are called when a Selection is added, with that selection as only argument; • callbacks connected to the "remove" event are called when a Selection is removed, with that selection as only argument. This method can also be used as a decorator:

@cursor.connect("add") def on_add(sel): ...

Examples of callbacks:

10.1. The mplcursors API 23 mplcursors Documentation, Release 0.4

# Change the annotation text and alignment: lambda sel: sel.annotation.set( text=sel.artist.get_label(), # or use e.g. sel.target.index ha="center", va="bottom")

# Make label non-draggable: lambda sel: sel.draggable(False)

Note that when a single event causes both the removal of an “old” selection and the addition of a “new” one (typically, clicking on an artist when another one is selected, or hovering – both assuming that multiple=False), the “add” callback is called first. This allows it, in particular, to “cancel” the addition (by immediately removing the “new” selection) and thus avoid removing the “old” selection. However, this call order may change in a future release. disconnect(event, cb) Disconnect a previously connected callback. If a callback is connected multiple times, only one connection is removed. remove() Remove a cursor. Remove all Selections, disconnect all callbacks, and allow the cursor to be garbage collected. remove_selection(sel) Remove a Selection. class mplcursors.HoverMode Bases: enum.IntEnum An enumeration. NoHover = 0 Persistent = 1 Transient = 2 mplcursors.cursor(pickables=None, **kwargs) Create a Cursor for a list of artists, containers, and axes. Parameters • pickables (Optional[List[Union[Artist, Container, Axes, Figure]]]) – All artists and containers in the list or on any of the axes or figures passed in the list are selectable by the constructed Cursor. Defaults to all artists and containers on any of the figures that pyplot is tracking. Note that the latter will only work when relying on pyplot, not when figures are directly instantiated (e.g., when manually embedding Matplotlib in a GUI toolkit). • **kwargs – Keyword arguments are passed to the Cursor constructor. class mplcursors.Selection(artist, target, dist, annotation, extras) Bases: tuple property annotation The instantiated matplotlib.text.Annotation. property artist The selected artist. property dist The distance from the click to the target, in pixels.

24 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

property extras An additional list of artists (e.g., highlighters) that will be cleared at the same time as the annotation. property target The point picked within the artist, in data coordinates. mplcursors.compute_pick(artist, event) Find whether artist has been picked by event. If it has, return the appropriate Selection; otherwise return None. This is a single-dispatch function; implementations for various artist classes follow. mplcursors.get_ann_text(artist, target, dist, annotation, extras) Compute an annotating text for a Selection (passed unpacked). This is a single-dispatch function; implementations for various artist classes follow. mplcursors.make_highlight(artist, target, dist, annotation, extras, *, highlight_kwargs) Create a highlight for a Selection. This is a single-dispatch function; implementations for various artist classes follow.

10.2 mplcursors examples

As mplcursors is fundamentally a library for interactivity, you should download the examples and try them yourself :-)

10.2.1 mplcursors’ core functionality

. . . is to add interactive data cursors to a figure.

10.2. mplcursors examples 25 mplcursors Documentation, Release 0.4

import matplotlib.pyplot as plt import numpy as np import mplcursors data= np.outer(range(10), range(1,5)) fig, ax= plt.subplots() lines= ax.plot(data) ax.set_title("Click somewhere on a line.\nRight-click to deselect.\n" "Annotations can be dragged.") fig.tight_layout() mplcursors.cursor(lines) plt.show()

26 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

10.2.2 Annotate on hover

When hover is set to True, annotations are displayed when the mouse hovers over the artist, without the need for clicking.

import matplotlib.pyplot as plt import numpy as np import mplcursors np.random.seed(42) fig, ax= plt.subplots() ax.scatter(*np.random.random((2, 26))) ax.set_title("Mouse over a point") mplcursors.cursor(hover=True) plt.show()

10.2. mplcursors examples 27 mplcursors Documentation, Release 0.4

10.2.3 Changing properties of the popup

Use an event handler to customize the popup.

import matplotlib.pyplot as plt import numpy as np import mplcursors fig, axes= plt.subplots(ncols=2) left_artist= axes[0].plot(range(11)) axes[0].set(title="No box, different position", aspect=1) right_artist= axes[1].imshow(np.arange(100).reshape(10, 10)) axes[1].set(title="Fancy white background")

# Make the text pop up "underneath" the line and remove the box... c1= mplcursors.cursor(left_artist) @c1.connect("add") def _(sel): sel.annotation.set(position=(15,-15)) # Note: Needs to be set separately due to matplotlib/matplotlib#8956. sel.annotation.set_bbox(None)

# Make the box have a white background with a fancier connecting arrow (continues on next page)

28 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

(continued from previous page) c2= mplcursors.cursor(right_artist) @c2.connect("add") def _(sel): sel.annotation.get_bbox_patch().set(fc="white") sel.annotation.arrow_patch.set(arrowstyle="simple", fc="white", alpha=.5) plt.show()

10.2.4 Contour plots

Contour plot support is limited to picking the individual LineCollections, which are directly registered with the axes and thus picked up by mplcursors.cursor (QuadContourSets are not even artists, which make them hard to handle without additional special-casing). It remains possible to retrieve the z value and add it manually to the annotation, though.

import numpy as np import matplotlib.pyplot as plt import mplcursors np.random.seed(42) fig, ax= plt.subplots() (continues on next page)

10.2. mplcursors examples 29 mplcursors Documentation, Release 0.4

(continued from previous page) cf= ax.contour(np.random.random((10, 10))) cursor= mplcursors.cursor()

@cursor.connect("add") def on_add(sel): ann= sel.annotation # `cf.collections.index(sel.artist)` is the index of the selected line # among all those that form the contour plot. # `cf.cvalues[...]` is the corresponding value. ann.set_text("{}\nz={:.3g}".format( ann.get_text(), cf.cvalues[cf.collections.index(sel.artist)])) plt.show()

10.2.5 Cursors on images

. . . display the underlying data value.

import matplotlib.pyplot as plt import numpy as np import mplcursors data= np.arange(100).reshape((10, 10)) (continues on next page)

30 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

(continued from previous page) fig, axes= plt.subplots(ncols=2) axes[0].imshow(data, interpolation="nearest", origin="lower") axes[1].imshow(data, interpolation="nearest", origin="upper", extent=[200, 300, 400, 500]) mplcursors.cursor() fig.suptitle("Click anywhere on the image") plt.show()

10.2.6 Datetime data mplcursors correctly formats datetime data.

import datetime as dt import numpy as np import matplotlib.pyplot as plt import matplotlib.dates as mdates import mplcursors t= mdates.drange(dt.datetime(2014,1, 15), dt.datetime(2014,2, 27), dt.timedelta(hours=2)) (continues on next page)

10.2. mplcursors examples 31 mplcursors Documentation, Release 0.4

(continued from previous page) y= np.sin(t) fig, ax= plt.subplots() ax.plot_date(t, y,"-") fig.autofmt_xdate()

# Note that mplcursors will automatically display the x-values as dates. mplcursors.cursor() plt.show()

10.2.7 Display a bar’s height and name on top of it upon hovering

Using an event handler to change the annotation text and position.

import string import matplotlib.pyplot as plt import mplcursors fig, ax= plt.subplots() ax.bar(range(9), range(1, 10), align="center") labels= string.ascii_uppercase[:9] ax.set(xticks=range(9), xticklabels=labels, title="Hover over a bar")

(continues on next page)

32 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

(continued from previous page) # With HoverMode.Transient, the annotation is removed as soon as the mouse # leaves the artist. Alternatively, one can use HoverMode.Persistent (or True) # which keeps the annotation until another artist gets selected. cursor= mplcursors.cursor(hover=mplcursors.HoverMode.Transient) @cursor.connect("add") def on_add(sel): x, y, width, height= sel.artist[sel.target.index].get_bbox().bounds sel.annotation.set(text=f"{x+width/2}: {height}", position=(0, 20), anncoords="offset points") sel.annotation.xy= (x+ width/2, y+ height) plt.show()

10.2.8 Display an artist’s label instead of x, y coordinates

Use an event handler to change the annotation text.

import numpy as np import matplotlib.pyplot as plt import mplcursors x= np.linspace(0, 10, 100)

(continues on next page)

10.2. mplcursors examples 33 mplcursors Documentation, Release 0.4

(continued from previous page) fig, ax= plt.subplots() ax.set_title("Click on a line to display its label")

# Plot a series of lines with increasing slopes. for i in range(1, 20): ax.plot(x, i * x, label=f"$y = {i}x$")

# Use a Cursor to interactively display the label for a selected line. mplcursors.cursor().connect( "add", lambda sel: sel.annotation.set_text(sel.artist.get_label())) plt.show()

10.2.9 Displaying a custom label for each individual point mpldatacursor’s point_labels functionality can be emulated with an event handler that sets the annotation text with a label selected from the target index.

import matplotlib.pyplot as plt import mplcursors import numpy as np

(continues on next page)

34 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

(continued from previous page) labels=["a","b","c","d","e"] x= np.array([0,1,2,3,4]) fig, ax= plt.subplots() line,= ax.plot(x, x,"ro") mplcursors.cursor(ax).connect( "add", lambda sel: sel.annotation.set_text(labels[sel.target.index])) plt.show()

10.2.10 Extracting data and labels from a DataFrame

DataFrames can be used similarly to any other kind of input. Here, we generate a scatter plot using two columns and label the points using a third column.

from matplotlib import pyplot as plt import mplcursors from pandas import DataFrame df= DataFrame( [("Alice", 163, 54), (continues on next page)

10.2. mplcursors examples 35 mplcursors Documentation, Release 0.4

(continued from previous page) ("Bob", 174, 67), ("Charlie", 177, 73), ("Diane", 168, 57)], columns=["name","height","weight"]) df.plot.scatter("height","weight") mplcursors.cursor().connect( "add", lambda sel: sel.annotation.set_text(df["name"][sel.target.index])) plt.show()

# test: skip

10.2.11 Highlighting the artist upon selection

Just pass highlight=True to cursor.

import numpy as np import matplotlib.pyplot as plt import mplcursors x= np.linspace(0, 10, 100) fig, ax= plt.subplots() (continues on next page)

36 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

(continued from previous page)

# Plot a series of lines with increasing slopes. lines=[] for i in range(1, 20): line,= ax.plot(x, i * x, label=f"$y = {i}x$") lines.append(line) mplcursors.cursor(lines, highlight=True) plt.show()

10.2.12 Keyboard shortcuts

By default, mplcursors uses “t” to toggle interactivity and “d” to hide/show annotation boxes. These shortcuts can be customized.

import matplotlib.pyplot as plt import mplcursors fig, ax= plt.subplots() ax.plot(range(10),"o-") ax.set_title('Press"e" to enable/disable the datacursor \n' 'Press"h" to hide/show any annotation boxes') (continues on next page)

10.2. mplcursors examples 37 mplcursors Documentation, Release 0.4

(continued from previous page) mplcursors.cursor(bindings={"toggle_visible":"h","toggle_enabled":"e"}) plt.show()

10.2.13 Linked artists

An example of connecting to cursor events: when an artist is selected, also highlight its “partner”.

import numpy as np import matplotlib.pyplot as plt import mplcursors def main(): fig, axes= plt.subplots(ncols=2) num=5 xy= np.random.random((num,2))

lines=[] for i in range(num): line,= axes[0].plot((i+1) * np.arange(10)) lines.append(line) (continues on next page)

38 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

(continued from previous page)

points=[] for x, y in xy: point,= axes[1].plot([x], [y], linestyle="none", marker="o") points.append(point)

cursor= mplcursors.cursor(points+ lines, highlight= True) pairs= dict(zip(points, lines)) pairs.update(zip(lines, points))

@cursor.connect("add") def on_add(sel): sel.extras.append(cursor.add_highlight(pairs[sel.artist]))

plt.show() if __name__ =="__main__": main()

10.2.14 Scatter plots are highlighted point-by-point.

. . . as opposed to lines with a "." style, which have the same appearance, but are highlighted as a whole.

10.2. mplcursors examples 39 mplcursors Documentation, Release 0.4

import numpy as np import matplotlib.pyplot as plt import mplcursors x, y, z= np.random.random((3, 10)) fig, axs= plt.subplots(3) fig.suptitle("Highlighting affects individual points\n" "only in scatter plots (top two axes)") axs[0].scatter(x, y, c=z, s=100 * np.random.random(10)) axs[1].scatter(x, y) axs[2].plot(x, y,"o") mplcursors.cursor(highlight=True) plt.show()

10.2.15 Step plots

A selection on a step plot holds precise information on the x and y position in the sel.target.index sub-attribute.

from matplotlib import pyplot as plt import mplcursors import numpy as np

(continues on next page)

40 Chapter 10. Indices and tables mplcursors Documentation, Release 0.4

(continued from previous page) fig, axs= plt.subplots(4, sharex= True, sharey=True) np.random.seed(42) xs= np.arange(5) ys= np.random.rand(5) axs[0].plot(xs, ys,"-o") axs[1].plot(xs, ys,"-o", drawstyle="steps-pre") axs[2].plot(xs, ys,"-o", drawstyle="steps-mid") axs[3].plot(xs, ys,"-o", drawstyle="steps-post") for ax in axs: ax.label_outer() mplcursors.cursor().connect( "add", lambda sel: sel.annotation.set_text(format(sel.target.index,".2f"))) plt.show()

10.2.16 Using multiple annotations and disabling draggability via signals

By default, each Cursor will ever display one annotation at a time. Pass multiple=True to display multiple annotations. Annotations can be made non-draggable by hooking their creation.

10.2. mplcursors examples 41 mplcursors Documentation, Release 0.4

import matplotlib.pyplot as plt import numpy as np import mplcursors data= np.outer(range(10), range(1,5)) fig, ax= plt.subplots() ax.set_title("Multiple non-draggable annotations") ax.plot(data) mplcursors.cursor(multiple=True).connect( "add", lambda sel: sel.annotation.draggable(False)) plt.show()

42 Chapter 10. Indices and tables PYTHON MODULE INDEX

m mplcursors, 21

43 mplcursors Documentation, Release 0.4

44 Python Module Index INDEX

Symbols M __init__() (mplcursors.Cursor method), 22 make_highlight() (in module mplcursors), 25 MPLCURSORS,7 A mplcursors (module), 21 add_highlight() (mplcursors.Cursor method), 23 add_selection() (mplcursors.Cursor method), 23 N annotation() (mplcursors.Selection property), 24 NoHover (mplcursors.HoverMode attribute), 24 annotation_kwargs (mplcursors.Cursor attribute), 21 P annotation_positions (mplcursors.Cursor Persistent (mplcursors.HoverMode attribute), 24 attribute), 21 PYTHONPATH,7 artist() (mplcursors.Selection property), 24 artists() (mplcursors.Cursor property), 23 R remove() (mplcursors.Cursor method), 24 B remove_selection() (mplcursors.Cursor method), bindings (mplcursors.Cursor attribute), 21 24 C S compute_pick() (in module mplcursors), 25 Selection (class in mplcursors), 24 connect() (mplcursors.Cursor method), 23 selections() (mplcursors.Cursor property), 23 Cursor (class in mplcursors), 21 cursor() (in module mplcursors), 24 T target() (mplcursors.Selection property), 25 D Transient (mplcursors.HoverMode attribute), 24 disconnect() (mplcursors.Cursor method), 24 dist() (mplcursors.Selection property), 24 V visible() (mplcursors.Cursor property), 23 E enabled() (mplcursors.Cursor property), 23 environment variable MPLCURSORS,7 PYTHONPATH,7 extras() (mplcursors.Selection property), 24 G get_ann_text() (in module mplcursors), 25 H highlight_kwargs (mplcursors.Cursor attribute), 22 HoverMode (class in mplcursors), 24

45