mixturefactory

mixturefactory

Construct a mixture distribution structure

Syntax

D = mixturefactory(ComponentD, num)
D = mixturefactory(ComponentD)

Description

D = mixturefactory(ComponentD, num) returns a structure representing a mixture distribution. ComponentD is a distribution structure defining mixture component distribution type, and num is the number of mixture components.

D = mixturefactory(ComponentD) where ComponentD is a cell array of distribution structures defined on the same data space, constructs a heterogeneous mixture distribution D where each component may be of a different distribution type.

Distribution Parameters

  • D (num-by-1 cell array of distribution parameter structures) : Contains the parameters for each component.
  • p (num-by-1 vector) : The vector of component weights.

Probability Density Function

The distribution has the following density:

$$ f(x)=\sum_{k=1}^{num} \pi_k f_k(x) $$

where $num$ is the number of components, $\pi_k$ is the weight for the k-th component, and $f_k$ represents the density function for the k-th component.

Example 1

% Construct a mixture of three bivariate normal distributions:
D = mixturefactory(mvnfactory(2), 3);
% Build a parameter structure for it:
theta.D{1} = struct('mu', [3; -1], 'sigma', [2 1; 3 4]);
theta.D{2} = struct('mu', [0; 3], 'sigma', [3 0; 0 4]);
theta.D{3} = struct('mu', [-4; -1], 'sigma', [4 0; 0 3]);
theta.p = [0.4; 0.3; 0.3];
% Plot the PDF:
x = -10:0.2:10;
y = -10:0.2:10;
[X, Y] = meshgrid(x, y);
data = [X(:) Y(:)]';
f = D.pdf(theta, data);
surf(X, Y, reshape(f, size(X)));

Example 2

% Construct a heterogeneous mixture distribution
% containing a gamma and a Gaussian component:
D = mixturefactory({gammafactory(); mvnfactory(1)});
% Build a parameter structure for it:
theta.D{1} = struct('a', 2, 'b', 1);
theta.D{2} = struct('mu', 7, 'sigma', 4);
theta.p = [0.7; 0.3];
% Plot the PDF:
x = 0:0.1:10;
plot(x, D.pdf(theta, x))

name

See distribution structure common members.

Flag to control the memory usage (resulting code will be slower)

M

See distribution structure common members.

num

Number of components (excluding any fixed components)

Syntax

num = D.num()

Description

num = D.num() returns the number of components in the mixture D. When some components are fixed, only the number of variable components is returned.

Note: You need to include the parentheses () for this to work.

numfixed

Number of fixed components

Syntax

numfixed = D.numfixed()

Description

numfixed = D.numfixed() returns the number of fixed components in the mixture D.

Note: You need to include the parentheses () for this to work.

numtotal

Total number of components

Syntax

numtotal = D.numtotal()

Description

numtotal = D.numtotal() returns the total number of components (variable and fixed) in the mixture D.

Note: You need to include the parentheses () for this to work.

nump

Number of elements in the component weight vector (theta.p)

Syntax

nump = D.nump()

Description

nump = D.nump() returns the number of elements in the component weight vector in the parameters for the mixture D. When there are no fixed components, this is the same as the number of mixture components. When some components are fixed, nump equals the number of variable components plus one, since in addition to the weights for the variable components, we store another weight which can scale the weights of the fixed components uniformly.

Note: You need to include the parentheses () for this to work.

component

Component distributions

Syntax

D_k = D.component(idx)

Description

D_k = D.component(idx) where idx is the index of a component, gives the component distribution structure at idx.

D_k = D.component(idx) where idx is an index vector with more than one element, returns a cell array of the distribution structures indexed in idx.

Valid range for the indices is from 1 to D.numtotal().

varD

Variable component distributions

Syntax

varD_k = D.varD(idx)

Description

varD_k = D.varD(idx) where idx is the index of a variable component, gives the variable component distribution structure at idx.

varD_k = D.varD(idx) where idx is an index vector with more than one element, returns a cell array of the variable distribution structures indexed in idx.

Valid range for the indices is from 1 to D.num().

fixedD

Fixed component distributions

Syntax

fixedD_k = D.fixedD(idx)

Description

fixedD_k = D.fixedD(idx) where idx is the index of a fixed component, gives the fixed component distribution structure at idx.

