Data matrix containing n observations on v variables.

Rows of Y represent observations, and columns represent variables.

Missing values (NaN's) and infinite values (Inf's) are allowed, since observations (rows) with missing or infinite values will automatically be excluded from the computations.

Data Types: single| double

Scalar which specifies the number of groups.

Data Types: single| double

alpha is a scalar between 0 and 0.5 or an integer specifying the number of observations which have to be trimmed. If alpha=0 tclust reduces to traditional model based or mixture clustering (mclust): see Matlab function gmdistribution.

More in detail, if 0< alpha <1 clustering is based on h=fix(n*(1-alpha)) observations, else if alpha is an integer greater than 1 clustering is based on h=n-floor(alpha);

Data Types: single| double

Positive scalar which constrains the allowed differences among group scatters. Larger values imply larger differences of group scatters. On the other hand a value of 1 specifies the strongest restriction forcing all eigenvalues/determinants to be equal and so the method looks for similarly scattered (respectively spherical) clusters. The default is to apply restrfactor to eigenvalues. In order to apply restrfactor to determinants it is necessary to use optional input argument restr. If restrfactor is a struct it may contain the following fields:

Value	Description
pars	type of Gaussian Parsimonious Clustering Model. Character. A 3 letter word in the set: 'VVE','EVE','VVV','EVV','VEE','EEE','VEV','EEV','VVI', 'EVI','VEI','EEI','VII','EII'. The field restrfactor.pars is compulsory. All the other fields are non necessary. If they are not present they are set to their default values.
cdet	scalar in the interval [1 Inf) which specifies the the restriction which has to be applied to the determinants. If pa.cdet=1 all determinants are forced to be equal. See section More About for additional details.
shw	scalar in the interval [1 Inf) which specifies the the restriction which has to be applied to the elements of the shape matrices inside each group. If pa.shw=1 all diagonal elements of the shape matrix of cluster j (with j=1, ..., k) will be equal.
shb	scalar in the interval [1 Inf) which specifies the the restriction which has to be applied to the elements of the shape matrices across each group.
maxiterS	positive integer which specifies the maximum number of iterations to obtain the restricted shape matrix. This parameter is used by routine restrshapeGPCM. The default value of restrfactor.maxiterS is 5.
maxiterR	positive integer which specifies the maximum number of iterations to obtain the common rotation matrix in presence of varying shape. This parameter is used by routine cpcV. The default value of restrfactor.maxiterR is 20.
maxiterDSR	positive integer which specifies the maximum number of iterations to obtain the requested restricted determinants, shape matrices and rotation. For all parametrizations restrfactor.maxiterDSR is set to 1 apart from for the specifications 'VVE', 'EVE' and 'VEE'. The default value of restrfactor.maxiterDSR is 20.
tolS	tolerance to use to exit the iterative procedure for estimating the shape. Scalar. The iterative procedures stops when the relative difference of a certain output matrix is smaller than itertol in two consecutive iterations. The default value of pa.tol is 1e-12.
zerotol	tolerance value to declare all input values equal to 0 in the eigenvalues restriction routine (file restreigen.m) or in the final reconstruction of covariance matrices. The default value of zerotol is 1e-10.
msg	boolean which if set equal to true enables to monitor the relative change of the estimates of lambda Gamma and Omega in each iteration. The defaul value of pa.msg is false, that is nothing is displayed in each iteration.
userepmat	scalar, which specifies whether to use implicit expansion or bsxfun. restrfactor.userepmat =2 implies implicit expansion, pa.userepmat=1 implies use of bsxfun. The default is to use implicit expansion (faster) if verLessThanFS('9.1') is false and bsxfun if MATLAB is older than 2016b.

Data Types: scalar or struct restrfactor.usepreviousest = boolean, which specifies if for each refining step we use values of constrained determints and rotation matrices found in the previous refining step. Default value is true. Data Types - boolean

