Represents a statistical collector for estimating a function of multiple means with a confidence interval based on the delta theorem. More...

Inheritance diagram for umontreal.ssj.stat.FunctionOfMultipleMeansTally:

Classes
enum	CIType

Public Member Functions
	FunctionOfMultipleMeansTally (MultivariateFunction func, int d)
	Constructs a function of multiple means tally with dimension d, and function func.
	FunctionOfMultipleMeansTally (MultivariateFunction func, String name, int d)
	Constructs a function of multiple means tally with name name, 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.
void	setName (String name)
	Sets the name of this statistical collector to name.
ListOfTalliesWithCovariance< Tally >	getListOfTallies ()
	Returns the (unmodifiable) list of tallies internally used by this object.
MultivariateFunction	getFunction ()
	Returns the function of multiple means used by this tally.
int	getDimension ()
	Returns the dimension of this tally, i.e., the size of any vector of observations.
void	add (double... x)
	).
int	numberObs ()
	Returns the number of vectors of observations given to this probe since its last initialization.
double	average ()
	Computes \(\bar{\nu}_n=g(\bar{\mathbf{X}}_n)\), an estimate of the function of means \(\nu\).
double	variance ()
	Estimates \(n\mathrm{Var}(g(\bar{\mathbf{X}}_n))\) where \(n\) is the number of vectors of observations given to this collector since the last initialization.
double	standardDeviation ()
	Returns the square root of variance.
void	confidenceIntervalDelta (double level, double[] centerAndRadius)
	Computes a confidence interval with confidence level level on.
String	formatCIDelta (double level, int d)
	Similar to confidenceIntervalDelta(double,double[]), but returns the confidence interval in a formatted string of the form "<tt>95% confidence interval for function of means: (32.431, 32.487)</tt>", using \(d\) decimal digits of accuracy.
String	formatCIDelta (double level)
	Same as `formatCIDelta(level, 3)`.
String	report ()
	Returns a string containing a formatted report on this probe.
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(double,int) ).
String	reportAndCIDelta (double level)
	Same as `reportAndCIDelta(level, 3)`.
String	shortReportHeader ()
	Returns a string containing the name of the values returned in the report strings.
String	shortReport ()
	Formats and returns a short statistical report for this function of multiple means tally.
double	getConfidenceLevel ()
	Returns the level of confidence for the intervals on the mean displayed in reports.
void	setConfidenceLevel (double level)
	Sets the level of confidence for the intervals on the mean displayed in reports.
void	setConfidenceIntervalNone ()
	Indicates that no confidence interval needs to be printed in reports formatted by report, and shortReport.
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	setShowNumberObs (boolean showNumObs)
	Determines if the number of observations must be displayed in reports.
double	min ()
	Returns Double.NaN.
double	max ()
	Returns Double.NaN.
double	sum ()
	Returns Double.NaN.
void	init ()
	Initializes the statistical collector.
FunctionOfMultipleMeansTally	clone ()
	Clones this object.
Public Member Functions inherited from umontreal.ssj.stat.StatProbe
String	getName ()
	Returns the name associated with this probe, or null if no name was specified upon construction.
boolean	isBroadcasting ()
	Determines if this statistical probe is broadcasting observations to registered observers.
void	setBroadcasting (boolean b)
	Instructs the probe to turn its broadcasting ON or OFF.
boolean	isCollecting ()
	Determines if this statistical probe is collecting values.
void	setCollecting (boolean b)
	Turns ON or OFF the collection of statistical observations.
void	addObservationListener (ObservationListener l)
	Adds the observation listener l to the list of observers of this statistical probe.
void	removeObservationListener (ObservationListener l)
	Removes the observation listener l from the list of observers of this statistical probe.
void	clearObservationListeners ()
	Removes all observation listeners from the list of observers of this statistical probe.
void	notifyListeners (double x)
	Notifies the observation x to all registered observers if broadcasting is ON.

Additional Inherited Members
Static Public Member Functions inherited from umontreal.ssj.stat.StatProbe
static String	report (String globalName, StatProbe[] probes)
	Formats short reports for each statistical probe in the array probes while aligning the probes’ names.
static String	report (String globalName, Iterable<? extends StatProbe > probes)
	Equivalent to report(String,StatProbe[]), except that probes is an Iterable object instead of an array.

Detailed Description

Represents a statistical collector for estimating a function of multiple means with a confidence interval based on the delta theorem.

[206] . Let \(\bar{\mathbf{X}}_n=(\bar{X}_{n, 0}, …, \bar{X}_{n, d-1})\) be a random vector computed by averaging vectors of observations:

\[ \bar{\mathbf{X}}_n=(1/n)\sum_{i=0}^{n-1}\mathbf{X}_i. \]

