API Reference ¶

Contents

API Reference

Run Tree ¶

Models ¶

class bluesky_widgets.models.run_tree.RunTree(run=None)[source]¶

Tree viewer for the metadata in a BlueskyRun.

Parameters

run: BlueskyRun or None, optional

property run¶: The currently-viewed Run. (None if empty.)

Views ¶

Qt ¶

class bluesky_widgets.qt.run_tree.QtTreeView(model, parent=None)[source]¶: Tree view showing a run

Plots ¶

Models ¶

Figures, Axes, and Plot Entities ¶

class bluesky_widgets.models.plot_specs.FigureSpec(axes, *, title, uuid=None, short_title=None)[source]¶

Describes a Figure

Parameters

axesTuple[AxesSpec]
titleString: Figure title text
uuidUUID, optional: Automatically assigned to provide a unique identifier for this Figure, used internally to track it.
short_title: String, optional: Shorter figure title text, used in (for example) tab labels. Views should fall back on title if this is None.

property axes¶

Tuple of AxesSpecs. Set at FigureSpec creation time and immutable.

Why is it immutable? Because rearranging Axes to make room for a new one is currently painful to do in matplotlib. This constraint might be relaxed in the future if the situation improves in matplotlib or if support for other plotting frameworks is added to bluesky-widgets.

property short_title¶: String for figure title tab label. Settable

property title¶: String for figure title. Settable.

class bluesky_widgets.models.plot_specs.AxesSpec(*, lines=None, images=None, title=None, x_label=None, y_label=None, uuid=None)[source]¶

Describes a set of Axes

Examples

Note that plot entities like lines may be declared at init time:

>>> axes = AxesSpec(lines=[LineSpec(...)])

Or added later:

>>> axes = AxesSpec()
>>> axes.lines.append(LineSpec(...))

Or a mix:

>>> axes = AxesSpec(lines=[LineSpec(...)])
>>> axes.lines.append(LineSpec(...))

And they can be removed at any point:

>>> del axes.lines[0]  # Remove the first one.
>>> del axes.lines[-1]  # Remove the last one.
>>> axes.lines.clear()  # Remove them all.

They may be accessed by type

>>> axes.lines  # all lines
[LineSpec(...), LineSpec(...), ...]

Or by label

>>> axes.by_label["Scan 8"]  # list of all plot entities with this label
[LineSpec(...)]  # typically contains just one element

property by_label¶

Access artists as a read-only dict keyed by label.

Since two artists are allowed to have the same label, the values are lists. In the common case, the list will have just one element.

Examples

Look up an object (e.g. a line) by its label and change its color.

>>> spec = axes_spec.by_label["Scan 3"]
>>> spec.style.update(color="red")

property by_uuid¶: Access artists as a read-only dict keyed by uuid.

property figure¶

The Figure in which this Axes is located.

Base Classes ¶

class bluesky_widgets.models.plot_specs.ArtistSpec(func, run, label, style=None, axes=None, uuid=None)[source]¶

Describes the data, computation, and style for an artist (plot element)

funccallable

Expected signature:

func(run: BlueskyRun)

The expected return type varies by artist.

runBlueskyRun

Contains data to be visualized.

labelString

Label used in legend and for lookup by label on AxesSpec.

styleDict, optional

Options passed through to plotting framework, such as color or label.

axesAxesSpec, optional

This may be specified here or set later using set_axes(). Once specified, it cannot be changed.

uuidUUID, optional

Automatically assigned to provide a unique identifier for this Figure, used internally to track it.

property axes¶

The Axes on which this Artist is drawn.

Views ¶

Qt ¶

class bluesky_widgets.qt.figures.QtFigure(model: bluesky_widgets.models.plot_specs.FigureSpec, parent=None)[source]¶

A Qt view for a FigureSpec model. This always contains one Figure.

property axes¶: Read-only access to the mapping AxesSpec UUID -> MatplotlibAxes

