Announcing: BreakoutReporter

[M Lang / S Railsback]

The Humboldt State fish modeling crowd is happy to release our latest
handy Swarm add-on, a tool for collecting data from collections of
agents. "BreakoutReporter" makes it easy to create and customize output
files with statistical summaries of agent characteristics, broken out by
up to five categories. For example, in our fish models we can use it to
write out, every 10 simulation days, the number and average weight of
fish broken out by fish species and age.

The code is in Objective C. Feedback on the value of adding it to Swarm
would I'm sure be welcome.

I put the code & documentation on the "Software" page of our web site:
http://math.humboldt.edu/~simsys/

Following is the overview from the documentation.

Steve Railsback

***************************************************

BreakoutReporter is an Objective C class that reports statistics on a
list of objects in a Swarm model, with the output broken out by up to
five variables and written to a file. (The model objects are referred to
here as agents, even though they can be any objects meeting the
conventions defined below.) For example, an animal model could use the
BreakoutReporter to periodically write to an output file the number of
animals and their mean weight, broken out by species, sex, and age.
Additional output columns can be added to report model variables such as
the simulation date.

BreakoutReporter uses a "breakout map"-a structure of five nested Swarm
maps to sort the objects by the breakout variables. The breakout
variables are defined during the create phase. One copy of the breakout
map contains Swarm lists, onto which are sorted the agents when the
breakoutReporter is updated. Other copies of the breakout map contain
Swarm averagers, attached to the lists of agents, that calculate the
output statistics. The averagers can provide the count, total, maximum,
mimimum, or average (mean) value over the agents.

A breakoutReporter can be updated during a simulation by either (1)
adding more agents to the lists for which statistics are reported, or
(2) replacing all the agents on these lists. For example, the number of
live animals in a model can be reported using a breakoutReporter updated
by replacing all the live animal objects (because some that were
previously alive are now dead); but the cumulative number of dead
animals can be reported using a breakoutReporter updated by adding the
newly deceased animal objects (because dead animals stay dead). A new
output line can be written after each update.

The output file is in column format so it can easily be imported into a
spreadsheet or data base. The columns are automatically labeled, and a
system time stamp is automatically written at the top of the output
file.

-- 
address@hidden
Lang, Railsback & Assoc.
250 California Ave., Arcata CA 95521
707-822-0453; Fax 822-1868

                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.