Then let \(\{\bar{\mathbf{X}}_n, n \ge0\}\) be a sequence of vectors converging to a vector \(\boldsymbol{\mu}\) when \(n\to\infty\). Then, if \(g(\bar{\mathbf{X}}_n)\) is a continuous function, it converges to \(g(\boldsymbol{\mu})\) as \(n\to\infty\).

This class collects \(\mathbf{X}\) vectors in order to compute \(g(\bar{\mathbf{X}}_n)\), to estimate \(\nu=g(\boldsymbol{\mu})\) with a confidence interval. The function \(g(\boldsymbol{\mu})\) as well as its gradient \(\nabla g(\boldsymbol{\mu})\) are defined using an implementation of umontreal.ssj.util.MultivariateFunction.

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

Definition at line 68 of file FunctionOfMultipleMeansTally.java.

Constructor & Destructor Documentation

◆ FunctionOfMultipleMeansTally() [1/3]

umontreal.ssj.stat.FunctionOfMultipleMeansTally.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.

Exceptions

NegativeArraySizeException if `d` is negative.

Definition at line 91 of file FunctionOfMultipleMeansTally.java.

◆ FunctionOfMultipleMeansTally() [2/3]

umontreal.ssj.stat.FunctionOfMultipleMeansTally.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.

Exceptions

NegativeArraySizeException if `d` is negative.

Definition at line 108 of file FunctionOfMultipleMeansTally.java.

◆ FunctionOfMultipleMeansTally() [3/3]

umontreal.ssj.stat.FunctionOfMultipleMeansTally.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.

Exceptions

NullPointerException if `ta` is `null`.

Definition at line 126 of file FunctionOfMultipleMeansTally.java.

Member Function Documentation

◆ add()

void umontreal.ssj.stat.FunctionOfMultipleMeansTally.add ( double... x )

).

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.

Exceptions

NullPointerException	if `x` is `null`.
IllegalArgumentException	if the length of `x` does not correspond to the dimension of this tally.

Definition at line 192 of file FunctionOfMultipleMeansTally.java.

◆ average()

double umontreal.ssj.stat.FunctionOfMultipleMeansTally.average ( )

Computes \(\bar{\nu}_n=g(\bar{\mathbf{X}}_n)\), an estimate of the function of means \(\nu\).

Note that if \(g(\mathbf{X})\) is non-linear, the \(\bar{\nu}_n\) estimator is biased but consistent: \(g(\bar{\mathbf{X}}_n)\to g(\boldsymbol{\mu})\) if

\(n\to\infty\).

Returns: the estimation of \(\nu\).

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 218 of file FunctionOfMultipleMeansTally.java.

◆ clone()

FunctionOfMultipleMeansTally umontreal.ssj.stat.FunctionOfMultipleMeansTally.clone ( )

Clones this object.

This clones the internal list of tallies as well as each tally in this list.

Reimplemented from umontreal.ssj.stat.StatProbe.

Reimplemented in umontreal.ssj.stat.list.lincv.FunctionOfMultipleMeansTallyWithCV.

Definition at line 585 of file FunctionOfMultipleMeansTally.java.

◆ confidenceIntervalDelta()

void umontreal.ssj.stat.FunctionOfMultipleMeansTally.confidenceIntervalDelta	(	double	level,
		double[]	centerAndRadius )

Computes a confidence interval with confidence level level on.

\(\nu=g(\boldsymbol{\mu})\), using the delta theorem [206] . 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 \(\nu\), with confidence level level, assuming that the vectors of observations given to this collector are independent and identically distributed (i.i.d.) copies of \(\mathbf{X}\), and that \(\bar{\mathbf{X}}_n\) has the \(d\)-dimensional normal distribution, which is approximately true if \(n\) is large enough. With this assumption, as \(n\to\infty\),

\[ \sqrt{n}(\bar{\mathbf{X}}_n - \boldsymbol{\mu}) \]

converges to a random vector \(\mathbf{Y}\) following the \(d\)-dimensional normal distribution with mean \(\mathbf{0}\) and covariance matrix \(\boldsymbol{\Sigma}\). According to the delta theorem,

\[ \sqrt{n}(g(\bar{\mathbf{X}}_n) - g(\boldsymbol{\mu}))\Rightarrow(\nabla g(\boldsymbol{\mu}))^{\mathsf{t}}\mathbf{Y}, \]

which follows the normal distribution with mean 0 and variance

\[ \sigma^2=(\nabla g(\boldsymbol{\mu}))^{\mathsf{t}}\boldsymbol{\Sigma}\nabla g(\boldsymbol{\mu}). \]

This variance is estimated by \(S_n^2\), which replaces \(\boldsymbol{\mu}\) by \(\bar{\mathbf{X}}_n\), and \(\boldsymbol{\Sigma}\) by a matrix of sample covariances computed by umontreal.ssj.stat.list.ListOfTallies.

