gov.sandia.cognition.statistics

Class UnivariateRandomVariable

java.lang.Object

gov.sandia.cognition.util.AbstractCloneableSerializable

gov.sandia.cognition.math.AbstractRing<RandomVariable<DataType>>

gov.sandia.cognition.statistics.AbstractRandomVariable<java.lang.Number>

gov.sandia.cognition.statistics.UnivariateRandomVariable

All Implemented Interfaces:

Ring<RandomVariable<java.lang.Number>>, Distribution<java.lang.Number>, DistributionWithMean<java.lang.Number>, RandomVariable<java.lang.Number>, UnivariateDistribution<java.lang.Number>, CloneableSerializable, Randomized, java.io.Serializable, java.lang.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<java.lang.Number>
implements UnivariateDistribution<java.lang.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

Fields

Modifier and Type	Field and Description
static int	DEFAULT_NUM_SAMPLES Default number of samples to draw from a distribution to perform the empirical algebra approximation, 10000.

Constructor Summary

Constructors

Constructor and Description
UnivariateRandomVariable(UnivariateDistribution<? extends java.lang.Number> distribution, java.util.Random random) Creates a new instance of UnivariateRandomVariable
UnivariateRandomVariable(UnivariateDistribution<? extends java.lang.Number> distribution, java.util.Random random, int numSamples) Creates a new instance of UnivariateRandomVariable

Method Summary

Modifier and Type	Method and Description
UnivariateRandomVariable	clone() This makes public the clone method on the Object class and removes the exception that it throws.
void	dotTimesEquals(RandomVariable<java.lang.Number> other) Inline element-wise multiplication of this and other
boolean	equals(java.lang.Object obj) Determines if two RingType objects are equal
boolean	equals(RandomVariable<java.lang.Number> other, double effectiveZero) Determines if two RingType objects are effectively equal
CumulativeDistributionFunction<java.lang.Number>	getCDF() Gets the CDF of a scalar distribution.
UnivariateDistribution<? extends java.lang.Number>	getDistribution() Getter for distribution
java.lang.Double	getMaxSupport() Gets the minimum support (domain or input) of the distribution.
java.lang.Number	getMean() Gets the arithmetic mean, or "first central moment" or "expectation", of the distribution.
double	getMeanAsDouble() Gets the mean of the distribution as a double.
java.lang.Double	getMinSupport() Gets the minimum support (domain or input) of the distribution.
int	getNumSamples() Getter for numSamples
java.util.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.
int	hashCode() Warning: The hashCode of this class is just the default hashCode, but equality uses a statistical test to see if two random variables are equal.
boolean	isZero(double effectiveZero) Determines if this ring is equal to zero using the element-wise effective zero value.
void	minusEquals(RandomVariable<java.lang.Number> other) Inline arithmetic subtraction of other from this
void	plusEquals(RandomVariable<java.lang.Number> other) Inline arithmetic addition of this and other
java.lang.Number	sample(java.util.Random random) Draws a single random sample from the distribution.
java.util.ArrayList<java.lang.Number>	sample(java.util.Random random, int numSamples) Draws multiple random samples from the distribution.
void	sampleInto(java.util.Random random, int sampleCount, java.util.Collection<? super java.lang.Number> output) Draws multiple random samples from the distribution and puts the result into the given collection.
void	scaledPlusEquals(double scaleFactor, RandomVariable<java.lang.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 java.lang.Number> distribution) Setter for distribution
void	setNumSamples(int numSamples) Setter for numSamples
void	setRandom(java.util.Random random) Sets the random number generator used by this object.

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, notify, notifyAll, toString, wait, wait, wait

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 java.lang.Number> distribution,
                                java.util.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 java.lang.Number> distribution,
                                java.util.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<java.lang.Number>>

Specified by:

clone in interface CloneableSerializable

Overrides:

clone in class AbstractRing<RandomVariable<java.lang.Number>>

Returns:

A clone of this object.

equals

public boolean equals(java.lang.Object obj)

Description copied from interface: Ring

Determines if two RingType objects are equal

