GaussianRandomizer.java
/*
* Copyright (C) 2012 Alberto Irurueta Carro (alberto@irurueta.com)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.irurueta.statistics;
import java.util.Random;
/**
* Generates pseudo-random values following a Gaussian distribution having
* the specified mMean and standard deviation. By default, mMean is equal to
* DEFAULT_MEAN and the standard deviation is equal to
* DEFAULT_STANDARD_DEVIATION.
*/
public class GaussianRandomizer extends Randomizer {
/**
* Specifies mMean value to be used for random value generation if no mMean
* is provided.
*/
public static final double DEFAULT_MEAN = 0.0;
/**
* Specifies standard deviation to be used for random value generation if
* none is provided.
*/
public static final double DEFAULT_STANDARD_DEVIATION = 1.0;
/**
* Contains mMean value to be used for random value generation.
*/
private double mean;
/**
* Standard deviation value to be used for random value generation.
*/
private double standardDeviation;
/**
* Constructor.
* Uses default {@link Random} implementation.
*/
public GaussianRandomizer() {
this(new Random());
}
/**
* Constructor.
* Uses default {@link Random} implementation.
*
* @param mean Mean value of generated Gaussian values.
* @param standardDeviation Standard deviation of generated Gaussian values.
* @throws IllegalArgumentException thrown if provided standard deviation
* is negative or zero.
* @throws NullPointerException if provided internal Random instance is null.
*/
public GaussianRandomizer(final double mean, final double standardDeviation) {
this(new Random(), mean, standardDeviation);
}
/**
* Constructor.
* Because neither mMean nor standard deviation are provided, values
* DEFAULT_MEAN and DEFAULT_STANDARD_DEVIATION will be used instead.
*
* @param internalRandom Internal Random instance in charge of generating
* pseudo-random values.
* @throws NullPointerException thrown if provided internal random is null.
*/
public GaussianRandomizer(final Random internalRandom) {
super(internalRandom);
mean = DEFAULT_MEAN;
standardDeviation = DEFAULT_STANDARD_DEVIATION;
}
/**
* Constructor.
*
* @param internalRandom Internal Random instance if charge of generating
* pseudo-random values.
* @param mean Mean value of generated Gaussian values.
* @param standardDeviation Standard deviation of generated Gaussian values.
* @throws IllegalArgumentException thrown if provided standard deviation
* is negative or zero.
* @throws NullPointerException if provided internal Random instance is null.
*/
public GaussianRandomizer(final Random internalRandom, final double mean, final double standardDeviation) {
super(internalRandom);
if (standardDeviation <= 0.0) {
throw new IllegalArgumentException();
}
this.mean = mean;
this.standardDeviation = standardDeviation;
}
/**
* Returns mMean value to be used for Gaussian random value generation.
*
* @return Mean value.
*/
public double getMean() {
return mean;
}
/**
* Sets mMean value to be used for Gaussian random value generation.
*
* @param mean Mean value.
*/
public void setMean(final double mean) {
this.mean = mean;
}
/**
* Returns standard deviation to be used for Gaussian random value
* generation.
*
* @return Standard deviation.
*/
public double getStandardDeviation() {
return standardDeviation;
}
/**
* Sets standard deviation to be used for Gaussian random value generation.
*
* @param standardDeviation Standard deviation.
* @throws IllegalArgumentException exception thrown if provided standard
* deviation is negative or zero.
*/
public void setStandardDeviation(final double standardDeviation) {
if (standardDeviation <= 0.0) {
throw new IllegalArgumentException();
}
this.standardDeviation = standardDeviation;
}
/**
* Returns next random boolean value. The probability of returning true
* is equal to obtaining a Gaussian value below the mMean, which is 50%.
*
* @return Next boolean value.
*/
@Override
public boolean nextBoolean() {
return nextBoolean(mean);
}
/**
* Returns next random boolean value. The probability of returning true
* is equal to obtaining a Gaussian value below the provided threshold,
* which is equal to erfc function.
*
* @param threshold Threshold to determine whether returned values will be
* true or false.
* @return Next random boolean value.
*/
public boolean nextBoolean(final double threshold) {
return (standardDeviation * getInternalRandom().nextGaussian() + mean) < threshold;
}
/**
* Fills provided array with random booleans where the probability
* of returning true is equal to obtaining a Gaussian value below the
* provided threshold, which is equal to erfc function.
*
* @param array array to be filled.
* @param threshold Threshold to determine whether generated values will be
* true or false.
*/
public void fill(final boolean[] array, final double threshold) {
for (int i = 0; i < array.length; i++) {
array[i] = nextBoolean(threshold);
}
}
/**
* Returns array of booleans having provided length and containing random
* boolean values. The probability of returning true is equal to
* obtaining a Gaussian value below the provided threshold, which is equal
* to erfc function.
*
* @param length Length of array to be created.
* @param threshold Threshold to determine whether returned values will be
* true or false.
* @return Array of random booleans.
* @throws IllegalArgumentException if provided length is zero or negative.
*/
public boolean[] nextBooleans(final int length, final double threshold) {
if (length <= 0) {
throw new IllegalArgumentException();
}
final var array = new boolean[length];
fill(array, threshold);
return array;
}
/**
* Returns next random Gaussian integer value having provided mMean and
* standard deviation.
*
* @return Next random Gaussian integer value.
*/
@Override
public int nextInt() {
return (int) (standardDeviation * getInternalRandom().nextGaussian() + mean);
}
/**
* Returns next random Gaussian long value having provided mMean and
* standard deviation.
*
* @return Next random Gaussian long value.
*/
@Override
public long nextLong() {
return (long) (standardDeviation * getInternalRandom().nextGaussian() + mean);
}
/**
* Returns next random Gaussian floating-point value having provided mMean
* and standard deviation.
*
* @return Next random Gaussian floating-point value.
*/
@Override
public float nextFloat() {
return (float) (standardDeviation * getInternalRandom().nextGaussian() + mean);
}
/**
* Returns next random Gaussian double precision floating-point value having
* provided mMean and standard deviation.
*
* @return Next random Gaussian double precision floating-point value.
*/
@Override
public double nextDouble() {
return standardDeviation * getInternalRandom().nextGaussian() + mean;
}
/**
* Returns the randomizer type of this instance.
*
* @return Randomizer type.
*/
@Override
public RandomizerType getType() {
return RandomizerType.GAUSSIAN_RANDOMIZER;
}
}