Plotting elements¶

Base plotting elements¶

Overview¶

Classes for plotting functionality¶

PlotNode : The base class for a .Node with the purpose of receiving data for visualization.
PlotWidgetContainer : A class that contains a PlotWidget (and can change it during runtime)
PlotWidget : An abstract widget that can be inherited to implement actual plotting.
AutoFigureMaker : A convenience class for semi-automatic generation of figures. The purpose is to keep actual plotting code out of the plot widget. This is not mandatory, just convenient.

Data structures¶

PlotDataType : Enum with types of data that can be plotted.
ComplexRepresentation: Enum with ways to represent complex-valued data.

Additional tools¶

makeFlowchartWithPlot() : convenience function for creating a flowchart that leads to a plot node.
determinePlotDataType() : try to infer which type of plot data is in a data set.

Object Documentation¶

plottr.plot.base – Contains the base classes for plotting nodes and widgets. Everything in here is independent of actual plotting backend, and does not contain plotting commands.

class plottr.plot.base.AutoFigureMaker¶

A class for semi-automatic creation of plot figures. It must be inherited to tie it to a specific plotting backend.

The main purpose of this class is to (a) implement actual plotting of plot items, and (b) distribute plot items correctly among subpanels of a figure.

FigureMaker is a context manager. The user should eventually only need to add data and specify what kind of data it is. FigureMaker will then generate plots from that.

In the simplest form, usage looks something like this:

>>> with AutoFigureMaker() as fm:
>>>     fm.addData(x, y, [...])
>>>     [...]

See addData() for details on how to specify data and how to pass plot options to it.

addData(*data, join=None, labels=None, plotDataType=<PlotDataType.unknown: 1>, **plotOptions)¶

Add data to the figure.

Parameters

data (Union[ndarray, MaskedArray]) – data arrays describing the plot (one or more independents, one dependent)
join (Optional[int]) – ID of a plot item the new item should be shown together with in the same subplot
labels (Optional[List[str]]) – list of labels for the data arrays
plotDataType (PlotDataType) – what kind of plot data the supplied data contains.
plotOptions (Any) – options (as kwargs) to be passed to the actual plot functions (depends on the backend)

Return type

int

Returns

ID of the new plot item.

addSubPlot()¶

Add a new subplot.

Return type: int
Returns: ID of the new subplot.

allPlotIds: List = None¶: ids of all plot items, incl those who are ‘joined’ with ‘main’ plot items.

combineTraces: bool = None¶: whether to combine 1D traces into one plot

complexRepresentation: ComplexRepresentation = None¶: how to represent complex data. must be set before adding data to the plot to have an effect.

dataDimensionsInSubPlot(subPlotId)¶

Determine what the data dimensions are in a subplot.

Parameters: subPlotId (int) – ID of the subplot
Return type: Dict[int, int]
Returns: dictionary with plot id as key, data dimension (i.e., number of independents) as value.

findPlotIndexInSubPlot(plotId)¶

find the index of a plot in its subplot

Parameters: plotId (int) – plot ID to check
Return type: int
Returns: index at which the plot is located in its subplot.

formatSubPlot(subPlotId)¶

Format a subplot. May be implemented by an inheriting class. By default, does nothing.

Parameters: subPlotId (int) – ID of the subplot.
Return type: Any
Returns: Depends on inheriting class.

makeSubPlots(nSubPlots)¶

Generate the subplots. Called after all data has been added. Must be implemented by an inheriting class.

Parameters: nSubPlots (int) – number of subplots
Return type: List[Any]
Returns: return values of the subplot generation methods.

nSubPlots()¶

Count the subplots in the figure.

Return type: int
Returns: number of subplots

plot(plotItem)¶

Plot an item. Must be implemented by an inheriting class.

Parameters: plotItem (PlotItem) – the item to plot.
Return type: Any
Returns: Depends on the inheriting class.

plotIds: List = None¶: ids of all main plot items (does not contain derived/secondary plot items)

