14.7. steps.API_2.visual

The visual module contains classes for interactively visualizing simulations.

14.7.1. Detailed documentation

steps.API_2.visual.SimControl
steps.API_2.visual.PlotDisplay

steps.API_2.visual.TimePlot

steps.API_2.visual.SpatialPlot

steps.API_2.visual.NewRow

steps.API_2.visual.SimDisplay

steps.API_2.visual.ElementDisplay

steps.API_2.visual.PartitionDisplay

class SimControl(Control', start_time=0.0, end_time=10, upd_interval=0.1, *args, **kwargs)[source]

Bases: NamedObject

Main visual class to wrap a simulation

Parameters

title (str) – Title of the simulation control window
start_time (float) – Initial start time of the simulation
end_time (float) – Initial end time of the simulation
upd_interval (float) – Initial update interval of the simulation

The SimControl object should be used as a context manager for declaring displays and displays should be used as context managers for declaring specific plots or 3D elements:

sim = Simulation(...)

rs = ResultSelector(sim)              # We need a result selector path root for
                                      # describing things to add to the plots.

...                                   # Setting up initial conditions

sc = SimControl()                     # Creating the SimControl object

with sc:                              # Then used as a context-manager

    with PlotDisplay('Species plot'): # Declaring a PlotDisplay in the sc SimControl and
                                      # using it as a context-manager to declare
                                      # sub-components.

        TimePlot(rs.comp1.S1.Count)   # First row will show a plot of the number of S1 in
                                      # comp1 as a function of time.

        NewRow()                      # Next plots will be added to a different row

        SpatialPlot(                  # Second row will show the distribution of S1 along
            rs.TETS().S1.Count,       # the z axis.
            axis=[0, 0, 1],
            nbins=100
        )

    with SimDisplay('3D plots'):      # Declaring a SimDisplay in the sc SimControl and
                                      # using it as a context-manager to declare which
                                      # elements should appear in the SimDisplay.

        ElementDisplay(               # All compartment and patches should be displayed
            rs.ALL(Compartment, Patch)
        )
        ElementDisplay(               # The S1 species in all compartments should be
            rs.ALL(Compartment).S1,   # plotted in yellow
            color=(0, 0.5, 0.5, 1)
        )
        ElementDisplay(               # The S2 species in all patches should be plotted
            rs.ALL(Patch).S2,         # in purple.
            color=(0.5, 0, 0.5, 1)
        )
        ElementDisplay(               # Complexes CC in comp1 should be plotted with a
            rs.comp1.CC,              # color that depends on their state.
            color=
                lambda x: (
                    x.Count(C1),
                    x.Count(C2),
                    x.Count(C3),
                    1,
                ),
        )

sc.run()                              # Launch the simulation control windows

run()[source]: Launch the simulation displays

class PlotDisplay(title=None, size=(800, 600), *args, **kwargs)[source]

Bases: NamedObject

A window containing one or several plots

Parameters

title (str) – Title of the window
size (Tuple[int, int]) – Size of the window, in pixels

The PlotDisplay object should be used as a context manager for declaring specific plots. See example in SimControl. Several plots can be declared in the same display. By default, the plots are added on a single row, from left to right. A new row can be added by calling NewRow. Subsequent plots will be added to the new row.

class TimePlot(rspath, title=None, pen=None, data_size=1000, x_range=None, y_range=None, show_x_grid=True, show_y_grid=True, label_pen=None, x_label=('Time', 's'), y_label=None, '#ffffff', '16px'}, *args, **kwargs)[source]

Bases: NamedObject

Plot time-dependent values

Parameters

rspath (ResultSelector) – Result selector path of the values to be plotted
title (str) – Title of the plot
pen (pyqtgraph.QPen) – Pen used to draw the plot lines
data_size (int) – Maximum number of time points that should be displayed per line
x_range (Union[None, Tuple[float, float]]) – Range of the x axis, automatic if None
y_range (Union[None, Tuple[float, float]]) – Range of the y axis, automatic if None
show_x_grid (bool) – Display x axis grid
show_y_grid (bool) – Display y axis grid
x_label (str) – Label for the x axis (time)
y_label (Union[None, str]) – Label for the y axis, automatic if None (based on rspath labels)
label_style (dict) – Label style parameters
**kwargs – Other keywords supported by pyqtgraph.PlotItem