fixedD_k = D.fixedD(idx) where idx is an index vector with more than one element, returns a cell array of the fixed distribution structures indexed in idx.

Valid range for the indices is from 1 to D.numfixed().

fixedparam

Parameters stored for the fixed components

Syntax

fixedtheta = D.fixedparam()

Description

fixedtheta = D.fixedparam() returns the parameter structure stored for the fixed components in the mixture D. The number of elements in fixedtheta.D and fixedtheta.p equals D.numfixed().

Note: You need to include the parentheses () for this to work.

subparam

Extract a subset of component parameters

Syntax

subtheta = D.subparam(theta, idx)

Description

subtheta = D.subparam(theta, idx) returns the mixture parameter structure subtheta containing the parameters for the subset of components indexed by idx, from theta. An additional weight is added to subtheta.p to make the sum of the weights equal to one.

When some components are fixed, you can pass indices from D.num() + 1 to D.num() + D.numfixed(), to refer to fixed components.

fullparam

Get the parameters for the entire mixture, given variable component parameters

Syntax

fulltheta = D.fullparam(theta)

Description

fulltheta = D.fullparam(theta) can be used when some components are fixed, to obtain the parameters for all the components, given the partial parameters theta corresponding to the variable components.

addcomponent

Add a mixture component (to the variable components)

Syntax

newD = D.addcomponent(CmptD)
[newD, newtheta] = D.addcomponent(CmptD, theta, CmptTheta)

Description

newD = D.addcomponent(CmptD) returns newD, a mixture distribution with the same components as D plus the new variable component distribution CmptD.

[newD, newtheta] = D.addcomponent(CmptD, theta, CmptTheta) also returns newtheta, the parameters for newD, given theta, the parameters for D, and CmptTheta, the parameters for CmptD.

removecomponent

Remove a component

Syntax

newD = D.removecomponent(idx)
[newD, newtheta] = D.removecomponent(idx, theta)

Description

newD = D.removecomponent(idx) returns newD, a mixture distribution the same as D where the component at index idx is removed from its components.

[newD, newtheta] = D.removecomponent(idx, theta) also returns newtheta, the parameters for newD, given theta, the parameters for D.

invertindex

Obtain an inverted component index vector (Find the other components)

Syntax

invidx = D.invertindex(idx)
invidx = D.invertindex(idx, 'fixed')

Description

invidx = D.invertindex(idx) returns the indices of the variable components other than those indexed in idx.

invidx = D.invertindex(idx, 'fixed') returns the indices of the fixed components other than those indexed in idx.

Example

D = mixturefactory(mvnfactory(1), 6);
invidx = D.invertindex([3,5])
invidx =
   1     2     4     6

fixate

Make some variable component(s) fixed

Syntax

newD = D.fixate(idx, theta)
[newD, theta] = D.fixate(idx, theta)
[newD, theta] = D.fixate(idx, theta, data)
[newD, theta, idxFixed] = D.fixate(...)
[newD, theta, idxFixed, idxMap] = D.fixate(...)

Description

newD = D.fixate(idx, theta) returns newD, the same mixture as D where the variable components indexed by the index vector idx are fixed and their parameter values will not change during estimation. theta is a full parameter structure for the mixture. The values for the parameters of the newly fixed components are read from theta.

[newD, theta] = D.fixate(idx, theta) also returns the output theta, containing the parameters for the variable components extracted from the input theta, applicable to the new mixture, newD.

[newD, theta] = D.fixate(idx, theta, data) can be used to fill the log-likelihood cache for the fixed components, using the given data. The cache is used for better performance while calculating the log-likelihood for newD.

[newD, theta, idxFixed] = D.fixate(...) also returns idxFixed, the indices of the newly fixed components in newD.fixedD().

[newD, theta, idxFixed, idxMap] = D.fixate(...) also returns idxMap, an index-map vector, with length D.num(), which maps the old indices of the variable components in D to their new indices in newD (for those that are not being fixed). You can use the map like this: idx_new = idxMap(idx_old), where idx_old denotes an index for a variable component in D and idx_new denotes its new index in the variable components of newD.

Example

This is how the estimatepartial function uses invertindex, fixate, estimate and unfix to perform partial parameter estimation for components indicated by idx:

function [newtheta, newD, info, options] = estimatepartial(idx, theta, data, options)
  % make the other components fixed
  invidx = invertindex(idx);
  [newD, theta0, idxfixed] = fixate(invidx, theta, data);
  % use the given theta as the initial point for estimation
  options.theta0 = theta0;
  % estimate the resulting partial mixture parameters
  [newtheta, newD, info, options] = newD.estimate(data, options);
  % bring the fixed components back
  [newD, newtheta] = newD.unfix(idxfixed, invidx, newtheta);
end

unfix

Make some fixed component(s) variable (undo fixate)

Syntax

newD = D.unfix(idx)
[newD, theta] = D.unfix(idx, idxFixated, theta)
[newD, theta] = D.unfix(idx, idxFixated, theta, data)
[newD, theta, idxUnfixed] = D.unfix(...)
[newD, theta, idxUnfixed, idxMap] = D.unfix(...)

Description

newD = D.unfix(idx) returns newD, the same mixture as D where the fixed components indexed by the index vector idx are made variable for estimation.

[newD, theta] = D.unfix(idx, idxFixated, theta) brings back the fixed components to their original place before fixation. idxFixated, same size as idx, should be the index vector that was previously given to fixate (as its first argument) to fixate these components. When idxFixated is an empty vector, the components are added to the end of the variable components. The input theta is a parameter structure for the mixture D which has some fixed components, and the output theta is the parameter structure for the mixture newD where the indexed components are made variable.

[newD, theta] = D.unfix(idx, idxFixated, theta, data) can be used to fill the log-likelihood cache for any remaining fixed components, using the given data. The cache is used for better performance while calculating the log-likelihood for newD.

[newD, theta, idxUnfixed] = D.unfix(...) also returns idxUnfixed, the indices of the unfixed components in newD.varD().

[newD, theta, idxUnfixed, idxMap] = D.unfix(...) also returns idxMap, an index-map vector, with length D.numfixed(), which maps the old indices of the fixed components in D to their new indices in newD (for those that are not being made variable). You can use the map like this: idx_new = idxMap(idx_old), where idx_old denotes an index for a fixed component in D and idx_new denotes its new index in the fixed components of newD.

Example

This is how the estimatepartial function uses invertindex, fixate, estimate and unfix to perform partial parameter estimation for components indicated by idx:

function [newtheta, newD, info, options] = estimatepartial(idx, theta, data, options)
  % make the other components fixed
  invidx = invertindex(idx);
  [newD, theta0, idxfixed] = fixate(invidx, theta, data);
  % use the given theta as the initial point for estimation
  options.theta0 = theta0;
  % estimate the resulting partial mixture parameters
  [newtheta, newD, info, options] = newD.estimate(data, options);
  % bring the fixed components back
  [newD, newtheta] = newD.unfix(idxfixed, invidx, newtheta);
end

splitinit

Calculate the initial parameters for two splitted mixture components to be substituted for the given component.

Syntax

newtheta = D.splitinit(idx, theta)
newtheta = D.splitinit(idx, theta, options)
newtheta = D.splitinit(idx, theta, options, data)
[newtheta, store] = D.splitinit(idx, theta, options, data, store)

Description

newtheta = D.splitinit(idx, theta) returns the parameters for a new mixture resulted by splitting the component indexed by idx. The input theta is the parameters for the mixture before the split. Initialization for the splitted components is performed using the default methods for each parameter.

newtheta = D.splitinit(idx, theta, options) uses options.splitInit to initialize the parameters for the splitted components as described here.

newtheta = D.splitinit(idx, theta, options, data) can be used if the initialization method requires estimation data.

[newtheta, store] = D.splitinit(idx, theta, options, data, store) can be used for caching purposes as described here.

Note: This function is automatically called by the split function and you don't usually need to call this function separately.

split

Split a variable component in two

Syntax

newD = D.split(idx)
[newD, newtheta] = D.split(idx, theta)
[newD, newtheta] = D.split(idx, theta, options)
[newD, newtheta] = D.split(idx, theta, options, data)
[newD, newtheta, idxSplitted, idxMap] = D.split(...)
[newD, newtheta, idxSplitted, idxMap, store] = D.split(idx, theta, options, data, store)

Description

