Getting started with plot widgets

This introduction to silx.gui.plot covers the following topics:

For a complete description of the API, see silx.gui.plot.

Use silx.gui.plot from the console

From IPython

To run silx.gui.plot widgets from IPython, IPython must be set to use Qt (and in case of using PyQt4 and Python 2.7, PyQt must be set ti use API version 2, see Explanation below).

As silx is performing some configuration of the Qt binding and matplotlib, the safest way to use silx from IPython is to import silx.gui.plot first and then run either %gui qt or %pylab qt:

In [1]: from silx.gui.plot import *
In [2]: %pylab qt

Alternatively, when using Python 2.7 and PyQt4, you can start IPython with the QT_API environment variable set to pyqt.

On Linux and MacOS X, run:

QT_API=pyqt ipython

On Windows, run from the command line:

set QT_API=pyqt&&ipython

Explanation

PyQt4 used from Python 2.x provides 2 incompatible versions of QString and QVariant:

  • version 1, the legacy which is the default, and
  • version 2, a more pythonic one, which is the only one supported by silx.

All other configurations (i.e., PyQt4 on Python 3.x, PySide, PyQt5, IPython QtConsole widget) uses version 2 only or as the default.

For more information, see IPython, PyQt and PySide.

From Python

The silx.sx package is a convenient module to use silx from the console. It sets-up Qt and provides functions for the main features of silx.

>>> from silx import sx

Alternatively, you can create a QApplication before using silx widgets:

>>> from silx.gui import qt  # Import Qt binding and do some set-up
>>> qapp = qt.QApplication([])

>>> from silx.gui.plot import *  # Import plot widgets and set-up matplotlib

Plot functions

The silx.sx package provides 2 functions to plot curves and images from the (I)Python console in a widget with a set of tools:

  • plot(), and
  • imshow().

For more features, use widgets directly (see Plot curves in a widget and Plot images in a widget).

Curve: plot()

The following examples must run with a Qt QApplication initialized (see Use silx.gui.plot from the console).

First import sx function:

>>> from silx import sx
>>> import numpy

Plot a single curve given some values:

>>> values = numpy.random.random(100)
>>> plot_1curve = sx.plot(values, title='Random data')

Plot a single curve given the x and y values:

>>> angles = numpy.linspace(0, numpy.pi, 100)
>>> sin_a = numpy.sin(angles)
>>> plot_sinus = sx.plot(angles, sin_a,
...                      xlabel='angle (radian)', ylabel='sin(a)')

Plot many curves by giving a 2D array, provided xn, yn arrays:

>>> plot_curves = sx.plot(x0, y0, x1, y1, x2, y2, ...)

Plot curve with style giving a style string:

>>> plot_styled = sx.plot(x0, y0, 'ro-', x1, y1, 'b.')

See plot() for details.

Image: imshow()

This example plot a single image.

First, import silx.sx:

>>> from silx import sx
>>> import numpy

>>> data = numpy.random.random(1024 * 1024).reshape(1024, 1024)
>>> plt = sx.imshow(data, title='Random data')

See imshow() for more details.

Use silx.gui.plot from a script

A Qt GUI script must have a QApplication initialized before creating widgets:

from silx.gui import qt

[...]

qapp = qt.QApplication([])

[...] # Widgets initialisation

if __name__ == '__main__':
    [...]
    qapp.exec_()

Unless a Qt binding has already been loaded, silx.gui.qt uses the first Qt binding it founds by probing in the following order: PyQt5, PyQt4 and finally PySide. If you prefer to choose the Qt binding yourself, import it before importing a module from silx.gui:

import PySide  # Importing PySide will force silx to use it
from silx.gui import qt

Warning

silx.gui.plot widgets are not thread-safe. All calls to silx.gui.plot widgets must be made from the main thread.

Plot curves in a widget

The Plot1D widget provides a plotting area and a toolbar with tools useful for curves such as setting logarithmic scale or defining region of interest.

First, create a Plot1D widget:

from silx.gui.plot import Plot1D

plot = Plot1D()  # Create the plot widget
plot.show()  # Make the plot widget visible

