ContactCenters
V. 0.9.9.

umontreal.iro.lecuyer.xmlconfig
Class RandomVariateGenParam

java.lang.Object
  extended by umontreal.iro.lecuyer.xmlconfig.AbstractParam
      extended by umontreal.iro.lecuyer.xmlconfig.RandomVariateGenParam
All Implemented Interfaces:
Cloneable, Param, StorableParam

public class RandomVariateGenParam
extends AbstractParam
implements StorableParam, Cloneable

Stores the parameters of a probability distribution to create the distribution object or a matching random variate generator at a later time. Three parameters need to be defined to use this object: the class of the probability distribution, a string defining the parameters as given to the distribution class' constructor, and the class of the random variate generator. Alternatively, the parameters of the distribution can be replaced by an array of values for parameters to be estimated by maximum likeliihood. One can also specify a location parameter $ \ell$ for the generated values. This parameter, which defaults to 0, is subtracted from any generated value and added to every value specified as data to estimate parameters. It does not affect explicitly-specified parameters.

The createDistribution() and createDistributionInt() methods can be used to construct a distribution object whereas the createGenerator(umontreal.iro.lecuyer.rng.RandomStream) and createGeneratorInt(umontreal.iro.lecuyer.rng.RandomStream) methods construct a generator.

In an XML element, the distributionClass attribute is required to correspond to the name of a class implementing the Distribution interface. The nested text of the element is used as an array of parameters the class tries to pass to a constructor inside the distribution class. To use MLE, one must specify the data in a data element or dataURL attribute. data is an array of double-precision values while dataURL points to a resource containing the data, one value per line. Note that the file is searched in the same directory as the XML parameter file. For discrete distributions on the integers, the given values are rounded to the the nearest integers.

The data element or the dataFile attribute can also be used for empirical distributions. More specifically, when distributionClass is set to EmpiricalDist or PiecewiseLinearEmpiricalDist, the given data is sorted and used directly by these distributions. The shift $ \ell$ is given via the shift attribute.

The class of the random variate generator can optionally be changed by providing a compatible class name in the generatorClass attribute. This allows the method for generating the variates to be selected from a parameter file.

For example, the element


 <?import umontreal.iro.lecuyer.probdist.*?>
 <?import umontreal.iro.lecuyer.randvar.*?>
 ...
    <rvg distributionClass="GammaDist"
         generatorClass="GammaAcceptanceRejectionGen">
       32.3, 25.2
    </rvg>
can be maped to a gamma distribution with α = 32.3 and λ = 25.2 and a gamma variate generator using acceptance-rejection.


Constructor Summary
RandomVariateGenParam()
          Default constructor for parameter reader.
RandomVariateGenParam(Class<? extends Distribution> distClass, String params)
          Constructs a new distribution parameter object with distribution class distClass and parameter string params.
RandomVariateGenParam(Distribution dist)
          Constructs a new random variate generator parameter object for the distribution dist.
 
Method Summary
 void addData(ArrayParam p)
          For internal use only.
 RandomVariateGenParam clone()
           
 ArrayParam createData()
          For internal use only.
 Distribution createDistribution()
          Returns the new probability distribution extracted from the parameters.
 DiscreteDistributionInt createDistributionInt()
          Returns the new discrete probability distribution extracted from the parameters.
static Distribution createDistributionMLE(Class<? extends Distribution> distClass, double[] data, double shift)
           
 RandomVariateGen createGenerator(RandomStream stream)
          Constructs a new random variate generator from the distribution information associated with this object and the stream stream.
 RandomVariateGenInt createGeneratorInt(RandomStream stream)
          Constructs a new integer random variate generator from the distribution information associated with this object and the stream stream.
 boolean equals(Object other)
           
 void estimateParameters(boolean clearData)
          Uses data obtained by getData() to estimate the parameters of the distribution with class getDistributionClass(), and stores the estimation in the distribution's parameters returned by getDistributionParameters().
 double[] getData()
          Returns the data used to estimate the parameters of the selected distribution.
 ArrayParam getDataParam()
           
 Class<? extends Distribution> getDistributionClass()
          Returns the class of distribution object contained in this parameter.
 String getDistributionParameters()
          Returns the parameters associated with the distribution.
