fsleyes.views.plotpanel

This module provides the PlotPanel and OverlayPlotPanel classes. The PlotPanel class is the base class for all FSLeyes views which display some sort of data plot. The OverlayPlotPanel is a PlotPanel which contains some extra logic for displaying plots related to the currently selected overlay.

The actual plotting logic (using matplotilb) is implemented within the PlotCanvas class.

class fsleyes.views.plotpanel.PlotPanel(parent, overlayList, displayCtx, frame)

Bases: fsleyes.views.viewpanel.ViewPanel

The PlotPanel class is the base class for all FSLeyes views which display some sort of 2D data plot, such as the TimeSeriesPanel, and the HistogramPanel.

Note

See also the OverlayPlotPanel, which contains extra logic for displaying plots related to the currently selected overlay, and which is the actual base class used by the TimeSeriesPanel, HistogramPanel and PowerSpectrumPanel.

PlotPanel uses a PlotCanvas, which in turn uses :mod`:matplotlib` for its plotting. The PlotCanvas instance used by a PlotPanel can be accessed via the canvas() method, which in turn can be used to manipulate the plot display settings. The matplotlib Figure, Axis, and Canvas instances can be accessed via the PlotCanvas instance, if they are needed.

Sub-class requirements

Sub-class implementations of PlotPanel must do the following:

1. Call the PlotPanel constructor.

2. Define one or more DataSeries sub-classes if needed.

3. Override the draw() method, so it calls the PlotCanvas.drawDataSeries() and PlotCanvas.drawArtists() methods (draw() is passed to the PlotCanvas as a custom drawFunc).

4. If necessary, override the prepareDataSeries() method to perform any preprocessing on extraSeries passed to the drawDataSeries() method (but not applied to DataSeries that have been added to the dataSeries list) (prepareDataSeries() is passed to the PlotCanvas as a custom prepareFunc).

5. If necessary, override the destroy() method, but make sure that the base-class implementation is called.

Plot panel actions

A number of actions are also provided by the PlotPanel class:

screenshot	Prompts the user to select a file name, then saves a screenshot of the current plot.
importDataSeries	Imports data series from a text file.
exportDataSeries	Exports displayed data series to a text file.

controlOptions(cpType)

Returns some options to be used by ViewPanel.togglePanel() for certain control panel types.

__init__(parent, overlayList, displayCtx, frame)

Create a PlotPanel.

Parameters

• parent – The wx parent object.

• overlayList – An OverlayList instance.

• displayCtx – A DisplayContext instance.

• frame – The FSLeyesFrame instance.

destroy()

Removes some property listeners, and then calls ViewPanel.destroy().

property canvas

Returns a reference to the PlotCanvas.

draw(*a)

This method must be overridden by PlotPanel sub-classes. Sub-class implementations should call the drawDataSeries() and meth:drawArtists methods.

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 - override it to perform any custom preprocessing.

screenshot(*a)

Prompts the user to select a file name, then saves a screenshot of the current plot.

See the ScreenshotAction.

importDataSeries(*a)

Imports data series from a text file.

See the ImportDataSeriesAction.

exportDataSeries(*args, **kwargs)

Exports displayed data series to a text file.

See the ExportDataSeriesAction.

__module__ = 'fsleyes.views.plotpanel'

class fsleyes.views.plotpanel.OverlayPlotPanel(*args, **kwargs)

Bases: fsleyes.views.plotpanel.PlotPanel

The OverlayPlotPanel is a PlotPanel which contains some extra logic for creating, storing, and drawing DataSeries instances for each overlay in the OverlayList.

Subclass requirements

Sub-classes must:

1. Implement the createDataSeries() method, so it creates a DataSeries instance for a specified overlay.

2. Implement the PlotPanel.draw() method so it calls the PlotCanvas.drawDataSeries(), passing DataSeries instances for all overlays where Display.enabled is True, and the call PlotCanvas.drawArtists() method.

3. Optionally implement the prepareDataSeries() method to perform any custom preprocessing.

The internal data series store

The OverlayPlotPanel maintains a store of DataSeries instances, one for each compatible overlay in the OverlayList. The OverlayPlotPanel manages the property listeners that must be registered with each of these DataSeries to refresh the plot. These instances are created by the createDataSeries() method, which is implemented by sub-classes. The following methods are available to sub-classes, for managing the internal store of DataSeries instances:

getDataSeries	Returns the DataSeries instance associated with the specified overlay, or None if there is no DataSeries instance.
getDataSeriesToPlot	Convenience method which returns a list of overlays which have DataSeries that should be plotted.
clearDataSeries	Destroys the internally cached DataSeries for the given overlay.
updateDataSeries	Makes sure that a DataSeries instance has been created for every compatible overlay, and that property listeners are correctly registered, so the plot can be refreshed when needed.
addDataSeries	Every DataSeries which is currently plotted, and has not been added to the PlotCanvas.dataSeries list, is added to said list.
removeDataSeries	Removes the most recently added DataSeries from the PlotCanvas.dataSeries.

Proxy images

