gov.sandia.cognition.statistics
Class UnivariateRandomVariable

java.lang.Object
  extended by gov.sandia.cognition.util.AbstractCloneableSerializable
      extended by gov.sandia.cognition.math.AbstractRing<RandomVariable<DataType>>
          extended by gov.sandia.cognition.statistics.AbstractRandomVariable<Number>
              extended by gov.sandia.cognition.statistics.UnivariateRandomVariable
All Implemented Interfaces:
Ring<RandomVariable<Number>>, Distribution<Number>, DistributionWithMean<Number>, RandomVariable<Number>, UnivariateDistribution<Number>, CloneableSerializable, Randomized, Serializable, Cloneable

@PublicationReference(author="Wikipedia",
                      title="Algebra of random variables",
                      type=WebPage,
                      year=2009,
                      url="http://en.wikipedia.org/wiki/Algebra_of_random_variables")
public class UnivariateRandomVariable
extends AbstractRandomVariable<Number>
implements UnivariateDistribution<Number>

This is an implementation of a RandomVariable for scalar distributions. The primary method by which random-variable algebra is conducted is by empirically sampling the distributions, performing the algebra on the samples, and then fitting an empirical distribution to the resulting samples.

Since:
3.0
Author:
Kevin R. Dixon
See Also:
Serialized Form

Field Summary
static int DEFAULT_NUM_SAMPLES
          Default number of samples to draw from a distribution to perform the empirical algebra approximation, 10000.
 
Constructor Summary
UnivariateRandomVariable(UnivariateDistribution<? extends Number> distribution, Random random)
          Creates a new instance of UnivariateRandomVariable
UnivariateRandomVariable(UnivariateDistribution<? extends Number> distribution, Random random, int numSamples)
          Creates a new instance of UnivariateRandomVariable
 
Method Summary
 UnivariateRandomVariable clone()
          This makes public the clone method on the Object class and removes the exception that it throws.
 void dotTimesEquals(RandomVariable<Number> other)
          Inline element-wise multiplication of this and other
 boolean equals(Object obj)
          Determines if two RingType objects are equal
 boolean equals(RandomVariable<Number> other, double effectiveZero)
          Determines if two RingType objects are effectively equal
 CumulativeDistributionFunction<Number> getCDF()
          Gets the CDF of a scalar distribution.
 UnivariateDistribution<? extends Number> getDistribution()
          Getter for distribution
 Double getMaxSupport()
          Gets the minimum support (domain or input) of the distribution.
 Number getMean()
          Gets the arithmetic mean, or "first central moment" or "expectation", of the distribution.
 Double getMinSupport()
          Gets the minimum support (domain or input) of the distribution.
 int getNumSamples()
          Getter for numSamples
 Random getRandom()
          Gets the random number generator used by this object.
 ConfidenceInterval getSamplingError(double confidence)
          Gets the 95% confidence interval estimated sampling error associated with this empirical random variable.
 double getVariance()
          Gets the variance of the distribution.
 boolean isZero(double effectiveZero)
          Determines if this ring is equal to zero using the element-wise effective zero value.
 void minusEquals(RandomVariable<Number> other)
          Inline arithmetic subtraction of other from this
 void plusEquals(RandomVariable<Number> other)
          Inline arithmetic addition of this and other
 ArrayList<Number> sample(Random random, int numSamples)
          Draws multiple random samples from the distribution.
 void scaledPlusEquals(double scaleFactor, RandomVariable<Number> other)
          Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor.
 void scaleEquals(double scaleFactor)
          Inline element-wise scaling of this by scaleFactor
 void setDistribution(UnivariateDistribution<? extends Number> distribution)
          Setter for distribution
 void setNumSamples(int numSamples)
          Setter for numSamples
 void setRandom(Random random)
          Sets the random number generator used by this object.
 
Methods inherited from class gov.sandia.cognition.statistics.AbstractRandomVariable
sample
 
Methods inherited from class gov.sandia.cognition.math.AbstractRing
dotTimes, isZero, minus, negative, negativeEquals, plus, scale, scaledMinus, scaledMinusEquals, scaledPlus, zero
 