static String getDistributionParametersMLE(Class<? extends Distribution> distClass, double[] data, double shift)
           
 double getExpLambda()
          Returns the λ parameter for the associated exponential distribution.
 double getGammaAlpha()
          Returns the α parameter for the associated gamma distribution.
 double getGammaLambda()
          Returns the λ parameter for the associated gamma distribution.
 Class<? extends RandomVariateGen> getGeneratorClass()
          Returns the class of the random variate generator associated with this object.
 double getMean()
          Returns the mean value for the current distribution.
 double getMean(TimeUnit targetUnit)
          Returns the mean for the current distribution, epxressed with the time unit targetUnit.
 double getShift()
          Returns the shift $ \ell$ applied to all generated values.
 TimeUnit getUnit()
          Returns the time unit in which the values produced by the probability distribution are expressed.
 double getVariance()
          Returns the variance for the current distribution.
 int hashCode()
           
 boolean isAttributeSupported(String a)
          For internal use only.
 boolean isDiscreteDistributionInt()
          Determines if the associated distribution class extends DiscreteDistributionInt.
 void nestedText(ParamReader reader, String par)
          For internal use only.
 void setConstant(double c)
          Sets the current distribution to a constant value c.
 void setData(double[] data)
          Sets the data used for estimating the parameters of the selected distribution to data.
 void setDataParam(ArrayParam dataParam)
           
 void setDistribution(Distribution dist)
          Sets the probability distribution to dist.
 void setDistribution(Distribution dist, String distParams)
           
 void setDistributionClass(Class<? extends Distribution> distClass)
          Sets the class of distribution object to distClass.
 void setDistributionParameters(String params)
          Sets the distribution parameters to params.
 void setExpLambda(double lambda)
          Sets the distribution class to exponential and sets the λ parameter to lambda.
 void setGammaParams(double alpha, double lambda)
          Sets the distribution class to gamma and sets the α and λ parameters to alpha and lambda, respectively.
 void setGeneratorClass(Class<? extends RandomVariateGen> genClass)
          Sets the class of random variate generator to genClass.
 void setShift(double shift)
          Sets the shift $ \ell$ being applied to all generated values to shift.
 void setUnit(TimeUnit unit)
          Sets the distribution's time unit to unit.
 Element toElement(ClassFinder finder, Node parent, String elementName, int spc)
          Converts this parameter object to a DOM element using the class finder finder for formatting class names, with parent node parent, element name elementName, and spc spaces for each indentation level.
 String toString()
           
 
Methods inherited from class umontreal.iro.lecuyer.xmlconfig.AbstractParam
check, createDocument, getId, getXref, setId, setXref, write, write, write, write, write, write, write, write
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RandomVariateGenParam

public RandomVariateGenParam()
Default constructor for parameter reader.


RandomVariateGenParam

public RandomVariateGenParam(Class<? extends Distribution> distClass,
                             String params)
Constructs a new distribution parameter object with distribution class distClass and parameter string params. The given distribution class must be a subclass of Distribution or DiscreteDistributionInt and the parameter string must correspond to the arguments given to the constructor of the distribution class, without the parentheses. Arrays can be given as arguments by surrounding them with braces.

Parameters:
distClass - the class of the represented distribution.
params - the parameters passed to the constructor.
Throws:
NullPointerException - if distClass is null.
IllegalArgumentException - if the given class is not a subclass of Distribution or DiscreteDistributionInt.

RandomVariateGenParam

public RandomVariateGenParam(Distribution dist)
Constructs a new random variate generator parameter object for the distribution dist.

Parameters:
dist - the probability distribution.
Method Detail

isDiscreteDistributionInt

public boolean isDiscreteDistributionInt()
Determines if the associated distribution class extends DiscreteDistributionInt. If this is the case, returns true. Otherwise, returns false. If the distribution class is not set, i.e., getDistributionClass() returns null, an IllegalStateException is thrown.

Returns:
true if and only if a discrete distribution of integer is associated with this parameter object.
Throws:
IllegalStateException - if the distribution class was not set up.

getDistributionClass

public Class<? extends Distribution> getDistributionClass()
Returns the class of distribution object contained in this parameter. If the distribution was not set, this returns null.

Returns:
the class of distribution object.

setDistributionClass

public void setDistributionClass(Class<? extends Distribution> distClass)
Sets the class of distribution object to distClass. This method resets the random variate generator class to the default value as specified in getGeneratorClass(), and the distribution parameters to null.

Parameters:
distClass - the new distribution class.
Throws:
NullPointerException - if distClass is null.
IllegalArgumentException - if the given class does not implement Distribution or extend DiscreteDistributionInt.

getShift

public double getShift()
Returns the shift $ \ell$ applied to all generated values.

Returns:
the shift being applied.

setShift

public void setShift(double shift)
Sets the shift $ \ell$ being applied to all generated values to shift.

Parameters:
shift - the new value of the shift.

getDistributionParameters

