Plot.PlotFrame

class PlotFrame(use_frame_model=True)

A plot frame lives inside a layout, and contains one or more plot models.

In the matplotlib front end, a frame is plotted as exactly one main matplotlib Axes object. However, the frame may control multiple auxiliary axes like e.g. colorbars.

The plot frame plots all the items contained in the plot models. Special care must be taken with the title, legend, axis’es and user annotations. Each model contains their own intances of these items, and it can be unclear how, for example, the x-axis of one plot model should be reconciled with another.

Instead, the frame uses only a single x-axis, y-axis etc. There are two implementations:

1. The frame uses a frame model, and ignores all the model titles, legends etc. This is the implementation for plots that are saved. This also means that plugin developers should not rely on changing axis, title or legends as part of their controls, since these features can easily be lost when the plot has been saved and loaded anew.

2. The frame instead uses the first model. This is the default solution for embedded plot views where frames are added using the GridLayout.addModel() method. It ensures maximum control for embedded PlotViews, but you should not rely too heavily on the freedom it allows, as all the saved plots use a private view model (see 1.).

Parameters:

use_frame_model (bool) – True, if the frame should use a separate view model..

addModel(model, flipped=False)

Add a model to the plot frame.

Note that the frame will explicitly not listen to model changes.

Syncronization between frame and model must happen in the view implementation.

Parameters:
  • model (PlotModel) – The model to add.

  • flipped (bool) – True, if the model axes are flipped.

autoscaleLimits()

Update the autoscaled axis limits.

axis(name)

The axis with a given name.

Parameters:

name (str) – The name (x or y).

Returns:

The axis.

Return type:

class:~.Plot.Axis

copy()

Make a copy of the plot storable by using the serialize/deserialize functionality.

This creates a new instance with a new id, but all other properties copied.

flip()

Flip the x- and y-axis.

classmethod fromProperties(properties)

Create a plot storable from a dict of properties.

Used when deserializing a PlotStorable.

Parameters:

properties (dict) – The properties which are used to populate the properties dict of the newly created plot storable.

Returns:

The newly created PlotStorable.

Return type:

PlotStorable

isFlipped()
Returns:

The frame model.

Return type:

Plot Model

isModelFlipped(model)

Check if a given model is flipped in this frame.

Parameters:

model (PlotModel) – The model to check.

Returns:

True, if the model is flipped.

Return type:

bool

model()
Returns:

The frame model.

Return type:

PlotModel

models(plotter=None)

Return all models, perhaps filtered by a plotter.

Parameters:

plotter (None | Plotter based) – The plotter to filter on.

Returns:

The added models.

Return type:

list of class:~.Plot.PlotModel

plotters()
Returns:

The plotter referenced in the frame.

Return type:

list of Plotter based

projection()
Returns:

The projection.

Return type:

str | NoneType

setFlipped(flipped)

Set flipped property.

Parameters:

flipped (bool) – True, if the frame is flipped.

setProjection(projection)

Set the projection.

Parameters:

projection (str) – The projection.

usesFrameModel()

. :returns: True, if the frame has a separate frame model. :rtype: bool

Usage Examples

A PlotFrame makes it possible to embed a Plot.PlotModel into a layout – just like a beautiful painting must be framed before it can be hung on the wall togehter with other paintings.

However, the PlotFrame is much more versatile than a standard picture frame. The PlotFrame can contain multiple PlotModels:

>>> frame = Plot.PlotFrame()
>>> frame.addModel(Plot.PlotModel())

And the frame can easily exchange the x- and y-axises:

>>> frame.flip()

Note

The PlotFrame must contain contain at least one PlotModel before it can be embedded in e.g. a Plot.GridLayout or a Plot.OverlayLayout.

Multiple PlotModels can also be embedded in a common PlotFrame, and complex plots can be built by combining multiple PlotFrames in a layout like the Plot.GridLayout or the Plot.OverlayLayout. A more complex usage example is given below.

# Build one plot model.
frame1.addModel(model1)
frame1.addModel(model2, flipped=True)

# Add the second model to its own frame.
frame2 = Plot.PlotFrame()
frame2.addmodel(model1)

# Add frames to grid layout.
layout = Plot.GridLayout(2, 1)
layout.addItem(frame1)
layout.addItem(frame2)

# Show the plot.
Plot.show(layout)