newD = D.split(idx) returns the new mixture, newD, resulted by splitting the component indexed by idx from D.

[newD, newtheta] = D.split(idx, theta) also initializes the parameters for the splitted components. The input theta is the parameter structure for the mixture D before the split. The output newtheta is the parameter structure of the new mixture, newD, after the split (containing the parameters for an additional component). The initialized parameter values for the first splitted component are stored at newtheta.D{idx} and for the second at newtheta.D{end}. The component weights in newtheta.p are also updated accordingly, such that each splitted component has half the weight of the original component.

[newD, newtheta] = D.split(idx, theta, options) uses options.splitInit to initialize the parameters for the splitted components as described here.

[newD, newtheta] = D.split(idx, theta, options, data) can be used if the initialization method requires estimation data.

[newD, newtheta, idxSplitted, idxMap] = D.split(...) also returns the two indices of the splitted components in the vector idxSplitted. The output idxMap is an index-map vector, with length D.num(), which maps the old indices of the components in D to their new indices in newD. You can use the map like this: idx_new = idxMap(idx_old), where idx_old denotes an index for a component in D and idx_new denotes its new index in the components of newD.

[newD, newtheta, idxSplitted, idxMap, store] = D.split(idx, theta, options, data, store) can be used for caching purposes as described here.

Example

The following code demonstrates a basic usage of split-related functions:

% Construct a mixture distribution and generate random
% parameters and data for demonstration
D = mixturefactory(mvnfactory(2), 3);
theta = D.randparam();
data = D.sample(theta, 1000);
% Find candidate components for splitting
idx_split = D.splitcandidates(theta, data);
% Split the first candidate component
idx = idx_split(1);
[newD, newtheta, idxSplitted] = D.split(idx, theta);
% We may estimate the parameters merely for the splitted components
newtheta = newD.estimatepartial(idxSplitted, newtheta, data)

mergeinit

Calculate the initial parameters for a merged mixture component to be substituted for two given components.

Syntax

theta = D.mergeinit(idx1, idx2, theta)
theta = D.mergeinit(idx1, idx2, theta, options)
theta = D.mergeinit(idx1, idx2, theta, options, data)
[theta, store] = D.mergeinit(idx1, idx2, theta, options, data, store)

Description

theta = D.mergeinit(idx1, idx2, theta) returns the parameters for a new mixture resulted by merging the components indexed by idx1 and idx2. The input theta is the parameters for the mixture before the merge. Initialization for the merged component is performed using the default methods for each parameter.

theta = D.mergeinit(idx1, idx2, theta, options) uses options.mergeInit to initialize the parameters for the merged component as described here.

theta = D.mergeinit(idx1, idx2, theta, options, data) can be used if the initialization method requires estimation data.

[theta, store] = D.mergeinit(idx1, idx2, theta, options, data, store) can be used for caching purposes as described here.

Note: This function is automatically called by the merge function and you don't usually need to call this function separately.

merge

Merge two variable components into one

Syntax

newD = D.merge(idx1, idx2)
[newD, newtheta] = D.merge(idx1, idx2, theta)
[newD, newtheta] = D.merge(idx1, idx2, theta, options)
[newD, newtheta] = D.merge(idx1, idx2, theta, options, data)
[newD, newtheta, idxMerged, idxMap] = D.merge(...)
[newD, newtheta, idxMerged, idxMap, store] = D.merge(idx1, idx2, theta, options, data, store)

Description

newD = D.merge(idx1, idx2) returns the new mixture, newD, resulted by merging the components indexed by idx1 and idx2 from D.

[newD, newtheta] = D.merge(idx1, idx2, theta) also initializes the parameters for the merged components. The input theta is the parameter structure for the mixture D before the merge. The output newtheta is the parameter structure of the new mixture, newD, after the merge (with one less item than theta). The initialized parameter values for the merged component are stored at newtheta.D{idx1} and theta.D{idx2} is removed in newtheta. The component weights in newtheta.p are also updated accordingly, such that the merged component has the sum of the weights of the original components.

[newD, newtheta] = D.merge(idx1, idx2, theta, options) uses options.mergeInit to initialize the parameters for the merged component as described here.

[newD, newtheta] = D.merge(idx1, idx2, theta, options, data) can be used if the initialization method requires estimation data.

