fsleyes.plotting.plotcanvas

This module provides the PlotCanvas class, which plots DataSeries instances on a matplotlib canvas. The PlotCanvas is used by the TimeSeriesPanel, HistogramPanel, and PowerSpectrumPanel views, and potentially by other FSLeyes control panels.

class fsleyes.plotting.plotcanvas.PlotCanvas(*args, **kwargs)

Bases: HasProperties

The PlotCanvas can be used to plot DataSeries instances onto a matplotlib FigureCanvasWxAgg canvas.

The PlotCanvas is used by all FSLeyes views which display some sort of 2D data plot, such as the TimeSeriesPanel, and the HistogramPanel.

The PlotCanvas uses matplotlib for its plotting. The matplotlib Figure, Axis, and Canvas instances can be accessed via the figure(), axis(), and canvas() methods, if they are needed. Various display settings can be configured through PlotCanvas properties, including legend, smooth, etc.

Basic usage

After you have created a PlotCanvas, you can add DataSeries instances to the dataSeries property, then call draw() or asyncDraw().

The draw() method simply calls drawDataSeries() and drawArtists(), so you can alternately call those methods directly, or pass your own drawFunc when creating a PlotCanvas.

The PlotCanvas itself is not a wx object, so cannot be displayed - the matplotilb Canvas object, accessible through the canvas() method, is what you should add to a wx parent object.

Data series

A PlotCanvas instance plots data contained in one or more DataSeries instances; all DataSeries classes are defined in the plotting sub-package.

DataSeries objects can be plotted by passing them to the drawDataSeries() method.

Or, if you want one or more DataSeries to be held, i.e. plotted every time, you can add them to the dataSeries list. The DataSeries in the dataSeries list will be plotted on every call to drawDataSeries() (in addition to any DataSeries passed directly to drawDataSeries()) until they are removed from the dataSeries list.

The draw queue

The PlotCanvas uses a async.TaskThread to asynchronously extract and prepare data for plotting, This is because data preparation may take a long time for certain types of DataSeries (e.g. TimeSeries which are retrieving data from large Image overlays), and the main application thread should not be blocked while this is occurring. The TaskThread instance is accessible through the getDrawQueue() method, in case anything needs to be scheduled on it.

dataSeries

This list contains DataSeries instances which are plotted on every call to drawDataSeries(). DataSeries instances can be added/removed directly to/from this list.

artists

This list contains any matplotlib.Artist instances which are plotted every call to drawArtists().

legend

If True, a legend is added to the plot, with an entry for every DataSeries instance in the dataSeries list.

xAutoScale

If True, the plot limits for the X axis are automatically updated to fit all plotted data.

yAutoScale

If True, the plot limits for the Y axis are automatically updated to fit all plotted data.

xLogScale

Toggle a \(log_{10}\) x axis scale.

yLogScale

Toggle a \(log_{10}\) y axis scale.

invertX

Invert the plot along the X axis.

invertY

Invert the plot along the Y axis.

xScale

Scale to apply to the X axis data.

yScale

Scale to apply to the Y axis data.

xOffset

Offset to apply to the X axis data.

yOffset

Offset to apply to the Y axis data.

ticks

Toggle axis ticks and tick labels on/off.

grid

Toggle an axis grid on/off.

gridColour

Grid colour (if grid is True).

bgColour

Plot background colour.

smooth

If True all plotted data is up-sampled, and smoothed using spline interpolation.

xlabel

A label to show on the x axis.

ylabel

A label to show on the y axis.

limits

The x/y axis limits. If xAutoScale and yAutoScale are True, these limit values are automatically updated on every call to drawDataSeries().

showPreparingMessage

Show a message on the canvas whilst data is being prepared for plotting.

__init__(parent, drawFunc=None, prepareFunc=None)

Create a PlotCanvas.

Parameters:

• parent – The wx parent object.

• drawFunc – Custon function to call instead of draw().

• prepareFunc – Custom function to call instead of prepareDataSeries().

__annotations__ = {}

__module__ = 'fsleyes.plotting.plotcanvas'

destroy()

Removes some property listeners, and clears references to all DataSeries, matplotlib and wx objects.

property destroyed

Returns True if destroy() has been called, False otherwise.

property figure

Returns the matplotlib Figure instance.

property axis

Returns the matplotlib Axis instance.

property canvas

Returns the matplotlib Canvas instance.

getDrawQueue()

Returns the :class`.idle.TaskThread` instance used for data preparation.

draw(*a)

Call drawDataSeries() and then drawArtists(). Or, if a drawFunc was provided, calls that instead.

You will generally want to call asyncDraw() instead of this method.

