SSJ
V. labo.

umontreal.iro.lecuyer.stat.list.lincv
Class ListOfTalliesWithCV<E extends Tally>

java.lang.Object
  extended by umontreal.iro.lecuyer.stat.list.ListOfStatProbes<E>
      extended by umontreal.iro.lecuyer.stat.list.ListOfTallies<E>
          extended by umontreal.iro.lecuyer.stat.list.ListOfTalliesWithCovariance<E>
              extended by umontreal.iro.lecuyer.stat.list.lincv.ListOfTalliesWithCV<E>
All Implemented Interfaces:
Cloneable, Iterable<E>, Collection<E>, List<E>, RandomAccess

public class ListOfTalliesWithCV<E extends Tally>
extends ListOfTalliesWithCovariance<E>

Represents a list of tallies with control variables that inherits the functionalities of a list of tallies, and accepts vectors of length p + q. The first p tallies in the list correspond to X while the q last tallies correspond to C. Methods are provided for adding observations with control variables, and estimating the β* matrix from the sample covariances. Convenience methods are also provided for the common cases where q = 1 and p = 1.

During simulation or pilot runs, one uses an add method to add observations with the associated values of the control variables. After the vectors of observations (and controls) are collected, one can obtain an estimate of β*, by using estimateBeta. One can also set β to an arbitrary matrix.

Before obtaining results with control variables, it is important to set the expected values of the controls, by using setExpectedValues. After E[C] is set, methods are then available to get the controlled average, and the controlled covariance matrix. One can also compute a confidence interval on a component Xi of X taking the control variables into account.

The β* matrix can be estimated using pilot runs. In this context, if the list of tallies is reset, the values of β and E[C] are retained. Observations generated from production runs can then be added to the list of tallies, and the controlled average can be computed.

The following pseudocode illustrates how q control variables can be used with a p-dimensional vector, the value of E[C] being stored in expControls.


   ListOfTalliesWithCV<Tally> list = ListOfTalliesWithCV.createWithTally (p, q);
   list.setExpectedValues (expControls);
   // Choose between NO PILOT RUNS or PILOT RUNS

   NO PILOT RUNS {
      // Make production runs and use list.add to add (X, C) vectors.
      list.estimateBeta();  // Biased consistent estimator of the beta matrix
   }
   
   PILOT RUNS {
      // Make pilot runs and use list.add to add (X, C) vectors.
      list.estimateBeta();   // Unbiased estimator of the beta matrix
      list.init();
      // Make production runs and use list.add to add (X, C) vectors.
   }

   // Call list.averageWithCV, list.covarianceWithCV, etc.


Constructor Summary
ListOfTalliesWithCV()
          Constructs a new empty list of tallies with no control variable.
ListOfTalliesWithCV(String name)
          Constructs a new empty list of tallies with no control variable and name name.
 
Method Summary
 void add(double[] x, double[] c)
          Adds a new observation (X, C) to this list of tallies.
 void add(double x, double c)
          Variant of the add that can be used when p = q = 1.
 void add(double x, double[] c)
          Variant of the add method that can be used when there is only one output variable.
 void averageC(double[] a)
          Fills the given array with the averages of the control variables.
 void averageWithCV(double[] a)
          Fills the given array with the controlled averages.
 double averageWithCV(int i)
          Returns the average of the ith component of XC, denoted XC, i.
 void averageX(double[] a)
          Fills the given array with the averages without control variables.
 ListOfTalliesWithCV<E> clone()
          Clones this object.
 void confidenceIntervalStudentWithCV(int i, double level, double[] centerAndRadius)
          Computes a confidence interval for the ith component of XC.
 void correlationC(DoubleMatrix2D c)
          Fills c with the sample correlation matrix of C.
 void correlationCX(DoubleMatrix2D c)
          Fills c with the sample correlation matrix of C and X.
 void correlationX(DoubleMatrix2D c)
          Fills c with the sample correlation matrix of X.
 void covarianceC(DoubleMatrix2D c)
          Fills c with the sample covariance matrix of C.
 void covarianceCX(DoubleMatrix2D c)
          Fills c with the sample covariance matrix of C and X.
 void covarianceWithCV(DoubleMatrix2D covCV)
          Computes the sample covariance of XC by replacing ΣX, ΣC, and ΣCX with the corresponding matrices of empirical covariances.
 double covarianceWithCV(int i, int j)
          Computes the covariance between component i and j of XC.
 void covarianceX(DoubleMatrix2D c)
          Fills c with the sample covariance matrix of X.
static ListOfTalliesWithCV<Tally> createWithTally(int p, int q)
          This factory method constructs and returns a list of tallies with p+q new instances of Tally, q being the number of control variables.
