org.ascape.util.data
Class StatCollector

java.lang.Object
  org.ascape.util.data.StatCollector

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable, DataPoint, HasName

Direct Known Subclasses:

StatCollectorCond, StatCollectorCSA

public class StatCollector
extends java.lang.Object
implements java.lang.Comparable, DataPoint, java.io.Serializable

Collects and stores aggregate statistics on some data source for every specified measurement type of that source, and for each succesive measurement of that source. These stats, when added to a scape, are available for observation by charting tools, data export, etc.. Statistics can be automatically collect by the framework, or collected manually. While this class is not abstract, it should be considered so when collecting statistics automatically. This class and its subclasses are intended to collaborate with classes that gather statistics on some collection of objects, by calling clear() to set all values to the appropriate 'zero' value, then addValue() on each object. Pick the stat collector class that provides all the measurements you will want to use. StatCollectorCSA provides count, sum and average measures. StatCollectorCSAMM also provides minimum and maximum measures. StatCollectorCSAMMVar also provides variance and standard deviation measures. Let us know if there are other measurements that you might want to use. (Median is being considered, but will be relativly costly.) The following example creates a class that gathers a count, sum of ages, and average age for supplied objects. To use within ascape, you could create a new class that overrides the getValue and getName methods.

 class AgeStatCollector extends StatCollectorCSA {
    public double getValue(Object object) {
         return ((AnObjectWithAge) object).getAge();
    }
    public String getName() {
        return "Age";
    }
 }
 

and then add it to your scape.

 myScape.addStatCollector(new AgeStatCollector());
 