This options only works is 'restrtype' is 'deter'.

When restrtype is deter the default value of the "shape" constraint (as defined below) applied to each group is fixed to $c_{shape}=10^{10}$, to ensure the procedure is (virtually) affine equivariant. In other words, the decomposition or the $j$-th scatter matrix $\Sigma_j$ is

\[ \Sigma_j=\lambda_j^{1/v} \Omega_j \Gamma_j \Omega_j' \] where $\Omega_j$ is an orthogonal matrix of eigenvectors, $\Gamma_j$ is a diagonal matrix with $|\Gamma_j|=1$ and with elements $\{\gamma_{j1},...,\gamma_{jv}\}$ in its diagonal (proportional to the eigenvalues of the $\Sigma_j$ matrix) and $|\Sigma_j|=\lambda_j$. The $\Gamma_j$ matrices are commonly known as "shape" matrices, because they determine the shape of the fitted cluster components. The following $k$ constraints are then imposed on the shape matrices: \[ \frac{\max_{l=1,...,v} \gamma_{jl}}{\min_{l=1,...,v} \gamma_{jl}}\leq c_{shape}, \text{ for } j=1,...,k, \]

In particular, if we are ideally searching for spherical clusters it is necessary to set $c_{shape}=1$. Models with variable volume and spherical clusters are handled with 'restrtype' 'deter', $1<restrfactor<\infty$ and $cshape=1$.

The $restrfactor=cshape=1$ case yields a very constrained parametrization because it implies spherical clusters with equal volumes.

Example: 'cshape',10

Data Types: single | double

A logical value specifying whether cluster weights shall be considered in the concentration, assignment steps and computation of the likelihood.

if equalweights = true we are (ideally) assuming equally sized groups by maximizing:

\[ \sum_{j=1}^k \sum_{ x_i \in group_j } \log f(x_i; m_j , S_j) \] else if equalweights = false (default) we allow for different group weights by maximizing: \[ \sum_{j=1}^k \sum_{ x_i \in group_j } \log \left[ \frac{n_j}{n} f(x_i; m_j , S_j) \right]= \] \[ = \sum_{j=1}^k n_j \log n_j/n + \sum_{j=1}^k \sum_{ x_i \in group_j} \log f(x_i; m_j , S_j) . \] Remark: $\sum_{j=1}^k n_j \log n_j/n$ is the so called entropy term

Example: 'equalweights',true

Data Types: Logical

Scalar which controls whether to display or not messages on the screen.

If msg=0 nothing is displayed on the screen.

If msg=1 (default) messages are displayed on the screen about estimated time to compute the estimator.

If msg=2 detailed messages are displayed. For example the information at iteration level, and or the number of subsets in which there was no convergence.

Example: 'msg',1

Data Types: single | double

Option mixt specifies whether mixture modelling or crisp assignment approach to model based clustering must be used.

In the case of mixture modelling parameter mixt also controls which is the criterion to find the untrimmed units in each step of the maximization.

If mixt >=1 mixture modelling is assumed else crisp assignment. The default value is mixt=0 (i.e. crisp assignment).

In mixture modelling the likelihood is given by:

\[ \prod_{i=1}^n \sum_{j=1}^k \pi_j \phi (y_i; \; \theta_j), \] while in crisp assignment the likelihood is given by: \[ \prod_{j=1}^k \prod _{i\in R_j} \phi (y_i; \; \theta_j), \]

where $R_j$ contains the indexes of the observations which are assigned to group $j$.

Remark - if mixt>=1 previous parameter equalweights is automatically set to 1.

Parameter mixt also controls the criterion to select the units to trim, if mixt = 2 the h units are those which give the largest contribution to the likelihood that is the h largest values of:

\[ \sum_{j=1}^k \pi_j \phi (y_i; \; \theta_j) \qquad i=1, 2, ..., n, \] else if mixt=1 the criterion to select the h units is exactly the same as the one which is used in crisp assignment. That is: the n units are allocated to a cluster according to criterion: \[ \max_{j=1, \ldots, k} \hat \pi'_j \phi (y_i; \; \hat \theta_j) \]

and then these n numbers are ordered and the units associated with the largest h numbers are untrimmed.

Example: 'mixt',1

Data Types: single | double

If nocheck is equal to 1 no check is performed on matrix Y.

As default nocheck=0.

Example: 'nocheck',1

Data Types: single | double

If nsamp is a scalar it contains the number of subsamples which will be extracted. If nsamp=0 all subsets will be extracted.

Remark - if the number of all possible subset is <300 the default is to extract all subsets, otherwise just 300 If nsamp is a matrix it contains in the rows the indexes of the subsets which have to be extracted. nsamp in this case can be conveniently generated by function subsets. nsamp can have k columns or k*(v+1) columns. If nsamp has k columns the k initial centroids each iteration i are given by X(nsamp(i,:),:) and the covariance matrices are equal to the identity.

If nsamp has k*(v+1) columns the initial centroids and covariance matrices in iteration i are computed as follows: X1=X(nsamp(i,:),:);

mean(X1(1:v+1,:)) contains the initial centroid for group 1;

cov(X1(1:v+1,:)) contains the initial cov matrix for group 1;

mean(X1(v+2:2*v+2,:)) contains the initial centroid for group 2;

cov((v+2:2*v+2,:)) contains the initial cov matrix for group 2;

...;

mean(X1((k-1)*v+1:k*(v+1))) contains the initial centroids for group k;

cov(X1((k-1)*v+1:k*(v+1))) contains the initial cov matrix for group k.

REMARK - if nsamp is not a scalar option option below startv1 is ignored. More precisely, if nsamp has k columns startv1=0 elseif nsamp has k*(v+1) columns option startv1 =1.

Example: 'nsamp',1000

Data Types: double

Prior solution supplied as a struct or a vector of length n which specifies how to initialize the centroids, the covariance matrices and the proportions in the iteration of the EM algorithm for the last subset which is extracted. If priorSol is a vector it must contain the positive integers associated with the units allocated to the different groups. For example if n=70 and priorSol=[ones(40,1) 2*ones(30,1)] it specifies that the last starting point among the nsamp tentative solutions must be based on a centroid, covariance matrix and sample size formed by the first 40 observations of matrix Y and the second centroid, cov matrix and sample size must be formed by the remainining 30 solutions.

If priorSol is a struct it must contain the following fields.

Value	Description
cini	a matrix of size k-times-v containing the centroids of the k groups;
sigmaini	a 3D array of size v-by-v-by-k containing the covariance matrices of the k groups;
niini	a vector of length k containing the sizes of the k groups. Note that this option takes effect just if input option startv1 is true. The default is empty value that is no prior solution is used.

Example: 'priorSol',[ones(50,1) 2*ones(20,1)];

Data Types: double

Matrix with size k-by-size(nsamp,1) containing the random numbers which are used to initialize the proportions of the groups. This option is effective just if nsamp is a matrix which contains pre-extracted subsamples. The purpose of this option is to enable to user to replicate the results in case routine tclust is called using a parfor instruction (as it happens for example in routine IC, where tclust is called through a parfor for different values of the restriction factor).

The default value of RandNumbForNini is empty that is random numbers from uniform are used.

Example: 'RandNumbForNini',''

Data Types: single | double

Number of refining iterations in each subsample. Default is 15.

refsteps = 0 means "raw-subsampling" without iterations.

Example: 'refsteps',10

Data Types: single | double

The default value is 1e-14;

Example: 'reftol',1e-05

Data Types: single | double

The type of restriction to be applied on the cluster scatter matrices. Valid values are 'eigen' (default), or 'deter'.

eigen implies restriction on the eigenvalues while deter implies restriction on the determinants. If restrtype is 'deter' it is also possible to specify through optional parameter cshape the constraint to apply to the shape matrices. Note that this option is ignored if input parameter restrfactor is a struct.

Example: 'restrtype','deter'

Data Types: char

If startv1 is true then initial centroids and covariance matrices are based on $(v+1)$ observations randomly chosen, else each centroid is initialized taking a random row of input data matrix and covariance matrices are initialized with identity matrices. The default value of startv1 is true.

Remark 1 - in order to start with a routine which is in the required parameter space, restrictions are immediately applied.

Remark 2 - option startv1 is used just if nsamp is a scalar that is the indexes of the subsamples to extract are not supplied.

(see for more details the help associated with nsamp).

Example: 'startv1',false

Data Types: logical

This option takes effect just when startv1 is true. When startv1true1unitCentroid is false (default) all the $(v+1)$ units are used to initialize the centroid for group $j$ ($j=1, ..., k$). When startv1true1unitCentroid is true just one of the $v+1$ extracted units is used to initialize the centroid for group $j$.

Example: 'startv1true1unitCentroid',true

Data Types: logical

Set Ysave to true to request that the input matrix Y is saved into the output structure out. Default is false, id est no saving is done.

Example: 'Ysave',true

Data Types: logical

Case 1: plots option used as scalar.

- If plots=0 (default), plots are not generated.

- If plots=1, a plot with the classification is shown on the screen (using the spmplot function). The plot can be: * for v=1, an histogram of the univariate data.

* for v=2, a bivariate scatterplot.

* for v>2, a scatterplot matrix generated by spmplot.

When v>=2 plots offers the following additional features (for v=1 the behaviour is forced to be as for plots=1): Case 2: plots option used as character array.

- plots='contourf' adds in the background of the bivariate scatterplots a filled contour plot. The colormap of the filled contour is based on grey levels as default.

This argument may also be inserted in a field named 'type' of a structure. In the latter case it is possible to specify the additional field 'cmap', which changes the default colors of the color map used. The field 'cmap' may be a three-column matrix of values in the range [0,1] where each row is an RGB triplet that defines one color.

Check the colormap function for additional informations.

- plots='contour' adds in the background of the bivariate scatterplots a contour plot. The colormap of the contour is based on grey levels as default. This argument may also be inserted in a field named 'type' of a structure.

In the latter case it is possible to specify the additional field 'cmap', which changes the default colors of the color map used. The field 'cmap' may be a three-column matrix of values in the range [0,1] where each row is an RGB triplet that defines one color.

Check the colormap function for additional informations.

- plots='ellipse' superimposes confidence ellipses to each group in the bivariate scatterplots. The size of the ellipse is chi2inv(0.95,2), i.e. the confidence level used by default is 95%. This argument may also be inserted in a field named 'type' of a structure. In the latter case it is possible to specify the additional field 'conflev', which specifies the confidence level to use and it is a value between 0 and 1.

- plots='boxplotb' superimposes on the bivariate scatterplots the bivariate boxplots for each group, using the boxplotb function. This argument may also be inserted in a field named 'type' of a structure.

Case 3: plots option used as struct.

If plots is a structure it may contain the following fields:

Value	Description
type	in this case the 'type' supplied is used to set the type of plot as when plots option is a character array. Therefore, plots.type can be: 'contourf', 'contour', 'ellipse' or 'boxplotb'.
cmap	this field is used to set a colormap for the plot type. For example, plots.cmap = 'autumn'. See the MATLAB help of colormap for a list of colormap possiblilites.
conflev	this is the confidence level for the confidence ellipses. It must me a scalar between 0 and 1. For example, one can set: plots.type = 'ellipse'; plots.conflev = 0.5;

REMARK - The labels=0 are automatically excluded from the overlaying phase, considering them as outliers.

Example: 'plots', 1

Data Types: single | double | character | struct