logncdf

Lognormal cumulative distribution function

Syntax

p = logncdf(x)

p = logncdf(x,mu)

p = logncdf(x,mu,sigma)

[p,pLo,pUp] = logncdf(x,mu,sigma,pCov)

[p,pLo,pUp] = logncdf(x,mu,sigma,pCov,alpha)

___ = logncdf(___,'upper')

Description

p = logncdf(x) returns the cumulative distribution function (cdf) of the standard lognormal distribution, evaluated at the values in x. In the standard lognormal distribution, the mean and standard deviation of logarithmic values are 0 and 1, respectively.

p = logncdf(x,mu) returns the cdf of the lognormal distribution with the distribution parameters mu (mean of logarithmic values) and 1 (standard deviation of logarithmic values), evaluated at the values in x.

p = logncdf(x,mu,sigma) returns the cdf of the lognormal distribution with the distribution parameters mu (mean of logarithmic values) and sigma (standard deviation of logarithmic values), evaluated at the values in x.

[p,pLo,pUp] = logncdf(x,mu,sigma,pCov) also returns the 95% confidence bounds [pLo,pUp] of p using the estimated parameters (mu and sigma) and their covariance matrix pCov.

[p,pLo,pUp] = logncdf(x,mu,sigma,pCov,alpha) specifies the confidence level for the confidence interval [pLo,pUp] to be 100(1–alpha)%.

___ = logncdf(___,'upper') returns the complement of the cdf, evaluated at the values in x, using an algorithm that more accurately computes the extreme upper-tail probabilities. 'upper' can follow any of the input argument combinations in the previous syntaxes.

Examples

Compute Lognormal Distribution cdf

Compute the cdf values evaluated at the values in x for the lognormal distribution with mean mu and standard deviation sigma.

x = 0:0.2:10;
mu = 0;
sigma = 1;
p = logncdf(x,mu,sigma);

Plot the cdf.

plot(x,p)
grid on
xlabel('x')
ylabel('p')

Confidence Interval of Lognormal cdf Value

Find the maximum likelihood estimates (MLEs) of the lognormal distribution parameters, and then find the confidence interval of the corresponding cdf value.

Generate 1000 random numbers from the lognormal distribution with the parameters 5 and 2.

rng('default') % For reproducibility
n = 1000; % Number of samples
x = lognrnd(5,2,n,1);

Find the MLEs for the distribution parameters (mean and standard deviation of logarithmic values) by using mle.

phat = mle(x,'distribution','LogNormal')

phat = 1×2

    4.9347    1.9969

muHat = phat(1);
sigmaHat = phat(2);

Estimate the covariance of the distribution parameters by using lognlike. The function lognlike returns an approximation to the asymptotic covariance matrix if you pass the MLEs and the samples used to estimate the MLEs.

[~,pCov] = lognlike(phat,x)

pCov = 2×2

    0.0040   -0.0000
   -0.0000    0.0020

Find the cdf value at 0.5 and its 95% confidence interval.

[p,pLo,pUp] = logncdf(0.5,muHat,sigmaHat,pCov)

p = 
0.0024

pLo = 
0.0016

pUp = 
0.0037

p is the cdf value of the lognormal distribution with the parameters muHat and sigmaHat. The interval [pLo,pUp] is the 95% confidence interval of the cdf evaluated at 0.5, considering the uncertainty of muHat and sigmaHat using pCov. The 95% confidence interval means the probability that [pLo,pUp] contains the true cdf value is 0.95.

Complementary cdf (Tail Distribution)

Determine the probability that an observation from a standard lognormal distribution will fall on the interval [exp(10),Inf].

p1 = 1 - logncdf(exp(10))

p1 = 
0

logncdf(exp(10)) is nearly 1, so p1 becomes 0. Specify 'upper' so that logncdf computes the extreme upper-tail probabilities more accurately.

p2 = logncdf(exp(10),'upper')

p2 = 
7.6199e-24

You can also use 'upper' to compute a right-tailed p-value.

Input Arguments

x — Values at which to evaluate cdf

positive scalar value | array of positive scalar values

Values at which to evaluate the cdf, specified as a positive scalar value or an array of positive scalar values.

If you specify pCov to compute the confidence interval [pLo,pUp], then x must be a scalar value.

To evaluate the cdf at multiple values, specify x using an array. To evaluate the cdfs of multiple distributions, specify mu and sigma using arrays. If one or more of the input arguments x, mu, and sigma are arrays, then the array sizes must be the same. In this case, logncdf expands each scalar input into a constant array of the same size as the array inputs. Each element in p is the cdf value of the distribution specified by the corresponding elements in mu and sigma, evaluated at the corresponding element in x.

Example: [-1,0,3,4]

Data Types: single | double

mu — Mean of logarithmic values

0 (default) | scalar value | array of scalar values

Mean of logarithmic values for the lognormal distribution, specified as a scalar value or an array of scalar values.

If you specify pCov to compute the confidence interval [pLo,pUp], then mu must be a scalar value.

