SSJ
V. labo.

umontreal.iro.lecuyer.stat.matrix
Class MatrixOfStatProbes<E extends StatProbe>

java.lang.Object
  extended by umontreal.iro.lecuyer.stat.matrix.MatrixOfStatProbes<E>
All Implemented Interfaces:
Cloneable, Iterable<E>
Direct Known Subclasses:
MatrixOfFunctionOfMultipleMeansTallies, MatrixOfTallies

public class MatrixOfStatProbes<E extends StatProbe>
extends Object
implements Cloneable, Iterable<E>

Represents a matrix of statistical probes that can be managed simultaneously. Each element of this matrix is a StatProbe instance which can be obtained and manipulated. Alternatively, several methods are provided to manipulate all probes in the matrix simultaneously.

Each matrix of probes can have a global name describing the contents of its elements, and local names for each cell. For example, a matrix of statistical probes for the waiting times can have the global name ``Waiting times'' while the first cell has local name ``type 1, period 1''.

Facilities are provided to fill matrices of sums, averages, etc. obtained from the individual statistical probes. DoubleMatrix2D is used instead of 2D arrays because it more efficiently stores the values, and it supports computations on the elements.


Constructor Summary
MatrixOfStatProbes(int numRows, int numColumns)
          Constructs a new unnamed matrix of statistical probes with numRows rows, and numColumns columns, and filled with null references.
MatrixOfStatProbes(String name, int numRows, int numColumns)
          Constructs a new matrix of statistical probes with name name, numRows rows, and numColumns columns, and filled with null references.
 
Method Summary
 void addMatrixOfObservationListener(MatrixOfObservationListener l)
          Adds the observation listener l to the list of observers of this matrix of statistical probes.
 void average(DoubleMatrix2D m)
          For each statistical probe in the matrix, computes the average by calling average, and stores it into the given matrix m.
 void clearMatrixOfObservationListeners()
          Removes all observation listeners from the list of observers of this matrix of statistical probes.
 MatrixOfStatProbes<E> clone()
          Clones this object.
 String columnReport(int c)
          Formats a report for the column c of the statistical probe matrix.
 int columns()
          Returns the number of columns in this matrix.
 E get(int r, int c)
          Returns the statistical probe corresponding to the row r and column c.
 String getName()
          Returns the global name of this matrix of statistical probes.
 void init()
          Initializes this matrix of statistical probes by calling StatProbe.init on each element.
 boolean isBroadcasting()
          Determines if this matrix of statistical probes is broadcasting values to registered observers.
 boolean isCollecting()
          Determines if this matrix of statistical probes is collecting values.
 Iterator<E> iterator()
           
 void notifyListeners(DoubleMatrix2D x)
          Notifies the observation x to all registered observers if broadcasting is ON.
 void removeMatrixOfObservationListener(MatrixOfObservationListener l)
          Removes the observation listener l from the list of observers of this matrix of statistical probes.
 String rowReport(int r)
          Formats a report for the row r of the statistical probe matrix.
 int rows()
          Returns the number of rows in this matrix.
 void set(int r, int c, E probe)
          Sets the statistical probe corresponding to the row r and column c to probe.
 void setBroadcasting(boolean b)
          Sets the status of the observation broadcasting mechanism to b.
 void setCollecting(boolean c)
          Sets the status of the statistical collecting mechanism to c.
 void setColumns(int newColumns)
          Similar to setRows, for setting the number of columns.
 void setName(String name)
          Sets the global name of this matrix to name.
 void setRows(int newRows)
          Sets the number of rows of this matrix of statistical probes to newRows, adding or removing cells as necessary.
 void sum(DoubleMatrix2D m)
          For each probe in the matrix, computes the sum by calling sum, and stores it into the given matrix m.
 List<E> viewColumn(int c)
          Returns a list representing a view on column c of this matrix of statistical probe.
 List<E> viewRow(int r)
          Returns a list representing a view on row r of this matrix of statistical probe.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

MatrixOfStatProbes

public MatrixOfStatProbes(int numRows,
                          int numColumns)
Constructs a new unnamed matrix of statistical probes with numRows rows, and numColumns columns, and filled with null references.

Parameters:
numRows - the number of rows in the matrix.
numColumns - the number of columns in the matrix.
Throws:
NegativeArraySizeException - if numRows or numColumns are negative.

MatrixOfStatProbes

public MatrixOfStatProbes(String name,
                          int numRows,
                          int numColumns)
Constructs a new matrix of statistical probes with name name, numRows rows, and numColumns columns, and filled with null references.

Parameters:
name - the global name of the matrix.
numRows - the number of rows in the matrix.
numColumns - the number of columns in the matrix.
Throws:
NegativeArraySizeException - if numRows or numColumns are negative.
Method Detail

getName

public String getName()
Returns the global name of this matrix of statistical probes.

Returns:
the global name of the matrix.

setName

public void setName(String name)
Sets the global name of this matrix to name.

Parameters:
name - the new global name of the matrix.

rows

public int rows()
Returns the number of rows in this matrix.

Returns:
the total number of rows.

columns

public int columns()
Returns the number of columns in this matrix.

Returns:
the total number of columns.

setRows