The OverlayPlotPanel will replace all ProxyImage instances with their base images. This functionality was originally added to support the HistogramSeries.showOverlay functionality - it adds a mask image to the OverlayList to display the histogram range. Sub-classes may wish to adhere to the same logic (replacing ProxyImage instances with their bases)

Control panels

The PlotControlPanel, PlotListPanel, and OverlayListPanel are FSLeyes control panels which work with the OverlayPlotPanel. The PlotControlPanel is not intended to be used directly - view-specific sub-classes are used instead. These panels can be added/removed via the ViewPanel.togglePanel() method.

Sub-classes

The OverlayPlotPanel is the base class for:

TimeSeriesPanel	The TimeSeriesPanel is an OverlayPlotPanel which plots time series data from overlays.
HistogramPanel	An OverlayPlotPanel which plots histograms from Image overlay data.
PowerSpectrumPanel	The PowerSpectrumPanel class is an OverlayPlotPanel which plots power spectra of overlay data.

plotColours = {}

This dictionary is used to store a collection of {overlay : colour} mappings. It is shared across all OverlayPlotPanel instances, so that the same (initial) colour is used for the same overlay, across multiple plots.

See also plotStyles.

Sub-classes should use the getOverlayPlotColour() and getOverlayPlotStyle() methods to retrieve the initial colour and linestyle to use for a given overlay.

plotStyles = {}

This dictionary is used to store a collection of {overlay : colour} mappings - it is used in conjunction with plotColours.

__init__(*args, **kwargs)

Create an OverlayPlotPanel.

Parameters

initialState – Must be passed as a keyword argument. Allows you to specify the initial enabled/disabled state for each overlay. See updateDataSeries(). If not provided, only the data series for the currently selected overlay is shown (if possible).

All other argumenst are passed through to PlotPanel.__init__().

destroy()

Must be called when this OverlayPlotPanel is no longer needed. Removes some property listeners, and calls PlotPanel.destroy().

getDataSeriesToPlot()

Convenience method which returns a list of overlays which have DataSeries that should be plotted.

getDataSeries(overlay)

Returns the DataSeries instance associated with the specified overlay, or None if there is no DataSeries instance.

getOverlayPlotColour(overlay)

Returns an initial colour to use for plots associated with the given overlay. If a colour is present in the plotColours dictionary, it is returned. Otherwise a random colour is generated, added to plotColours, and returned.

getOverlayPlotStyle(overlay)

Returns an initial line style to use for plots associated with the given overlay. If a colour is present in the plotStyles dictionary, it is returned. Otherwise a line style is generated, added to plotStyles, and returned.

The format of the returned line style is suitable for use with the linestyle argument of the matplotlib plot functions.

addDataSeries()

Every DataSeries which is currently plotted, and has not been added to the PlotCanvas.dataSeries list, is added to said list.

removeDataSeries(*a)

Removes the most recently added DataSeries from the PlotCanvas.dataSeries.

createDataSeries(overlay)

This method must be implemented by sub-classes. It must create and return a DataSeries instance for the specified overlay.

Note

Sub-class implementations should set the DataSeries.colour property to that returned by the getOverlayPlotColour() method, and the DataSeries.lineStyle property to that returned by the getOverlayPlotStyle() method

Different DataSeries types need to be re-drawn when different properties change. For example, a VoxelTimeSeries` instance needs to be redrawn when the DisplayContext.location property changes, whereas a MelodicTimeSeries instance needs to be redrawn when the VolumeOpts.volume property changes.

Therefore, in addition to creating and returning a DataSeries instance for the given overlay, sub-class implementations must also specify the properties which affect the state of the DataSeries instance. These must be specified as two lists:

• the targets list, a list of objects which own the dependant properties (e.g. the DisplayContext or VolumeOpts instance).

• The properties list, a list of names, each specifying the property on the corresponding target.

This method must therefore return a tuple containing:

• A DataSeries instance, or None if the overlay is incompatible.

• A list of target instances.

• A list of property names.

The target and property name lists must have the same length.

clearDataSeries(overlay)

Destroys the internally cached DataSeries for the given overlay.

updateDataSeries(initialState=None)

Makes sure that a DataSeries instance has been created for every compatible overlay, and that property listeners are correctly registered, so the plot can be refreshed when needed.

Parameters

initialState – If provided, must be a dict of { overlay : bool } mappings, specifying the initial value of the DataSeries.enabled property for newly created instances. If not provided, only the data series for the currently selected overlay (if it has been newly added) is initially enabled.

__dataSeriesChanged(*a)

Called when the PlotCanvas.dataSeries list changes. Enables/disables the removeDataSeries() action accordingly.

__module__ = 'fsleyes.views.plotpanel'

__overlayListChanged(*a, **kwa)

Called when the OverlayList changes. Makes sure that there are no DataSeries instances in the PlotCanvas.dataSeries list, or in the internal cache, which refer to overlays that no longer exist.

Parameters

initialState – Must be passed as a keyword argument. If provided, passed through to the updateDataSeries() method.