MixEst distribution structures expose functionality through structure fields which are (mostly) function handles. Here is the list of common fields available in all distributions (in no special order).
name
Distribution name
Syntax
str = D.name()
Description
str = D.name() returns the name of the distribution D as a string.
Note: You need to include the parentheses () for this to work.
Example
D = mvnfactory(1); D.name()
ans = mvn
M
Distribution parameter manifold.
Syntax
D.M
Example
D = mvnfactory(2); D.M.name()
ans = Product manifold: [mu: Euclidean space R^(2x1)] x [sigma: SPD manifold (2, 2)]
dim
Parameter space dimensions
Syntax
dim = D.dim()
Description
dim = D.dim() returns the dimensions of the parameter space of the distribution D.
Note: You need to include the parentheses () for this to work.
Example
The parameter space dimensions of a multi-variate normal distribution defined over a 2-dimensional data space is 6: 2 for the mean vector and 4 for the 2-by-2 covariance matrix.
D = mvnfactory(2); dim = D.dim()
dim = 6
datadim
Data space dimensions
Syntax
n = D.datadim()
Description
n = D.datadim() returns the dimensions of the data space where the distribution D is defined.
Note: You need to include the parentheses () for this to work.
Example
The following example creates a multi-variate normal distribution defined over a 2-dimensional data space and calls datadim to get its data-space dimensions.
D = mvnfactory(2); n = D.datadim()
n = 2
ll
Log-likelihood
Syntax
ll = D.ll(theta, data) [ll, store] = D.ll(theta, data, store)
Description
ll = D.ll(theta, data) returns the total log-likelihood of the distribution D calculated over data, given the distribution parameters theta.
[ll, store] = D.ll(theta, data, store) can be used for caching purposes as described here.
For information about the parameter input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.
Example
% create a distribution and random parameters D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % find the log-likelihood ll = D.ll(theta, data)
llvec
Log-likelihood for each data point
Syntax
llvec = D.llvec(theta, data) [llvec, store] = D.llvec(theta, data, store)
Description
llvec = D.llvec(theta, data) returns the log-likelihood for each point in data as a 1-by-N vector where N is the number of data points. theta is the distribution parameters.
[llvec, store] = D.llvec(theta, data, store) can be used for caching purposes as described here.
For information about the parameter input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.
Example
% create a distribution and random parameters D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % find the log-likelihood vector llvec = D.llvec(theta, data)
llgrad
Gradient of the log-likelihood, with respect to parameters
Syntax
dll = D.llgrad(theta, data) [dll, store] = D.llgrad(theta, data, store)
Description
dll = D.llgrad(theta, data) returns the (Euclidean) gradient of the log-likelihood (of the distribution D calculated over data, given the distribution parameters theta), with respect to parameters, in the parameter structure dll.
[dll, store] = D.llgrad(theta, data, store) can be used for caching purposes as described here.
For information about the parameter input theta and output dll, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.
Example
% create a distribution and random parameters D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % This is how you should call the functions if you % need the log-likelihood along with its gradient, in % order to share the common intermediate variables: [ll, store] = D.ll(theta, data); dll = D.llgrad(theta, data, store);
llgraddata
Gradient of the log-likelihood, with respect to data
Syntax
dld = D.llgraddata(theta, data) [dld, store] = D.llgraddata(theta, data, store)
Description
dld = D.llgraddata(theta, data) returns the (Euclidean) gradient of the log-likelihood (of the distribution D calculated over data, given the distribution parameters theta), with respect to each data point, in the n-by-N vector dld, where n is the data dimensions and N is the number of data points.
[dld, store] = D.llgraddata(theta, data, store) can be used for caching purposes as described here.
For information about the parameter input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.
Example
% create a distribution and random parameters D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % This is how you should call the functions if you % need the log-likelihood along with its gradient, in % order to share the common intermediate variables: [ll, store] = D.ll(theta, data); dld = D.llgraddata(theta, data, store);
cdf
Cumulative distribution function
Syntax
y = D.cdf(theta, data)
Description
y = D.cdf(theta, data) returns the cumulative distribution function (CDF) of the distribution D evaluated at points in data, given the distribution parameters theta. y is a 1-by-N vector where N is the number of data points.
For information about the parameter input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.
Example
% create a distribution and random parameters D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % find the CDF on data y = D.cdf(theta, data)
Probability density function
Syntax
y = D.pdf(theta, data)
Description
y = D.pdf(theta, data) returns the probability density function (PDF) of the distribution D evaluated at points in data, given the distribution parameters theta. y is a 1-by-N vector where N is the number of data points.
For information about the parameter input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.
Example
% create a distribution and random parameters D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % find the PDF on data y = D.pdf(theta, data)
sample
Generate random samples
Syntax
data = D.sample(theta) data = D.sample(theta, num)
Description
data = D.sample(theta) generates a random sample drawn from the distribution D, given the distribution parameters theta. data is an n-by-1 vector where n is the dimensions of the data space.
data = D.sample(theta, num) generates num random samples. data is an n-by-num matrix.
Example
Generate 1000 random samples from an N(0,1) distribution:
D = mvnfactory(1); theta = struct('mu', 0, 'sigma', 1); data = D.sample(theta, 1000)
randparam
Generate random parameters for the distribution
Syntax
theta = D.randparam()
Description
theta = D.randparam() generates a valid random parameter structure for the distribution D.
Note: You need to include the parentheses () for this to work.
For more information about the output theta, see Distribution Parameters Structure.
Example
Generate a random parameter structure for a Gaussian distribution:
D = mvnfactory(1); theta = D.randparam()
init
Generate initial parameters appropriate for the given data
Syntax
theta = D.init(data) theta = D.init(data, ...)
Description
theta = D.init(data) generates suitable parameters to be used as the initial point for later estimation on data.
theta = D.init(data, ...) Some distributions may accept additional arguments for the init function. This should be mentioned in their specific documentation.
For information about the output theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.
Example
% create a mixture of two Gaussian distributions D = mixturefactory(mvnfactory(1), 2); % generate 1000 random data points data = [randn(1,500), randn(1,500)+5]; % find a suitable initialization point options.theta0 = D.init(data); % perform estimation theta = D.estimate(data, options)
estimate
Estimate distribution parameters to fit data
Syntax
theta = D.estimate(data) theta = D.estimate(data, options) [theta, D] = D.estimate(...) [theta, D, info] = D.estimate(...) [theta, D, info, options] = D.estimate(...)
Description
theta = D.estimate(data) returns estimated parameters for the distribution D, using data.
theta = D.estimate(data, options) utilizes applicable options from the options structure in the estimation procedure.
[theta, D] = D.estimate(...) also returns D, the distribution structure for which theta is applicable. (This is the same as the distribution structure D from which you called estimate, and so it should not normally be used. The purpose of including it in the output is to maintain compatibility with other estimation functions).
[theta, D, info] = D.estimate(...) also returns info, a structure array containing information about successive iterations performed by iterative estimation functions.
[theta, D, info, options] = D.estimate(...) also returns the effective options used, so you can see what default values the function used on top of the options you possibly specified.
For information about the output theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions. You may also want to read about options or info arguments.
Available Options
This function supports all the options described in estimation options.
Returned info fields
The fields present in the returned info structure array, depend on the solver used (options.solver). When a Manopt solver is specified, the info returned by the Manopt solver is returned directly. For the 'default' solver see the documentation of the 'estimatedefault' function for the specific distribution. You can read more at our documentation on estimation statistics structure.
Example
% create a Gaussian distribution D = mvnfactory(1); % generate 1000 random data points data = randn(1,1000) .* 2 + 1; % set some options options.solver = 'cg'; options.verbosity = 2; % fit distribution parameters to data theta = D.estimate(data, options)
penalizerparam
Generate parameter structure for the default penalization function
Syntax
penalizer_theta = D.penalizerparam(data)
Description
penalizer_theta = D.penalizerparam(data) returns the parameter structure for the default penalization function related to the distribution D, appropriate for data.
For more information on special penalization functions and their parameters for each distribution, refer to the documentation of that distribution.
The input argument data is described in Data Input Argument to Functions.
penalizercost
Cost penalty of the default penalization function
Syntax
costP = D.penalizercost(theta, penalizer_theta) [costP, store] = D.penalizercost(theta, penalizer_theta, store)
Description
costP = D.penalizercost(theta, penalizer_theta) returns the cost penalty calculated by the default penalization function related to the distribution D. theta is the distribution parameter structure and penalizer_theta represents the parameter structure for the penalization function.
[costP, store] = D.penalizercost(theta, penalizer_theta, store) can be used for caching purposes as described here.
The output of this function is used as a regularizer for the cost function during parameter estimation when penalization is turned on.
For information about the parameter input theta, see Distribution Parameters Structure. penalizer_theta can be obtained by calling penalizerparam.
penalizergrad
Gradient penalty of the default penalization function
Syntax
gradP = D.penalizergrad(theta, penalizer_theta) [gradP, store] = D.penalizergrad(theta, penalizer_theta, store)
Description
gradP = D.penalizergrad(theta, penalizer_theta) returns the (Euclidean) gradient penalty calculated by the default penalization function related to the distribution D. theta is the distribution parameter structure and penalizer_theta represents the parameter structure for the penalization function.
[gradP, store] = D.penalizergrad(theta, penalizer_theta, store) can be used for caching purposes as described here.
The output of this function is used as a regularizer for the cost-gradient function during parameter estimation when penalization is turned on.
For information about the parameter input theta and output gradP, see Distribution Parameters Structure. penalizer_theta can be obtained by calling penalizerparam.
sumparam
Sum of two parameter structures
Syntax
theta = D.sumparam(theta1, theta2)
Description
theta = D.sumparam(theta1, theta2) calculates the element-by-element sum of two parameter structures theta1 and theta2 of the distribution D. theta1 and theta2 can also be Euclidean gradients with respect to parameter distributions.
For information about the parameter structures theta, theta1 and theta2, see Distribution Parameters Structure.
Example
Following example shows how to add two Euclidean gradients of the log-likelihood with respect to parameters:
% create a distribution and random parameter values D = mvnfactory(1); theta1 = D.randparam(); theta2 = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % find Euclidean gradients of ll and penalizer dll1 = D.llgrad(theta1, data); dll2 = D.llgrad(theta2, data); % sum the gradients dllsum = D.sumparam(dll1, dll2)
scaleparam
Multiply parameter structure by a scalar
Syntax
theta = D.scaleparam(scalar, theta)
Description
theta = D.scaleparam(scalar, theta) calculates the product of the scalar scalar by the parameter structure theta of the distribution D.
For information about the parameter structure theta, see Distribution Parameters Structure.
Example
Following example shows how to negate the Euclidean gradient of the log-likelihood with respect to parameters:
% create a distribution and random parameter values D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % find Euclidean gradient of ll dll = D.llgrad(theta, data); % negate the gradient grad = D.scaleparam(-1, dll)
sumgrad
Sum of two Riemannian gradients
Syntax
rgrad = D.sumgrad(rgrad1, rgrad2, theta)
Description
rgrad = D.sumgrad(rgrad1, rgrad2, theta) calculates the sum of two Riemannian gradients rgrad1 and rgrad2 on the tangent space at the point theta on the parameter manifold of the distribution D. rgrad1 and rgrad2 should be obtained by D.M.egrad2rgrad from the corresponding Euclidean gradients.
For information about the parameter input theta, see Distribution Parameters Structure.
Example
Following example shows how to add the Riemannian gradients of the penalizer and log-likelihood at some parameter value:
% create a distribution and random parameter values D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % find Euclidean gradients of ll and penalizer dll = D.llgrad(theta, data); penalizer_theta = D.penalizerparam(data); gradP = D.penalizergrad(theta, penalizer_theta); % convert the gradients to Riemannian rdll = D.M.egrad2rgrad(theta, dll); rgradP = D.M.egrad2rgrad(theta, gradP); % sum the gradients grad = D.sumgrad(rdll, rgradP, theta)
scalegrad
Multiply Riemannian gradient by a scalar
Syntax
rgrad = D.scalegrad(scalar, rgrad, theta)
Description
rgrad = D.scalegrad(scalar, rgrad, theta) calculates the product of the scalar scalar by the Riemannian gradient rgrad, on the tangent space at the point theta on the parameter manifold of the distribution D. rgrad should be obtained by D.M.egrad2rgrad from the corresponding Euclidean gradient.
For information about the parameter input theta, see Distribution Parameters Structure.
Example
Following example shows how to negate the Riemannian gradient of the log-likelihood at some parameter value:
% create a distribution and random parameter values D = mvnfactory(1); theta = D.randparam(); % generate 1000 random data points data = randn(1, 1000); % find Euclidean gradient of ll dll = D.llgrad(theta, data); % convert the gradient to Riemannian rdll = D.M.egrad2rgrad(theta, dll); % negate the gradient grad = D.scalegrad(-1, rdll, theta)
entropy
Calculate entropy
Syntax
h = D.entropy(theta)
Description
h = D.entropy(theta) calculates the entropy of the distribution D given parameters theta.
For information about the parameter input theta, see Distribution Parameters Structure.
Example
% create a distribution and random parameter values D = mvnfactory(2); theta = D.randparam(); % find the entropy h = D.entropy(theta)
kl
Calculate Kullback–Leibler divergence
Syntax
kl = D.kl(theta1, theta2)
Description
kl = D.kl(theta1, theta2) calculates the KL divergence between the distribution D given parameters theta1 and the same distribution given parameters theta2.
For information about the parameter inputs theta1 and theta2, see Distribution Parameters Structure.
Example
% create a distribution and two random parameter structures D = mvnfactory(2); theta1 = D.randparam(); theta2 = D.randparam(); % find the KL divergence kl = D.kl(theta1, theta2)
AICc
Calculate corrected Akaike information criterion without the likelihood term
Syntax
aicc = D.AICc(data)
Description
aicc = D.AICc(data) calculates the corrected Akaike information criterion (AICc) of the distribution D for the given data, without the likelihood term. This should be added to the log-likelihood to obtain the full AICc (multiplied by -1/2).
The input argument data is described in Data Input Argument to Functions.
Example
% create a distribution and random parameters D = mvnfactory(2); theta = D.randparam(); % generate 1000 random data points data = randn(2, 1000); % find the AICc aicc = D.ll(theta, data) + D.AICc(data)
BIC
Calculate Bayesian information criterion without the likelihood term
Syntax
bic = D.BIC(data)
Description
bic = D.BIC(data) calculates the Bayesian information criterion (BIC) of the distribution D for the given data, without the likelihood term. This should be added to the log-likelihood to obtain the full BIC (multiplied by -1/2).
The input argument data is described in Data Input Argument to Functions.
Example
% create a distribution and random parameters D = mvnfactory(2); theta = D.randparam(); % generate 1000 random data points data = randn(2, 1000); % find the BIC bic = D.ll(theta, data) + D.BIC(data)
display
Display parameter values
Syntax
str = D.display(theta) D.display(theta)
Description
str = display(theta) returns a string containing information about the parameter values in theta.
D.display(theta) displays the distribution name along with information about the parameter values in theta.
For information about the parameter input theta, see Distribution Parameters Structure.
Example
% create a distribution and parameter structure D = mvnfactory(1); theta = struct('mu', [0;0], 'sigma', [2 1;3 4]); % display parameter values D.display(theta)
ans = mvn distribution parameters: mean (2-by-1): [0;0] covariance (2-by-2): [2 1;3 4]
selfsplit
Calculate the initial parameters for two splitted distributions to be substituted for current distribution (used in split-and-merge mixture estimation)
Syntax
[value1, value2] = D.selfsplit(theta, param_name) [value1, value2] = D.selfsplit(theta, param_name, method) [value1, value2] = D.selfsplit(theta, param_name, method, data) [value1, value2, store] = D.selfsplit(theta, param_name, method, data, store) [value1, value2, store, mixture_store] = D.selfsplit(theta, param_name, method, data, store, mixture_D, mixture_theta, idx, mixture_store)
selfmerge
Calculate the initial parameters for a merged distribution to be substituted for two distributions (used in split-and-merge mixture estimation)
Syntax
value = D.selfmerge(theta1, theta2, param_name, w1, w2) value = D.selfmerge(theta1, theta2, param_name, w1, w2, method) value = D.selfmerge(theta1, theta2, param_name, w1, w2, method, data) [value, store] = D.selfmerge(theta1, theta2, param_name, w1, w2, method, data, store) [value, store, mixture_store] = mvn_selfmerge(theta1, theta2, param_name, w1, w2, method, data, store, mixture_D, mixture_theta, idx1, idx2, mixture_store)