SSJ
V. labo.

umontreal.iro.lecuyer.stat
Class FunctionOfMultipleMeansTally

java.lang.Object
  extended by umontreal.iro.lecuyer.stat.StatProbe
      extended by umontreal.iro.lecuyer.stat.FunctionOfMultipleMeansTally
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
FunctionOfMultipleMeansTallyWithCV

public class FunctionOfMultipleMeansTally
extends StatProbe
implements Cloneable

Represents a statistical collector for estimating a function of multiple means with a confidence interval based on the delta theorem. Let bar(X)n = (bar(X)n, 0,…, bar(X)n, d-1) be a random vector computed by averaging vectors of observations:

bar(X)n = (1/n)∑i=0n-1Xi.

Then let {bar(X)n, n >= 0} be a sequence of vectors converging to a vector μ when n -> ∞. Then, if g(bar(X)n) is a continuous function, it converges to g(μ) as n -> ∞.

This class collects X vectors in order to compute g(bar(X)n), to estimate ν = g(μ) with a confidence interval. The function g(μ) as well as its gradient g(μ) are defined using an implementation of MultivariateFunction.

This class defines the methods add(double[]) for adding vectors of observations to the tally, average() for estimating ν, and confidenceIntervalDelta(double, double[]) for applying the delta theorem to compute a confidence interval on ν. It uses an internal ListOfTalliesWithCovariance instance to manage the tallies and covariance estimation.


Constructor Summary
FunctionOfMultipleMeansTally(MultivariateFunction func, int d)
          Constructs a function of multiple means tally with dimension d, and function func.
FunctionOfMultipleMeansTally(MultivariateFunction func, ListOfTalliesWithCovariance<Tally> ta)
          Constructs a function of multiple means tally using the function func and the list of tallies ta for observation management and covariance estimation.
FunctionOfMultipleMeansTally(MultivariateFunction func, String name, int d)
          Constructs a function of multiple means tally with name name, dimension d, and function func.
 
Method Summary
 void add(double... x)
          Adds a new vector x = (X0,…, Xd-1) of observations to this tally.
 double average()
          Computes bar(ν)n = g(bar(X)n), an estimate of the function of means ν.
 FunctionOfMultipleMeansTally clone()
          Clones this object.
 void confidenceIntervalDelta(double level, double[] centerAndRadius)
          Computes a confidence interval with confidence level level on ν = g(μ), using the delta theorem.
 String formatCIDelta(double level)
          Same as formatCIDelta (level, 3).
 String formatCIDelta(double level, int d)
          Similar to confidenceIntervalDelta, but returns the confidence interval in a formatted string of the form ``95% confidence interval for function of means: (32.431, 32.487)'', using d decimal digits of accuracy.
 double getConfidenceLevel()
          Returns the level of confidence for the intervals on the mean displayed in reports.
 int getDimension()
          Returns the dimension of this tally, i.e., the size of any vector of observations.
 MultivariateFunction getFunction()
          Returns the function of multiple means used by this tally.
 ListOfTalliesWithCovariance<Tally> getListOfTallies()
          Returns the (unmodifiable) list of tallies internally used by this object.
 void init()
          Initializes the statistical collector.
 double max()
          Returns Double.NaN.
 double min()
          Returns Double.NaN.
 int numberObs()
          Returns the number of vectors of observations given to this probe since its last initialization.
 String report()
          Returns a string containing a formatted report on this probe.
 String reportAndCIDelta(double level)
          Same as reportAndCIDelta (level, 3).
 String reportAndCIDelta(double level, int d)
          Returns a string containing a formatted report on this probe (as in report), followed by a confidence interval (as in formatCIDelta).
 void setConfidenceIntervalDelta()
          Indicates that a confidence interval on the true mean, based on the delta and central limit theorems, needs to be included in reports formatted by report, and shortReport.
 void setConfidenceIntervalNone()
          Indicates that no confidence interval needs to be printed 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 setName(String name)
          Sets the name of this statistical collector to name.
 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 function of multiple means tally.
 String shortReportHeader()
          Returns a string containing the name of the values returned in the report strings.
 double standardDeviation()
          Returns the square root of variance.
 double sum()
          Returns Double.NaN.
 double variance()
          Estimates nVar(g(bar(X)n)) where n is the number of vectors of observations given to this collector since the last initialization.
 
