Plot.OverlayLayout¶

class OverlayLayout¶

An overlaying plot layout that can contain exactly two frames, shown as an overlay on the same plot.

The two frames can share either the x-axis or the y-axis. The actual mode can take values of either SHARE_X or SHARE_Y.

addItem(item)¶

Add a frame to the layout.

Raise an error if more than two frames are added.

Parameters:: item (PlotFrame) – The frame.

copy()¶

Returns:: A copy of the layout.
Return type:: BaseLayout

find(*, types=None, function=None, **kwargs)¶

Find plot items within this layout filtered on types and properties.

Find all lines with e.g. the label “Result”, by writing:

layout.find(types=Line, label='Result')

Or find all Scatter plots with an outline:

layout.find(types=Scatter, outline=True).

Or all lines which has a label that starts with the characters ‘band’,:

def labelStartWithBand(item):
    return item.label().lower().startswith('band')

layout.find(
    types=Line,
    function=labelStartsWithBand
).

Parameters:

types (None | PlotItem type) – An optional type or multiple types, e.g. Line or Scatter.
function (None | function) – An optional filter function taking the plot item as the only input.
**kwargs (dict) – Optional properties which should be matched exactly for the items.

Returns:

A list of the items matching the query.

Return type:

list of PlotItem

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

items()¶

Returns:: The items in the layout.
Return type:: list of LayoutItems.

mode()¶

Returns:: The overlay mode.
Return type:: enumerator | int

models(plotter=None)¶

Get all models in the layout for a given plotter.

Parameters:: plotter (Plotter based | NoneType) – The plotter or None for all plotters.
Returns:: The models.
Return type:: list

plotters()¶

Returns:: The plotters in the layout.
Return type:: set of Plotters

removeItem(item)¶

Remove a frame from the layout.

Parameters:: item (PlotFrame) – The frame to remove.

replaceItem(old_item, new_item)¶

Replace an existing item.

Parameters:

old_item (LayoutItem based) – The old item to replace.
new_item (LayoutItem based) – The new item the replaces the old item.

setMode(mode)¶

Set the overlay mode.

Note that this layout does not have a “LAYOUT_MODES.NORMAL” layout mode, but only supports “LAYOUT_MODES.SHARE_X” or “LAYOUT_MODES.SHARE_Y”.

Parameters:: mode (enumerator | int) – The overlay layout mode.

Usage Examples¶

An OverlayLayout lays two Plot.PlotFrame over one another. Each PlotFrame has its own axises. The most common usage is to show two PlotFrames together which only share a single axis.

An OverlayLayout can be constructed in the NanoLab GUI by dropping one plot on top of another. See the Merge plots part of the Plotting guide for further details.

Below we show how to achieve the same functionality in a script. As an example we construct two PlotModels, the first showing density as a function of distance, the other showing energy as a function of distance. They are overlaid on top of each other with a shared x-axis.

# Model showing the density as a function of distance.
density_model = Plot.PlotModel(Angstrom, Angstrom**-3)
density_model.addItem(Plot.Line([0, 1,  2] * Angstrom, [0.1, 0.2, 0.3] * Angstrom**-3))

# Frame the model.
density_frame = PlotFrame()
density_frame.addModel(density_model)

# Model showing an energy potential as a function of distance.
potential_model = Plot.PlotModel(Angstrom, eV)
potential_model.addItem(Plot.Line([0, 1, 2] * Angstrom, [2, 3, 4] * eV))

# Frame the model. Position y-axis to the right.
potential_frame = PlotFrame()
potential_frame.addModel(density_model)
potential_frame.yAxis().setMirrored(True)
potential_frame.title().setVisible(False)

# Construct the OverlayLayout and add the two models such that they share the x-axis.
overlay = Plot.OverlayLayout()
overlay.setMode(Plot.LAYOUT_MODES.SHARE_X)
overlay.addItem(density_frame)
overlay.addItem(potential_frame)

# Show the plot.
Plot.show(overlay)