// // 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); } } } }