Methods inherited from class umontreal.iro.lecuyer.stat.StatProbe
addObservationListener, clearObservationListeners, getName, isBroadcasting, isCollecting, notifyListeners, removeObservationListener, report, report, setBroadcasting, setCollecting
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FunctionOfMultipleMeansTally

public FunctionOfMultipleMeansTally(MultivariateFunction func,
                                    int d)
Constructs a function of multiple means tally with dimension d, and function func.

Parameters:
func - the function being computed.
d - the dimension of the tally.
Throws:
NegativeArraySizeException - if d is negative.

FunctionOfMultipleMeansTally

public FunctionOfMultipleMeansTally(MultivariateFunction func,
                                    String name,
                                    int d)
Constructs a function of multiple means tally with name name, dimension d, and function func. The given name is also used as a global name for the internal list of tallies.

Parameters:
func - the function being computed.
name - the name of the tally.
d - the dimension of the tally.
Throws:
NegativeArraySizeException - if d is negative.

FunctionOfMultipleMeansTally

public FunctionOfMultipleMeansTally(MultivariateFunction func,
                                    ListOfTalliesWithCovariance<Tally> ta)
Constructs a function of multiple means tally using the function func and the list of tallies ta for observation management and covariance estimation.

Parameters:
func - the function being computed.
ta - the list of tallies to be used.
Throws:
NullPointerException - if ta is null.
Method Detail

setName

public void setName(String name)
Description copied from class: StatProbe
Sets the name of this statistical collector to name.

Overrides:
setName in class StatProbe

getListOfTallies

public ListOfTalliesWithCovariance<Tally> getListOfTallies()
Returns the (unmodifiable) list of tallies internally used by this object. Note: for the sample covariances to be consistent, each tally in the returned list must always have the same number of observations. Therefore, it is not recommended to manually add observations to the individual tallies, by using add.

Returns:
the internal list of tallies.

getFunction

public MultivariateFunction getFunction()
Returns the function of multiple means used by this tally.

Returns:
the function of multiple means.

getDimension

public int getDimension()
Returns the dimension of this tally, i.e., the size of any vector of observations.

Returns:
the dimension of the tally.

add

public void add(double... x)
Adds a new vector x = (X0,…, Xd-1) of observations to this tally. If statistical collecting is turned ON, this adds the vector to the internal list of tallies. This method takes a variable number of arguments to allow one to pass the components of X without creating an array when the dimension is fixed. However, one can also give an array to this method. For example, if the computed function is a ratio, for estimating a ratio of two expectations, d = 2 and the call add(x, y) is equivalent to add(new double[] {x, y}). On the other hand, if the function is a sum or a product of d terms, the dimension is not constant in general, e.g., it can depend on an input parameter. In this case, one must pass an array to this method, and could also call the add method of the internal list of tallies directly.

Parameters:
x - the vector of observations being added.
Throws:
NullPointerException - if x is null.
IllegalArgumentException - if the length of x does not correspond to the dimension of this tally.

numberObs

public int numberObs()
Returns the number of vectors of observations given to this probe since its last initialization.

Returns:
the number of collected vectors of observations.

average

public double average()
Computes bar(ν)n = g(bar(X)n), an estimate of the function of means ν. Note that if g(X) is non-linear, the bar(ν)n estimator is biased but consistent: g(bar(X)n) -> g(μ) if n -> ∞.

Specified by:
average in class StatProbe
Returns:
the estimation of ν.

variance

public double variance()
Estimates nVar(g(bar(X)n)) where n is the number of vectors of observations given to this collector since the last initialization. Assuming that, as n -> ∞, (n)1/2(bar(X)n - μ) converges to a random vector Y with mean 0 and covariance matrix Σ ( Σ is also the covariance matrix of X), the delta theorem shows that (n)1/2(g(bar(X)n) - g(μ))⇒(∇g(μ))tY. As a result, nVar[g(bar(X)n)] = nVar[g(bar(X)n) - g(μ)] = Var[(n)1/2(g(bar(X)n) - g(μ))] -> Var[(∇g(μ))tY] = (∇g(μ))tΣg(μ) = σ2. Here, g(μ) is the gradient of g(μ). This method computes

Sn2 = (∇g(bar(X)n))tSng(bar(X)n),

where Sn is the matrix of empirical covariances of X. When n -> ∞, Sn2 -> σ2 if Sn -> Σ, and g(bar(X)n) -> ∇g(μ). Therefore, Sn2 is a biased but consistent estimator of nVar(g(bar(X)n)).