public void setRows(int newRows)
Sets the number of rows of this matrix of statistical probes to newRows, adding or removing cells as necessary. If newRows is negative, a NegativeArraySizeException is thrown. Otherwise, if newRows is equal to rows, nothing happens. If the number of rows is reduced, the last rows - newRows rows of statistical probes are lost. If the number of rows is increased, the new elements of the matrix are set to null.

Parameters:
newRows - the new number of rows of the matrix.
Throws:
IllegalArgumentException - if an error occurs during construction of statistical probes.
NegativeArraySizeException - if newRows is negative.

setColumns

public void setColumns(int newColumns)
Similar to setRows, for setting the number of columns.

Parameters:
newColumns - the new number of columns of the matrix.
Throws:
IllegalArgumentException - if an error occurs during construction of statistical probes.
NegativeArraySizeException - if newolumns is negative.

get

public E get(int r,
             int c)
Returns the statistical probe corresponding to the row r and column c.

Parameters:
r - the row to look at.
c - the column to look at.
Returns:
the corresponding statistical probe.
Throws:
ArrayIndexOutOfBoundsException - if r or c are negative, if r is greater than or equal to rows, or if c is greater than or equal to columns.

set

public void set(int r,
                int c,
                E probe)
Sets the statistical probe corresponding to the row r and column c to probe.

Parameters:
r - the row to modify.
c - the column to modify.
probe - t he new probe.
Throws:
ArrayIndexOutOfBoundsException - if r or c are negative, if r is greater than or equal to rows, or if c is greater than or equal to columns.

init

public void init()
Initializes this matrix of statistical probes by calling StatProbe.init on each element.


sum

public void sum(DoubleMatrix2D m)
For each probe in the matrix, computes the sum by calling sum, and stores it into the given matrix m.

Parameters:
m - the matrix to be filled with sums.
Throws:
NullPointerException - if m is null.
IllegalArgumentException - if m.rows() does not correspond to rows, or m.columns() does not correspond to columns.

average

public void average(DoubleMatrix2D m)
For each statistical probe in the matrix, computes the average by calling average, and stores it into the given matrix m.

Parameters:
m - the matrix to be filled with averages.
Throws:
NullPointerException - if m is null.
IllegalArgumentException - if m.rows() does not correspond to rows, or m.columns() does not correspond to columns.

isCollecting

public boolean isCollecting()
Determines if this matrix of statistical probes is collecting values. The default is true.

Returns:
the status of statistical collecting.

setCollecting

public void setCollecting(boolean c)
Sets the status of the statistical collecting mechanism to c. A true value turns statistical collecting ON, a false value turns it OFF.

Parameters:
c - the status of statistical collecting.

isBroadcasting

public boolean isBroadcasting()
Determines if this matrix of statistical probes is broadcasting values to registered observers. The default is false.

Returns:
the status of broadcasting.

setBroadcasting

public void setBroadcasting(boolean b)
Sets the status of the observation broadcasting mechanism to b. A true value turns broadcasting ON, a false value turns it OFF.

Parameters:
b - the status of broadcasting.

addMatrixOfObservationListener

public void addMatrixOfObservationListener(MatrixOfObservationListener l)
Adds the observation listener l to the list of observers of this matrix of statistical probes.

Parameters:
l - the new observation listener.
Throws:
NullPointerException - if l is null.

removeMatrixOfObservationListener

public void removeMatrixOfObservationListener(MatrixOfObservationListener l)
Removes the observation listener l from the list of observers of this matrix of statistical probes.

Parameters:
l - the observation listener to be deleted.

clearMatrixOfObservationListeners

public void clearMatrixOfObservationListeners()
Removes all observation listeners from the list of observers of this matrix of statistical probes.


notifyListeners

public void notifyListeners(DoubleMatrix2D x)
Notifies the observation x to all registered observers if broadcasting is ON. Otherwise, does nothing.


viewRow

public List<E> viewRow(int r)
Returns a list representing a view on row r of this matrix of statistical probe. The returned list cannot be modified, and becomes invalid if the number of rows in this matrix of statistical probes is changed.

Parameters:
r - the row to look at.
Returns:
the list of statistical probes on the row.

viewColumn

public List<E> viewColumn(int c)
Returns a list representing a view on column c of this matrix of statistical probe. The returned list cannot be modified, and becomes invalid if the number of columns in this matrix of statistical probes is changed.

Parameters:
c - the column to look at.
Returns:
the list of statistical probes on the column.

rowReport

public String rowReport(int r)
Formats a report for the row r of the statistical probe matrix. The returned string is constructed by getting a view of row r and using StatProbe.report on this list.

Parameters:
r - the row being reported.
Returns:
the report formatted as a string.

columnReport

public String columnReport(int c)
Formats a report for the column c of the statistical probe matrix. The returned string is constructed by getting a view of column c and using StatProbe.report on this list.

Parameters:
c - the column being reported.
Returns:
the report formatted as a string.

clone

public MatrixOfStatProbes<E> clone()
Clones this object. This makes a shallow copy of this matrix, i.e., this does not clone all the probes in the matrix.

Overrides:
clone in class Object

iterator

public Iterator<E> iterator()
Specified by:
iterator in interface Iterable<E extends StatProbe>

SSJ
V. labo.

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