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