plotIdsInSubPlot(subPlotId)¶

return all plot IDs in a given subplot

Parameters: subPlotId (int) – ID of the subplot
Return type: List[int]
Returns: list of plot IDs

plotItems: OrderedDictType[int, PlotItem] = None¶: items that will be plotted

previousPlotId()¶: Get the ID of the most recently added plot item. :rtype: Optional[int] :return: the ID.

subPlotItems(subPlotId)¶

Get items in a given subplot.

Parameters: subPlotId (int) – ID of the subplot
Return type: OrderedDict[int, PlotItem]
Returns: Dictionary with all plot items and their ids.

subPlotLabels(subPlotId)¶

Get the data labels for a given subplot.

Parameters: subPlotId (int) – ID of the subplot.
Return type: List[List[str]]
Returns: a list with one element per plot item in the subplot. Each element contains a list of the labels for that item.

subPlots: OrderedDictType[int, SubPlot] = None¶: subplots to create

class plottr.plot.base.ComplexRepresentation(label)¶

Options for plotting complex-valued data.

magAndPhase = 4¶: magnitude and phase

real = 1¶: only real

realAndImag = 2¶: real and imaginary

realAndImagSeparate = 3¶: real and imaginary, separated

class plottr.plot.base.PlotDataType¶

Types of (plottable) data

grid2d = 5¶: grid data with 2 dependents

line1d = 3¶: line data with 1 dependent (data is on a grid)

scatter1d = 2¶: scatter-type data with 1 dependent (data is not on a grid)

scatter2d = 4¶: scatter data with 2 dependents (data is not on a grid)

unknown = 1¶: unplottable data

class plottr.plot.base.PlotItem(data: List[Union[numpy.ndarray, numpy.ma.core.MaskedArray]], id: int, subPlot: int, plotDataType: plottr.plot.base.PlotDataType = <PlotDataType.unknown: 1>, labels: Optional[List[str]] = None, plotOptions: Optional[Dict[str, Any]] = None, plotReturn: Optional[Any] = None)¶

Data class describing a plot item in AutoFigureMaker.

data: List[Union[np.ndarray, np.ma.MaskedArray]] = None¶: List of data arrays (independents and one dependent)

id: int = None¶: unique ID of the plot item

labels: Optional[List[str]] = None¶: labels of the data arrays

plotDataType: plottr.plot.base.PlotDataType = 1¶: type of plot data (unknown is typically OK)

plotOptions: Optional[Dict[str, Any]] = None¶: options to be passed to plotting functions (depends on backend). Could be formatting options, for example.

plotReturn: Optional[Any] = None¶: return value from the plot command (like matplotlib Artists)

subPlot: int = None¶: ID of the subplot the item will be plotted in

class plottr.plot.base.PlotNode(name)¶

Basic Plot Node, derived from plottr.node.node.Node.

At the moment this doesn’t do much besides passing data to the plotting widget. Data is just passed through. On receipt of new data, newPlotData is emitted.

newPlotData¶: Signal emitted when process() is called, with the data passed to it as argument.

process(dataIn=None)¶

Emits the newPlotData signal when called. Note: does not call the parent method plottr.node.node.Node.process().

Parameters: dataIn (Optional[DataDictBase]) – input data
Return type: Dict[str, Optional[DataDictBase]]
Returns: input data as is: {dataOut: dataIn}

setPlotWidgetContainer(w)¶

Set the plot widget container.

Makes sure that newly arriving data is sent to plot GUI elements.

Parameters: w (PlotWidgetContainer) – container to connect the node to.
Return type: None

class plottr.plot.base.PlotWidget(parent=None)¶

Base class for Plot Widgets, this just defines the API. Derived from QWidget.

Implement a child class for actual plotting.

analyzeData(data)¶

checks data and compares with previous properties.

Parameters

data (Optional[DataDictBase]) – incoming data to compare to already existing data in the object.

Return type

Dict[str, bool]

Returns