[newD, newtheta, idxMerged, idxMap] = D.merge(...) also returns the index of the merged component in idxMerged. The output idxMap is an index-map vector, with length D.num(), which maps the old indices of the components in D to their new indices in newD. You can use the map like this: idx_new = idxMap(idx_old), where idx_old denotes an index for a component in D and idx_new denotes its new index in the components of newD.

[newD, newtheta, idxMerged, idxMap, store] = D.merge(idx1, idx2, theta, options, data, store) can be used for caching purposes as described here.

Example

The following code demonstrates a basic usage of merge-related functions:

% Construct a mixture distribution and generate random
% parameters and data for demonstration
D = mixturefactory(mvnfactory(2), 3);
theta = D.randparam();
data = D.sample(theta, 1000);
% Find candidate components for merging
[idx_merge1, idx_merge2] = D.mergecandidates(theta, data);
% Merge the first candidate components
idx1 = idx_merge1(1);
idx2 = idx_merge2(1);
[newD, newtheta, idxMerged] = D.merge(idx1, idx2, theta);
% We may estimate the parameters merely for the merged component
newtheta = newD.estimatepartial(idxMerged, newtheta, data)

splitcandidates

Find split candidates

Syntax

idx = D.splitcandidates(theta, data)
idx = D.splitcandidates(theta, data, options)
idx = D.splitcandidates(theta, data, options, n)

Description

idx = D.splitcandidates(theta, data) returns the vector idx containing indices of the components of D, sorted based on the default split criterion (see Split-and-merge options). idx has a length equal to the number of components (D.num()). The first element in idx refers to the best candidate component for splitting, and the last element refers to the one having the worse value of the split criterion.

idx = D.splitcandidates(theta, data, options) uses options.sm.splitCriterion as the split criterion for sorting the components. see Split-and-merge options for more details.

idx = D.splitcandidates(theta, data, options, n) where n is a positive integer less than or equal to D.num(), returns only the n best split candidates (idx will have a length of n).

Example

The following code demonstrates a basic usage of split-related functions:

% Construct a mixture distribution and generate random
% parameters and data for demonstration
D = mixturefactory(mvnfactory(2), 3);
theta = D.randparam();
data = D.sample(theta, 1000);
% Find candidate components for splitting
idx_split = D.splitcandidates(theta, data);
% Split the first candidate component
idx = idx_split(1);
[newD, newtheta, idxSplitted] = D.split(idx, theta);
% We may estimate the parameters merely for the splitted components
newtheta = newD.estimatepartial(idxSplitted, newtheta, data)

mergecandidates

Find merge candidates

Syntax

[idx1, idx2] = D.mergecandidates(theta, data)
[idx1, idx2] = D.mergecandidates(theta, data, options)
[idx1, idx2] = D.mergecandidates(theta, data, options, n)

Description

[idx1, idx2] = D.mergecandidates(theta, data) returns the vectors idx1 and idx2 containing index pairs of the components of D, sorted based on the default merge criterion (see Split-and-merge options). idx1 and idx2 both have a length equal to the number of components (D.num()). The first elements in idx1 and idx2 refer to the best pair of candidate components for merging, and the last pair of elements refer to those having the worse value of the merge criterion.

[idx1, idx2] = D.mergecandidates(theta, data, options) uses options.sm.mergeCriterion as the merge criterion for sorting the components. see Split-and-merge options for more details.

[idx1, idx2] = D.mergecandidates(theta, data, options, n) where n is a positive integer less than or equal to D.num(), returns only the n best merge candidates (idx1 and idx2 will each have a length of n).

Example

The following code demonstrates a basic usage of merge-related functions:

% Construct a mixture distribution and generate random
% parameters and data for demonstration
D = mixturefactory(mvnfactory(2), 3);
theta = D.randparam();
data = D.sample(theta, 1000);
% Find candidate components for merging
[idx_merge1, idx_merge2] = D.mergecandidates(theta, data);
% Merge the first candidate components
idx1 = idx_merge1(1);
idx2 = idx_merge2(1);
[newD, newtheta, idxMerged] = D.merge(idx1, idx2, theta);
% We may estimate the parameters merely for the merged component
newtheta = newD.estimatepartial(idxMerged, newtheta, data)

dim

See distribution structure common members.

