
A Matplotlib-based visualizer for a variety of visualizations that display data that reflects only a single point in time (as opposed to TimeSeries
, which displays data over time).
Features
- Can display a variety of plot types alongside one another, including bar charts, network and spatial plots, and time series, and can also register custom plot types with subclasses of
ChartPlot
(see the tutorial for an example). See the specific plot classes for features specific to built-in plot types. - Time bar at the bottom allows the user to scrub back over the model history
Initialization Parameters
model — Helipad, required
The model object.
Methods
Click a method name for more detailed documentation.
addKeypress( key, fn )
Registers a function to be run when a key is pressed in a Matplotlib visualizer.
fn
will run ifkey
is pressed at any time when the plot window is in focus. To narrow the focus to a particular plot, definecatchKeypress()
in a subclass ofChartPlot
.addPlot( name, label, type, … )
Adds a plot area to the Chart visualizer. Defaults to a bar chart, but can be set to any subclass of
ChartPlot
.addPlotType( clss )
Registers a new plot type for the
Charts
visualizer. Registered plot types can then be added to the visualization area withCharts.addPlot()
.event( t, color, **kwargs )
Called when an event is triggered, in order to be reflected in the visualization. For example, a line is drawn in
TimeSeries
, and the background flashes inCharts
. Any kwargs passed toEvents.add()
are passed to this function, allowing subclasses to receive custom arguments (for example,linestyle
inTimeSeries.event()
). This method is mandatory for subclasses to implement.This function is called automatically when an event is triggered and should not be called by user code.
launch( title )
Launches the visualization window (if in Tkinter) or cell (if in Jupyter). This method is required to be implemented by subclasses, which should call
super().launch(title)
after creating the Matplotlib figure object.scrub( t )
Updates the visualizer with the values from model time
t
. This function is called when the time slider is modified and should not be called from user code.sendEvent( event )
An event handler for Matplotlib-based visualizations that executes functions registered with
MPLVisualization.addKeypress()
and routes other events to the appropriateChartPlot
object depending on the current mouse position, which are received byChartPlot.MPLEvent()
. This function should not be called directly by user code.sendEvent()
currently routeskey_press_event
(keystrokes),button_press_event
(mouse clicks), andpick_event
(mouse clicks associated with particular pickableArtist
s).terminate( )
Cleanup on model termination. This function is called automatically from
model.terminate()
and should not be called from user code.update( data )
Updates the visualization with new data and refreshes the display. This is mandatory for any subclasses to implement. Subclasses implementing this method should also use it to store any data necessary for future visualizer operations.
This function should only rarely be called by the user; call
model.step()
instead to increment the model by one period and update the graph.
Object Properties
isNull — bool
True
when the model should run as-if with no visualization, for example if all the plots are unselected.False
indicates the window can be launched.lastUpdate — int
Because the model can be set to refresh the visualization only every so many periods, this property records the model time when data was last drawn to the visualization. This property is
None
until the visualization window is launched.Initial value: None
fig — matplotlib.Figure
The Matplotlib Figure object used for rendering the visualization as a whole.
plots — dict{str:Plot}
A dict of registered
TimeSeriesPlot
objects.activePlots — dict{str:Plot}
A dynamic property consisting of the subset of the
plots
containing the Plots that are currently active.keys — dict{str: list[func]}
Where functions defined in
MPLVisualization.addKeypress()
are stored.Initial value: {}
dim — tuple(int, int)
The height and width at which the visualization window should open at launch, if using the Tkinter frontend. Default is the screen height and 2/3 the screen width.
Initial value: None
pos — tuple(int, int)
The
(x, y)
position at which the visualization window should open at launch, if using the Tkinter frontend. The defaultx
position places the window immediately to the right of the control panel.Initial value: (400, 0)
Hooks
Click a hook name for more detailed documentation.
visualRefresh( model, visual )
Runs when the visualizer updates, every n periods as determined by the
refresh
parameter.visualLaunch( model, visual )
Runs when
model.launchVisual()
is called, after the visualization is launched. Use themodelPostSetup
hook to catch before the visualization is launched.
Notes and Examples