dictionary with information on what has changed from previous to new data. contains key/value pairs where the key is the property analyzed, and the value is True of False. Keys are:

dataTypeChanged – has the data class changed?
dataStructureChanged – has the internal structure (data fields, etc) changed?
dataShapesChanged – have the data fields changed shape?
dataLimitsChanged – have the maxima/minima of the data fields changed?

dataIsComplex(dependentName=None)¶

Determine whether our data is complex.

Parameters: dependentName (Optional[str]) – name of the dependent to check. if None, check all.
Return type: bool
Returns: True if data is complex, False if not.

setData(data)¶

Set data. Use this to trigger plotting.

Parameters: data (Optional[DataDictBase]) – data to be plotted.
Return type: None

class plottr.plot.base.PlotWidgetContainer(parent=None)¶

This is the base widget for Plots, derived from QWidget.

This widget does not implement any plotting. It merely is a wrapping widget that contains the actual plot widget in it. This actual plot widget can be set dynamically.

Use PlotWidget as base for implementing widgets that can be added to this container.

setData(data)¶

set Data. If a plot widget is defined, call the widget’s PlotWidget.setData() method.

Parameters: data (DataDictBase) – input data to be plotted.
Return type: None

setPlotWidget(widget)¶

Set the plot widget.

Makes sure that the added widget receives new data.

Parameters: widget (PlotWidget) – plot widget
Return type: None

class plottr.plot.base.SubPlot(id: int, axes: Optional[List[Any]] = None)¶

Data class describing a subplot in a AutoFigureMaker.

axes: Optional[List[Any]] = None¶: list of subplot objects (type depends on backend)

id: int = None¶: ID of the subplot (unique per figure)

plottr.plot.base.determinePlotDataType(data)¶

Analyze input data and determine most likely PlotDataType.

Analysis is simply based on number of dependents and data type.

Parameters: data (Optional[DataDictBase]) – data to analyze.
Return type: PlotDataType
Returns: type of plot data inferred

plottr.plot.base.makeFlowchartWithPlot(nodes, plotNodeName='plot')¶

create a linear FlowChart terminated with a plot node.

Parameters

nodes (List[Tuple[str, Type[Node]]]) – List of Node classes, in the order they are to be arranged.
plotNodeName (str) – name of the plot node that will be appended.

Return type

Flowchart

Returns

the resulting FlowChart instance

Matplotlib plotting tools¶

Overview¶

plottr.plot.mpl – matplotlib plotting system for plottr. Contains the following main objects:

Base UI elements¶

widgets.MPLPlot (matplotlib.backends.backend_qt5agg.FigureCanvasQTAgg) – Figure and Canvas widget. The most elementary Qt widget that contains the the matplotlib figure instance.
widgets.MPLPlotWidget (plottr.plot.base.PlotWidget) – A widget that contains the figure/canvas

General plotting functionality¶

plotting.PlotType – Enum for currently implemented plot types in automatic plotting.

Automatic plotting¶

autoplot.AutoPlot (mpl.widgets.PlotWidget) – PlotWidget that allows user selection of plot types and plots using autoplot.FigureMaker.
autoplot.FigureMaker (base.AutoFigureMaker) – Matplotlib implementation of the figure manager.

Utilities¶

widgets.figureDialog() – make a dialog window containing a plot widget.

Configuration¶

This module looks for a file plottr_default.mplstyle in the plottr config directories and applies it to matplotlib plots using pyplot.style.use.

Object Documentation¶

General Widgets¶

plottr.plot.mpl.widgets – This module contains general matplotlib plotting tools.

class plottr.plot.mpl.widgets.MPLPlot(parent=None, width=4.0, height=3.0, dpi=150, constrainedLayout=True)¶

This is the basic matplotlib canvas widget we are using for matplotlib plots. This canvas only provides a few convenience tools for automatic sizing, but is otherwise not very different from the class FCanvas that comes with matplotlib (and which we inherit). It can be used as any QT widget.

