//
// Math.NET Numerics, part of the Math.NET Project
// http://numerics.mathdotnet.com
// http://github.com/mathnet/mathnet-numerics
// http://mathnetnumerics.codeplex.com
// Copyright (c) 2009-2010 Math.NET
// Permission is hereby granted, free of charge, to any person
// obtaining a copy of this software and associated documentation
// files (the "Software"), to deal in the Software without
// restriction, including without limitation the rights to use,
// copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following
// conditions:
// The above copyright notice and this permission notice shall be
// included in all copies or substantial portions of the Software.
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
// OTHER DEALINGS IN THE SOFTWARE.
//
using MathNet.Numerics.Properties;
using MathNet.Numerics.Statistics;
using System.Collections.Generic;
namespace MathNet.Numerics.Distributions
{
using System;
///
/// Implements the univariate Normal (or Gaussian) distribution. For details about this distribution, see
/// Wikipedia - Normal distribution.
///
/// The distribution will use the by default.
/// Users can get/set the random number generator by using the property.
/// The statistics classes will check all the incoming parameters whether they are in the allowed
/// range. This might involve heavy computation. Optionally, by setting Control.CheckDistributionParameters
/// to false, all parameter checks can be turned off.
public class Normal : IContinuousDistribution
{
///
/// Keeps track of the mean of the normal distribution.
///
double _mean;
///
/// Keeps track of the standard deviation of the normal distribution.
///
double _stdDev;
///
/// The distribution's random number generator.
///
Random _random;
///
/// Initializes a new instance of the Normal class. This is a normal distribution with mean 0.0
/// and standard deviation 1.0. The distribution will
/// be initialized with the default random number generator.
///
public Normal()
: this(0.0, 1.0)
{
}
///
/// Initializes a new instance of the Normal class. This is a normal distribution with mean 0.0
/// and standard deviation 1.0. The distribution will
/// be initialized with the default random number generator.
///
/// The random number generator which is used to draw random samples.
public Normal(Random randomSource)
: this(0.0, 1.0, randomSource)
{
}
///
/// Initializes a new instance of the Normal class with a particular mean and standard deviation. The distribution will
/// be initialized with the default random number generator.
///
/// The mean of the normal distribution.
/// The standard deviation of the normal distribution.
public Normal(double mean, double stddev)
{
_random = new Random();
SetParameters(mean, stddev);
}
///
/// Initializes a new instance of the Normal class with a particular mean and standard deviation. The distribution will
/// be initialized with the default random number generator.
///
/// The mean of the normal distribution.
/// The standard deviation of the normal distribution.
/// The random number generator which is used to draw random samples.
public Normal(double mean, double stddev, Random randomSource)
{
_random = randomSource ?? new Random();
SetParameters(mean, stddev);
}
///
/// Constructs a normal distribution from a mean and standard deviation. The distribution will
/// be initialized with the default random number generator.
///
/// The mean of the normal distribution.
/// The standard deviation of the normal distribution.
/// a normal distribution.
public static Normal WithMeanStdDev(double mean, double stddev)
{
return new Normal(mean, stddev);
}
///
/// Constructs a normal distribution from a mean and variance. The distribution will
/// be initialized with the default random number generator.
///
/// The mean of the normal distribution.
/// The variance of the normal distribution.
/// a normal distribution.
public static Normal WithMeanVariance(double mean, double var)
{
return new Normal(mean, Math.Sqrt(var));
}
///
/// Constructs a normal distribution from a mean and precision. The distribution will
/// be initialized with the default random number generator.
///
/// The mean of the normal distribution.
/// The precision of the normal distribution.
/// a normal distribution.
public static Normal WithMeanPrecision(double mean, double precision)
{
return new Normal(mean, 1.0/Math.Sqrt(precision));
}
///
/// Estimates the normal distribution parameters from sample data with maximum-likelihood.
///
public static Normal Estimate(IEnumerable samples)
{
var meanVariance = samples.MeanVariance();
return new Normal(meanVariance.Item1, Math.Sqrt(meanVariance.Item2));
}
///
/// A string representation of the distribution.
///
/// a string representation of the distribution.
public override string ToString()
{
return "Normal(Mean = " + _mean + ", StdDev = " + _stdDev + ")";
}
///
/// Checks whether the parameters of the distribution are valid.
///
/// The mean of the normal distribution.
/// The standard deviation of the normal distribution.
/// true when the parameters are valid, false otherwise.
static bool IsValidParameterSet(double mean, double stddev)
{
if (stddev < 0.0 || Double.IsNaN(mean) || Double.IsNaN(stddev))
{
return false;
}
return true;
}
///
/// Sets the parameters of the distribution after checking their validity.
///
/// The mean of the normal distribution.
/// The standard deviation of the normal distribution.
/// When the parameters don't pass the function.
void SetParameters(double mean, double stddev)
{
if (Control.CheckDistributionParameters && !IsValidParameterSet(mean, stddev))
{
throw new ArgumentOutOfRangeException(Resources.InvalidDistributionParameters);
}
_mean = mean;
_stdDev = stddev;
}
///
/// Gets or sets the precision of the normal distribution.
///
public double Precision
{
get { return 1.0/(_stdDev*_stdDev); }
set
{
var sdev = 1.0/Math.Sqrt(value);
// Handle the case when the precision is -0.
if (Double.IsInfinity(sdev))
{
sdev = Double.PositiveInfinity;
}
SetParameters(_mean, sdev);
}
}
///
/// Gets or sets the random number generator which is used to draw random samples.
///
public Random RandomSource
{
get { return _random; }
set
{
if (value == null)
{
throw new ArgumentNullException();
}
_random = value;
}
}
///
/// Gets or sets the mean of the normal distribution.
///
public double Mean
{
get { return _mean; }
set { SetParameters(value, _stdDev); }
}
///
/// Gets or sets the variance of the normal distribution.
///
public double Variance
{
get { return _stdDev*_stdDev; }
set { SetParameters(_mean, Math.Sqrt(value)); }
}
///
/// Gets or sets the standard deviation of the normal distribution.
///
public double StdDev
{
get { return _stdDev; }
set { SetParameters(_mean, value); }
}
///
/// Gets the entropy of the normal distribution.
///
public double Entropy
{
get { return Math.Log(_stdDev) + Constants.LogSqrt2PiE; }
}
///
/// Gets the skewness of the normal distribution.
///
public double Skewness
{
get { return 0.0; }
}
///
/// Gets the mode of the normal distribution.
///
public double Mode
{
get { return _mean; }
}
///
/// Gets the median of the normal distribution.
///
public double Median
{
get { return _mean; }
}
///
/// Gets the minimum of the normal distribution.
///
public double Minimum
{
get { return Double.NegativeInfinity; }
}
///
/// Gets the maximum of the normal distribution.
///
public double Maximum
{
get { return Double.PositiveInfinity; }
}
///
/// Computes the density of the normal distribution (PDF), i.e. dP(X <= x)/dx.
///
/// The mean of the normal distribution.
/// The standard deviation of the normal distribution.
/// The location at which to compute the density.
/// the density at .
internal static double Density(double mean, double sdev, double x)
{
var d = (x - mean)/sdev;
return Math.Exp(-0.5*d*d)/(Constants.Sqrt2Pi*sdev);
}
///
/// Computes the log density of the normal distribution (lnPDF), i.e. ln(dP(X <= x)/dx).
///
/// The mean of the normal distribution.
/// The standard deviation of the normal distribution.
/// The location at which to compute the density.
/// the log density at .
internal static double DensityLn(double mean, double sdev, double x)
{
var d = (x - mean)/sdev;
return (-0.5*d*d) - Math.Log(sdev) - Constants.LogSqrt2Pi;
}
///
/// Computes the density of the normal distribution (PDF), i.e. dP(X <= x)/dx.
///
/// The location at which to compute the density.
/// the density at .
public double Density(double x)
{
return Density(_mean, _stdDev, x);
}
///
/// Computes the log density of the normal distribution (lnPDF), i.e. ln(dP(X <= x)/dx).
///
/// The location at which to compute the log density.
/// the log density at .
public double DensityLn(double x)
{
return DensityLn(_mean, _stdDev, x);
}
///
/// Computes the cumulative distribution function (CDF) of the normal distribution, i.e. P(X <= x).
///
/// The mean of the normal distribution.
/// The standard deviation of the normal distribution.
/// The location at which to compute the cumulative density.
/// the cumulative density at .
internal static double CumulativeDistribution(double mean, double sdev, double x)
{
return 0.5*(1.0 + SpecialFunctions.Erf((x - mean)/(sdev*Constants.Sqrt2)));
}
///
/// Computes the cumulative distribution function (CDF) of the normal distribution, i.e. P(X <= x).
///
/// The location at which to compute the cumulative density.
/// the cumulative density at .
public double CumulativeDistribution(double x)
{
return CumulativeDistribution(_mean, _stdDev, x);
}
///
/// Computes the inverse cumulative distribution function of the normal distribution.
///
/// The location at which to compute the inverse cumulative density.
/// the inverse cumulative density at .
public double InverseCumulativeDistribution(double p)
{
return _mean - (_stdDev*Math.Sqrt(2.0)*SpecialFunctions.ErfcInv(2.0*p));
}
///
/// Samples a pair of standard normal distributed random variables using the Box-Muller algorithm.
///
/// The random number generator to use.
/// a pair of random numbers from the standard normal distribution.
internal static Tuple SampleUncheckedBoxMuller(Random rnd)
{
var v1 = (2.0*rnd.NextDouble()) - 1.0;
var v2 = (2.0*rnd.NextDouble()) - 1.0;
var r = (v1*v1) + (v2*v2);
while (r >= 1.0 || r == 0.0)
{
v1 = (2.0*rnd.NextDouble()) - 1.0;
v2 = (2.0*rnd.NextDouble()) - 1.0;
r = (v1*v1) + (v2*v2);
}
var fac = Math.Sqrt(-2.0*Math.Log(r)/r);
return new Tuple(v1*fac, v2*fac);
}
///
/// Samples the distribution.
///
/// The random number generator to use.
/// The mean of the normal distribution from which to generate samples.
/// The standard deviation of the normal distribution from which to generate samples.
/// a random number from the distribution.
internal static double SampleUnchecked(Random rnd, double mean, double stddev)
{
return mean + (stddev*SampleUncheckedBoxMuller(rnd).Item1);
}
///
/// Generates a sample from the normal distribution using the Box-Muller algorithm.
///
/// a sample from the distribution.
public double Sample()
{
return SampleUnchecked(RandomSource, _mean, _stdDev);
}
///
/// Generates a sequence of samples from the normal distribution using the Box-Muller algorithm.
///
/// a sequence of samples from the distribution.
public IEnumerable Samples()
{
while (true)
{
var sample = SampleUncheckedBoxMuller(RandomSource);
yield return _mean + (_stdDev*sample.Item1);
yield return _mean + (_stdDev*sample.Item2);
}
}
///
/// Generates a sample from the normal distribution using the Box-Muller algorithm.
///
/// The random number generator to use.
/// The mean of the normal distribution from which to generate samples.
/// The standard deviation of the normal distribution from which to generate samples.
/// a sample from the distribution.
public static double Sample(Random rnd, double mean, double stddev)
{
if (Control.CheckDistributionParameters && !IsValidParameterSet(mean, stddev))
{
throw new ArgumentOutOfRangeException(Resources.InvalidDistributionParameters);
}
return SampleUnchecked(rnd, mean, stddev);
}
///
/// Generates a sequence of samples from the normal distribution using the Box-Muller algorithm.
///
/// The random number generator to use.
/// The mean of the normal distribution from which to generate samples.
/// The standard deviation of the normal distribution from which to generate samples.
/// a sequence of samples from the distribution.
public static IEnumerable Samples(Random rnd, double mean, double stddev)
{
if (Control.CheckDistributionParameters && !IsValidParameterSet(mean, stddev))
{
throw new ArgumentOutOfRangeException(Resources.InvalidDistributionParameters);
}
while (true)
{
var sample = SampleUncheckedBoxMuller(rnd);
yield return mean + (stddev*sample.Item1);
yield return mean + (stddev*sample.Item2);
}
}
}
}