See example in SimControl. The result selector path can contain several values. If no pen is specified, the different values will be automatically attributed different colors, otherwise, all lines will share the same pen.

class SpatialPlot(rspath, title=None, mode='distr', axis=array([1, 0, 0]), nbins=20, x_label=('Position', 'm'), y_range=None, show_x_grid=True, show_y_grid=True, label_pen=None, '#ffffff', '16px'}, *args, **kwargs)[source]

Bases: NamedObject

Plot space-dependent values

Parameters

rspath (ResultSelector) – Result selector path of the values to be plotted
title (str) – Title of the plot
mode (str) – 'distr' or 'mean', see explanation below
axis (Tuple[float, float, float]) – Axis on which the data should be projected
nbins (int) – Number of bins
x_label (Tuple[str, str]) – Label for the x axis, first element is the label title, second is the unit
y_range (Union[None, Tuple[float, float]]) – Range of the y axis, automatic if None
show_x_grid (bool) – Display x axis grid
show_y_grid (bool) – Display y axis grid
label_pen (pyqtgraph.QPen) – Pen used to draw the labels
label_style (dict) – Label style parameters
**kwargs – Other keywords supported by pyqtgraph.PlotItem

See example in SimControl. The result selector path should encompass values in different places in space (i.e using TETS(...) or TRIS()). The position of each of the covered geometrical elements is then projected on the given axis and data is binned with the given number of bins. If 'distr' mode is used, the plot will be a histogram displaying the accumulated (summed) values in each bin. If 'mean' mode is used, the plot will display the average value for each bin.

class NewRow(*args, **kwargs)[source]

Bases: NamedObject

Add a new row to the display

class SimDisplay(title=None, size=(800, 600), *args, **kwargs)[source]

Bases: NamedObject

A window containing 3D elements

Parameters

title (str) – Title of the window
size (Tuple[int, int]) – Size of the window, in pixels

The SimDisplay object should be used as a context manager for declaring specific elements. See example in SimControl.

add(elemDisp)[source]

Add a previously declared element display

Parameters: elemDisp (ElementDisplay) – The element display

This is useful when wanting to reuse element displays that were declared in other SimDisplays.

merge(*simDisp)[source]

Merge with a previously declared simulation display

Parameters: *simDisp (SimDisplay) – The simulation displays to merge to self

This method adds all ElementDisplay that were associated to the given simulation display(s) to the current simulation display. This is useful when separate views of subcomponents are necessary but the user still wants a full view using all components.

class ElementDisplay(path, color=None, spec_size=0.2, max_nspec=10000, max_density=1e+21, auto_adjust=True, *args, **kwargs)[source]

Bases: NamedObject

3D element to be displayed in a SimDisplay

Parameters

path (steps.API_2.saving.ResultSelector) – A result selector path to a geometrical location or to an object (see steps.API_2.sim.SimPath)
color (Union[Callable[[StepsElement], Tuple[float, ...]], Tuple[float, ...], None]) – A color for the element or a function that takes an element as a parameter and returns a color (in case several elements are provided). An automatic color is selected if this is None.
spec_size (float) – If species are provided as elements, defines their size in the 3D plot.
max_nspec (int) – Maximum number of species that can be visualized in the plot.
max_density (float) – Maximum density of species that can be visualized in the plot.
auto_adjust (bool) – Flag for auto adjustment of visualized species counts

See example in SimControl. If the result selector path that is given points to geometrical elements (like compartments, patches, tetrahedrons, etc.), the corresponding 3D surface is added to the display. If the result selector path points to objects instead (like species, complexes, channels, etc.), points corresponding to their location are added to the display.

class PartitionDisplay(partition, elem='tet', title=None, size=(800, 600), *args, **kwargs)[source]

Bases: NamedObject

A window displaying a mesh partition

Parameters

partition (steps.API_2.geom.MeshPartition) – The partition to be displayed
elem (str) – 'tet' for displaying tetrahedron partition and 'tri' for displaying triangle partition
title (str) – Title of the window
size (Tuple[int, int]) – Size of the window, in pixels