// // Math.NET Numerics, part of the Math.NET Project // http://mathnet.opensourcedotnet.info // // Copyright (c) 2009 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. // namespace MathNet.Numerics.Distributions { using System; using System.Collections.Generic; using Properties; /// /// Implements the univariate Log-Normal distribution. For details about this distribution, see /// Wikipedia - Log-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 LogNormal : IContinuousDistribution { /// /// Keeps track of the mu of the logarithm of the log-log-normal distribution. /// private double _mu; /// /// Keeps track of the standard deviation of the logarithm of the log-log-normal distribution. /// private double _sigma; /// /// The distribution's random number generator. /// private Random _random; /// /// Initializes a new instance of the Log-Normal class. The distribution will /// be initialized with the default random number generator. /// /// The mu of the logarithm of the distribution. /// The standard deviation of the logarithm of the distribution. public LogNormal(double mu, double sigma) { SetParameters(mu, sigma); RandomSource = new Random(); } /// /// A string representation of the distribution. /// /// a string representation of the distribution. public override string ToString() { return "LogNormal(Mu = " + _mu + ", Sigma = " + _sigma + ")"; } /// /// Checks whether the parameters of the distribution are valid. /// /// The mu of the logarithm of the distribution. /// The standard deviation of the logarithm of the distribution. /// True when the parameters are valid, false otherwise. private static bool IsValidParameterSet(double mu, double sigma) { if (sigma < 0.0 || Double.IsNaN(mu) || Double.IsNaN(mu) || Double.IsNaN(sigma)) { return false; } return true; } /// /// Sets the parameters of the distribution after checking their validity. /// /// The mu of the logarithm of the distribution. /// The standard deviation of the logarithm of the distribution. /// When the parameters don't pass the function. private void SetParameters(double mu, double sigma) { if (Control.CheckDistributionParameters && !IsValidParameterSet(mu, sigma)) { throw new ArgumentOutOfRangeException(Resources.InvalidDistributionParameters); } _mu = mu; _sigma = sigma; } /// /// Gets or sets the mean of the logarithm of the log-normal. /// public double Mu { get { return _mu; } set { SetParameters(value, _sigma); } } /// /// Gets or sets the standard deviation of the logarithm of the log-normal. /// public double Sigma { get { return _sigma; } set { SetParameters(_mu, value); } } #region IDistribution implementation /// /// 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 the mu of the log-normal distribution. /// public double Mean { get { return Math.Exp(_mu + _sigma * _sigma / 2.0); } } /// /// Gets the variance of the log-normal distribution. /// public double Variance { get { double sigma2 = _sigma * _sigma; return (Math.Exp(sigma2) - 1.0) * Math.Exp(_mu + _mu + sigma2); } } /// /// Gets the standard deviation of the log-normal distribution. /// public double StdDev { get { double sigma2 = _sigma * _sigma; return Math.Sqrt((Math.Exp(sigma2) - 1.0) * Math.Exp(_mu + _mu + sigma2)); } } /// /// Gets the entropy of the log-normal distribution. /// public double Entropy { get { return 0.5 + Math.Log(_sigma) + _mu + Constants.LogSqrt2Pi; } } /// /// Gets the skewness of the log-normal distribution. /// public double Skewness { get { double expsigma2 = Math.Exp(_sigma * _sigma); return (expsigma2 + 2.0) * Math.Sqrt(expsigma2 - 1); } } #endregion #region IContinuousDistribution implementation /// /// Gets the mode of the log-normal distribution. /// public double Mode { get { return Math.Exp(_mu - _sigma * _sigma); } } /// /// Gets the median of the log-normal distribution. /// public double Median { get { return Math.Exp(_mu); } } /// /// Gets the minimum of the log-normal distribution. /// public double Minimum { get { return 0.0; } } /// /// Gets the maximum of the log-normal distribution. /// public double Maximum { get { return Double.PositiveInfinity; } } /// /// Computes the density of the log-normal distribution. /// /// The location at which to compute the density. /// the density at . public double Density(double x) { if (x < 0.0) { return 0.0; } double a = (Math.Log(x) - _mu) / _sigma; return Math.Exp(-0.5 * a * a) / (x * _sigma * Constants.Sqrt2Pi); } /// /// Computes the log density of the log-normal distribution. /// /// The location at which to compute the log density. /// the log density at . public double DensityLn(double x) { if (x < 0.0) { return Double.NegativeInfinity; } double a = (Math.Log(x) - _mu) / _sigma; return -0.5 * a * a - Math.Log(x * _sigma) - Constants.LogSqrt2Pi; } /// /// Computes the cumulative distribution function of the log-normal distribution. /// /// The location at which to compute the cumulative density. /// the cumulative density at . public double CumulativeDistribution(double x) { if (x < 0.0) { return 0.0; } return 0.5 * (1.0 + SpecialFunctions.Erf((Math.Log(x) - _mu) / (_sigma * Constants.Sqrt2))); } /// /// Generates a sample from the log-normal distribution using the Box-Muller algorithm. /// /// a sample from the distribution. public double Sample() { double r2; return Math.Exp(_mu + (_sigma * Normal.SampleBoxMuller(RandomSource, out r2))); } /// /// Generates a sequence of samples from the log-normal distribution using the Box-Muller algorithm. /// /// a sequence of samples from the distribution. public IEnumerable Samples() { double r2; while (true) { double r1 = Normal.SampleBoxMuller(RandomSource, out r2); yield return Math.Exp(_mu + (_sigma * r1)); yield return Math.Exp(_mu + (_sigma * r2)); } } #endregion /// /// Generates a sample from the log-normal distribution using the Box-Muller algorithm. /// /// The random number generator to use. /// The mu of the logarithm of the distribution. /// The standard deviation of the logarithm of the distribution. /// a sample from the distribution. public static double Sample(Random rng, double mu, double sigma) { if (Control.CheckDistributionParameters && !IsValidParameterSet(mu, sigma)) { throw new ArgumentOutOfRangeException(Resources.InvalidDistributionParameters); } double r2; return Math.Exp(mu + (sigma * Normal.SampleBoxMuller(rng, out r2))); } /// /// Generates a sequence of samples from the log-normal distribution using the Box-Muller algorithm. /// /// The random number generator to use. /// The mu of the logarithm of the distribution. /// The standard deviation of the logarithm of the distribution. /// a sequence of samples from the distribution. public static IEnumerable Samples(Random rng, double mu, double sigma) { if (Control.CheckDistributionParameters && !IsValidParameterSet(mu, sigma)) { throw new ArgumentOutOfRangeException(Resources.InvalidDistributionParameters); } double r2; while (true) { double r1 = Normal.SampleBoxMuller(rng, out r2); yield return Math.Exp(mu + (sigma * r1)); yield return Math.Exp(mu + (sigma * r2)); } } } }