
Displays a spatial grid of Patch
es, as well as agent positions on them.
This class should not be instantiated directly. Use model.spatial()
instead.
Note that patches are centered on the integer coordinates, numbering starts at 0, and agents can take fractional positions. The coordinate system for agents, therefore, runs from (-0.5, -0.5)
to (x-0.5, x-0.5)
.
Features
- Ability to tie patch color to a property value or stocks of a good
- Ability to tie agent size to a property value or stocks of a good
- Agent color reflects breed color
- Agents and patches are both clickable; clicked agents and patches are passed to a
spatialAgentClick
andspatialPatchClick
hook, respectively.
Methods
Click a method name for more detailed documentation.
config( param, val )
Sets options for the spatial plot. One argument will return the value; two arguments sets the parameter. Config options are:
patchColormap
(str
): The name of a Matplotlib colormap for coloring the patches. Default:'blues'
patchProperty
(str
): The name of a property to which the colormap should correspond. For example, The default value of'mapcolor'
for example means that patch color will represent the patch's value ofPatch.mapcolor
, which can be set in thepatchStep
hook. If the string is formatted'good:goodname'
, patch colors will represent the patch's stocks of the good represented bygoodname
. Default:'mapcolor'
agentMarker
(str
): a string representing the Matplotlib marker to be used to represent agents on the map. Default:'o'
agentSize
(int|str
): If an integer, sets the size of the marker used to represent agents. If a string, represents an agent property or the stocks of a good to size the agent by, identically to patchProperty. Default:5
draw( t, forceUpdate )
Updates the
axes
object for display on the visualizer. This function is called afterChartPlot.update()
when the visualizer receives new data, and when scrubbing the time bar. Theupdate()
method, therefore, should be used to store model data by time, which can then be used bydraw()
.Charts will refresh the entire canvas after updating each of the individual plots, so there is no need to refresh the canvas manually here unless it is desired to redraw the graph out of sync (e.g. if the subclass provides for interactivity and the plot should update while the model is paused).
Subclasses should call
super().draw(t, forceUpdate)
at the end of the function.update( data, t )
Receives current model data and stores it for future scrubbing.
Note that this function is called when the visualizer receives new data from the model. Because
ChartPlot.draw()
is called both afterChartPlot.update()
and when the time bar is scrubbed, drawing code should be but inChartPlot.draw()
and not here, unless there is code to be run only in the event of new data that should not be run when scrubbing (e.g. calculating new plot bounds).If the visualizer needs model properties besides the current data, the model object can be accessed with
self.viz.model
.This function should not typically be called from user code, though it can be for out-of-sync plot updates when interacting with a plot. See the
networkNodeClick
hook for an example.agentLoc( update )
Helper function to retrieve historical agent location, color, and size data.
getPatchParamValue( patch, t )
Helper function that gathers historical patch data for use in color generation.
launch( axes )
Initial code to set up
ChartPlot.axes
whenCharts
launches the visualization window. Subclasses should callsuper().launch()
at the beginning of the method. This function should not be called from user code.patchData( t )
Helper function that gathers historical patch data.
Properties
type — str
A short identifying string, to be used in the
type
argument ofCharts.addPlot()
.name — str
A short name, used to refer back to the plot afterward.
label — str
The title of the chart, displayed above it in the visualizer.
axes — matplotlib.AxesSubplot
The
AxesSubplot
object to be drawn to the plot area. The object is created onCharts.launch()
and passed toChartPlot.launch()
, where it must be stored subsequently.projection — str
The Matplotlib coordinate projection to use.
None
defaults to'rectilinear'
, but other projections available by default are'polar'
,'3d'
,'aitoff'
,'hammer'
,'lambert'
, and'mollweide'
. Custom Matplotlib projection objects can also be passed to this argument.Initial value: None
viz — Charts
The parent
Charts
visualizer object.selected — bool
Whether or not the plot should be drawn when
Charts
is launched.params — dict{str: str|num}
A dict of option values for the plot. See
SpatialPlot.config()
for options.agentHistory — dict{int: tuple(list)}
A dict keyed by model time, containing location, breed color, size, and id data for each agent at each refresh interval.
Initial value: {}
Hooks
Click a hook name for more detailed documentation.
spatialPatchClick( patch, plot, t )
Receives the patch clicked when the SpatialPlot plot is clicked.
spatialAgentClick( agents, plot, t )
Runs when an agent is clicked in the SpatialPlot plot.
Notes and Examples