Accelerating the pace of engineering and science

# mle

Maximum likelihood estimates

## Syntax

• phat = mle(data)
• phat = mle(data,'distribution',dist) example
• phat = mle(data,'pdf',pdf,'start',start)
• phat = mle(data,'pdf',pdf,'start',start,'cdf',cdf) example
• phat = mle(data,'logpdf',logpdf,'start',start)
• phat = mle(data,'logpdf',logpdf,'start',start,'logsf',logsf) example
• phat = mle(data,'nloglf',nloglf,'start',start) example
• phat = mle(___,Name,Value)
• [phat,pci] = mle(___) example

## Description

phat = mle(data) returns maximum likelihood estimates (MLEs) for the parameters of a normal distribution, using the sample data in the vector data.

example

phat = mle(data,'distribution',dist) returns parameter estimates for a distribution specified by dist.

phat = mle(data,'pdf',pdf,'start',start) returns parameter estimates for a custom distribution specified by the probability density function pdf. You must also specify the initial parameter values, start.

example

phat = mle(data,'pdf',pdf,'start',start,'cdf',cdf) returns parameter estimates for a custom distribution specified by the probability density function pdf and custom cumulative distribution function cdf.

phat = mle(data,'logpdf',logpdf,'start',start) returns parameter estimates for a custom distribution specified by the log probability density function logpdf. You must also specify the initial parameter values, start.

example

phat = mle(data,'logpdf',logpdf,'start',start,'logsf',logsf) returns parameter estimates for a custom distribution specified by the log probability density function logpdf and custom log survival function logsf.

example

phat = mle(data,'nloglf',nloglf,'start',start) returns parameter estimates for the custom distribution specified by the negative loglikelihood function nloglf. You must also specify the initial parameter values, start.

phat = mle(___,Name,Value) also returns the parameter estimates with additional options specified by one or more name-value pair arguments. You can use any of the input arguments in the previous syntaxes.

example

[phat,pci] = mle(___) also returns the 95% confidence intervals for the parameters.

## Examples

expand all

### Estimate Parameters of Burr Distribution

`load carbig`

The variable MPG has the miles per gallon for different models of cars.

Draw a histogram of MPG data.

` hist(MPG)`

The distribution is somewhat right skewed. A symmetric distribution, such as normal distribution, might not be a good fit.

Estimate the parameters of the Burr Type XII distribution for the MPG data.

`phat = mle(MPG,'distribution','burr')`
```phat =

34.6447    3.7898    3.5722```

The maximum likelihood estimates for the scale parameter α is 34.6447. The estimates for the two shape parameters c and k of the Burr Type XII distribution are 3.7898 and 3.5722, respectively.

### Fit Custom Distribution to Censored Data

Navigate to a folder containing sample data.

```cd(matlabroot)
cd('help/toolbox/stats/examples')```

`load readmissiontimes`

The data includes ReadmissionTime, which has readmission times for 100 patients. The column vector Censored has the censorship information for each patient, where 1 indicates a censored observation, and 0 indicates the exact readmission time is observed. This is simulated data.

Define a custom probability density and cumulative distribution function.

```custpdf = @(data,lambda) lambda*exp(-lambda*data);
custcdf = @(data,lambda) 1-exp(-lambda*data);```

Estimate the parameter, lambda, of the custom distribution for the censored sample data.

```phat = mle(ReadmissionTime,'pdf',custpdf,...
'cdf',custcdf,'start',0.05,'Censoring',Censored)
phat```
```phat =

0.1096```

### Fit Custom Log pdf and Survival Function

Navigate to a folder containing sample data.

```cd(matlabroot)
cd('help/toolbox/stats/examples')```

`load readmissiontimes`

The data includes ReadmissionTime, which has readmission times for 100 patients. The column vector Censored has the censorship information for each patient, where 1 indicates a censored observation, and 0 indicates the exact readmission time is observed. This is simulated data.

Define a custom log probability density and survival function.

```custlogpdf = @(data,lambda,k) log(k)-k*log(lambda)...
+(k-1)*log(data)-(data/lambda).^k;
custlogsf = @(data,lambda,k) -(data/lambda).^k;
```

Estimate the parameters, lambda and k, of the custom distribution for the censored sample data.

