`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:

where is the number of components, is the weight for the k-th component, and 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**

- 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**

- 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**

- 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**

`display`

See distribution structure common members.

`visualize`

**Syntax**

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

`gaussianize`

**Syntax**

y = gaussianize(theta, data)