To evaluate the cdf at multiple values, specify x using an array. To evaluate the cdfs of multiple distributions, specify mu and sigma using arrays. If one or more of the input arguments x, mu, and sigma are arrays, then the array sizes must be the same. In this case, logncdf expands each scalar input into a constant array of the same size as the array inputs. Each element in p is the cdf value of the distribution specified by the corresponding elements in mu and sigma, evaluated at the corresponding element in x.

Example: [0 1 2; 0 1 2]

Data Types: single | double

sigma — Standard deviation of logarithmic values

1 (default) | positive scalar value | array of positive scalar values

Standard deviation of logarithmic values for the lognormal distribution, specified as a positive scalar value or an array of positive scalar values.

If you specify pCov to compute the confidence interval [pLo,pUp], then sigma must be a scalar value.

To evaluate the cdf at multiple values, specify x using an array. To evaluate the cdfs of multiple distributions, specify mu and sigma using arrays. If one or more of the input arguments x, mu, and sigma are arrays, then the array sizes must be the same. In this case, logncdf expands each scalar input into a constant array of the same size as the array inputs. Each element in p is the cdf value of the distribution specified by the corresponding elements in mu and sigma, evaluated at the corresponding element in x.

Example: [1 1 1; 2 2 2]

Data Types: single | double

pCov — Covariance of estimates

2-by-2 numeric matrix

Covariance of the estimates mu and sigma, specified as a 2-by-2 matrix.

If you specify pCov to compute the confidence interval [pLo,pUp], then x, mu, and sigma must be scalar values.

You can estimate the maximum likelihood estimates of mu and sigma by using mle, and estimate the covariance of mu and sigma by using lognlike. For an example, see Confidence Interval of Lognormal cdf Value.

Data Types: single | double

alpha — Significance level

0.05 (default) | scalar in the range (0,1)

Significance level for the confidence interval, specified as a scalar in the range (0,1). The confidence level is 100(1–alpha)%, where alpha is the probability that the confidence interval does not contain the true value.

Example: 0.01

Data Types: single | double

Output Arguments

p — cdf values

scalar value | array of scalar values

cdf values, evaluated at the values in x, returned as a scalar value or an array of scalar values. p is the same size as x, mu, and sigma after any necessary scalar expansion. Each element in p is the cdf value of the distribution specified by the corresponding elements in mu and sigma, evaluated at the corresponding element in x.

pLo — Lower confidence bound for p

scalar value | array of scalar values

Lower confidence bound for p, returned as a scalar value or an array of scalar values. pLo has the same size as p.

pUp — Upper confidence bound for p

scalar value | array of scalar values

Upper confidence bound for p, returned as a scalar value or an array of scalar values. pUp has the same size as p.

More About

Lognormal Distribution

The lognormal distribution is a probability distribution whose logarithm has a normal distribution.

The cumulative distribution function (cdf) of the lognormal distribution is

$$p=F(x|\mu ,\sigma )=\frac{1}{\sigma \sqrt{2\pi }}{\displaystyle {\int }_0^x\frac{1}{t}}\exp \left\{\frac{-{(\log t-\mu )}^2}{2{\sigma }^2}\right\}dt,\text{for}x>0.$$

Algorithms

• The logncdf function uses the complementary error function erfc. The relationship between logncdf and erfc is

  $$\text{logncdf}(x,0,1)=\frac{1}{2}\text{erfc}\left(-\frac{\log x}{\sqrt{2}}\right).$$

  The complementary error function erfc(x) is defined as

  $$\text{erfc}(x)=1-\text{erf}(x)=\frac{2}{\sqrt{\pi }}{\displaystyle {\int }_x^{\infty }{e}^{-t^2}dt}.$$

• The logncdf function computes confidence bounds for p by using the delta method. The normal distribution cdf value of log(x) with the parameters mu and sigma is equivalent to the cdf value of (log(x)–mu)/sigma with the parameters 0 and 1. Therefore, the logncdf function estimates the variance of (log(x)–mu)/sigma using the covariance matrix of mu and sigma by the delta method, and finds the confidence bounds of (log(x)–mu)/sigma using the estimates of this variance. Then, the function transforms the bounds to the scale of p. The computed bounds give approximately the desired confidence level when you estimate mu, sigma, and pCov from large samples.

Alternative Functionality

• logncdf is a function specific to lognormal distribution. Statistics and Machine Learning Toolbox™ also offers the generic function cdf, which supports various probability distributions. To use cdf, create a LognormalDistribution probability distribution object and pass the object as an input argument or specify the probability distribution name and its parameters. Note that the distribution-specific function logncdf is faster than the generic function cdf.

• Use the Probability Distribution Function app to create an interactive plot of the cumulative distribution function (cdf) or probability density function (pdf) for a probability distribution.

References

[1] Abramowitz, M., and I. A. Stegun. Handbook of Mathematical Functions. New York: Dover, 1964.

[2] Evans, M., N. Hastings, and B. Peacock. Statistical Distributions. 2nd ed., Hoboken, NJ: John Wiley & Sons, Inc., 1993.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

This function fully supports GPU arrays. For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

Version History

Introduced before R2006a