One curve

To display a single curve, use the PlotWidget.addCurve() method:

plot.addCurve(x=(1, 2, 3), y=(3, 2, 1))  # Add a curve with default style

When you need to update this curve, call PlotWidget.addCurve() again with the new values to display:

plot.addCurve(x=(1, 2, 3), y=(1, 2, 3))  # Replace the existing curve

To clear the plotting area, call PlotWidget.clear():

plot.clear()

Multiple curves

In order to display multiple curves at the same time, you need to provide a different legend string for each of them:

import numpy

x = numpy.linspace(-numpy.pi, numpy.pi, 1000)
plot.addCurve(x, numpy.sin(x), legend='sinus')
plot.addCurve(x, numpy.cos(x), legend='cosinus')
plot.addCurve(x, numpy.random.random(len(x)), legend='random')

To update a curve, call PlotWidget.addCurve() with the legend of the curve you want to udpdate. By default, the new curve will keep the same color (and style) as the curve it is updating:

plot.addCurve(x, numpy.random.random(len(x)) - 1., legend='random')

To remove a curve from the plot, call PlotWidget.remove() with the legend of the curve you want to remove from the plot:

plot.remove('random')

To clear the plotting area, call PlotWidget.clear():

plot.clear()

Curve style

By default, different curves will automatically use different styles to render, and keep the same style when updated.

It is possible to specify the color of the curve, its linewidth and linestyle as well as the symbol to use as markers for data points (See PlotWidget.addCurve() for more details):

import numpy

x = numpy.linspace(-numpy.pi, numpy.pi, 100)

# Curve with a thick dashed line
plot.addCurve(x, numpy.sin(x), legend='sinus',
              linewidth=3, linestyle='--')

# Curve with pink markers only
plot.addCurve(x, numpy.cos(x), legend='cosinus',
              color='pink', linestyle=' ', symbol='o')

# Curve with green line with square markers
plot.addCurve(x, numpy.random.random(len(x)), legend='random',
              color='green', linestyle='-', symbol='s')

Histogram

Data can be displayed as an histogram. This must be specified when calling the the addCurve function. (using histogram, See PlotWidget.addCurve() for more details ).

Histogram steps can be centered on x values or set at the left or the right of the given x values.

import numpy
x = numpy.arange(0, 20, 1)
plot.addCurve(x, x+1, histogram='center', fill=True, color='green')

Note

You can also give x as edges. For this you must have len(x) = len(y) + 1

Plot images in a widget

The Plot2D widget provides a plotting area and a toolbar with tools useful for images, such as keeping aspect ratio, changing the colormap or defining a mask.

First, create a Plot2D widget:

from silx.gui.plot import Plot2D

plot = Plot2D()  # Create the plot widget
plot.show()  # Make the plot widget visible

One image

To display a single image, use the PlotWidget.addImage() method:

import numpy

data = numpy.random.random(512 * 512).reshape(512, -1)  # Create 2D image
plot.addImage(data)  # Plot the 2D data set with default colormap

To update this image, call PlotWidget.addImage() again with the new image to display:

# Create a RGB image
rgb_image = (numpy.random.random(512*512*3) * 255).astype(numpy.uint8)
rgb_image.shape = 512, 512, 3

plot.addImage(rgb_image)  # Plot the RGB image instead of the previous data

To clear the plotting area, call PlotWidget.clear():

plot.clear()

Origin and scale

PlotWidget.addImage() supports both 2D arrays of data displayed with a colormap and RGB(A) images as 3D arrays of shape (height, width, color channels).

When displaying an image, it is possible to specify the origin and the scale of the image array in the plot area coordinates:

data = numpy.random.random(512 * 512).reshape(512, -1)
plot.addImage(data, origin=(100, 100), scale=(0.1, 0.1))

When updating an image, if origin and scale are not provided, the previous values will be used:

data = numpy.random.random(512 * 512).reshape(512, -1)
plot.addImage(data)  # Keep previous origin and scale

Colormap

A colormap is described with a Colormap class as follows:

