mpld3 Documentation

I want to take some notes on mpld3 to see if it is more practical to use / whether I should use it vs Bokeh.

• mpld3 Documentation
• mpld3 Example Gallery
• mpld3 Notebook Examples
• mpld3 GitHub
• mpld3 API Documentation

The mpld3 project brings together Matplotlib, the popular Python-based graphing libraru, and D3js, the popular JavaScript library for creating interactive data visualizations for the web. The result is a simple API for exporting your matplotlib graphics to HTML code which can be used within the browser, within standard web pages, blogs, or tools such as the IPython notebook.

The mpld3 package is extremely easy to use: you simply take any script generating a matplotlib plot, run it through one of mpld3's convenience routines, and embed the result in a web page. The current release of mpld3 can be installed with pip:

bash $ pip install mpld3

Then you can make an interactive plot like so:

python import matplotlib.pyplot as plt, mpld3 plt.plot([3,1,4,1,5], 'ks-', mec='w', mew=5, ms=20) mpld3.show()

These are the general functions used to convert matplotlib graphics into HTML and D3js.

• fig_to_html()
  • This is the core routine which takes a figure and constructs a string of HTML and JavaScript which can be embedded in any webpage
• fig_to_dict()
  • This routine converts a matplotlib image to a JSON-serializable dictionary, which can be loaded into an appropraite HTML page and rendered via the mpld3 JavaScript library. Note the custom plugins which are not built into mpld3 will not be part of the JSON serialization.
• show()
  • This function is mpld3's equivalent of matpltlib's plt.show function. It will convert the current figure to HTML using fig_to_d3(), start a local webserver which serves this HTML, and (if the operating system allows it) automatically open this page in the web browser.

Figures can be saved to file either in a stand-alone HTML format, or in a JSON format. mpld3 supplies the following convenience routines for this purpose:

• save_html()
  • Save a figure to a stand-alone HTML file
• save_json()
  • Save the JSON representatoon of the figure to a file. Note that custom plugins which are not built into mpld3 will not be part of the JSON serialization.

The mpld3 plugin framework nearly endless possibilities for adding interactive behavior to matplotlib plots rendered in d3. The package includes several built-in plugins, which add zooming, panning, and other interactive behaviors to plots. Several examples of these plugins can be seen in the Example Gallery.

A core piece of the mpld3 package are the JavaScript libraries, which are located in the package in the mpld3/js/ directory. The mpld3.*.js is automatically constructed from a number of source JavaScript files; if you modify these sources, the libraries must be rebuilt before mpld3 is installed.

• Does mpld3 work for large datasets?

Short answer: not really. Mpld3, like matplotlib itself, is designed for small to medium-scale visualizations, and this is unlikely to change. The reason is that mpld3 is built upon the foundation of HTML's SVGm which is not particularly well-suited for large datasets. Plots with more than a few thousand elements will have noticeably slow response for interactive features.

• What matplotlib features are not supported?

A list of unsupported features can be found with this GitHub link.

• Can I use mpld3 without matplotlib?

The client-side interface of mpld3 is a pure JavaScript library, which builds figures based on a well-defined JSON specification. This specification was designed with matplotlib in mind, but there's nothing stopping you from generating the JSON from another source.

• Can mpld3 render to HTML5 canvas rather than SVG?

At the moment, mpld3 only renders to SVG via D3, not to canvas.

• Where is the mpld3 JavaScript library located?

There is a local copy of the mpld3 library bundled with the package, which you can find in mpld3/js/mpld3.v0.2/js where v0.2 indicates the library version,and matches the version of the mpld3 Python package.

• How can I use mpld3 without an internet connection?

To use mpld3 without an internet connection, you need to use a local version of the mpld3 and d3 libraries.