datadim

See distribution structure common members.

weighting

Calculate the weighting (posterior probability) of each mixture component for each data point

Syntax

component_weights = D.weighting(theta, data)
[component_weights, store] = D.weighting(theta, data, store)

Description

component_weights = D.weighting(theta, data) returns a K-by-N matrix where K is the number of mixture components (D.num()) and N is the number of data points. Each column of the matrix contains the posterior probabilities of each mixture component for the corresponding data point. The probabilities are normalized such that each column sums up to unity. theta is the parameter structure for the mixture, and data is the data input.

[component_weights, store] = D.weighting(theta, data, store) can be used for caching purposes as described here.

For information about the input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.

Example

D = mixturefactory(mvnfactory(1), 2);
theta.D{1} = struct('mu',0, 'sigma',1);
theta.D{2} = struct('mu',2, 'sigma',1);
theta.p = [0.5 0.5];
data = [0 1 2];
component_weights = D.weighting(theta, data)
component_weights =
  0.8808    0.5000    0.1192
  0.1192    0.5000    0.8808

ll

See distribution structure common members.

llvec

See distribution structure common members.

llgrad

See distribution structure common members.

llgraddata

See distribution structure common members.

cdf

See distribution structure common members.

pdf

See distribution structure common members.

sample

See distribution structure common members.

You can also get the component labels for each data point using the following syntax:

[data, label] = D.sample(...)

randparam

See distribution structure common members.

init

See distribution structure common members.

estimatedefault

Default estimation function for mixture distribution. This function implements the expectation maximization (EM) method.

Syntax

theta = D.estimatedefault(data)
theta = D.estimatedefault(data, options)
[theta, D] = D.estimatedefault(...)
[theta, D, info] = D.estimatedefault(...)
[theta, D, info, options] = D.estimatedefault(...)

Description

theta = D.estimatedefault(data) returns estimated parameters for the distribution D, using data.

theta = D.estimatedefault(data, options) utilizes applicable options from the options structure in the estimation procedure.

[theta, D] = D.estimatedefault(...) 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.estimatedefault(...) also returns info, a structure array containing information about successive iterations performed by iterative estimation functions.

[theta, D, info, options] = D.estimatedefault(...) 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 the following options from the options described in estimation options.

  • theta0
  • verbosity
  • plotCost
  • crossVal
  • minIter
  • maxIter
  • maxTime
  • tolCost
  • tolCostDiff
  • statsfun
  • stopfun

Returned info fields

This function puts the following fields in the returned info structure array. You can read more about them in our documentation on estimation statistics structure.

  • iter
  • cost
  • time
  • cvCost

Example

% create a mixture of two Gaussian distributions
D = mixturefactory(mvnfactory(1), 2);
% generate 1000 random data points
data = [randn(1,300).*2-5, randn(1,700).*3+10];
% use an appropriate theta0
options.theta0 = D.init(data);
% estimate mixture parameters using the EM algorithm
theta = D.estimatedefault(data, options)

estimatepartial

Estimate parameters for a subset of components, while fixing the others

Syntax

newtheta = D.estimatepartial(idx, theta, data)
newtheta = D.estimatepartial(idx, theta, data, options)
[newtheta, D] = D.estimatepartial(...)
[newtheta, D, info] = D.estimatepartial(...)
[newtheta, D, info, options] = D.estimatepartial(...)

Description

newtheta = D.estimatepartial(idx, theta, data) estimates the parameters for the components indexed by the vector idx while preserving the parameter values for the other mixture components. theta contains the current values of parameters for all mixture components. The parameter values for those components that are indexed by idx are used as the initial point for their estimation, and the other parameters remain unchanged in the returned parameter structure.

newtheta = D.estimatepartial(idx, theta, data, options) utilizes applicable options from the options structure in the estimation procedure.

[newtheta, D] = D.estimatepartial(...) 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).

[newtheta, D, info] = D.estimatepartial(...) also returns info, a structure array containing information about successive iterations performed by iterative estimation functions.

[newtheta, D, info, options] = D.estimatepartial(...) 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 input theta and output newtheta, 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.

Note: options.theta0 will be ignored since the input theta contains the initial point for estimation.

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

The following code uses estimatepartial to estimate the parameters of splitted components after a split:

% Construct a mixture distribution and generate random
% parameters and data for demonstration
D = mixturefactory(mvnfactory(2), 3);
theta = D.randparam();
data = D.sample(theta, 1000);
% Find candidate components for splitting
idx_split = D.splitcandidates(theta, data);
% Split the first candidate component
idx = idx_split(1);
[newD, newtheta, idxSplitted] = D.split(idx, theta);
% Estimate the parameters merely for the splitted components
newtheta = newD.estimatepartial(idxSplitted, newtheta, data)

penalizerparam

See distribution structure common members.

Penalizer Info

The default penalizer for the mixture distribution is the sum of the default penalizers of its components.

penalizercost

See distribution structure common members.

penalizergrad

See distribution structure common members.

regcost

Regularizer cost

Syntax

reg = D.regcost(theta, data)
[reg, store] = D.regcost(theta, data, store)

Description

reg = D.regcost(theta, data) returns the cost penalty for the model-free regularization method (Hosseini, 2012). This regularization penalizes components that take few data points.

[reg, store] = D.regcost(theta, data, 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 options.regularize is turned on.

For information about the input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.

References

  1. R. Hosseini, “Natural Image Modelling using Mixture Models with compression as an application,” Berlin, Technische Universtit?t Berlin, Diss., 2012, 2012.

reggrad

Regularizer gradient with respect to parameters

Syntax

dll = D.reggrad(theta, data)
[dll, store] = D.reggrad(theta, data, store)

Description

dll = D.reggrad(theta, data) returns the (Euclidean) gradient penalty for the model-free regularization method (Hosseini, 2012). This regularization penalizes components that take few data points.

[dll, store] = D.reggrad(theta, data, 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 options.regularize is turned on.

For information about the input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.

References

  1. R. Hosseini, “Natural Image Modelling using Mixture Models with compression as an application,” Berlin, Technische Universtit?t Berlin, Diss., 2012, 2012.

sumparam

See distribution structure common members.

scaleparam

See distribution structure common members.

sumgrad

See distribution structure common members.

scalegrad

See distribution structure common members.

entropy

See distribution structure common members.

kl

Calculate Kullback–Leibler divergence between mixture components

Syntax

kl = D.kl(theta)

Description

kl = D.kl(theta) returns a symmetric K-by-K matrix where K is the number of mixture components (D.num()). The element at (i,j) in this matrix contains the KL divergence between the i'th and j'th components. theta is the parameter structure for the mixture.

For information about the parameter input theta, see Distribution Parameters Structure.

AICc

See distribution structure common members.

BIC

See distribution structure common members.

MML

Calculate minimum message length information criterion

Syntax

mml = D.MML(theta, data)
[mml, gradMML] = D.MML(theta, data)

Description

mml = D.MML(theta, data) calculates the minimum message length (MML) information criterion of the distribution D with parameters theta for the given data.

[mml, gradMML] = D.MML(theta, data) also returns gradMML, the gradient of MML with respect to component posterior probabilities.

For information about the parameter input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.

BICm

Calculate modified Bayesian information criterion

Syntax

bic = D.BICm(theta, data)

Description

bic = D.BICm(theta, data) calculates the modified Bayesian information criterion (Hosseini, 2012) of the distribution D with parameters theta for the given data.

For information about the parameter input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.

References

  1. R. Hosseini, “Natural Image Modelling using Mixture Models with compression as an application,” Berlin, Technische Universtit?t Berlin, Diss., 2012, 2012.

AICmc

Calculate modified corrected Akaike information criterion

Syntax

aicc = D.AICmc(theta, data)
[aicc, gradAicc] = D.AICmc(theta, data)

Description

aicc = D.AICmc(theta, data) calculates the modified corrected Akaike information criterion (Hosseini, 2012) of the distribution D with parameters theta for the given data.

For information about the parameter input theta, see Distribution Parameters Structure. The input argument data is described in Data Input Argument to Functions.

References

  1. R. Hosseini, “Natural Image Modelling using Mixture Models with compression as an application,” Berlin, Technische Universtit?t Berlin, Diss., 2012, 2012.

display

See distribution structure common members.

visualize

Syntax

handle_array = D.visualize(D, theta, vis_options)

gaussianize

Syntax

y = gaussianize(theta, data)