Overview | Package | Class | Tree | Deprecated | Index | Help
| SSJ V. 2.1.1.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## umontreal.iro.lecuyer.stat
Class StatProbe

    java.lang.Object
      umontreal.iro.lecuyer.stat.StatProbe

Direct Known Subclasses:
  Accumulate, Tally

    public abstract class StatProbe

extends Object

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 `Accumulate` (from package `simevents`) 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)` Adds the observation listener `l` to the list of observers of this statistical probe.
`abstract double` | `average()` Returns the average for this collector.
`void` | `clearObservationListeners()` Removes all observation listeners from the list of observers of this statistical probe.
`StatProbe` | `clone()`
`String` | `getName()` Returns the name associated with this probe, or `null` if no name was specified upon construction.
`abstract void` | `init()` Initializes the statistical collector.
`boolean` | `isBroadcasting()` Determines if this statistical probe is broadcasting observations to registered observers.
`boolean` | `isCollecting()` Determines if this statistical probe is collecting values.
`double` | `max()` Returns the largest value taken by the variable since the last initialization of this probe.
`double` | `min()` Returns the smallest value taken by the variable since the last initialization of this probe.
`void` | `notifyListeners(double x)` Notifies the observation `x` to all registered observers if broadcasting is ON.
`void` | `removeObservationListener(ObservationListener l)` Removes the observation listener `l` from the list of observers of this statistical probe.
`abstract String` | `report()` Returns a string containing a report for this statistical collector.
`static String` | `report(String globalName, Iterable<? extends StatProbe> probes)` Equivalent to `report`, except that `probes` is an `Iterable` object instead of an array.
`static String` | `report(String globalName, StatProbe[] probes)` Formats short reports for each statistical probe in the array `probes` while aligning the probes' names.
`void` | `setBroadcasting(boolean b)` Instructs the probe to turn its broadcasting ON or OFF.
`void` | `setCollecting(boolean b)` Turns ON or OFF the collection of statistical observations.
`void` | `setName(String name)` Sets the name of this statistical collector to `name`.
`abstract String` | `shortReport()` Formats and returns a short, one-line report about this statistical probe.
`abstract String` | `shortReportHeader()` Returns a string containing the name of the values returned in the report strings.
`double` | `sum()` Returns the sum cumulated so far for this probe.

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()

  Initializes the statistical collector.

### setName

    public void setName(String name)

  Sets the name of this statistical collector to `name`.

### getName

    public String getName()

  Returns the name associated with this probe, or `null` if no name was specified upon construction.

  Returns:
    the name associated to this collector, or `null` if not specified

### min

    public double min()

  Returns the smallest value taken by the variable since the last initialization of this probe. This returns `Double.POSITIVE_INFINITY` if the probe was not updated since the last initialization.

  Returns:
    the smallest value taken by the collector since last initialization

### max

    public double max()

  Returns the largest value taken by the variable since the last initialization of this probe. This returns `Double.NEGATIVE_INFINITY` if the probe was not updated since the last initialization.

  Returns:
    the largest value taken by the collector since last initialization

### sum

    public double sum()

  Returns the sum cumulated so far for this probe. The meaning of this sum depends on the subclass (e.g., `Tally` or `Accumulate`). This returns 0 if the probe was not updated since the last initialization.

  Returns:
    the sum for this probe

### average

    public abstract double average()

  Returns the average for this collector. This returns `Double.NaN` if the probe was not updated since the last initialization.

  Returns:
    the average value of the collected observations

### report

    public abstract String report()

  Returns a string containing a report for this statistical collector. The contents of this report depends on the statistical probe as well as on the parameters set by the user through probe-specific methods.

  Returns:
    a report for this probe, represented as a string

### shortReport

    public abstract String shortReport()

  Formats and returns a short, one-line report about this statistical probe. This line is composed of whitespace-separated fields which must correspond to the column names given by `shortReportHeader`(). This report should not contain any end-of-line character, and does not include the name of the probe. Its contents depends on the statistical probe as well as on the parameters set by the user through probe-specific methods.

  Returns:
    the short report for the probe.

### shortReportHeader

    public abstract String shortReportHeader()

  Returns a string containing the name of the values returned in the report strings. The returned string must depend on the type of probe and on the reporting options only. It must not depend on the observations received by the probe. This can be used as header when printing several reports. For example,

                System.out.println (probe1.shortReportHeader());
                System.out.println (probe1.getName() + " " + probe1.shortReport());
                System.out.println (probe2.getName() + " " + probe2.shortReport());
                ...

  Alternatively, one can use `report` `(String,StatProbe[])` to get a report with aligned probe names.

  Returns:
    the header string for the short reports.

### report

    public static String report(String globalName,
                                StatProbe[] probes)

  Formats short reports for each statistical probe in the array `probes` while aligning the probes' names. This method first formats the given global name. It then determines the maximum length of the names of probes in the given array. The first line of the report is composed of [tex2html_wrap_inline224] + 3 spaces followed by the string returned by `shortReportHeader` called on the first probe in `probes`. Each remaining line corresponds to a statistical probe; it contains the probe's name followed by the contents returned by `shortReport`. Note that this method assumes that `probes` contains no `null` element.

  Parameters:
    `globalName` - the global name given to the formatted report.
    `probes` - the probes to include in the report.
  Returns:
    the formatted report.

### report

    public static String report(String globalName,
                                Iterable<? extends StatProbe> probes)

  Equivalent to `report`, except that `probes` is an `Iterable` object instead of an array. Of course, the iterator returned by `probes` should enumerate the statistical probes to include in the report in a consistent and sensible order.

  Parameters:
    `globalName` - the global name given to the formatted report.
    `probes` - the probes to include in the report.
  Returns:
    the formatted report.

### isBroadcasting

    public boolean isBroadcasting()

  Determines if this statistical probe is broadcasting observations to registered observers. The default is `false`.

  Returns:
    the status of broadcasting.

### setBroadcasting

    public void setBroadcasting(boolean b)

  Instructs the probe to turn its broadcasting ON or OFF. The default value is OFF.

  Warning: To avoid useless overhead and performance degradation, broadcasting should never be turned ON when there are no registered observers.

  Parameters:
    `b` - `true` to turn broadcasting ON, `false` to turn it OFF

### isCollecting

    public boolean isCollecting()

  Determines if this statistical probe is collecting values. The default is `true`.

  Returns:
    the status of statistical collecting.

### setCollecting

    public void setCollecting(boolean b)

  Turns ON or OFF the collection of statistical observations. The default value is ON. When statistical collection is turned OFF, observations added to the probe are passed to the registered observers if broadcasting is turned ON, but are not counted as observations by the probe itself.

  Parameters:
    `b` - `true` to activate statistical collection, `false` to deactivate it

### addObservationListener

    public void addObservationListener(ObservationListener l)

  Adds the observation listener `l` to the list of observers of this statistical probe.

  Parameters:
    `l` - the new observation listener.
  Throws:
    `NullPointerException` - if `l` is `null`.

### removeObservationListener

    public void removeObservationListener(ObservationListener l)

  Removes the observation listener `l` from the list of observers of this statistical probe.

  Parameters:
    `l` - the observation listener to be deleted.

### clearObservationListeners

    public void clearObservationListeners()

  Removes all observation listeners from the list of observers of this statistical probe.

### notifyListeners

    public void notifyListeners(double x)

  Notifies the observation `x` to all registered observers if broadcasting is ON. Otherwise, does nothing.

### clone

    public StatProbe clone()
                    throws CloneNotSupportedException

  Overrides:
    `clone` in class `Object`
  Throws:
    `CloneNotSupportedException`

Overview | Package | Class | Tree | Deprecated | Index | Help
| SSJ V. 2.1.1.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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