Methods inherited from class java.lang.Object
finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface gov.sandia.cognition.statistics.Distribution
sample
 
Methods inherited from interface gov.sandia.cognition.math.Ring
dotTimes, isZero, minus, negative, negativeEquals, plus, scale, scaledMinus, scaledMinusEquals, scaledPlus, zero
 

Field Detail

DEFAULT_NUM_SAMPLES

public static final int DEFAULT_NUM_SAMPLES
Default number of samples to draw from a distribution to perform the empirical algebra approximation, 10000.

See Also:
Constant Field Values
Constructor Detail

UnivariateRandomVariable

public UnivariateRandomVariable(UnivariateDistribution<? extends Number> distribution,
                                Random random)
Creates a new instance of UnivariateRandomVariable

Parameters:
distribution - Scalar distribution that backs the random variable, from which samples will be drawn to approximate the distribution during algebra.
random - Random number generator used to sample the distribution

UnivariateRandomVariable

public UnivariateRandomVariable(UnivariateDistribution<? extends Number> distribution,
                                Random random,
                                int numSamples)
Creates a new instance of UnivariateRandomVariable

Parameters:
distribution - Scalar distribution that backs the random variable, from which samples will be drawn to approximate the distribution during algebra.
random - Random number generator used to sample the distribution
numSamples -
Method Detail

clone