class bluesky_widgets.qt.figures.QtFigures(model: bluesky_widgets.models.plot_specs.FigureSpecList, parent=None)[source]¶

A Jupyter (ipywidgets) view for a FigureSpecList model.

property figures¶: Read-only access to the mapping FigureSpec UUID -> QtFigure

Jupyter ¶

class bluesky_widgets.jupyter.figures.JupyterFigure(**kwargs)[source]¶

A Jupyter view for a FigureSpec model. This always contains one Figure.

property axes¶: Read-only access to the mapping AxesSpec UUID -> MatplotlibAxes

class bluesky_widgets.jupyter.figures.JupyterFigures(**kwargs)[source]¶

A Jupyter (ipywidgets) view for a FigureSpecList model.

property figures¶: Read-only access to the mapping FigureSpec UUID -> JupyterFigure

Headless ¶

class bluesky_widgets.headless.figures.HeadlessFigure(model: bluesky_widgets.models.plot_specs.FigureSpec)[source]¶

A Headless “view” for a FigureSpec model. This always contains one Figure.

Examples

Export the figure.

>>> headless = HeadlessFigure(model)
>>> headless.export("my-figure.png")

property axes¶: Read-only access to the mapping AxesSpec UUID -> MatplotlibAxes

export(filename, format='png', **kwargs)[source]¶

Export figure.

Parameters

filenamestr | Path
formatstr, optional: Default is “png”.
**kwargs :: Passed through to matplotlib.figure.Figure.savefig

class bluesky_widgets.headless.figures.HeadlessFigures(model: bluesky_widgets.models.plot_specs.FigureSpecList)[source]¶

A headless “view” for a FigureSpecList model.

It does not produce a graphical user interface. Instead, it provides methods for exporting figures as images.

Examples

Export all the figures to a directory. They will be named by their title. If there are duplciate titles, a counting number will appended like x-1.png, x-2.png.

>>> headless = HeadlessFigures(model)
>>> headless.export_all("path/to/directory/")

Control the format.

>>> headless.export_all("path/to/directory/", format="png")
>>> headless.export_all("path/to/directory/", format="jpg")

export_all(directory, format='png', **kwargs)[source]¶

Export all figures.

Parameters

directorystr | Path
formatstr, optional: Default is “png”.
**kwargs :: Passed through to matplotlib.figure.Figure.savefig

Returns

filenamesList[String]

property figures¶: Read-only access to the mapping FigureSpec UUID -> HeadlessFigure

Plot Builders ¶

These are models which build a models.plot_specs.FigureSpec or a list of them. This is an example of a builder that creates one Figure:

from bluesky_widgets.models.plot_builders import RecentLines
model = RecentLines(3, "motor", "det")
model.runs  # append Runs to this list

# Build a view by passing model.figure to any Figure view, e.g.
from bluesky_widgets.jupyter.figures import JupyterFigure
view = JupyterFigure(model.figure)

And this is an example of a builder that creates a list of Figures:

from bluesky_widgets.models.plot_builders import AutoRecentLines
model = AutoRecentLines(3)
model.runs  # append Runs to this list

# Build a view by passing model.figures to any Figures view, e.g.
from bluesky_widgets.jupyter.figures import JupyterFigures
view = JupyterFigures(model.figures)

Builders with a Single Figure ¶

class bluesky_widgets.models.plot_builders.RecentLines(max_runs, x, y, stream_name='primary', func=None, axes=None)[source]¶

Plot y vs x for the last N runs.

Parameters

max_runsint

Number of lines to show at once

xstring

Field name

ystring

Field name

stream_namestring, optional

Stream where fields x and y are found. Default is “primary”.

funccallable, optional

Expected signature:

func(run: BlueskyRun, stream_name: str, x: str, y: str) -> x: Array, y: Array

Default:

def func(run, stream_name, x, y):
    ds = run[stream_name].to_dask()
    return ds[x], ds[y]

axesAxesSpec, optional

If None, an axes and figure are created with default labels and titles derived from the x and y parameters.

Examples