```phat = mle(ReadmissionTime,'logpdf',custlogpdf,...
'logsf',custlogsf,'start',[1,0.75],'Censoring',Censored)```
```phat =

9.2090    1.4223```

The scale and shape parameters of the custom-defined distribution are 9.2090 and 1.4223, respectively.

### Fit Custom Log Negative Likelihood Function

Navigate to a folder containing sample data.

```cd(matlabroot)
cd('help/toolbox/stats/examples')```

`load readmissiontimes`

The data includes ReadmissionTime, which has readmission times for 100 patients. This is simulated data.

Define a negative log likelihood function.

```custnloglf=@(lambda,data,cens,freq) -length(data)*log(lambda)...
+ nansum(lambda*data);```

Estimate the parameters of the defined distribution.

`phat = mle(ReadmissionTime,'nloglf',custnloglf,'start',0.05)`
```phat =

0.1462```

### Estimate Probability of Success

Generate 100 random observations from a binomial distribution with the number of trials, n = 20, and the probability of success, p = 0.75.

```data = binornd(20,0.75,100,1);
```

Estimate the probability of success and 95% confidence limits using the simulated sample data.

```[phat,pci] = mle(data,'distribution','binomial',...
'alpha',.05,'ntrials',20)
```
```phat =
0.7370
pci =
0.7171
0.7562```

The estimate of probability of success is 0.737 and the lower and upper limits of the 95% confidence interval are 0.7171 and 0.7562. This interval covers the true value used to simulate the data.

## Input Arguments

expand all

### data — Sample datavector

Sample data mle uses to estimate the distribution parameters, specified as a vector.

Data Types: single | double

### dist — Distribution type'normal' (default) | string

Distribution type to estimate parameters for, specified as one of the following.

distDescriptionParameter 1Parameter 2Parameter 3
'bernoulli'Bernoulli Distributionp: probability of success for each trial
'beta' or 'Beta'Beta Distributionab
'bino' or 'Binomial'Binomial Distributionn: number of trialsp: probability of success for each trial
'birnbaumsaunders'Birnbaum-Saunders Distributionβ: scale γ: shape
'burr' or 'Burr'Burr Type XII Distributionα: scale c: first shape k: second shape
'Discrete Uniform' or 'unid'Uniform Distribution (Discrete)N: maximum observable value
'exp' or 'Exponential'Exponential Distributionμ: mean
'ev' or 'Extreme Value'Extreme Value Distributionμ: location σ: scale
'gam' or 'Gamma'Gamma Distributiona: shape b: scale
'gev' or 'Generalized Extreme Value'Generalized Extreme Value Distributionk: shape σ: scale μ: location
'gp' or 'Generalized Pareto'Generalized Pareto Distributionk: tail index (shape) σ: scale θ: threshold
'geo' or 'Geometric'Geometric Distributionp: probability
'inversegaussian'Inverse Gaussian Distributionμ: scale λ: shape
'logistic'Logistic Distributionμ: location σ: scale
'loglogistic'Loglogistic Distributionμ: log location σ: log scale
'logn' or 'Lognormal'Lognormal Distributionμ: log locationσ: log scale
'nakagami'Nakagami Distributionμ: shapeω: scale
'nbin' or 'Negative Binomial'Negative Binomial Distributionr: number of successesp: probability of success in a single trial
'norm' or 'Normal'Normal Distributionμ: location (mean) σ: scale (standard deviation)
'poiss' or 'Poisson'Poisson Distributionλ: mean
'rayl' or 'Rayleigh'Rayleigh Distributionb: scale
'rician'Rician Distributions: noncentrality σ: scale
'tlocationscale't Location-Scale Distributionμ: location σ: scale ν: degrees of freedom
'unif' or 'Uniform'Uniform Distribution (Continuous)a: lower endpoint (minimum)b: upper endpoint (maximum)
'wbl' or 'Weibull'Weibull Distributiona: scale b: shape

Example: 'rician'

### pdf — Custom probability density functionfunction handle

Custom probability distribution function, specified as a function handle created using @.

This custom function accepts the vector data and one or more individual distribution parameters as input parameters, and returns a vector of probability density values.

For example, if the name of the custom probability density function is newpdf, then you can specify the function handle in mle as follows.

Example: @newpdf

Data Types: function_handle