autosize()¶

Sets some default spacings/margins.

Return type: None

clearFig()¶

clear and reset the canvas.

Return type: None

resizeEvent(event)¶

Re-implementation of the widget resizeEvent method. Makes sure we resize the plots appropriately.

Return type: None

setFigureInfo(info)¶

Display an info string in the figure

Return type: None

setFigureTitle(title)¶

Add a title to the figure.

Return type: None

setRcParams()¶

apply matplotlibrc config from plottr configuration files.

Return type: None

setShowInfo(show)¶

Whether to show additional info in the plot

Return type: None

toClipboard()¶

Copy the current canvas to the clipboard.

Return type: None

class plottr.plot.mpl.widgets.MPLPlotWidget(parent=None)¶

Base class for matplotlib-based plot widgets. Per default, add a canvas and the matplotlib NavBar.

addMplBarOptions()¶

Add options for displaying info meta data and copying the figure to the clipboard to the plot toolbar.

Return type: None

mplBar = None¶: the matplotlib toolbar

plot = None¶: the plot widget

setMeta(data)¶

Add meta info contained in the data to the figure.

Parameters: data (DataDictBase) – data object containing the meta information if meta field title or info are in the data object, then they will be added as text info to the figure.
Return type: None

plottr.plot.mpl.widgets.figureDialog()¶

Make a dialog window containing a MPLPlotWidget.

Return type: Tuple[Figure, QDialog]
Returns: The figure object of the plot, and the dialog window object.

General plotting tools¶

plottr.plot.mpl.plotting – Plotting tools (mostly used in Autoplot)

class plottr.plot.mpl.plotting.PlotType¶

Plot types currently supported in Autoplot.

colormesh = 5¶: colormesh plot of 2D data

empty = 1¶: no plot defined

image = 4¶: image plot of 2D data

multitraces = 3¶: multiple 1D lines/scatter plots per panel

scatter2d = 6¶: 2D scatter plot

singletraces = 2¶: a single 1D line/scatter plot per panel

class plottr.plot.mpl.plotting.SymmetricNorm(vmin=None, vmax=None, vcenter=0, clip=False)¶: Color norm that’s symmetric and linear around a center value.

plottr.plot.mpl.plotting.colorplot2d(ax, x, y, z, plotType=<PlotType.image: 4>, axLabels=('', '', ''), **kw)¶

make a 2d colorplot. what plot is made, depends on plotType. Any of the 2d plot types in PlotType works.

Parameters

ax (Axes) – matplotlib subPlots to plot in
x (Union[ndarray, MaskedArray]) – x coordinates (meshgrid)
y (Union[ndarray, MaskedArray]) – y coordinates (meshgrid)
z (Union[ndarray, MaskedArray]) – z data
plotType (PlotType) – the plot type
axLabels (Tuple[Optional[str], Optional[str], Optional[str]]) – labels for the x, y subPlots, and the colorbar.

all keywords are passed to the actual plotting functions, depending on the plotType:

PlotType.image –
plotImage()
PlotType.colormesh –
ppcolormesh_from_meshgrid()
PlotType.scatter2d –
matplotlib’s scatter

Return type: Optional[AxesImage]

plottr.plot.mpl.plotting.plotImage(ax, x, y, z, **kw)¶

Plot 2d meshgrid data as image.

Parameters

ax (Axes) – matplotlib subPlots to plot the image in.
x (ndarray) – x coordinates (as meshgrid)
y (ndarray) – y coordinates
z (ndarray) – z values

Return type

AxesImage

Returns

the image object returned by imshow

All keywords are passed to imshow.

plottr.plot.mpl.plotting.ppcolormesh_from_meshgrid(ax, x, y, z, **kw)¶

Plot a pcolormesh with some reasonable defaults. Input are the corresponding arrays from a 2D MeshgridDataDict.

Will attempt to fix missing points in the coordinates.

Parameters