public String getDistributionParameters()
Returns the parameters associated with the distribution. This corresponds to a comma-separated list of parameters as given to the constructor of the distribution class, without the parentheses.

Returns:
the parameters of the distribution.

setDistributionParameters

public void setDistributionParameters(String params)
Sets the distribution parameters to params.

Parameters:
params - the distribution parameters.

getData

public double[] getData()
Returns the data used to estimate the parameters of the selected distribution. Note that this data is ignored if parameters are specified directly (getDistributionParameters() returns a non-empty string).

Returns:
the data for estimating the parameters.

setData

public void setData(double[] data)
Sets the data used for estimating the parameters of the selected distribution to data.

Parameters:
data - the data used for parameter estimation.

getDataParam

public ArrayParam getDataParam()

setDataParam

public void setDataParam(ArrayParam dataParam)

getGeneratorClass

public Class<? extends RandomVariateGen> getGeneratorClass()
Returns the class of the random variate generator associated with this object. The default class is RandomVariateGen for a Distribution and RandomVariateGenInt for a DiscreteDistributionInt. This has a non-null value only after the distribution class is set up, using a constructor, an XML element, or setDistributionClass(java.lang.Class).

Returns:
the class of random variate generator.

setGeneratorClass

public void setGeneratorClass(Class<? extends RandomVariateGen> genClass)
Sets the class of random variate generator to genClass. This method cannot be called until a distribution class is set up.

Parameters:
genClass - the new random variate generator class.
Throws:
NullPointerException - if genClass is null.
IllegalArgumentException - if the given class does not extend RandomVariateGen.
IllegalStateException - if a distribution class was not set up.

createDistribution

public Distribution createDistribution()
Returns the new probability distribution extracted from the parameters. This method can be called only if isDiscreteDistributionInt() returns false.

Returns:
the extracted probability distribution.
Throws:
IllegalStateException - if the distribution class is not set or corresponds to a DiscreteDistributionInt subclass.
DistributionCreationException - if the distribution cannot be created successfully.

createDistributionInt

public DiscreteDistributionInt createDistributionInt()
Returns the new discrete probability distribution extracted from the parameters. This method can be called only if isDiscreteDistributionInt() returns true.

Returns:
the extracted probability distribution.
Throws:
IllegalStateException - if the distribution class is not set or corresponds to a Distribution implementation.
DistributionCreationException - if the distribution cannot be created successfully.

setDistribution

public void setDistribution(Distribution dist)
Sets the probability distribution to dist. This resets the generator class to RandomVariateGen.

Parameters:
dist - the new distribution.

setDistribution

public void setDistribution(Distribution dist,
                            String distParams)

getUnit

public TimeUnit getUnit()
Returns the time unit in which the values produced by the probability distribution are expressed. If this is set to null (the default), no time conversion is performed.

Returns:
the distribution's time unit.

setUnit

public void setUnit(TimeUnit unit)
Sets the distribution's time unit to unit.

Parameters:
unit - the new distribution's time unit.
See Also:
getUnit()

setConstant

public void setConstant(double c)
Sets the current distribution to a constant value c. This is a special case of a discrete distribution with a single observation c having probability 1.

Parameters:
c - the constant returned by the produced generator.

getMean

public double getMean()
Returns the mean value for the current distribution. This method calls createDistribution().getMean().

Returns:
the mean.

getMean

public double getMean(TimeUnit targetUnit)
Returns the mean for the current distribution, epxressed with the time unit targetUnit. This method returns the same value as getMean() if getUnit() returns null or targetUnit is null.

Parameters:
targetUnit - the target time unit.
Returns:
the mean, possibly converted to the target time unit.

getVariance

public double getVariance()
Returns the variance for the current distribution. This method calls createDistribution().getVariance().

Returns:
the mean.

getExpLambda

public double getExpLambda()
Returns the λ parameter for the associated exponential distribution. If the distribution class is not set up or not exponential, this throws an IllegalStateException. Otherwise, the method tries to create the exponential distribution object and returns the corresponding λ parameter.

Returns:
the λ parameter.
Throws:
IllegalStateException - if the distribution is incompatible.

setExpLambda

public void setExpLambda(double lambda)
Sets the distribution class to exponential and sets the λ parameter to lambda.

Parameters:
lambda - the λ parameter for the exponential distribution.
Throws:
IllegalArgumentException - if lambda is negative or 0.

getGammaAlpha

public double getGammaAlpha()
Returns the α parameter for the associated gamma distribution. If the distribution class is not set up or not gamma, this throws an IllegalStateException. Otherwise, the method tries to create the gamma distribution object and returns the corresponding γ parameter.

Returns:
the α parameter.
Throws:
IllegalStateException - if the distribution is incompatible.

getGammaLambda

public double getGammaLambda()
Returns the λ parameter for the associated gamma distribution. If the distribution class is not set up or not gamma, this throws an IllegalStateException. Otherwise, the method tries to create the gamma distribution object and returns the corresponding λ parameter.

Returns:
the λ parameter.
Throws:
IllegalStateException - if the distribution is incompatible.

setGammaParams

public void setGammaParams(double alpha,
                           double lambda)
Sets the distribution class to gamma and sets the α and λ parameters to alpha and lambda, respectively.

Parameters:
alpha - the α parameter for the gamma distribution.
lambda - the λ parameter for the gamma distribution.
Throws:
IllegalArgumentException - if alpha or lambda are negative or 0.

createGenerator

public RandomVariateGen createGenerator(RandomStream stream)
Constructs a new random variate generator from the distribution information associated with this object and the stream stream. This method constructs a random variate generator from the class given by getGeneratorClass() by selecting an appropriate constructor. The method only uses constructors taking a random stream and a probability distribution. Other constructors from a random variate generator are ignored. If the parameter object contains information about a discrete distribution of integers, a RandomVariateGenInt is constructed.

Parameters:
stream - the random stream used to generate uniforms.
Throws:
DistributionCreationException - if the probability distribution could not be created successfully.
GeneratorCreationException - if the generator cannot be created.
IllegalStateException - if some distribution or generator parameters are missing or invalid.

createGeneratorInt

public RandomVariateGenInt createGeneratorInt(RandomStream stream)
Constructs a new integer random variate generator from the distribution information associated with this object and the stream stream. This is similar to createGenerator(umontreal.iro.lecuyer.rng.RandomStream), except it returns an integer random variate generator. An IllegalStateException is thrown if the parameter object contains information about a Distribution implementation.

Parameters:
stream - the random stream used to generate uniforms.
Throws:
DistributionCreationException - if the probability distribution could not be created successfully.
GeneratorCreationException - if the generator cannot be created.
IllegalStateException - if some distribution or generator parameters are missing or invalid, or if the associated parameters correspond to an incompatible distribution.

isAttributeSupported

public boolean isAttributeSupported(String a)
For internal use only.


nestedText

public void nestedText(ParamReader reader,
                       String par)
For internal use only.


estimateParameters

public void estimateParameters(boolean clearData)
Uses data obtained by getData() to estimate the parameters of the distribution with class getDistributionClass(), and stores the estimation in the distribution's parameters returned by getDistributionParameters(). This method does nothing if getDistributionClass() returns null or a class corresponding to an empirical distribution. Otherwise, it tries to call a static method getMaximumLikelihoodEstimate (double[], int) or getMaximumLikelihoodEstimate (int[], int) (for discrete distributions over the integers) with the values in the array returned by getData(). The resulting array is converted into a string assuming that an appropriate constructor exists in the distribution class. If clearData is true, the references to the data and the data file for this object are set to null after parameter estimation.

Parameters:
clearData - determines if the data bound to this object must be discarded.

getDistributionParametersMLE

public static String getDistributionParametersMLE(Class<? extends Distribution> distClass,
                                                  double[] data,
                                                  double shift)

createDistributionMLE

public static Distribution createDistributionMLE(Class<? extends Distribution> distClass,
                                                 double[] data,
                                                 double shift)

createData

public ArrayParam createData()
For internal use only.


addData

public void addData(ArrayParam p)
For internal use only.


toElement

public Element toElement(ClassFinder finder,
                         Node parent,
                         String elementName,
                         int spc)
Description copied from interface: StorableParam
Converts this parameter object to a DOM element using the class finder finder for formatting class names, with parent node parent, element name elementName, and spc spaces for each indentation level. The method must create an Element instance with name elementName and add it to the node parent of the DOM tree. It is recommended to use DOMUtils helper methods for this. After the element is created, attributes can be set and nested contents can be added. The configured DOM element is then returned.

Specified by:
toElement in interface StorableParam
Parameters:
finder - the class finder used to format class names.
parent - the parent of the new element.
elementName - the name of the constructed element.
spc - the number of spaces for each indentation level.
Returns:
the newly-constructed element.

toString

public String toString()
Overrides:
toString in class AbstractParam

equals

public boolean equals(Object other)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

clone

public RandomVariateGenParam clone()
Overrides:
clone in class Object

ContactCenters
V. 0.9.9.

To submit a bug or ask questions, send an e-mail to Richard Simard.