### cdf — Custom cumulative distribution functionfunction handle

Custom cumulative distribution function, specified as a function handle created using @.

This custom function accepts the vector data and one or more individual distribution parameters as input parameters, and returns a vector of cumulative probability values.

You must define cdf with pdf if data is censored and you use the 'censoring' name-value pair argument. If 'censoring' is not present, you do not have to specify cdf while using pdf.

For example, if the name of the custom cumulative distribution function is newcdf, then you can specify the function handle in mle as follows.

Example: @newcdf

Data Types: function_handle

### logpdf — Custom log probability density functionfunction handle

Custom log probability density function, specified as a function handle created using @.

This custom function accepts the vector data and one or more individual distribution parameters as input parameters, and returns a vector of log probability values.

For example, if the name of the custom log probability density function is customlogpdf, then you can specify the function handle in mle as follows.

Example: @customlogpdf

Data Types: function_handle

### logsf — Custom log survival functionfunction handle

Custom log survival function, specified as a function handle created using @.

This custom function accepts the vector data and one or more individual distribution parameters as input parameters, and returns a vector of log survival probability values.

You must define logsf with logpdf if data is censored and you use the 'censoring' name-value pair argument. If 'censoring' is not present, you do not have to specify logsf while using logpdf.

For example, if the name of the custom log survival function is logsurvival, then you can specify the function handle in mle as follows.

Example: @logsurvival

Data Types: function_handle

### nloglf — Custom negative loglikelihood functionfunction handle

Custom negative loglikelihood function, specified as a function handle created using @.

This custom function accepts the following input arguments.

 params Vector of distribution parameter values. mle detects the number of parameters from the number of elements in start. data Vector of data. cens Boolean vector of censored values. freq Vector of integer data frequencies.

nloglf must accept all four arguments even if you do not use the 'censoring' or 'frequency' name-value pair arguments. You can write 'nloglf' to ignore cens and freq arguments in that case.

nloglf returns a scalar negative loglikelihood value and optionally, a negative loglikelihood gradient vector (see the 'GradObj' field in 'options').

If the name of the custom negative log likelihood function is negloglik, then you can specify the function handle in mle as follows.

Example: @negloglik

Data Types: function_handle

### start — Initial parameter valuesscalar | vector

Initial parameter values for the custom functions, specified as a scalar value or a vector of scalar values.

Use start when you fit custom distributions, that is, when you use pdf and cdf, logpdf and logsf, or nloglf input arguments.

Example: 0.05

Example: [100,2]

Data Types: single | double

### Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'censoring',Cens,'alpha',0.01,'options',Opt specifies that mle estimates the parameters for the distribution of censored data specified by array Cens, computes the 99% confidence limits for the parameter estimates, and uses the algorithm control parameters specified by the structure Opt.

### 'censoring' — Indicator for censoringarray of 0s (default) | array of 0s and 1s

Indicator for censoring, specified as the comma-separated pair consisting of 'censoring' and a Boolean array of the same size as data. Use 1 for observations that are right censored and 0 for observations that are fully observed. The default is all observations are fully observed.

Censoring is not supported for all distributions.

For example, if the censored data information is in the binary array called Censored, then you can specify the censored data as follows.

Example: 'censoring',Censored

Data Types: logical

### 'frequency' — Frequency of observationsarray of 1s (default) | vector of nonnegative integer counts

Frequency of observations, specified as the comma-separated pair consisting of 'frequency' and an array containing nonnegative integer counts, which is the same size as data. The default is one observation per element of data.

For example, if the observation frequencies are stored in an array named Freq, you can specify the frequencies as follows.

Example: 'frequency',Freq

Data Types: single | double

### 'alpha' — Confidence level0.05 (default) | scalar value in the range (0,1)

Confidence level for the confidence interval of parameter estimates, pci, specified as the comma-separated pair consisting of 'alpha' and a scalar value in the range (0,1). The confidence level of pci is 100(1-alpha)% . The default is 0.05 for 95% confidence.

For example, for 99% confidence limits, you can specify the confidence level as follows.

Example: 'alpha',0.01

Data Types: single | double

### 'ntrials' — Number of trialsscalar value | vector

Number of trials for the corresponding element of data, specified as the comma-separated pair consisting of 'ntrials' and a scalar or a vector of the same size as data.

