umontreal.iro.lecuyer.stat
Class Tally

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

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

TallyHistogram, TallyStore

public class Tally
extends StatProbe
implements Cloneable

This type of statistical collector takes a sequence of real-valued observations and can return the average, the variance, a confidence interval for the theoretical mean, etc. Each call to add provides a new observation. When the broadcasting to observers is activated, the method add will also pass this new information to its registered observers. This type of collector does not memorize the individual observations, but only their number, sum, sum of squares, maximum, and minimum. The subclass TallyStore offers a collector that memorizes the observations.

Constructor Summary

Tally()
Constructs a new unnamed Tally statistical probe.

Tally(String name)
Constructs a new Tally statistical probe with name name.

Method Summary

void	add(double x) Gives a new observation x to the statistical collector.
double	average() Returns the average value of the observations since the last initialization.
Tally	clone() Clones this object.
void	confidenceIntervalNormal(double level, double[] centerAndRadius) Computes a confidence interval on the mean.
void	confidenceIntervalStudent(double level, double[] centerAndRadius) Computes a confidence interval on the mean.
void	confidenceIntervalVarianceChi2(double level, double[] interval) Computes a confidence interval on the variance.
String	formatCINormal(double level) Equivalent to formatCINormal (level, 3).
String	formatCINormal(double level, int d) Similar to confidenceIntervalNormal.
String	formatCIStudent(double level) Equivalent to formatCIStudent (level, 3).
String	formatCIStudent(double level, int d) Similar to confidenceIntervalStudent.
String	formatCIVarianceChi2(double level, int d) Similar to confidenceIntervalVarianceChi2.
double	getConfidenceLevel() Returns the level of confidence for the intervals on the mean displayed in reports.
void	init() Initializes the statistical collector.
int	numberObs() Returns the number of observations given to this probe since its last initialization.
String	report() Returns a formatted string that contains a report on this probe.
String	report(double level, int d) Returns a formatted string that contains a report on this probe with a confidence interval level level using d fractional decimal digits.
String	reportAndCIStudent(double level) Same as reportAndCIStudent (level, 3).
String	reportAndCIStudent(double level, int d) Returns a formatted string that contains a report on this probe (as in report), followed by a confidence interval (as in formatCIStudent), using d fractional decimal digits.
void	setConfidenceIntervalNone() Indicates that no confidence interval needs to be printed in reports formatted by report, and shortReport.
void	setConfidenceIntervalNormal() Indicates that a confidence interval on the true mean, based on the central limit theorem, needs to be included in reports formatted by report and shortReport.
void	setConfidenceIntervalStudent() Indicates that a confidence interval on the true mean, based on the normality assumption, needs to be included in reports formatted by report and shortReport.
void	setConfidenceLevel(double level) Sets the level of confidence for the intervals on the mean displayed in reports.
void	setShowNumberObs(boolean showNumObs) Determines if the number of observations must be displayed in reports.
String	shortReport() Formats and returns a short statistical report for this tally.
String	shortReportHeader() Returns a string containing the name of the values returned in the report strings.
double	standardDeviation() Returns the sample standard deviation of the observations since the last initialization.
double	variance() Returns the sample variance of the observations since the last initialization.

Methods inherited from class umontreal.iro.lecuyer.stat.StatProbe

addObservationListener, clearObservationListeners, getName, isBroadcasting, isCollecting, max, min, notifyListeners, removeObservationListener, report, report, setBroadcasting, setCollecting, setName, sum

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Tally

public Tally()

Constructs a new unnamed Tally statistical probe.

Tally

public Tally(String name)

Constructs a new Tally statistical probe with name name.

Parameters:

name - name of the tally

Method Detail

init

public void init()

Description copied from class: StatProbe

Initializes the statistical collector.

Specified by:

init in class StatProbe

add

public void add(double x)

Gives a new observation x to the statistical collector. If broadcasting to observers is activated for this object, this method also transmits the new information to the registered observers by invoking the method notifyListeners.

Parameters:

x - observation being added to this tally

numberObs