The confidence interval is computed based on the statistic

\[ Z = {\sqrt{n}(g(\bar{\mathbf{X}}_n) - g(\boldsymbol{\mu}))\over{S_n}} \]

where \(n\) is the number of vectors of observations given to this collector since its last initialization, \(g(\bar{\mathbf{X}}_n) =\) average is the average of these observations, and \(S_n =\) 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.

Definition at line 357 of file FunctionOfMultipleMeansTally.java.

◆ formatCIDelta() [1/2]

String umontreal.ssj.stat.FunctionOfMultipleMeansTally.formatCIDelta ( double level )

Same as formatCIDelta(level, 3).

Definition at line 390 of file FunctionOfMultipleMeansTally.java.

◆ formatCIDelta() [2/2]

String umontreal.ssj.stat.FunctionOfMultipleMeansTally.formatCIDelta	(	double	level,
		int	d )

Similar to confidenceIntervalDelta(double,double[]), but returns the confidence interval in a formatted string of the form "<tt>95% confidence interval for function of means: (32.431, 32.487)</tt>", 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.

Definition at line 375 of file FunctionOfMultipleMeansTally.java.

◆ getConfidenceLevel()

double umontreal.ssj.stat.FunctionOfMultipleMeansTally.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)

Definition at line 501 of file FunctionOfMultipleMeansTally.java.

◆ getDimension()

int umontreal.ssj.stat.FunctionOfMultipleMeansTally.getDimension ( )

Returns the dimension of this tally, i.e., the size of any vector of observations.

Returns: the dimension of the tally.

Definition at line 169 of file FunctionOfMultipleMeansTally.java.

◆ getFunction()

MultivariateFunction umontreal.ssj.stat.FunctionOfMultipleMeansTally.getFunction ( )

Returns the function of multiple means used by this tally.

Returns: the function of multiple means.

Definition at line 159 of file FunctionOfMultipleMeansTally.java.

◆ getListOfTallies()

ListOfTalliesWithCovariance< Tally > umontreal.ssj.stat.FunctionOfMultipleMeansTally.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 umontreal.ssj.stat.Tally.add(double).

Returns: the internal list of tallies.

Definition at line 150 of file FunctionOfMultipleMeansTally.java.

◆ init()

void umontreal.ssj.stat.FunctionOfMultipleMeansTally.init ( )

Initializes the statistical collector.

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 576 of file FunctionOfMultipleMeansTally.java.

◆ max()

double umontreal.ssj.stat.FunctionOfMultipleMeansTally.max ( )

Returns Double.NaN.

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 558 of file FunctionOfMultipleMeansTally.java.

◆ min()

double umontreal.ssj.stat.FunctionOfMultipleMeansTally.min ( )

Returns Double.NaN.

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 551 of file FunctionOfMultipleMeansTally.java.

◆ numberObs()

int umontreal.ssj.stat.FunctionOfMultipleMeansTally.numberObs ( )

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

Returns: the number of collected vectors of observations.

Definition at line 206 of file FunctionOfMultipleMeansTally.java.

◆ report()

String umontreal.ssj.stat.FunctionOfMultipleMeansTally.report ( )

Returns a string containing a formatted report on this probe.

The report contains the function of averages, the standard deviation of

\(g(\mathbf{X})\), as well as the number of vectors of observations.

Returns: a statistical report formated as a string.

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 401 of file FunctionOfMultipleMeansTally.java.

◆ reportAndCIDelta() [1/2]

String umontreal.ssj.stat.FunctionOfMultipleMeansTally.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.

Definition at line 447 of file FunctionOfMultipleMeansTally.java.

◆ reportAndCIDelta() [2/2]

String umontreal.ssj.stat.FunctionOfMultipleMeansTally.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(double,int) ).

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.

Definition at line 426 of file FunctionOfMultipleMeansTally.java.

◆ setConfidenceIntervalDelta()

void umontreal.ssj.stat.FunctionOfMultipleMeansTally.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.

Definition at line 534 of file FunctionOfMultipleMeansTally.java.

◆ setConfidenceIntervalNone()

void umontreal.ssj.stat.FunctionOfMultipleMeansTally.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.

Definition at line 525 of file FunctionOfMultipleMeansTally.java.

◆ setConfidenceLevel()

void umontreal.ssj.stat.FunctionOfMultipleMeansTally.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)

Definition at line 512 of file FunctionOfMultipleMeansTally.java.

◆ setName()

void umontreal.ssj.stat.FunctionOfMultipleMeansTally.setName ( String name )

Sets the name of this statistical collector to name.

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 136 of file FunctionOfMultipleMeansTally.java.

◆ setShowNumberObs()

void umontreal.ssj.stat.FunctionOfMultipleMeansTally.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.