static ListOfTalliesWithCV<TallyStore> createWithTallyStore(int p, int q)
          This factory method constructs and returns a list of tallies with p+q new instances of TallyStore, q being the number of control variables.
 void estimateBeta()
          Estimates the β* matrix from the observations currently in this list of tallies.
 DoubleMatrix2D getBeta()
          Returns the current matrix β.
 double getExpectedValue(int i)
          Gets the expected value of the ith control variable.
 double[] getExpectedValues()
          Returns E[C], the expected value of the vector of control variables.
 int getNumControlVariables()
          Returns the number q of control variables.
 void init()
          Initializes this list of statistical probes by calling init on each element.
 void setBeta(DoubleMatrix2D beta)
          Sets the β matrix to beta.
 void setExpectedValue(int i, double e)
          Sets the expected value of the ith control variable to e.
 void setExpectedValues(double[] exp)
          Sets E[C] to exp.
 void setNumControlVariables(int q)
          Sets the number of control variables to q.
 int sizeWithoutCV()
          Returns the size of this list excluding the control variables.
 void standardDeviationWithCV(double[] std)
          Fills the given array with the square root of the variance of each component of XC.
 void varianceWithCV(double[] v)
          Fills the given array with the variance of each component of XC.
 
Methods inherited from class umontreal.iro.lecuyer.stat.list.ListOfTalliesWithCovariance
add, add, covariance, createWithTally, createWithTallyStore
 
Methods inherited from class umontreal.iro.lecuyer.stat.list.ListOfTallies
areAllNumberObsEqual, average, correlation, correlation, covariance, numberObs, standardDeviation, variance
 
Methods inherited from class umontreal.iro.lecuyer.stat.list.ListOfStatProbes
add, add, addAll, addAll, addArrayOfObservationListener, clear, clearArrayOfObservationListeners, contains, containsAll, equals, get, getName, hashCode, indexOf, isBroadcasting, isCollecting, isEmpty, isModifiable, iterator, lastIndexOf, listIterator, listIterator, notifyListeners, remove, remove, removeAll, removeArrayOfObservationListener, report, retainAll, set, setBroadcasting, setCollecting, setName, setUnmodifiable, size, subList, sum, toArray, toArray
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ListOfTalliesWithCV

public ListOfTalliesWithCV()
Constructs a new empty list of tallies with no control variable. After calling this constructor, one must fill the list with tallies, call setNumControlVariables, and init.


ListOfTalliesWithCV

public ListOfTalliesWithCV(String name)
Constructs a new empty list of tallies with no control variable and name name. After calling this constructor, one must fill the list with tallies, call setNumControlVariables, and init.

Parameters:
name - the name of the list.
Method Detail

createWithTally

public static ListOfTalliesWithCV<Tally> createWithTally(int p,
                                                         int q)
This factory method constructs and returns a list of tallies with p+q new instances of Tally, q being the number of control variables.

Parameters:
p - the value of p.
q - the value of q.
Returns:
the created list.

createWithTallyStore

public static ListOfTalliesWithCV<TallyStore> createWithTallyStore(int p,
                                                                   int q)
This factory method constructs and returns a list of tallies with p+q new instances of TallyStore, q being the number of control variables.

Parameters:
p - the value of p.
q - the value of q.
Returns:
the created list.

init

public void init()
Description copied from class: ListOfStatProbes
Initializes this list of statistical probes by calling init on each element.

Overrides:
init in class ListOfTalliesWithCovariance<E extends Tally>

getBeta

public DoubleMatrix2D getBeta()
Returns the current matrix β. By default, this matrix is filled with 0's.

Returns:
the β matrix.

setBeta

public void setBeta(DoubleMatrix2D beta)
Sets the β matrix to beta. The given matrix must be q×p, or an exception is thrown.

Parameters:
beta - the new β matrix.

getExpectedValue

public double getExpectedValue(int i)
Gets the expected value of the ith control variable. By default, this is set to 0.

Parameters:
i - the index of the control variable.
Returns:
the queried expectation.

setExpectedValue

public void setExpectedValue(int i,
                             double e)
Sets the expected value of the ith control variable to e.

Parameters:
i - the index of the control variable.
e - the new value of the expectation.

getExpectedValues

public double[] getExpectedValues()
Returns E[C], the expected value of the vector of control variables.

Returns:
the expected values of the control variables.

setExpectedValues

public void setExpectedValues(double[] exp)
Sets E[C] to exp. The length of the given array must be q, or an exception is thrown.

Parameters:
exp - the new expected values for control variables.

sizeWithoutCV

public int sizeWithoutCV()
Returns the size of this list excluding the control variables. This corresponds to the number of output variables p.

Returns:
the size of this list excluding control variables.

getNumControlVariables

public int getNumControlVariables()
Returns the number q of control variables.