public int numberObs()

Returns the number of observations given to this probe since its last initialization.

Returns:

the number of collected observations

average

public double average()

Returns the average value of the observations since the last initialization.

Specified by:

average in class StatProbe

Returns:

the average value of the collected observations

variance

public double variance()

Returns the sample variance of the observations since the last initialization. This returns Double.NaN if the tally contains less than two observations.

Returns:

the variance of the observations

standardDeviation

public double standardDeviation()

Returns the sample standard deviation of the observations since the last initialization. This returns Double.NaN if the tally contains less than two observations.

Returns:

the standard deviation of the observations

confidenceIntervalNormal

public void confidenceIntervalNormal(double level,
                                     double[] centerAndRadius)

Computes a confidence interval on the mean. Returns, in elements 0 and 1 of the array object centerAndRadius[], the center and half-length (radius) of a confidence interval on the true mean of the random variable X, with confidence level level, assuming that the n observations given to this collector are independent and identically distributed (i.i.d.) copies of X, and that n is large enough for the central limit theorem to hold. This confidence interval is computed based on the statistic

Z = bar(X)_n-μ/(S_{n, x}/(n)^1/2)

where n is the number of observations given to this collector since its last initialization, bar(X)_n = average() is the average of these observations, S_{n, x} = standardDeviation() is the empirical standard deviation. Under the assumption that the observations of X are i.i.d. and n is large, Z has the standard normal distribution. The confidence interval given by this method is valid only if this assumption is approximately verified.

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

centerAndRadius - array of size 2 in which are returned the center and radius of the confidence interval, respectively

confidenceIntervalStudent

public void confidenceIntervalStudent(double level,
                                      double[] centerAndRadius)

Computes a confidence interval on the mean. Returns, in elements 0 and 1 of the array object centerAndRadius[], the center and half-length (radius) of a confidence interval on the true mean of the random variable X, with confidence level level, assuming that the observations given to this collector are independent and identically distributed (i.i.d.) copies of X, and that X has the normal distribution. This confidence interval is computed based on the statistic

T = bar(X)_n-μ/(S_{n, x}/(n)^1/2)

where n is the number of observations given to this collector since its last initialization, bar(X)_n = average() is the average of these observations, S_{n, x} = standardDeviation() is the empirical standard deviation. Under the assumption that the observations of X are i.i.d. and normally distributed, T has the Student distribution with n - 1 degrees of freedom. The confidence interval given by this method is valid only if this assumption is approximately verified, or if n is large enough so that bar(X)_n is approximately normally distributed.

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

centerAndRadius - array of size 2 in which are returned the center and radius of the confidence interval, respectively

formatCINormal

public String formatCINormal(double level,
                             int d)

Similar to confidenceIntervalNormal. Returns the confidence interval in a formatted string of the form

``95% confidence interval for mean (normal): (32.431, 32.487)'',

using d fractional decimal digits.

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

d - number of fractional decimal digits

Returns:

a confidence interval formatted as a string

formatCINormal

public String formatCINormal(double level)

Equivalent to formatCINormal (level, 3).

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

Returns:

a confidence interval formatted as a string

formatCIStudent

public String formatCIStudent(double level,
                              int d)

Similar to confidenceIntervalStudent. Returns the confidence interval in a formatted string of the form

``95% confidence interval for mean (student): (32.431, 32.487)'',

using d fractional decimal digits.

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

d - number of fractional decimal digits

Returns:

a confidence interval formatted as a string

formatCIStudent

public String formatCIStudent(double level)

Equivalent to formatCIStudent (level, 3).

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

Returns:

a confidence interval formatted as a string

confidenceIntervalVarianceChi2

public void confidenceIntervalVarianceChi2(double level,
                                           double[] interval)

