This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

mpldatacursor provides interactive “data cursors” (clickable annotation boxes) for matplotlib.

Major Changes in v0.6

Version 0.6 adds:

  • Better handling of date-formatted axes.
  • “Popup” text boxes can be interactively hidden by right-clicking (controllable through the hide_button and display_button kwargs).
  • Proper support for twinned axes.
  • Better unicode support for the formatter function. Note that this makes mpldatacursor incompatibile with early 3.x versions (3.0, 3.1, and 3.2). However, it remains compatible with Python >= 3.3 (e.g. 3.3, 3.4, and 3.5) as well as 2.6 and 2.7.
  • Annotation boxes will now try to stay visible inside the figure by default. Specify keep_inside=False to disable this.
  • Added basic support for extracting the z-value of 3D artists.
  • Made the precision of the default x & y formatting depend on the range of the axes.
  • Full support for interactive IPython notebooks through the nbagg backend. Note that the performance on the nbagg may be very poor.
  • Full support for matplotlib 1.5.x, Python 3.5, and Qt5 (in v0.6.2).
  • Numerous bugfixes (Thanks to everyone for the reports!).

Basic Usage

mpldatacursor offers a few different styles of interaction through the datacursor function.

As an example, this displays the x, y coordinates of the selected artist in an annotation box:

import matplotlib.pyplot as plt
import numpy as np
from mpldatacursor import datacursor

data = np.outer(range(10), range(1, 5))

fig, ax = plt.subplots()
lines = ax.plot(data)
ax.set_title('Click somewhere on a line')

datacursor(lines)

plt.show()

If no artist or sequence of artists is specified, all manually plotted artists in all axes in all figures will be activated. (This can be limited to only certain axes by passing in an axes object or a sequence of axes to the axes kwarg.)

As an example (the output is identical to the first example):

import matplotlib.pyplot as plt
import numpy as np
from mpldatacursor import datacursor

data = np.outer(range(10), range(1, 5))

plt.plot(data)
plt.title('Click somewhere on a line')

datacursor()

plt.show()

Hiding Annotation Boxes and Toggling Interactivity

To hide a specific annotation box, right-click on it (Customizable through the hide_button kwarg). To hide all annotation boxes, press “d” on the keyboard. (Think of “delete”. “h” was taken by matplotlib’s default key for “home”.) To disable or re-enable interactive datacursors, press “t” (for “toggle”). These keys can be customized through the keybindings kwarg.

Controlling the Displayed Text

The displayed text can be controlled either by using the formatter kwarg, which expects a function that accepts an arbitrary sequence of kwargs and returns the string to be displayed. Often, it’s convenient to pass in the format method of a template string (e.g. formatter="longitude:{x:.2f}\nlatitude{y:.2f}".format).

As an example of using the formatter kwarg to display only the label of the artist instead of the x, y coordinates:

import numpy as np
import matplotlib.pyplot as plt
from mpldatacursor import datacursor

x = np.linspace(0, 10, 100)

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='$y = {}x$'.format(i))

# Use a DataCursor to interactively display the label for a selected line...
datacursor(formatter='{label}'.format)

plt.show()

Working with Images

datacursor will also display the array value at the selected point in an image. This example also demonstrates using the display="single" option to display only one data cursor instead of one-per-axes.:

import matplotlib.pyplot as plt
import numpy as np
from mpldatacursor import datacursor

data = np.arange(100).reshape((10,10))

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])
datacursor(display='single')

fig.suptitle('Click anywhere on the image')

plt.show()

Draggable Boxes

If draggable=True is specified, the annotation box can be interactively dragged to a new position after creation.

As an example (This also demonstrates using the display='multiple' kwarg):

import matplotlib.pyplot as plt
import numpy as np
from mpldatacursor import datacursor

data = np.outer(range(10), range(1, 5))

fig, ax = plt.subplots()
ax.set_title('Try dragging the annotation boxes')
ax.plot(data)

datacursor(display='multiple', draggable=True)

plt.show()

Further Customization

Additional keyword arguments to datacursor are passed on to annotate. This allows one to control the appearance and location of the “popup box”, arrow, etc. Note that properties passed in for the bbox and arrowprops kwargs will be merged with the default style. Therefore, specifying things like bbox=dict(alpha=1) will yield an opaque, yellow, rounded box, instead of matplotlib’s default blue, square box. As a basic example:

import matplotlib.pyplot as plt
import numpy as np
from mpldatacursor import datacursor

fig, axes = plt.subplots(ncols=2)

left_artist = axes[0].plot(range(11))
axes[0].set(title='No box, different position', aspect=1.0)

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...
dc1 = datacursor(left_artist, xytext=(15, -15), bbox=None)

# Make the box have a white background with a fancier connecting arrow
dc2 = datacursor(right_artist, bbox=dict(fc='white'),
                 arrowprops=dict(arrowstyle='simple', fc='white', alpha=0.5))

plt.show()

Highlighting Selected Lines

HighlightingDataCursor highlights a Line2D artist in addition to displaying the selected coordinates.:

import numpy as np
import matplotlib.pyplot as plt
from mpldatacursor import HighlightingDataCursor

x = np.linspace(0, 10, 100)

fig, ax = plt.subplots()

# Plot a series of lines with increasing slopes...
lines = []
for i in range(1, 20):
    line, = ax.plot(x, i * x, label='$y = {}x$'.format(i))
    lines.append(line)

HighlightingDataCursor(lines)

plt.show()

Installation

mpldatacursor can be installed from PyPi using easy_install/pip/etc. (e.g. pip install mpldatacursor) or you may download the source and install it directly with python setup.py install.

Release History

Release History

0.6.2

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.6.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.6.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
mpldatacursor-0.6.2-py2-none-any.whl (27.6 kB) Copy SHA256 Checksum SHA256 py2 Wheel Feb 13, 2016
mpldatacursor-0.6.2-py3-none-any.whl (27.6 kB) Copy SHA256 Checksum SHA256 py3 Wheel Feb 13, 2016
mpldatacursor-0.6.2.tar.gz (22.8 kB) Copy SHA256 Checksum SHA256 Source Feb 13, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting