Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## umontreal.iro.lecuyer.xmlconfig
Class RandomVariateGenParam

    java.lang.Object
      umontreal.iro.lecuyer.xmlconfig.AbstractParam
          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 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 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 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 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 applied to all generated values.

  Returns:
    the shift being applied.

### setShift

    public void setShift(double shift)

  Sets the shift 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`

Overview | Package | Class | Tree | Deprecated | Index | Help
| ContactCenters V. 0.9.9.
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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