public UnivariateRandomVariable clone()
Description copied from class: AbstractCloneableSerializable
This makes public the clone method on the Object class and removes the exception that it throws. Its default behavior is to automatically create a clone of the exact type of object that the clone is called on and to copy all primitives but to keep all references, which means it is a shallow copy. Extensions of this class may want to override this method (but call super.clone() to implement a "smart copy". That is, to target the most common use case for creating a copy of the object. Because of the default behavior being a shallow copy, extending classes only need to handle fields that need to have a deeper copy (or those that need to be reset). Some of the methods in ObjectUtil may be helpful in implementing a custom clone method. Note: The contract of this method is that you must use super.clone() as the basis for your implementation.

Specified by:
clone in interface Ring<RandomVariable<Number>>
Specified by:
clone in interface CloneableSerializable
Overrides:
clone in class AbstractRing<RandomVariable<Number>>
Returns:
A clone of this object.

equals

public boolean equals(Object obj)
Description copied from interface: Ring
Determines if two RingType objects are equal

Specified by:
equals in interface Ring<RandomVariable<Number>>
Overrides:
equals in class Object
Parameters:
obj - RingType to compare against this
Returns:
True if the two objects are equal, false otherwise

equals

public boolean equals(RandomVariable<Number> other,
                      double effectiveZero)
Description copied from interface: Ring
Determines if two RingType objects are effectively equal

Specified by:
equals in interface Ring<RandomVariable<Number>>
Parameters:
other - RingType to compare against this
effectiveZero - tolerance threshold for element-wise equality
Returns:
True if the two objects are equal, false otherwise

plusEquals

public void plusEquals(RandomVariable<Number> other)
Description copied from interface: Ring
Inline arithmetic addition of this and other

Specified by:
plusEquals in interface Ring<RandomVariable<Number>>
Parameters:
other - object to add to this

minusEquals

public void minusEquals(RandomVariable<Number> other)
Description copied from interface: Ring
Inline arithmetic subtraction of other from this

Specified by:
minusEquals in interface Ring<RandomVariable<Number>>
Parameters:
other - object to subtract from this

dotTimesEquals

public void dotTimesEquals(RandomVariable<Number> other)
Description copied from interface: Ring
Inline element-wise multiplication of this and other

Specified by:
dotTimesEquals in interface Ring<RandomVariable<Number>>
Parameters:
other - elements of other will be multiplied to the corresponding elements of this

scaleEquals

public void scaleEquals(double scaleFactor)
Description copied from interface: Ring
Inline element-wise scaling of this by scaleFactor

Specified by:
scaleEquals in interface Ring<RandomVariable<Number>>
Parameters:
scaleFactor - amount to scale the elements of this

scaledPlusEquals

public void scaledPlusEquals(double scaleFactor,
                             RandomVariable<Number> other)
Description copied from interface: Ring
Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x += a * y. It is typically a more efficient way of doing this.plusEquals(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Specified by:
scaledPlusEquals in interface Ring<RandomVariable<Number>>
Parameters:
scaleFactor - The scale factor to multiply by the elements of other before adding to the elements of this.
other - Object to scale and then add to this.

isZero

public boolean isZero(double effectiveZero)
Description copied from interface: Ring
Determines if this ring is equal to zero using the element-wise effective zero value.

Specified by:
isZero in interface Ring<RandomVariable<Number>>
Parameters:
effectiveZero - Tolerance threshold for element-wise equality
Returns:
True if all of the elements of this ring are effectively zero.

sample

public ArrayList<Number> sample(Random random,
                                int numSamples)
Description copied from interface: Distribution
Draws multiple random samples from the distribution. It is generally more efficient to use this multiple-sample method than multiple calls of the single-sample method. (But not always.)

Specified by:
sample in interface Distribution<Number>
Parameters:
random - Random-number generator to use in order to generate random numbers.
numSamples - Number of samples to draw from the distribution.
Returns:
Samples drawn according to this distribution.

getNumSamples

public int getNumSamples()
Getter for numSamples

Returns:
Number of samples to draw from the distribution to perform the empirical algebra approximation.

setNumSamples

public void setNumSamples(int numSamples)
Setter for numSamples

Parameters:
numSamples - Number of samples to draw from the distribution to perform the empirical algebra approximation.

getRandom

public Random getRandom()
Description copied from interface: Randomized
Gets the random number generator used by this object.

Specified by:
getRandom in interface Randomized
Returns:
The random number generator used by this object.

setRandom

public void setRandom(Random random)
Description copied from interface: Randomized
Sets the random number generator used by this object.

Specified by:
setRandom in interface Randomized
Parameters:
random - The random number generator for this object to use.

getDistribution

public UnivariateDistribution<? extends Number> getDistribution()
Getter for distribution

Returns:
Scalar distribution that backs the random variable, from which samples will be drawn to approximate the distribution during algebra.

setDistribution

public void setDistribution(UnivariateDistribution<? extends Number> distribution)
Setter for distribution

Parameters:
distribution - Scalar distribution that backs the random variable, from which samples will be drawn to approximate the distribution during algebra.

getMean

public Number getMean()
Description copied from interface: DistributionWithMean
Gets the arithmetic mean, or "first central moment" or "expectation", of the distribution.

Specified by:
getMean in interface DistributionWithMean<Number>
Returns:
Mean of the distribution.

getVariance

public double getVariance()
Description copied from interface: UnivariateDistribution
Gets the variance of the distribution. This is sometimes called the second central moment by more pedantic people, which is equivalent to the square of the standard deviation.

Specified by:
getVariance in interface UnivariateDistribution<Number>
Returns:
Variance of the distribution.

getMinSupport

public Double getMinSupport()
Description copied from interface: UnivariateDistribution
Gets the minimum support (domain or input) of the distribution.

Specified by:
getMinSupport in interface UnivariateDistribution<Number>
Returns:
Minimum support.

getMaxSupport

public Double getMaxSupport()
Description copied from interface: UnivariateDistribution
Gets the minimum support (domain or input) of the distribution.

Specified by:
getMaxSupport in interface UnivariateDistribution<Number>
Returns:
Minimum support.

getSamplingError

@PublicationReference(author="Wikipedia",
                      title="Standard error (statistics)",
                      type=WebPage,
                      year=2009,
                      url="http://en.wikipedia.org/wiki/Standard_error_(statistics)")
public ConfidenceInterval getSamplingError(double confidence)
Gets the 95% confidence interval estimated sampling error associated with this empirical random variable.

Parameters:
confidence - Confidence required. If you want 95% confidence, which is the standard in social science, then use 0.95.
Returns:
Estimated sampling error associated with this empirical random variable.

getCDF

public CumulativeDistributionFunction<Number> getCDF()
Description copied from interface: UnivariateDistribution
Gets the CDF of a scalar distribution.

Specified by:
getCDF in interface UnivariateDistribution<Number>
Returns:
CDF of the scalar distribution.