colormap = Colormap(name='gray',             # Name of the colormap
                    normalization='linear',  # Either 'linear' or 'log'
                    vmin=0.0,                # If not autoscale, data value to bind to min of colormap
                    vmax=1.0                 # If not autoscale, data value to bind to max of colormap
            )

At least the following colormap names are guaranteed to be available, but any colormap name from matplotlib (see Choosing Colormaps) should work:

  • gray
  • reversed gray
  • temperature
  • red
  • green
  • blue
  • viridis
  • magma
  • inferno
  • plasma

It is possible to change the default colormap of PlotWidget.addImage() for the plot widget with PlotWidget.setDefaultColormap() (and to get it with PlotWidget.getDefaultColormap()):

colormap = Colormap(name='viridis',
                    normalization='linear',
                    vmin=0.0,
                    vmax=1.0)
plot.setDefaultColormap(colormap)

data = numpy.arange(512 * 512.).reshape(512, -1)
plot.addImage(data)  # Rendered with the default colormap set before

It is also possible to provide a Colormap to PlotWidget.addImage() to override this default for an image:

colormap = Colormap(name='magma',
                    normalization='log',
                    vmin=1.2,
                    vmax=1.8)
data = numpy.random.random(512 * 512).reshape(512, -1) + 1.
plot.addImage(data, colormap=colormap)

As for Origin and scale, when updating an image, if colormap is not provided, the previous colormap will be used:

data = numpy.random.random(512 * 512).reshape(512, -1) + 1.
plot.addImage(data)  # Keep previous colormap

The colormap can be changed by the user from the widget’s toolbar.

Multiple images

In order to display multiple images at the same time, you need to provide a different legend string for each of them and to set the replace argument to False:

data = numpy.random.random(512 * 512).reshape(512, -1)
plot.addImage(data, legend='random', replace=False)

data = numpy.arange(512 * 512.).reshape(512, -1)
plot.addImage(data, legend='arange', replace=False, origin=(512, 512))

To update an image, call PlotWidget.addImage() with the legend of the curve you want to udpdate. By default, the new image will keep the same colormap, origin and scale as the image it is updating:

data = (512 * 512. - numpy.arange(512 * 512.)).reshape(512, -1)
plot.addImage(data, legend='arange', replace=False)  # Beware of replace=False

To remove an image from the plot, call PlotWidget.remove() with the legend of the image you want to remove:

plot.remove('random')

Control plot axes

The following examples illustrate the API to control the plot axes. PlotWidget.getXAxis() and PlotWidget.getYAxis() give access to each plot axis (items.Axis) in order to control them.

Labels and title

Use PlotWidget.setGraphTitle() to set the plot main title. Use PlotWidget.getXAxis() and PlotWidget.getYAxis() to get the axes and set their text label with items.Axis.setLabel():

plot.setGraphTitle('My plot')
plot.getXAxis().setLabel('X')
plot.getYAxis().setLabel('Y')

Axes limits

Different methods allows to get and set the data limits displayed on each axis.

The following code moves the visible plot area to the right:

xmin, xmax = plot.getXAxis().getLimits()
offset = 0.1 * (xmax - xmin)
plot.getXAxis().setLimits(xmin + offset, xmax + offset)

PlotWidget.resetZoom() set the plot limits to the bounds of the data:

plot.resetZoom()

See PlotWidget.resetZoom(), PlotWidget.setLimits(), PlotWidget.getXAxis(), PlotWidget.getYAxis() and items.Axis for details.

Axes

Different methods allow plot axes modifications:

plot.getYAxis().setInverted(True)  # Makes the Y axis pointing downward
plot.setKeepDataAspectRatio(True)  # To keep aspect ratio between X and Y axes

See PlotWidget.getYAxis(), PlotWidget.setKeepDataAspectRatio() for details.

plot.setGraphGrid(which='both')  # To show a grid for both minor and major axes ticks

# Use logarithmic axes
plot.getXAxis().setScale("log")
plot.getYAxis().setScale("log")

See PlotWidget.setGraphGrid(), PlotWidget.getXAxis(), PlotWidget.getXAxis() and items.Axis for details.