## 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`