Returns:
the number of control variables.

setNumControlVariables

public void setNumControlVariables(int q)
Sets the number of control variables to q. The new value of q must not be negative or exceed size(). This method throws an exception if it is called after init.

Parameters:
q - the new number of control variables.

correlationX

public void correlationX(DoubleMatrix2D c)
Fills c with the sample correlation matrix of X.

Parameters:
c - the p×p matrix filled with correlations.

covarianceX

public void covarianceX(DoubleMatrix2D c)
Fills c with the sample covariance matrix of X.

Parameters:
c - the p×p matrix filled with covariances.

correlationC

public void correlationC(DoubleMatrix2D c)
Fills c with the sample correlation matrix of C.

Parameters:
c - the q×q matrix filled with correlations.

covarianceC

public void covarianceC(DoubleMatrix2D c)
Fills c with the sample covariance matrix of C.

Parameters:
c - the q×q matrix filled with covariances.

correlationCX

public void correlationCX(DoubleMatrix2D c)
Fills c with the sample correlation matrix of C and X.

Parameters:
c - the q×p matrix filled with correlations.

covarianceCX

public void covarianceCX(DoubleMatrix2D c)
Fills c with the sample covariance matrix of C and X.

Parameters:
c - the q×p matrix filled with covariances.

add

public void add(double[] x,
                double[] c)
Adds a new observation (X, C) to this list of tallies. The array x contains the value for X, while c contains the value of C.

Parameters:
x - the value of X.
c - the value of C.

add

public void add(double x,
                double[] c)
Variant of the add method that can be used when there is only one output variable.

Parameters:
x - the output variable.
c - the vector of control variables.

add

public void add(double x,
                double c)
Variant of the add that can be used when p = q = 1.

Parameters:
x - the output variable.
c - the control variable.

averageWithCV

public double averageWithCV(int i)
Returns the average of the ith component of XC, denoted XC, i. This corresponds to

XC, i = Xi - (β⋅, i)t(C - E[C])

where β⋅, i is the ith column of the β matrix.

Parameters:
i - the index of the output variable.
Returns:
the controlled average.

covarianceWithCV

public void covarianceWithCV(DoubleMatrix2D covCV)
Computes the sample covariance of XC by replacing ΣX, ΣC, and ΣCX with the corresponding matrices of empirical covariances. These are obtained by calling covarianceX, covarianceC, and covarianceCX, respectively. This gives an estimate of

Cov(XC) = ΣX + βtΣCβ -2βtΣCX.

Parameters:
covCV - the p×p matrix that will be filled with covariances.

covarianceWithCV

public double covarianceWithCV(int i,
                               int j)
Computes the covariance between component i and j of XC. This is given by

Cov(XC, i, XC, j) = Cov(Xi, Xj) + (β⋅, i)tΣCβ⋅, j - (ΣCX,⋅, i)tβ⋅, j - (ΣCX,⋅, j)tβ⋅, i.

Parameters:
i - the index of the first component.
j - the index of the second component.
Returns:
the covariance.

averageWithCV

public void averageWithCV(double[] a)
Fills the given array with the controlled averages.


averageX

public void averageX(double[] a)
Fills the given array with the averages without control variables.

Parameters:
a - the array to be filled with averages.

averageC

public void averageC(double[] a)
Fills the given array with the averages of the control variables.

Parameters:
a - the array to be filled with averages.

standardDeviationWithCV

public void standardDeviationWithCV(double[] std)
Fills the given array with the square root of the variance of each component of XC.


varianceWithCV

public void varianceWithCV(double[] v)
Fills the given array with the variance of each component of XC.


confidenceIntervalStudentWithCV

public void confidenceIntervalStudentWithCV(int i,
                                            double level,
                                            double[] centerAndRadius)
Computes a confidence interval for the ith component of XC. This is the same as confidenceIntervalStudent except that the variance with control variables, obtained by covarianceWithCV (i, i), is used instead of the ordinary variance.

Parameters:
i - the index of the component.
level - the level of confidence of the interval.
centerAndRadius - the array that will be filled with the center and radius of the interval.

estimateBeta

public void estimateBeta()
Estimates the β* matrix from the observations currently in this list of tallies. This uses covarianceC and covarianceCX to get estimates of ΣC, and ΣCX. The result of the estimation of

β* = ΣC-1ΣCX

is stored in the matrix returned by getBeta.


clone

public ListOfTalliesWithCV<E> clone()
Clones this object. This clones the list of tallies as well as the data structures holding the sums of products, the β matrix, and the C vector, but this does not clone the tallies comprising the list. The created clone is modifiable, even though the original list is unmodifiable.

Overrides:
clone in class ListOfTalliesWithCovariance<E extends Tally>

SSJ
V. labo.

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