Returns:
the estimate of the variance.

standardDeviation

public double standardDeviation()
Returns the square root of variance.

Returns:
the standard deviation.

confidenceIntervalDelta

public void confidenceIntervalDelta(double level,
                                    double[] centerAndRadius)
Computes a confidence interval with confidence level level on ν = g(μ), using the delta theorem. Returns, in elements 0 and 1 of the array object centerAndRadius[], the center and half-length (radius) of a confidence interval on the true function of means ν, with confidence level level, assuming that the vectors of observations given to this collector are independent and identically distributed (i.i.d.) copies of X, and that bar(X)n has the d-dimensional normal distribution, which is approximately true if n is large enough. With this assumption, as n -> ∞,

(n)1/2(bar(X)n - μ)

converges to a random vector Y following the d-dimensional normal distribution with mean 0 and covariance matrix Σ. According to the delta theorem,

(n)1/2(g(bar(X)n) - g(μ))⇒(∇g(μ))tY,

which follows the normal distribution with mean 0 and variance

σ2 = (∇g(μ))tΣg(μ).

This variance is estimated by Sn2, which replaces μ by bar(X)n, and Σ by a matrix of sample covariances computed by ListOfTallies.

The confidence interval is computed based on the statistic

Z = (n)1/2(g(bar(X)n)-g(μ))/(Sn)

where n is the number of vectors of observations given to this collector since its last initialization, g(bar(X)n) = average is the average of these observations, and Sn = standardDeviation is the standard deviation. Under the previous assumptions, Z has the normal distribution with mean 0 and variance 1. The confidence interval given by this method is valid only if these assumptions are approximately verified.

Parameters:
level - desired probability that the (random) confidence interval covers the true function of means (a constant).
centerAndRadius - array of size 2 in which are returned the center and radius of the confidence interval, respectively.

formatCIDelta

public String formatCIDelta(double level,
                            int d)
Similar to confidenceIntervalDelta, but returns the confidence interval in a formatted string of the form ``95% confidence interval for function of means: (32.431, 32.487)'', using d decimal digits of accuracy.

Parameters:
level - desired probability that the confidence interval covers the true function of means.
d - the number of decimal digits of accuracy.
Returns:
a confidence interval formatted as a string.

formatCIDelta

public String formatCIDelta(double level)
Same as formatCIDelta (level, 3).


report

public String report()
Returns a string containing a formatted report on this probe. The report contains the function of averages, the standard deviation of g(X), as well as the number of vectors of observations.

Specified by:
report in class StatProbe
Returns:
a statistical report formated as a string.

reportAndCIDelta

public String reportAndCIDelta(double level,
                               int d)
Returns a string containing a formatted report on this probe (as in report), followed by a confidence interval (as in formatCIDelta).

Parameters:
level - desired probability that the confidence interval covers the true mean.
d - the number of decimal digits of accuracy.
Returns:
statistical report with a confidence interval, formatted as a string.

reportAndCIDelta

public String reportAndCIDelta(double level)
Same as reportAndCIDelta (level, 3).

Parameters:
level - desired probability that the confidence interval covers the true mean.
Returns:
statistical report with a confidence interval, 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 function of multiple means tally. The returned single-line report contains the function of averages g(bar(X)n), and the standard deviation Sn, in that order, separated by three spaces. If the number of observations is included in short reports, a column containing the number of observations is added.

Specified by:
shortReport in class StatProbe
Returns:
the string containing the report.

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.


setConfidenceIntervalDelta

public void setConfidenceIntervalDelta()
Indicates that a confidence interval on the true mean, based on the delta and central limit theorems, needs to be included in reports formatted by report, and shortReport. The confidence interval is formatted using formatCIDelta.


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.

min

public double min()
Returns Double.NaN.

Overrides:
min in class StatProbe
Returns:
the smallest value taken by the collector since last initialization

max

public double max()
Returns Double.NaN.

Overrides:
max in class StatProbe
Returns:
the largest value taken by the collector since last initialization

sum

public double sum()
Returns Double.NaN.

Overrides:
sum in class StatProbe
Returns:
the sum for this probe

init

public void init()
Description copied from class: StatProbe
Initializes the statistical collector.

Specified by:
init in class StatProbe

clone

public FunctionOfMultipleMeansTally clone()
Clones this object. This clones the internal list of tallies as well as each tally in this list.

Overrides:
clone in class StatProbe

SSJ
V. labo.

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