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

Inheritance diagram for FunctionOfMultipleMeansTally:

[legend]

Collaboration diagram for FunctionOfMultipleMeansTally:

[legend]

Public Member Functions
	FunctionOfMultipleMeansTally (MultivariateFunction func, int d)
	Constructs a function of multiple means tally with dimension `d`, and function `func`. More...

	FunctionOfMultipleMeansTally (MultivariateFunction func, String name, int d)
	Constructs a function of multiple means tally with name `name`, dimension `d`, and function `func`. More...

	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. More...

void	setName (String name)

ListOfTalliesWithCovariance< Tally >	getListOfTallies ()
	Returns the (unmodifiable) list of tallies internally used by this object. More...

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

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

void	add (double... x)
	). More...

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

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

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. More...

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

void	confidenceIntervalDelta (double level, double[] centerAndRadius)
	Computes a confidence interval with confidence level `level` on \(\nu=g(\boldsymbol{\mu})\), using the delta theorem [214] . More...

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. More...

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

String	report ()
	Returns a string containing a formatted report on this probe. More...

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) ). More...

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

String	shortReportHeader ()

String	shortReport ()
	Formats and returns a short statistical report for this function of multiple means tally. More...

double	getConfidenceLevel ()
	Returns the level of confidence for the intervals on the mean displayed in reports. More...

void	setConfidenceLevel (double level)
	Sets the level of confidence for the intervals on the mean displayed in reports. More...

void	setConfidenceIntervalNone ()
	Indicates that no confidence interval needs to be printed in reports formatted by report, and shortReport. More...

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. More...

void	setShowNumberObs (boolean showNumObs)
	Determines if the number of observations must be displayed in reports. More...

double	min ()
	Returns `Double.NaN`.

double	max ()
	Returns `Double.NaN`.

double	sum ()
	Returns `Double.NaN`.

void	init ()

FunctionOfMultipleMeansTally	clone ()
	Clones this object. More...

Public Member Functions inherited from StatProbe
abstract void	init ()
	Initializes the statistical collector.

void	setName (String name)
	Sets the name of this statistical collector to `name`.

String	getName ()
	Returns the name associated with this probe, or `null` if no name was specified upon construction. More...

double	min ()
	Returns the smallest value taken by the variable since the last initialization of this probe. More...

double	max ()
	Returns the largest value taken by the variable since the last initialization of this probe. More...

double	sum ()
	Returns the sum cumulated so far for this probe. More...

abstract double	average ()
	Returns the average for this collector. More...

abstract String	report ()
	Returns a string containing a report for this statistical collector. More...

abstract String	shortReport ()
	Formats and returns a short, one-line report about this statistical probe. More...

abstract String	shortReportHeader ()
	Returns a string containing the name of the values returned in the report strings. More...

boolean	isBroadcasting ()
	Determines if this statistical probe is broadcasting observations to registered observers. More...

void	setBroadcasting (boolean b)
	Instructs the probe to turn its broadcasting ON or OFF. More...

boolean	isCollecting ()
	Determines if this statistical probe is collecting values. More...

void	setCollecting (boolean b)
	Turns ON or OFF the collection of statistical observations. More...

void	addObservationListener (ObservationListener l)
	Adds the observation listener `l` to the list of observers of this statistical probe. More...

void	removeObservationListener (ObservationListener l)
	Removes the observation listener `l` from the list of observers of this statistical probe. More...

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. More...

StatProbe	clone () throws CloneNotSupportedException

Protected Attributes
MultivariateFunction	func

CIType	confidenceInterval = CIType.CI_NONE

double	level = 0.95

Protected Attributes inherited from StatProbe
String	name

double	maxValue

double	minValue

double	sumValue

boolean	collect = true

boolean	broadcast = false

boolean	showNobs = true

Additional Inherited Members
Static Public Member Functions inherited from StatProbe
static String	report (String globalName, StatProbe[] probes)
	Formats short reports for each statistical probe in the array `probes` while aligning the probes’ names. More...

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. More...

Detailed Description

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

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.

Constructor & Destructor Documentation

◆ FunctionOfMultipleMeansTally() [1/3]

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.

◆ FunctionOfMultipleMeansTally() [2/3]

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.

◆ FunctionOfMultipleMeansTally() [3/3]

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.

Member Function Documentation

◆ add()

void 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.

◆ average()

double 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\).

◆ clone()

FunctionOfMultipleMeansTally clone ( )

Clones this object.

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

◆ confidenceIntervalDelta()

void confidenceIntervalDelta	(	double	level,
		double []	centerAndRadius
	)

Computes a confidence interval with confidence level level on \(\nu=g(\boldsymbol{\mu})\), using the delta theorem [214] .

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.

◆ formatCIDelta()

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.

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.

◆ getConfidenceLevel()

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)

◆ getDimension()

int getDimension ( )

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

Returns: the dimension of the tally.

◆ getFunction()

MultivariateFunction getFunction ( )

Returns the function of multiple means used by this tally.

Returns: the function of multiple means.

◆ getListOfTallies()

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

Returns: the internal list of tallies.

◆ numberObs()

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.

◆ report()

String 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.

◆ reportAndCIDelta() [1/2]

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

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() [2/2]

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.

◆ setConfidenceIntervalDelta()

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.

◆ setConfidenceIntervalNone()

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.

◆ setConfidenceLevel()

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)

◆ setShowNumberObs()

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.

◆ shortReport()

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{\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.

◆ standardDeviation()

double standardDeviation ( )

Returns the square root of variance.

Returns: the standard deviation.

◆ variance()

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.

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 [214] 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.

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

FunctionOfMultipleMeansTally.java

Public Member Functions

Protected Attributes

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

◆ getConfidenceLevel()

◆ getDimension()

◆ getFunction()

◆ getListOfTallies()

◆ numberObs()

◆ report()

◆ reportAndCIDelta() [1/2]

◆ reportAndCIDelta() [2/2]

◆ setConfidenceIntervalDelta()

◆ setConfidenceIntervalNone()

◆ setConfidenceLevel()

◆ setShowNumberObs()

◆ shortReport()

◆ standardDeviation()

◆ variance()