Computes a confidence interval on the variance. Returns, in elements 0 and 1 of array interval, the left and right boundaries [I₁, I₂] of a confidence interval on the true variance σ² of the random variable X, with confidence level level, assuming that the observations given to this collector are independent and identically distributed (i.i.d.) copies of X, and that X has the normal distribution. This confidence interval is computed based on the statistic χ²_n-1 = (n - 1)S²_n/σ² where n is the number of observations given to this collector since its last initialization, and S²_n = variance() is the empirical variance of these observations. Under the assumption that the observations of X are i.i.d. and normally distributed, χ²_n-1 has the chi-square distribution with n - 1 degrees of freedom. Given the level = 1 - α, one has P[χ²_n-1 < x₁] = P[χ²_n-1 > x₂] = α/2 and [I₁, I₂] = [(n - 1)S²_n/x₂, (n - 1)S²_n/x₁].

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

interval - array of size 2 in which are returned the left and right boundaries of the confidence interval, respectively

formatCIVarianceChi2

public String formatCIVarianceChi2(double level,
                                   int d)

Similar to confidenceIntervalVarianceChi2. Returns the confidence interval in a formatted string of the form

``95.0% confidence interval for variance (chi2): ( 510.642, 519.673 )'',

using d fractional decimal digits.

Parameters:

level - desired probability that the (random) confidence interval covers the true variance

d - number of fractional decimal digits

Returns:

a confidence interval formatted as a string

report

public String report()

Returns a formatted string that contains a report on this probe.

Specified by:

report in class StatProbe

Returns:

a statistical report formatted as a string

report

public String report(double level,
                     int d)

Returns a formatted string that contains a report on this probe with a confidence interval level level using d fractional decimal digits.

Parameters:

level - desired probability that the confidence interval covers the true mean

d - number of fractional decimal digits

Returns:

a statistical report formatted as a string

shortReportHeader

public String shortReportHeader()

Description copied from class: StatProbe

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.

Specified by:

shortReportHeader in class StatProbe

Returns:

the header string for the short reports.

shortReport

public String shortReport()

Formats and returns a short statistical report for this tally. The returned single-line report contains the minimum value, the maximum value, the average, and the standard deviation, in that order, separated by three spaces. If the number of observations is shown in the short report, a column containing the number of observations in this tally is added.

Specified by:

shortReport in class StatProbe

Returns:

the string containing the report.

reportAndCIStudent

public String reportAndCIStudent(double level,
                                 int d)

Returns a formatted string that contains a report on this probe (as in report), followed by a confidence interval (as in formatCIStudent), using d fractional decimal digits.

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

d - number of fractional decimal digits

Returns:

a statistical report with a confidence interval, formatted as a string

reportAndCIStudent

public String reportAndCIStudent(double level)

Same as reportAndCIStudent (level, 3).

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

Returns:

a statistical report with a confidence interval, formatted as a string

getConfidenceLevel

public double getConfidenceLevel()

Returns the level of confidence for the intervals on the mean displayed in reports. The default confidence level is 0.95.

Returns:

desired probability that the (random) confidence interval covers the true mean (a constant)

setConfidenceLevel

public void setConfidenceLevel(double level)

Sets the level of confidence for the intervals on the mean displayed in reports.

Parameters:

level - desired probability that the (random) confidence interval covers the true mean (a constant)

setConfidenceIntervalNone

public void setConfidenceIntervalNone()

Indicates that no confidence interval needs to be printed in reports formatted by report, and shortReport. This restores the default behavior of the reporting system.

setConfidenceIntervalNormal

public void setConfidenceIntervalNormal()

Indicates that a confidence interval on the true mean, based on the central limit theorem, needs to be included in reports formatted by report and shortReport. The confidence interval is formatted using formatCINormal.

setConfidenceIntervalStudent

public void setConfidenceIntervalStudent()

Indicates that a confidence interval on the true mean, based on the normality assumption, needs to be included in reports formatted by report and shortReport. The confidence interval is formatted using formatCIStudent.

setShowNumberObs

public void setShowNumberObs(boolean showNumObs)

Determines if the number of observations must be displayed in reports. By default, the number of observations is displayed.

Parameters:

showNumObs - the value of the indicator.

clone

public Tally clone()

Clones this object.

Overrides:

clone in class StatProbe