Specified by:

equals in interface Ring<RandomVariable<java.lang.Number>>

Overrides:

equals in class java.lang.Object

Parameters:

obj - RingType to compare against this

Returns:

True if the two objects are equal, false otherwise

equals

public boolean equals(RandomVariable<java.lang.Number> other,
                      double effectiveZero)

Description copied from interface: Ring

Determines if two RingType objects are effectively equal

Specified by:

equals in interface Ring<RandomVariable<java.lang.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

hashCode

public int hashCode()

Warning: The hashCode of this class is just the default hashCode, but equality uses a statistical test to see if two random variables are equal.

Overrides:

hashCode in class java.lang.Object

Returns:

@inheritDoc

plusEquals

public void plusEquals(RandomVariable<java.lang.Number> other)

Description copied from interface: Ring

Inline arithmetic addition of this and other

Specified by:

plusEquals in interface Ring<RandomVariable<java.lang.Number>>

Parameters:

other - object to add to this

minusEquals

public void minusEquals(RandomVariable<java.lang.Number> other)

Description copied from interface: Ring

Inline arithmetic subtraction of other from this

Specified by:

minusEquals in interface Ring<RandomVariable<java.lang.Number>>

Parameters:

other - object to subtract from this

dotTimesEquals

public void dotTimesEquals(RandomVariable<java.lang.Number> other)

Description copied from interface: Ring

Inline element-wise multiplication of this and other

Specified by:

dotTimesEquals in interface Ring<RandomVariable<java.lang.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<java.lang.Number>>

Parameters:

scaleFactor - amount to scale the elements of this

scaledPlusEquals

public void scaledPlusEquals(double scaleFactor,
                             RandomVariable<java.lang.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<java.lang.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<java.lang.Number>>

Parameters:

effectiveZero - Tolerance threshold for element-wise equality

Returns:

True if all of the elements of this ring are effectively zero.

sample

public java.lang.Number sample(java.util.Random random)

Description copied from interface: Distribution

Draws a single random sample from the distribution.

Specified by:

sample in interface Distribution<java.lang.Number>

Overrides:

sample in class AbstractRandomVariable<java.lang.Number>

Parameters:

random - Random-number generator to use in order to generate random numbers.

Returns:

Sample drawn according to this distribution.

sample

public java.util.ArrayList<java.lang.Number> sample(java.util.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<java.lang.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.

sampleInto

public void sampleInto(java.util.Random random,
                       int sampleCount,
                       java.util.Collection<? super java.lang.Number> output)

Description copied from interface: Distribution

Draws multiple random samples from the distribution and puts the result into the given collection.

Specified by:

sampleInto in interface Distribution<java.lang.Number>

Parameters:

random - Random number generator to use.

sampleCount - The number of samples to draw. Cannot be negative.

output - The collection to add the samples into.

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 java.util.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(java.util.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 java.lang.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 java.lang.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 java.lang.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<java.lang.Number>

Returns:

Mean of the distribution.

getMeanAsDouble

public double getMeanAsDouble()

Description copied from interface: UnivariateDistribution

Gets the mean of the distribution as a double.

Specified by:

getMeanAsDouble in interface UnivariateDistribution<java.lang.Number>

Returns:

The mean as a double.

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<java.lang.Number>

Returns:

Variance of the distribution.

getMinSupport

public java.lang.Double getMinSupport()

Description copied from interface: UnivariateDistribution

Gets the minimum support (domain or input) of the distribution.

Specified by:

getMinSupport in interface UnivariateDistribution<java.lang.Number>

Returns:

Minimum support.

getMaxSupport

public java.lang.Double getMaxSupport()

Description copied from interface: UnivariateDistribution

Gets the minimum support (domain or input) of the distribution.

Specified by:

getMaxSupport in interface UnivariateDistribution<java.lang.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<java.lang.Number> getCDF()

Description copied from interface: UnivariateDistribution

Gets the CDF of a scalar distribution.

Specified by:

getCDF in interface UnivariateDistribution<java.lang.Number>

Returns:

CDF of the scalar distribution.