Definition at line 544 of file FunctionOfMultipleMeansTally.java.

◆ shortReport()

String umontreal.ssj.stat.FunctionOfMultipleMeansTally.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{\mathbf{X}}_n)\), and the standard deviation \(S_n\), 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.

Returns: the string containing the report.

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 473 of file FunctionOfMultipleMeansTally.java.

◆ shortReportHeader()

String umontreal.ssj.stat.FunctionOfMultipleMeansTally.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.

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 451 of file FunctionOfMultipleMeansTally.java.

◆ standardDeviation()

double umontreal.ssj.stat.FunctionOfMultipleMeansTally.standardDeviation ( )

Returns the square root of variance.

Returns: the standard deviation.

Definition at line 303 of file FunctionOfMultipleMeansTally.java.

◆ sum()

double umontreal.ssj.stat.FunctionOfMultipleMeansTally.sum ( )

Returns Double.NaN.

Reimplemented from umontreal.ssj.stat.StatProbe.

Definition at line 565 of file FunctionOfMultipleMeansTally.java.

◆ variance()

double umontreal.ssj.stat.FunctionOfMultipleMeansTally.variance ( )

Estimates \(n\mathrm{Var}(g(\bar{\mathbf{X}}_n))\) where \(n\) is the number of vectors of observations given to this collector since the last initialization.

Assuming that, as \(n\to\infty\),

\(\sqrt{n}(\bar{\mathbf{X}}_n - \boldsymbol{\mu})\) converges to a random vector \(\mathbf{Y}\) with mean \(\mathbf{0}\) and covariance matrix \(\boldsymbol{\Sigma}\) ( \(\boldsymbol{\Sigma}\) is also the covariance matrix of \(\mathbf{X}\)), the delta theorem [206] shows that \(\sqrt{n}(g(\bar{\mathbf{X}}_n) - g(\boldsymbol{\mu}))\Rightarrow(\nabla g(\boldsymbol{\mu}))^{\mathsf{t}}\mathbf{Y}\). As a result, \(n\mathrm{Var}[g(\bar{\mathbf{X}}_n)]=n\mathrm{Var}[g(\bar{\mathbf{X}}_n) - g(\boldsymbol{\mu})]=\mathrm{Var}[\sqrt{n}(g(\bar{\mathbf{X}}_n) - g(\boldsymbol{\mu}))]\to\mathrm{Var}[(\nabla g(\boldsymbol{\mu}))^{\mathsf{t}}\mathbf{Y}]=(\nabla g(\boldsymbol{\mu}))^{\mathsf{t}}\boldsymbol{\Sigma}\nabla g(\boldsymbol{\mu})=\sigma^2\). Here, \(\nabla g(\boldsymbol{\mu})\) is the gradient of \(g(\boldsymbol{\mu})\). This method computes

\[ S_n^2 = (\nabla g(\bar{\mathbf{X}}_n))^{\mathsf{t}}\mathbf{S}_n\nabla g(\bar{\mathbf{X}}_n), \]

where \(\mathbf{S}_n\) is the matrix of empirical covariances of \(\mathbf{X}\). When \(n\to\infty\), \(S_n^2\to\sigma^2\) if \(\mathbf{S}_n\to\boldsymbol{\Sigma}\), and \(\nabla g(\bar{\mathbf{X}}_n)\to\nabla g(\boldsymbol{\mu})\). Therefore, \(S_n^2\) is a biased but consistent estimator of \(n\mathrm{Var}(g(\bar{\mathbf{X}}_n))\).

Returns: the estimate of the variance.

Definition at line 267 of file FunctionOfMultipleMeansTally.java.

The documentation for this class was generated from the following file:

src/main/java/umontreal/ssj/stat/FunctionOfMultipleMeansTally.java

SSJ API Documentation Stochastic Simulation in Java

Classes

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ FunctionOfMultipleMeansTally() [1/3]

◆ FunctionOfMultipleMeansTally() [2/3]

◆ FunctionOfMultipleMeansTally() [3/3]

Member Function Documentation

◆ add()

◆ average()

◆ clone()

◆ confidenceIntervalDelta()

◆ formatCIDelta() [1/2]

◆ formatCIDelta() [2/2]

◆ getConfidenceLevel()

◆ getDimension()

◆ getFunction()

◆ getListOfTallies()

◆ init()

◆ max()

◆ min()

◆ numberObs()

◆ report()

◆ reportAndCIDelta() [1/2]

◆ reportAndCIDelta() [2/2]

◆ setConfidenceIntervalDelta()

◆ setConfidenceIntervalNone()

◆ setConfidenceLevel()

◆ setName()

◆ setShowNumberObs()

◆ shortReport()

◆ shortReportHeader()

◆ standardDeviation()

◆ sum()

◆ variance()