SSJ
V. labo.

umontreal.iro.lecuyer.stat
Class StatProbe

java.lang.Object
  extended by umontreal.iro.lecuyer.stat.StatProbe
Direct Known Subclasses:
Accumulate, FunctionOfMultipleMeansTally, Tally

public abstract class StatProbe
extends Object

StatProbe

The objects of this class are statistical probes or collectors, which are elementary devices for collecting statistics. Each probe collects statistics on a given variable. The subclasses Tally, TallyStore, and umontreal.iro.lecuyer.simeventsAccumulate (from package umontreal.iro.lecuyersimevents) implement two kinds of probes, for the case of successive observations X1, X2, X3,..., and for the case of a variable whose value evolves in time, respectively.

Each instance of StatProbe contains a list of ObservationListener that can listen to individual observations. When a probe is updated, i.e., receives a new statistical observation, it broadcasts this new data to all registered observers. The broadcasting of observations to registered observers can be turned ON or OFF at any time. It is initially OFF by default and should stay OFF when there are no registered observers, to avoid unnecessary overhead.

The data collection by the statistical probe itself can also be turned ON or OFF. By default, it is initially ON. We can turn it OFF, for example, if we want to use the statistical probe only to pass data to the observers, and do not need it to store any information.

In the simplest programs, collection is ON, broadcast is OFF, and the overall stats are accessed via the methods min, max, sum, average, ... of the collector.


Constructor Summary
StatProbe()
           
 
Method Summary
 void addObservationListener(ObservationListener l)
          .
abstract  double average()
          .
 void clearObservationListeners()
          .
 StatProbe clone()
           
 String getName()
          .
abstract  void init()
          .
 boolean isBroadcasting()
          .
 boolean isCollecting()
          .
 double max()
          .
 double min()
          .
 void notifyListeners(double x)
          .
 void removeObservationListener(ObservationListener l)
          .
abstract  String report()
          .
static String report(String globalName, Iterable<? extends StatProbe> probes)
          .
static String report(String globalName, StatProbe[] probes)
          .
 void setBroadcasting(boolean b)
          .
 void setCollecting(boolean b)
          .
 void setName(String name)
          .
abstract  String shortReport()
          .
abstract  String shortReportHeader()
          .
 double sum()
          .
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StatProbe

public StatProbe()
Method Detail

init

public abstract void init()
. \begin{tabb}Initializes the statistical collector.
 \end{tabb}


setName

public void setName(String name)
. \begin{tabb}Sets the name of this statistical collector to \texttt{name}.
 \end{tabb}


getName

public String getName()
. \begin{tabb}Returns the name associated with this probe,
 or \texttt{null} if no name was specified upon construction.
 \end{tabb}
the name associated to this collector, or null if not specified


min

public double min()
. \begin{tabb}Returns the smallest value taken by the variable
 since the last ini...
 ...FINITY}
 if the probe was not updated since the last initialization.
 \end{tabb}
the smallest value taken by the collector since last initialization


max

public double max()
. \begin{tabb}Returns the largest value taken by the variable
 since the last init...
 ...FINITY}
 if the probe was not updated since the last initialization.
 \end{tabb}
the largest value taken by the collector since last initialization


sum

public double sum()
. \begin{tabb}Returns the sum cumulated so far for this probe.
 The meaning of thi...
 ...turns 0
 if the probe was not updated since the last initialization.
 \end{tabb}
the sum for this probe


average

public abstract double average()
. \begin{tabb}Returns the average for this collector.
 This returns \texttt{Double.NaN}
 if the probe was not updated since the last initialization.
 \end{tabb}
the average value of the collected observations


report

public abstract String report()
. \begin{tabb}Returns a string containing a report for this statistical
 collector...
 ...as on the parameters set by the user through probe-specific methods.
 \end{tabb}
a report for this probe, represented as a string


shortReport

public abstract String shortReport()
. \begin{tabb}Formats and returns a short, one-line report
 about this statistical...
 ...as on the
 parameters set by the user through probe-specific methods.
 \end{tabb}
the short report for the probe.


shortReportHeader

public abstract String shortReportHeader()
. \begin{tabb}Returns a string containing
 the name of the values returned in the ...
 ...xttt{(String,StatProbe[])}
 to get a report with aligned probe names.
 \end{tabb}
the header string for the short reports.


report

public static String report(String globalName,
                            StatProbe[] probes)
. \begin{tabb}Formats short reports for each statistical probe in the array
 \text...
 ...thod assumes that \texttt{probes}
 contains no \texttt{null} element.
 \end{tabb}
globalNamethe global name given to the formatted report. probesthe probes to include in the report. the formatted report.


report

public static String report(String globalName,
                            Iterable<? extends StatProbe> probes)
. \begin{tabb}Equivalent to \method{report}{(String,StatProbe[])}, except that
 \t...
 ...l probes to include in the report in a consistent and sensible order.
 \end{tabb}
globalNamethe global name given to the formatted report. probesthe probes to include in the report. the formatted report.


isBroadcasting

public boolean isBroadcasting()
. \begin{tabb}Determines if this statistical probe
 is broadcasting observations to registered observers.
 The default is \texttt{false}.
 \end{tabb}
the status of broadcasting.


setBroadcasting

public void setBroadcasting(boolean b)
. \begin{tabb}Instructs the probe to turn its broadcasting ON or OFF.
 The default...
 ...ng
 should never be turned ON when there are no registered observers.
 \end{tabb}
btrue to turn broadcasting ON, false to turn it OFF


isCollecting

public boolean isCollecting()
. \begin{tabb}Determines if this statistical probe
 is collecting values. The default is \texttt{true}.
 \end{tabb}
the status of statistical collecting.


setCollecting

public void setCollecting(boolean b)
. \begin{tabb}Turns ON or OFF the collection of statistical
 observations. The def...
 ... turned ON, but are not
 counted as observations by the probe itself.
 \end{tabb}
btrue to activate statistical collection, false to deactivate it


addObservationListener

public void addObservationListener(ObservationListener l)
. \begin{tabb}Adds the observation listener \texttt{l} to the list of observers of
 this statistical probe.
 \end{tabb}
lthe new observation listener. NullPointerExceptionif l is null.


removeObservationListener

public void removeObservationListener(ObservationListener l)
. \begin{tabb}Removes the observation listener \texttt{l} from the list of observers of
 this statistical probe.
 \end{tabb}
lthe observation listener to be deleted.


clearObservationListeners

public void clearObservationListeners()
. \begin{tabb}Removes all observation listeners from the list of observers of
 this statistical probe.
 \end{tabb}


notifyListeners

public void notifyListeners(double x)
. \begin{tabb}Notifies the observation \texttt{x} to all registered observers
 if broadcasting is ON. Otherwise, does nothing.
 \end{tabb}


clone

public StatProbe clone()
                throws CloneNotSupportedException
Overrides:
clone in class Object
Throws:
CloneNotSupportedException

SSJ
V. labo.

To submit a bug or ask questions, send an e-mail to Pierre L'Ecuyer.