Reference 〉 Class


The TimeSeries class is a Matplotlib-based visualizer for displaying time series data on plots so the whole history of any given variable over the model’s runtime can be seen at once.

This class should not be initialized by user code. Rather, import the class and use model.useVisual(TimeSeries). The instantiated object can be accessed at model.visual, and individual plot objects can be accessed by indexing TimeSeries, e.g. model.visual['plotName'].


  • Plots automatically rescale with new data
  • Series registered with an AgentReporter created with the std or percentiles arguments will display intervals alongside the main series.
  • In addition to the normal display, series can also be stacked vertically within a plot
  • Creates a checkgrid parameter ‘plots’ where the various registered plots can be toggled on and off before runtime
  • Legend boxes in the top-right corner can be toggled by pressing ‘t’
  • The plot underneath the mouse cursor can be toggled between log and linear scale by pressing ‘l’
  • Individual lines can be toggled on and off in a particular plot by clicking the name of the line in the legend box.
  • Automatically adjusts resolution downward at t=2,500, 25,000, etc. in order to remain performant

Initialization Parameters

  • model Helipad, required

    The model object.


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 if key is pressed at any time when the plot window is in focus. To narrow the focus to a particular plot, define catchKeypress() in a subclass of ChartPlot.

  • addPlot( name, label, position, … )

    Registers a plot area in the TimeSeries plot area to which data series can be added.

  • removePlot( name, reassign )

    Removes a plot or plots and optionally reassigns their series to a different plot. This function can only be run prior to model.launchCpanel().

  • event( t, color, linestyle, … )

    Draws a vertical line on the plots area at time t. This function should not be called directly; specify an event instead.

  • 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.

  • refresh( 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.

  • terminate( )

    Cleanup on model termination. This function is called automatically from model.terminate() and should not be called from user code.

  • toggleLine( event )

    Toggles a series on or off. This function is called when a series name is clicked in the legend of a plot.

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}

    The subset of plots containing the Plot objects that are currently selected.

  • keyListeners 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 default x position places the window immediately to the right of the control panel.

    Initial value: (400, 0)

  • resolution int

    The time elapsing between any two data points drawn to screen (not the time elapsing between two updates, which is a user-controlled parameter). resolution increases by 10× at period 2,500, 25,000, 250,000, etc.

    Initial value: 1


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 the modelPostSetup hook to catch before the visualization is launched.

Notes and Examples

  1. Contribute a Note

    Your email address will not be published. Required fields are marked *

    You may use limited HTML for formatting. Please embed blocks of code in <pre><code> </code></pre> tags.