asyncDraw(*a)

Schedules draw() to be run asynchronously. This method should be used in preference to calling draw() directly in most cases, particularly where the call occurs within a property callback function.

This method is automatically called called whenever a DataSeries is added to the dataSeries list, or when any plot display properties change.

message(msg, clear=True, border=False)

Displays the given message in the centre of the figure.

This is a convenience method provided for use by subclasses.

getArtist(ds)

Returns the matplotlib.Artist (typically a Line2D instance) associated with the given DataSeries instance. A KeyError is raised if there is no such artist.

getDrawnDataSeries()

Returns a list of tuples, each tuple containing the (DataSeries, x, y) data for one DataSeries instance as it is shown on the plot.

prepareDataSeries(ds)

Prepares the data from the given DataSeries so it is ready to be plotted. Called by the __drawOneDataSeries() method for any extraSeries passed to the drawDataSeries() method (but not applied to DataSeries that have been added to the dataSeries list).

This implementation just returns DataSeries.getData - you can pass a prepareFunc to __init__ to perform any custom preprocessing.

drawArtists(refresh=True, immediate=False)

Draw all matplotlib.Artist instances in the artists list, then refresh the canvas.

Parameters:

refresh – If True (default), the canvas is refreshed.

drawDataSeries(extraSeries=None, refresh=False, **plotArgs)

Queues a request to plot all of the DataSeries instances in the dataSeries list.

This method does not do the actual plotting - it is performed asynchronously, to avoid locking up the GUI:

1. The data for each DataSeries instance is prepared on separate threads (using idle.run()).

2. A call to idle.wait() is enqueued on a TaskThread.

3. This wait function waits until all of the data preparation threads have completed, and then passes all of the data to the __drawDataSeries() method.

Parameters:

• extraSeries – A sequence of additional DataSeries to be plotted. These series are passed through the prepareDataSeries() method before being plotted.

• refresh – If True, the canvas is refreshed. Otherwise, you must call getCanvas().draw() manually. Defaults to False - the drawArtists() method will refresh the canvas, so if you call drawArtists() immediately after calling this method (which you should), then you don’t need to manually refresh the canvas.

• plotArgs – Passed through to the __drawDataSeries() method.

Note

This method must only be called from the main application thread (the wx event loop).

__drawDataSeries(dataSeries, allXdata, allYdata, oldxlim, oldylim, refresh, xlabel=None, ylabel=None, **plotArgs)

Called by __drawDataSeries(). Plots all of the data associated with the given dataSeries.

Parameters:

• dataSeries – The list of DataSeries instances to plot.

• allXdata – A list of arrays containing X axis data, one for each DataSeries.

• allYdata – A list of arrays containing Y axis data, one for each DataSeries.

• oldxlim – X plot limits from the previous draw. If xAutoScale is disabled, this limit is preserved.

• oldylim – Y plot limits from the previous draw. If yAutoScale is disabled, this limit is preserved.

• refresh – Refresh the canvas - see drawDataSeries().

• xlabel – If provided, overrides the value of the xlabel property.

• ylabel – If provided, overrides the value of the ylabel property.

• plotArgs – Remaining arguments passed to the __drawOneDataSeries() method.

__drawOneDataSeries(ds, xdata, ydata, **plotArgs)

Plots a single DataSeries instance. This method is called by the drawDataSeries() method.

Parameters:

• ds – The DataSeries instance.

• xdata – X axis data.

• ydata – Y axis data.

• plotArgs – May be used to customise the plot - these arguments are all passed through to the Axis.plot function.

__dataSeriesChanged(*a)

Called when the dataSeries list changes. Adds listeners to any new DataSeries instances, and then calls asyncDraw().

__artistsChanged(*a)

Called when the artists list changes. Calls asyncDraw().

__limitsChanged(*a)

Called when the limits change. Updates the axis limits accordingly.

__calcLimits(dataxlims, dataylims, axisxlims, axisylims, axWidth, axHeight)

Calculates and returns suitable axis limits for the current plot. Also updates the limits property. This method is called by the drawDataSeries() method.

If xAutoScale or yAutoScale are enabled, the limits are calculated from the data range, using the canvas width and height to maintain consistent padding around the plotted data, irrespective of the canvas size.

. Otherwise, the existing axis limits are retained.

Parameters:

• dataxlims – A tuple containing the (min, max) x data range.

• dataylims – A tuple containing the (min, max) y data range.

• axisxlims – A tuple containing the current (min, max) x axis limits.

• axisylims – A tuple containing the current (min, max) y axis limits.

• axWidth – Canvas width in pixels

• axHeight – Canvas height in pixels