ax (Axes) – subPlots to plot the colormesh into.
x (ndarray) – x component of the meshgrid coordinates
y (ndarray) – y component of the meshgrid coordinates
z (ndarray) – data values

Return type

Optional[AxesImage]

Returns

the image returned by pcolormesh.

Keywords are passed on to pcolormesh.

Autoplot¶

plottr.plot.mpl.autoplot – This module contains the tools for automatic plotting with matplotlib.

class plottr.plot.mpl.autoplot.AutoPlot(parent=None)¶

A widget for plotting with matplotlib.

When data is set using setData() the class will automatically try to determine what good plot options are from the structure of the data.

User options (for different types of plots, styling, etc) are presented through a toolbar.

setData(data)¶

Analyses data and determines whether/what to plot.

Parameters: data (Optional[DataDictBase]) – input data
Return type: None

class plottr.plot.mpl.autoplot.AutoPlotToolBar(name, parent=None)¶

A toolbar that allows the user to configure AutoPlot.

Currently, the user can select between the plots that are possible, given the data that AutoPlot has.

complexRepresentationSelected¶: signal emitted when the complex data option has been changed

plotTypeSelected¶: signal emitted when the plot type has been changed

selectComplexType(comp)¶

makes sure that the selected comp is active (checked), all others are not active. This method should be used to catch a trigger from the UI. If the active plot type has been changed by using this method, we emit complexPolarSelected.

Return type: None

selectPlotType(plotType)¶

makes sure that the selected plotType is active (checked), all others are not active.

This method should be used to catch a trigger from the UI.

If the active plot type has been changed by using this method, we emit plotTypeSelected.

Parameters: plotType (PlotType) – type of plot
Return type: None

setAllowedComplexTypes(*complexOptions)¶

Disable all complex representation choices that are not allowed. If the current selection is now disabled, instead select the first enabled one.

Return type: None

setAllowedPlotTypes(*args)¶

Disable all plot type choices that are not allowed. If the current selection is now disabled, instead select the first enabled one.

Parameters: args (PlotType) – which types of plots can be selected.
Return type: None

class plottr.plot.mpl.autoplot.FigureMaker(fig)¶

Matplotlib implementation for AutoFigureMaker. Implements plotting routines for data with 1 or 2 dependents, as well as generation and formatting of subplots.

The class tries to lay out the subplots to be generated on a grid that’s as close as possible to square. The allocation of plot to subplots depends on the type of plot we’re making, and the type of data. Subplots may contain either one 2d plot (image, 2d scatter, etc) or multiple 1d plots.

addData(*data, join=None, labels=None, plotDataType=<PlotDataType.unknown: 1>, **plotOptions)¶

Add data to the figure.

Parameters

data (Union[ndarray, MaskedArray]) – data arrays describing the plot (one or more independents, one dependent)
join (Optional[int]) – ID of a plot item the new item should be shown together with in the same subplot
labels (Optional[List[str]]) – list of labels for the data arrays
plotDataType (PlotDataType) – what kind of plot data the supplied data contains.
plotOptions (Any) – options (as kwargs) to be passed to the actual plot functions (depends on the backend)

Return type

int

Returns

ID of the new plot item.

formatSubPlot(subPlotId)¶

Format a subplot. Parses the plot items that go into that subplot, and attaches axis labels and legend handles.

Parameters: subPlotId (int) – ID of the subplot.
Return type: None

makeSubPlots(nSubPlots)¶

Create subplots (Axes). They are arranged on a grid that’s close to square.

Parameters: nSubPlots (int) – number of subplots to make
Return type: List[Axes]
Returns: list of matplotlib axes.

plot(plotItem)¶

Plots data in a PlotItem.

Parameters: plotItem (PlotItem) – the item to plot.
Return type: Union[Artist, List[Artist], None]
Returns: matplotlib Artist(s), or None if nothing was plotted.

plotType = None¶: what kind of plot we’re making. needs to be set before adding data. Incompatibility with the data provided will result in failure.