In practice, we usually just do something like:

 scape.addStatCollector(new StatCollectorCSA("Age") {
    public double getValue(Object object) {
         return ((AnObjectWithAge) object).getAge();
    }
 }
 

If you only want to collect statistics on a subpopulation of a scape (i.e. "Wealth of all agents over 30"), use a StatCollectorCond.
Often, you will want to collect statistics on some activity (behavior) that occurs during the model run, instead of on individual agents. For example, it would be hard to collect statistics on agent deaths using automatic stat collection. In this case, use a manual stat collector. Manual stat collectors are still cleared automatically every iteration, but but the developer is responsible for adding values to them. The following example creates a new statistic recording a count of the number of times it was invoked (the number of deaths that have occurred), the total wealth of all agents that have died in the current period, and the average wealth of agents who have died during this period.

 public void scapeCreated() {
     ...
     myScape.addStatCollector(new StatCollectorCSA("Death Wealth", false));
     ...
 }
 ...
 public void die() {
     super.die();
     scape.getData().getStatCollector("Death Wealth").addValue(wealth);
     ...
 }
 

Performance note: This manual method requires a string comparison in the model to compare the name of the stat collector to the list of stat collectors. We usually try to avoid this kind of thing inside the body of a running model but for typical usage this hit is probably minimal. To avoid it, you could create a static class member for the stat, or make the stat a member of the parent scape, and access it directly.

Since:

1.0

Version:

2.0

Author:

Miles Parker

See Also:

StatCollectorCond, StatCollectorCSA, StatCollectorCSAMM, StatCollectorCSAMMVar, StatCollectorCondCSA, StatCollectorCondCSAMM, StatCollectorCondCSAMMVar, Serialized Form

Field Summary

protected static java.lang.String[]	allMeasureNames Names for all statistical measures implemented.
protected static java.lang.String[]	allMeasureNamesShort Short names for all statistical measures implemented.
protected boolean	autoCollect Should the stat be collected automatically? Default is true.
static int	COLLECTING
protected int	count The number of values collected.
protected java.lang.String	name The name of the stat.
static int	NOT_COLLECTING
static int	SET_BY_DATAGROUP

Constructor Summary

StatCollector()
Constructs a new StatCollector.

StatCollector(java.lang.String name)
Constructs a new StatCollector.

StatCollector(java.lang.String name, boolean autoCollect)
Constructs a new StatCollector.

Method Summary

void	addValue(double value) Add the value, incrementing count.
void	addValueFor(java.lang.Object object)
void	calculateCollection(java.util.Collection collection) Calcualtes the statcollector across the provided list.
void	calculateIterator(java.util.Iterator iter) Calcualtes the statcollector across the provided iterator.
double	calculateValue() Calculate the value to be added (once) to the statistic.
void	clear() Override to clear all values related to this stat.
int	compareTo(java.lang.Object o) Compares one stat collector to another by name.
void	createDataSeries(boolean collectingLongitudinalData) Creates a data series for every measure of this statistic collector.
DataSeries[]	getAllDataSeries() Returns a data series for every statistical measure this collector is capable of generating.
static java.lang.String[]	getAllMeasureNames() Returns all names for measures that statistics collectors are capable of generating.
static java.lang.String[]	getAllMeasureNamesShort() Returns all short names for measures that statistics collectors are capable of generating.
int	getCollectingLongitudinalDataMode()
int	getCount() Returns the current number of values added.
DataGroup	getDataGroup()
DataSeries	getDataSeries(java.lang.String measureName) Returns a data series for the measure name provided.
java.lang.String	getName() Override to provide a short name, or set a name, in the constructor or using this method.
double	getValue(java.lang.Object object) Override to return the value being used to calculate this statistic.
boolean	isAutoCollect() Is value collected automatically by iterating over a scape? Default is true; override to set false;
boolean	isCalculated() Is value collected automatically by iterating over a scape? Default is true; override to set false;
boolean	isCollectingLongitudinalData()
boolean	isPhase2()
void	setAutoCollect(boolean autoCollect) Set whether the value is collected automatically.
void	setCollectingLongitudinalDataMode(int mode)
void	setDataGroup(DataGroup dataGroup)
void	setName(java.lang.String name) Sets the name of this statistic.
java.lang.String	toString() Returns a short desription of this stat collector.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

count

protected int count

The number of values collected.

name

protected java.lang.String name

The name of the stat.

autoCollect

protected boolean autoCollect

Should the stat be collected automatically? Default is true.

SET_BY_DATAGROUP

public static final int SET_BY_DATAGROUP

See Also:

Constant Field Values

COLLECTING

public static final int COLLECTING

See Also:

Constant Field Values

NOT_COLLECTING

public static final int NOT_COLLECTING

See Also:

Constant Field Values

allMeasureNames

protected static java.lang.String[] allMeasureNames

Names for all statistical measures implemented.

allMeasureNamesShort

protected static java.lang.String[] allMeasureNamesShort

Short names for all statistical measures implemented.

Constructor Detail

StatCollector

public StatCollector()

Constructs a new StatCollector.

StatCollector

public StatCollector(java.lang.String name,
                     boolean autoCollect)

Constructs a new StatCollector.

Parameters:

name - the name of the stat collector.

autoCollect - should the stat be collected automatically?

StatCollector

public StatCollector(java.lang.String name)

Constructs a new StatCollector. (Automatic by default.)

Parameters:

name - the name of the stat collector.

Method Detail

clear

public void clear()

Override to clear all values related to this stat. Sets count to 0.

addValueFor

public void addValueFor(java.lang.Object object)

addValue

public void addValue(double value)

Add the value, incrementing count. Override to track additional measurements.

getValue

public double getValue(java.lang.Object object)

Override to return the value being used to calculate this statistic. For base case, returns 0.0, not the value of interest for the supplied object. We return 0.0 since value doesn't matter in the most limited case; it is unneccesary to override this method if you just want to get a count. If you are implementing a subclass of this stat collector, you must override this class unless you will be collecting the statistic manually, or you are only intersted in collecting a count. Overide the method with a call to the getter for the value this stat is tracking. For example:

    public double getValue(Object object) {
        return ((MyClass) object).getMyInterestingValue();
    }
 

Specified by:

getValue in interface DataPoint

Parameters:

object - an object that contains the value of interest, ignored in base case

calculateValue

public double calculateValue()

Calculate the value to be added (once) to the statistic.

isCalculated

public boolean isCalculated()

Is value collected automatically by iterating over a scape? Default is true; override to set false;

isPhase2

public boolean isPhase2()

isAutoCollect

public boolean isAutoCollect()

Is value collected automatically by iterating over a scape? Default is true; override to set false;

setAutoCollect

public void setAutoCollect(boolean autoCollect)

Set whether the value is collected automatically.

Parameters:

autoCollect - true to collect statistic automatically.

isCollectingLongitudinalData

public boolean isCollectingLongitudinalData()

setCollectingLongitudinalDataMode

public void setCollectingLongitudinalDataMode(int mode)

getCollectingLongitudinalDataMode

public int getCollectingLongitudinalDataMode()

getCount

public int getCount()

Returns the current number of values added.

getAllMeasureNames

public static java.lang.String[] getAllMeasureNames()

Returns all names for measures that statistics collectors are capable of generating.

getAllMeasureNamesShort

public static java.lang.String[] getAllMeasureNamesShort()

Returns all short names for measures that statistics collectors are capable of generating.

getAllDataSeries

public DataSeries[] getAllDataSeries()

Returns a data series for every statistical measure this collector is capable of generating. If these data series don't allready exist, they are created.

See Also:

createDataSeries(boolean)

getDataSeries

public DataSeries getDataSeries(java.lang.String measureName)

Returns a data series for the measure name provided. For example, myStat.getDataSeries("Count") would return the entire series for Count of myStat. If the series doesn't exist, a runtime excpetion will be thrown.

calculateCollection

public void calculateCollection(java.util.Collection collection)

Calcualtes the statcollector across the provided list.

Parameters:

collection -

calculateIterator

public void calculateIterator(java.util.Iterator iter)

Calcualtes the statcollector across the provided iterator.

Parameters:

iter - the list to calcualte statistics on.

createDataSeries

public void createDataSeries(boolean collectingLongitudinalData)

Creates a data series for every measure of this statistic collector.

setDataGroup

public void setDataGroup(DataGroup dataGroup)

getDataGroup

public DataGroup getDataGroup()

getName

public java.lang.String getName()

Override to provide a short name, or set a name, in the constructor or using this method. By default, returns "Unnamed". You should always provide a name unless the stat is temporary. Otherwise, there will be duplicate stat names, and there will be no way to select statistics by name! For example:

    public double getName(Object object) {
        return "Interesting Value";
    }
 

Or simply: myStat.setName("Interesting Value");

Specified by:

getName in interface DataPoint

Specified by:

getName in interface HasName

setName

public void setName(java.lang.String name)

Sets the name of this statistic.

toString

public java.lang.String toString()

Returns a short desription of this stat collector.

Overrides:

toString in class java.lang.Object

compareTo

public int compareTo(java.lang.Object o)

Compares one stat collector to another by name. Again, it is important to ensure that all stats within a datagroup have different names.

Specified by:

compareTo in interface java.lang.Comparable