>>> model = RecentLines(3, "motor", "det")
>>> from bluesky_widgets.jupyter.figures import JupyterFigure
>>> view = JupyterFigure(model.figure)
>>> model.add_run(run)
>>> model.add_run(another_run, pinned=True)

Attributes

max_runsint: Number of Runs to plot at once. This may be changed at any point. (Note: Increasing it will not restore any Runs that have already been removed, but it will allow more new Runs to be added.)
runsRunList[BlueskyRun]: As runs are appended entries will be removed from the beginning of the last (first in, first out) so that there are at most max_runs.
pinnedFrozenset[String]: Run uids of pinned runs.
figureFigureSpec
funccallable
axesAxesSpec
xstring: Read-only access to x field name
ystring: Read-only access to y field name
stream_namestring: Read-only access to stream name

add_run(run, pinned=False)[source]¶

Add a Run.

Parameters

runBlueskyRun
pinnedBoolean: If True, retain this Run until it is removed by the user.

discard_run(run)[source]¶

Discard a Run, including any pinned and unpinned.

If the Run is not present, this will return silently.

Parameters

runBlueskyRun

class bluesky_widgets.models.plot_builders.Image(field, stream_name='primary', func=None, axes=None)[source]¶

Plot an image from a Run.

By default, higher-dimensional data is handled by repeatedly averaging over the leading dimension until there are only two dimensions.

Parameters

fieldstring

Field name (“data key”) for this image

stream_namestring, optional

Stream where fields x and y are found. Default is “primary”.

funccallable, optional

Expected signature:

func(run: BlueskyRun, stream_name: str, x: str, y: str) -> x: Array, y: Array

Default:

def func(run, field):
    ds = run[stream_name].to_dask()
    data = ds[field].data
    # Reduce the data until it is 2D by repeatedly averaging over
    # the leading axis until there only two axes.
    while data.ndim > 2:
        data = data.mean(0)
    return data

axesAxesSpec, optional

If None, an axes and figure are created with default labels and titles derived from the x and y parameters.

Examples

>>> model = RecentLines(3, "motor", "det")
>>> from bluesky_widgets.jupyter.figures import JupyterFigure
>>> view = JupyterFigure(model.figure)
>>> model.add_run(run)
>>> model.add_run(another_run, pinned=True)

Attributes

runBlueskyRun: The currently-viewed Run
figureFigureSpec
funccallable
axesAxesSpec
xstring: Read-only access to x field name
ystring: Read-only access to y field name
stream_namestring: Read-only access to stream name

Builders with a List of Figures ¶

class bluesky_widgets.models.plot_builders.AutoRecentLines(max_runs)[source]¶

Automatically guess useful lines to plot. Show the last N runs (per figure).

Parameters

max_runsint: Number of Runs to plot at once, per figure

Examples

>>> model = AutoRecentLines(3)
>>> from bluesky_widgets.jupyter.figures import JupyterFigures
>>> view = JupyterFigures(model.figures)
>>> model.add_run(run)
>>> model.add_run(another_run, pinned=True)

Attributes

figuresFigureSpecList[FigureSpec]
max_runsint: Number of Runs to plot at once. This may be changed at any point. (Note: Increasing it will not restore any Runs that have already been removed, but it will allow more new Runs to be added.)
keys_to_figuresdict: Read-only mapping of each key to the active RecentLines instance.

add_run(run, pinned=False)[source]¶

Add a Run.

Parameters

runBlueskyRun
pinnedBoolean: If True, retain this Run until it is removed by the user.

discard_run(run)[source]¶

Discard a Run, including any pinned and unpinned.

If the Run is not present, this will return silently. Also, note that this only affect “active” plots that are currently receive new runs. Inactive ones will be left as they are.

Parameters

runBlueskyRun

property keys_to_figures¶: Read-only mapping of each key to the active RecentLines instance.

new_instance_for_key(key)[source]¶

Make a new RecentLine instance for a key.