Applies only to binomial distribution.

Example: 'ntrials',total

Data Types: single | double

### 'options' — Fitting algorithm control parametersstructure

Fitting algorithm control parameters, specified as the comma-separated pair consisting of 'options' and a structure returned by statset.

Not applicable to all distributions.

Use the 'options' name-value pair argument to control details of the maximum likelihood optimization when fitting a custom distribution. For parameter names and default values, type statset('mlecustom'). You can set the options under a new name and use that in the name-value pair argument. mle interprets the following statset parameters for custom distribution fitting.

ParameterValue

Default is 'off'.

'on' or 'off', indicating whether or not fmincon can expect the custom function provided with the nloglf input argument to return the gradient vector of the negative log-likelihood as a second output.

mle ignores 'GradObj' when using fminsearch.

'DerivStep'

Default is eps^(1/3).

The relative difference, specified as a scalar or a vector the same size as start, used in finite difference derivative approximations when using fmincon, and 'GradObj' is 'off'.

mle ignores 'DerivStep' when using fminsearch.

'FunValCheck'

Default is 'on'.

'on' or 'off', indicating whether or not mle should check the values returned by the custom distribution functions for validity.

A poor choice of starting point can sometimes cause these functions to return NaNs, infinite values, or out-of-range values if they are written without suitable error checking.

'TolBnd'Default is 1e-6.

An offset for upper and lower bounds when using fmincon.

mle treats upper and lower bounds as strict inequalities, that is, open bounds. With fmincon, this is approximated by creating closed bounds inset from the specified upper and lower bounds by TolBnd.

Example: 'options',statset('mlecustom')

Data Types: struct

### 'lowerbound' — Lower bounds for distribution parameters – ∞ (default) | vector

Lower bounds for distribution parameters, specified as the comma-separated pair consisting of 'lowerbound' and a vector the same size as start.

This name-value pair argument is valid only when you use the pdf and cdf, logpdf and logcdf, or nloglf input arguments.

Example: 'lowerbound',0

Data Types: single | double

### 'upperbound' — Upper bounds for distribution parameters∞ (default) | vector

Upper bounds for distribution parameters, specified as the comma-separated pair consisting of 'upperbound' and a vector the same size as start.

This name-value pair argument is valid only when you use the pdf and cdf, logpdf and logsf, or nloglf input arguments.

Example: 'upperbound',1

Data Types: single | double

### 'optimfun' — Optimization function'fminsearch' (default) | 'fmincon'

Optimization function mle uses in maximizing the likelihood, specified as the comma-separated pair consisting of 'optimfun' and either 'fminsearch' or 'fmincon'.

Default is 'fminsearch'.

You can only specify 'fmincon' if Optimization Toolbox™ is available.

The 'optimfun' name-value pair argument is valid only when you fit custom distributions, that is, when you use the pdf and cdf, logpdf and logsf, or nloglf input arguments.

Example: 'optimfun','fmincon'

## Output Arguments

expand all

### phat — Parameter estimatesscalar value | row vector

Parameter estimates, returned as a scalar value or a row vector.

### pci — Confidence intervals for parameter estimates2-by-k matrix

Confidence intervals for parameter estimates, returned as a column vector or a matrix depending on the number of parameters, hence the size of phat.

pci is a 2-by-k matrix, where k is the number of parameters mle estimates. The first and second rows of the pci show the upper and lower confidence limits, respectively.

expand all

### Survival Function

The survival function is the probability of survival as a function of time. It is also called the survivor function. It gives the probability that the survival time of an individual exceeds a certain value. Since the cumulative distribution function, F(t), is the probability that the survival time is less than or equal to a given point in time, the survival function for a continuous distribution, S(t), is the complement of the cumulative distribution function: S(t) = 1 – F(t).

### Tips

When you supply distribution functions, mle computes the parameter estimates using an iterative maximization algorithm. With some models and data, a poor choice of starting point can cause mle to converge to a local optimum that is not the global maximizer, or to fail to converge entirely. Even in cases for which the log-likelihood is well-behaved near the global maximum, the choice of starting point is often crucial to convergence of the algorithm. In particular, if the initial parameter values are far from the MLEs, underflow in the distribution functions can lead to infinite log-likelihoods.