Live Plotter

Table of Contents

• Requirements
• Installation
• Notes about backends
• Usage
  • Record data to be plotted
  • Set up live plotting
    • Use one of the existing live plot classes
    • Write your own live plot class
• Example
• Building documentation locally

This package provides a simple interface to do live plotting and realtime plotting using matplotlib.

Detailed documentation here: https://igitugraz.github.io/live-plotter/

Supports Python 2.7+ and Python 3.2+

Requirements

System dependencies:

• zeromq

Python dependencies are listed in requirements.txt

Installation

# Use pip3 and python3 to use Python 3.x
pip install --process-dependency-links https://github.com/IGITUGraz/live-plotter/archive/master.zip

You can also install by cloning the repository:

git clone git@github.com:IGITUGraz/live-plotter.git
cd live-plotter
# Use pip3 and python3 to use Python 3.x
pip install -r requirements.txt
python setup.py install

Notes about backends

This package has been tested with the TkAgg backend on linux and Gtk3Agg backend on macOS, but none of the other combinations.

To set the default backend on linux, edit $HOME/.config/matplotlib/matplotlibrc and add the following line:

backend : tkagg

This backend requires tkinter to be installed -- the python-tk ( python3-tk) package on Ubuntu/Debian

To set the default backend on macOS, edit $HOME/.matplotlib/matplotlibrc and add the following line:

backend : gtk3agg

This backend requires the pygobject package to be installed -- the py27-gobject3 ( py36-gobject3 -- replace py36 with your python3 version) package on MacPorts.

See [1] and [2] for more information

[1]	http://matplotlib.org/faq/usage_faq.html#what-is-a-backend

[2]	http://matplotlib.org/faq/virtualenv_faq.html

Usage

Record data to be plotted

It consists of two parts: a PlotRecorder and a Plotter.

For any code you have, you can record the values that you want to plot using the PlotRecorder as follows:

from liveplotter.plotrecorder import PlotRecorder
plot_recorder = PlotRecorder()


def simulate():
  ...
  # Your simulation code here
  x = ...
  x_sq = x**2
  plot_recorder.record("x_sq", x_sq)

This sends the recorded variable to a ZeroMQ Queue, but otherwise is very low overhead and doesn't affect your simulation, even if you decide not to do live plotting for any particular run.

After the simulation is finished, call plot_recorder.close('x_sq') to do a clean shutdown.

Set up live plotting

To actually do live plotting, you can do one of two things:

Use one of the existing live plot classes

There are plotting methods available for single lines, multiple lines, images and spikes. Look at the documentation in the classes in liveplotter.plotter_impls.py in the documentation

Write your own live plot class

would implement a Plotter in a different file that inherits from PlotterBase as follows:

from liveplotter.plotrecorder import PlotterBase

class YourPlotter(PlotterBase):
    def init(self):
        # Make sure you call the super `init` method. This initializes `self.plt`
        super().init()

        logger.info("First initializing plots in thread %s", self.entity_name)
        # It is necessary to assign the variable `self.fig` in this init function

        self.fig, self.ax = self.plt.subplots()

        # Your initialization code here
        ...

        return self

    def plot_loop(self, var_value, i):
        # Implements the plotting loop.
        logger.debug("Plotting %s in %s", self.var_name, self.entity_name)

        # Plot the variable and return a matplotlib.artist.Artist object

And start it with:

YourPlotter('x_sq').start()

Example

You can find an example in the example directory.

To run it, do cd example; ./run.sh

It runs the two files example/simulation.py and example/plot.py and shows the fractal generation live.

The animation will look like this:

Building documentation locally

After cloning the repository, go to the doc directory and first install the documentation requirements with

cd doc
pip install -r requirements.txt  # use pip3 for python3

Then run:

make html

and open the documentation at doc/build/html/index.html