See !118

[[TOC]]

[DOCUMENTATION INCOMPLETE -- Still need to document AgentWidgets use and relationship to GlobalAgent -- see notes in feat-agentwidgets line 258]

Histograms can be used to plot a dictionary of values, e.g.:

    countByProp = [
       ['0', 11],
       ['1', 53],
       ['2', 22],
     ]

The dictionary keys are the bar labels and dictionary values are the bar values.

There are two basic histogram calls:

1. countAgentsByPropType -- counts the number of agents for each value of a prop, e.g. the number of Moths at
2. countExistingAgentsByFeatPropType -- counts the number of agents that match a particular featProp value, e.g. the number of Moths at each value of featProp Costume colorScaleIndex.

Both calls generate a Population private map object _countsByProp. This is used to send data to the histogram.

In order to plot bars with no values, you need to first initialize the histogram data with keys for all bars using setAgentsByFeatPropTypeKeys, e.g.

• to set keys for a colorScale index: featCall Population setAgentsByFeatPropTypeKeys 0 1 2 3 4 5 6 7 8 9 10 11
• to set keys for a dictionary with string keys: featCall Population setAgentsByFeatPropTypeKeys "algae" "frogs" "fish"

featCall Population countAgentsByPropType <blueprint> <prop> <clear>

Where

• <blueprint> is the name of a blueprint, e.g. "Moth"
• <prop> is the name of a prop, typically an enumerated type, e.g. "flowerType" where the values might be "daisy", "rose", and "violet".

To enable changing the graph via the Script UI, you can also set the parameters for countAgentsByPropType via featProp settings:

• monitoredAgent property -- aka <blueprint>
• monitoredAgentProp property -- aka <prop>

e.g. featProp Population monitoredAgent setTo 'Moth'

featCall Population countExistingAgentsByFeatPropType <blueprint> <feature> <featProp> <clear>

Where

• <blueprint> is the name of a blueprint, e.g. "Moth"
• <feature> is the name of the feature that contains the featProp, e.g. Costume
• <featProp> is the name of a feature prop, typically an enumerated type, e.g. "ColorScaleIndex" where the values might be "0", "1", "2", etc.

To enable changing the graph via the Script UI, you can also set the parameters for countAgentsByPropType via featProp settings:

• monitoredAgent property -- aka <blueprint>
• monitoredAgentPropFeature property -- aka <feature>
• monitoredAgentProp property -- aka <featProp>

e.g. featProp Population monitoredAgent setTo 'Moth'

See !151

We're replacing the old line-graph histogram with a new implementation that uses actual bar graphs. Histograms and Bar Graphs work with Map objects. Currently the only built-in Map object is the Population._countsByProp property that is generated by calls to Population countAgentsByPropType and countAgentsByFeatPropType calls.

Overview:

1. Create a Histogram agent.
2. Set Bar Graph Property -- In the instance definition, set the target property you want to graph.
3. Set the keys and labels to use for each column
4. Periodically update the target property -- AgentWidgets will automatically update the Bar Graph with the new values.

The graph will be plotted by the Histogram agent. Use the agent to position the graph.

• You need to use the AgentWidgets feature to render the bar graph.
• You need to use the Population feature to handle the statistics generation.

# BLUEPRINT Histogram
# PROGRAM DEFINE
useFeature AgentWidgets
useFeature Population

We set two separate properties for the graph:

1. The property we run statistics on, aka the monitoredAgentProp
2. The resulting statistics property to graph, e.g. _countsByProp.

If you're creating multiple histograms, you can set these properties in the instance init script. If you're always using _countsByProp in all of the histograms, you can of course put the AgentWidgets definitions in the blueprint # PROGRAM DEFINE block.

// Histogram initScript

// Set the property you want to run statistics on
featProp Population monitoredAgent setTo 'Moth'
featProp Population monitoredAgentPropFeature setTo 'Costume'
featProp Population monitoredAgentProp setTo 'colorScaleIndex'

// Set the barGraph to point to the Map object you want to plot
featProp AgentWidgets barGraphProp setTo '_countsByProp'
featProp AgentWidgets barGraphPropFeature setTo 'Population'
featProp AgentWidgets text setTo 'colorScaleIndex'

As with other countExistingAgentByFeatPropType calls, you'll want to set the keys so empty bars will be displayed.

Put this in the init script:

featCall Population setAgentsByFeatPropTypeKeys 0 1 2 3 4 5 6 7 8 9 10 11

The keys will be used as the labels for the histogram.

You need to decide how often you want to update the histogram.

Keep in mind that running statistics on the whole population can be costly if we're doing that every single frame.

In this example, we know that we only need to update the histogram statistics right at the beginning of a round, right after the Moths mutate. So we use a onEvent Start script:

# BLUEPRINT Histogram
...
# PROGRAM EVENT
onEvent Start [[
  dbgOut 'Starting Round!  Update Histogram'
  featCall Population countExistingAgentsByFeatPropType
]]

Since we set the monitoredAgent* featProps, we can call countExistingAgentsByFeatPropType without any parameters. So whenever a round starts, countExistingAgentsByFeatPropType is called, the monitoredAgents are counted, and the results are stored in _countsByProp, which is then plotted by AgentWidget.

Blueprint:

# BLUEPRINT Histogram
# PROGRAM DEFINE
useFeature Population
useFeature AgentWidgets

# PROGRAM EVENT
onEvent Start [[
  dbgOut 'Starting Round!  Update Histogram'
  featCall Population countExistingAgentsByFeatPropType
]]

Instance Init Script

// Histogram
prop x setTo -290
prop y setTo 370
featCall Population setAgentsByFeatPropTypeKeys 0 1 2 3 4 5 6 7 8 9 10 11
featProp Population monitoredAgent setTo 'Moth'
featProp Population monitoredAgentPropFeature setTo 'Costume'
featProp Population monitoredAgentProp setTo 'colorScaleIndex'
featProp AgentWidgets barGraphProp setTo '_countsByProp'
featProp AgentWidgets barGraphPropFeature setTo 'Population'
featProp AgentWidgets text setTo 'colorScaleIndex

See Histogram description for full example.

• Line Graph Histogram