If there is an existing one the instance and figure will remain but will no longer be updated with new Runs. Those will go to a new instance and figure, created here.

class bluesky_widgets.models.plot_builders.PromptPlotter(builders)[source]¶

Produce Figures from BlueskyRuns promptly (as Run completion time).

Parameters

buildersBuilderList[callable]: A list of functions that accept a BlueskyRun and return FigureSpec(s).

Attributes

runsRunList[BlueskyRun]

Add or remove runs from this list.

figuresFigureSpecList[FigureSpec]

Figures will be added to this list.

buildersBuilderList[callable]

A list of functions with the expected signature:

f(run: BlueskyRun) -> FigureSpec

or:

f(run: BlueskyRun) -> List{FigureSpec]

add_run(run)[source]¶

Add a Run.

Parameters

runBlueskyRun

discard_run(run)[source]¶

Discard a Run.

If the Run is not present, this will return silently.

Parameters

runBlueskyRun

Streaming Utilities ¶

bluesky_widgets.utils.streaming.stream_documents_into_runs(add_run)[source]¶

Convert a flat stream of documents to “live” BlueskyRuns.

Parameters

add_runcallable: This will be called as add_run(run: BlueskyRun) each time a ‘start’ document is received.

Returns

callbackcallable: This should be subscribed to a callback registry that calls it like callback(name, doc).

Examples

This is used for connecting something that emits a flat stream of documents to something that wants to receive BlueskyRuns.

Append to a plain list.

>>> from bluesky import RunEngine
>>> RE = RunEngine()
>>> runs = []
>>> RE.subscribe(stream_documents_into_runs(runs.append))

Or, more usefully to an observable list.

>>> from bluesky_widgets.models.utils import RunList
>>> runs = RunList()
>>> RE.subscribe(stream_documents_into_runs(runs.append))

Add runs to a model with an add_run method. For example, it might be a model that generates figures.

>>> from bluesky_widgets.models.plot_builders import AutoRecentLines
>>> model = AutoRecentLines(3)

>>> RE.subscribe(stream_documents_into_runs(model.add_run))

class bluesky_widgets.qt.zmq_dispatcher.RemoteDispatcher(address, *, prefix=b'', deserializer=<built-in function loads>, parent=None)[source]¶

Dispatch documents received over the network from a 0MQ proxy.

This is designed to be run in a Qt application.

Parameters

addresstuple | str: Address of a running 0MQ proxy, given either as a string like '127.0.0.1:5567' or as a tuple like ('127.0.0.1', 5567)
prefixbytes, optional: User-defined bytestring used to distinguish between multiple Publishers. If set, messages without this prefix will be ignored. If unset, no mesages will be ignored.
deserializer: function, optional: optional function to deserialize data. Default is pickle.loads

Examples

Print all documents generated by remote RunEngines.

>>> d = RemoteDispatcher(('localhost', 5568))
>>> d.subscribe(stream_documents_into_runs(model.add_run))
>>> d.start()  # launches periodic workers on background threads
>>> d.stop()  # stop launching workers

class bluesky_widgets.jupyter.zmq_dispatcher.RemoteDispatcher(address, *, prefix=b'', deserializer=<built-in function loads>)[source]¶

Dispatch documents received over the network from a 0MQ proxy.

This is designed to be run in a Jupyter kernel.

Parameters

addresstuple | str: Address of a running 0MQ proxy, given either as a string like '127.0.0.1:5567' or as a tuple like ('127.0.0.1', 5567)
prefixbytes, optional: User-defined bytestring used to distinguish between multiple Publishers. If set, messages without this prefix will be ignored. If unset, no mesages will be ignored.
deserializer: function, optional: optional function to deserialize data. Default is pickle.loads

Examples

Print all documents generated by remote RunEngines.

>>> d = RemoteDispatcher(('localhost', 5568))
>>> d.subscribe(stream_documents_into_runs(model.add_run))
>>> d.start()  # starts a thread and a long-running subprocess
>>> d.stop()  # stops them and blocks until they stop