mixtCompLearn: Learn and predict using RMixtComp

In RMixtComp: Mixture Models with Heterogeneous and (Partially) Missing Data

Learn and predict using RMixtComp

Description

Estimate the parameter of a mixture model or predict the cluster of new samples. It manages heterogeneous data as well as missing and incomplete data.

Usage

mixtCompLearn(
  data,
  model = NULL,
  algo = createAlgo(),
  nClass,
  criterion = c("BIC", "ICL"),
  hierarchicalMode = c("auto", "yes", "no"),
  nRun = 1,
  nCore = min(max(1, ceiling(detectCores()/2)), nRun),
  verbose = TRUE
)

mixtCompPredict(
  data,
  model = NULL,
  algo = resLearn$algo,
  resLearn,
  nClass = NULL,
  nRun = 1,
  nCore = min(max(1, ceiling(detectCores()/2)), nRun),
  verbose = FALSE
)

Arguments

data	a data.frame, a matrix or a named list containing the data (see Details and Data format sections).
model	a named list containing models and hyperparameters (see Details section).
algo	a list containing the parameters of the SEM-Gibbs algorithm (see Details or createAlgo).
nClass	the number of classes of the mixture model. Can be a vector for mixtCompLearn only.
criterion	"BIC" or "ICL". Criterion used for choosing the best model.
hierarchicalMode	"auto", "yes" or "no". If "auto", it performs a hierarchical version of MixtComp (clustering in two classes then each classes is split in two ...) when a functional variable is present (see section Hierarchical Mode).
nRun	number of runs for every given number of class. If >1, SEM is run nRun times for every number of class, and the best according to observed likelihood is kept.
nCore	number of cores used for the parallelization of the nRun runs.
verbose	if TRUE, print some information.
resLearn	output of mixtCompLearn (only for mixtCompPredict function).

Details

The data object can be a matrix, a data.frame or a list. In the case of a matrix or data.frame, each column must be names and corresponds to a variable. In the case of a list, each element corresponds to a variable, each element must be named. Missing and incomplete data are managed, see section Data format for how to format them.

The model object is a named list containing the variables to use in the model. All variables listed in the model object must be in the data object. model can contain less variables than data. An element of the list is the model's name to use (see below for the list of available models). For example, model <- list(real1 = "Gaussian", counting1 = "Poisson") indicates a mixture model with 2 variables named real1 and counting1 with Gaussian and Poisson as model. Some models require hyperparameters in this case, the model is described by a list of 2 elements: type containing the model name and paramStr containing the hyperparameters. For example: model <- list(func1 = list(type = "Func_CS", paramStr = "nSub: 4, nCoeff: 2"), counting1 = "Poisson"). If the model is NULL, data are supposed to be provided in data.frame or list with R format (numeric, factor, character, NA as missing value). Models will be imputed as follows: "Gaussian" for numeric variable, "Multinomial" for character or factor variable and "Poisson" for integer variable. A summary of available models (and associated hyperparameters and missing format) can be accessed by calling the availableModels function.

Eight models are available in RMixtComp: Gaussian, Multinomial, Poisson, NegativeBinomial, Weibull, Func_CS, Func_SharedAlpha_CS, Rank_ISR. Func_CS and Func_SharedAlpha_CS models require hyperparameters: the number of subregressions of functional and the number of coefficients of each subregression. These hyperparameters are specified by: nSub: i, nCoeff: k in the paramStr field of the model object. The Func_SharedAlpha_CS is a variant of the Func_CS model with the alpha parameter shared between clusters. It means that the start and end of each subregression will be the same across the clusters.

To perform a (semi-)supervised clustering, user can add a variable named z_class in the data and model objects with LatentClass as model in the model object.

The algo object is a list containing the different number of iterations for the algorithm. This list can be generated using the createAlgo function. The algorithm is decomposed in a burn-in phase and a normal phase. Estimates from the burn-in phase are not shown in output.

• nbBurnInIter: Number of iterations of the burn-in part of the SEM algorithm.

• nbIter: Number of iterations of the SEM algorithm.

• nbGibbsBurnInIter: Number of iterations of the burn-in part of the Gibbs algorithm.

• nbGibbsIter: Number of iterations of the Gibbs algorithm.

• nInitPerClass: Number of individuals used to initialize each cluster (default = 10).

• nSemTry: Number of try of the algorithm for avoiding an error.

• confidenceLevel: confidence level for confidence bounds for parameter estimation

• ratioStableCriterion: stability partition required to stop earlier the SEM

• nStableCriterion: number of iterations of partition stability to stop earlier the SEM

Value

An object of classes MixtCompLearn and MixtComp for mixtCompLearn function. An object of class MixtComp for mixtCompPredict (see details section).

Data format

See the associated vignette for more details (RShowDoc("dataFormat", package = "RMixtComp")).

- Gaussian data: Gaussian data are real values with the dot as decimal separator. Missing data are indicated by a ?. Partial data can be provided through intervals denoted by [a:b] where a (resp. b) is a real or -inf (resp. +inf).

- Categorical Data: Categorical data must be consecutive integer with 1 as minimal value. Missing data are indicated by a ?. For partial data, a list of possible values can be provided by a_1,...,a_j, where a_i denotes a categorical value.

- Poisson and NegativeBinomial Data: Poisson and NegativeBinomial data must be positive integer. Missing data are indicated by a ?. Partial data can be provided through intervals denoted by [a:b] where a and b are positive integers. b can be +inf.

- Weibull Data: Weibull data are real positive values with the dot as decimal separator. Missing data are indicated by a ?. Partial data can be provided through intervals denoted by [a:b] where a and b are positive reals. b can be +inf.

- Rank data: The format of a rank is: o_1, ..., o_j where o_1 is an integer corresponding to the number of the object ranked in 1st position. For example: 4,2,1,3 means that the fourth object is ranked first then the second object is in second position and so on. Missing data can be specified by replacing and object by a ? or a list of potential object, for example: 4, {2 3}, {2 1}, ? means that the object ranked in second position is either the object number 2 or the object number 3, then the object ranked in third position is either the object 2 or 1 and the last one can be anything. A totally missing rank is specified by ?,?,...,?

- Functional data: The format of a functional data is: time_1:value_1,..., time_j:value_j. Between individuals, functional data can have different length and different time. i is the number of subregressions in a functional data and k the number of coefficients of each regression (2 = linear, 3 = quadratic, ...). Missing data are not supported.

- z_class: To perform a (semi-)supervised clustering, user can add a variable named 'z_class' (with eventually some missing values) with "LatentClass" as model. Missing data are indicated by a ?. For partial data, a list of possible values can be provided by a_1,...,a_j, where a_i denotes a class number.

MixtComp object

A MixtComp object is a result of a single run of MixtComp algorithm. It is a list containing three elements mixture, variable and algo. If MixtComp fails to run, the list contains a single element: warnLog containing error messages.

The mixture element contains

• BIC: value of BIC

• ICL: value of ICL

• nbFreeParameters: number of free parameters of the mixture

• lnObservedLikelihood: observed loglikelihood

• lnCompletedLikelihood: completed loglikelihood

• IDClass: entropy used to compute the discriminative power of variable: -\sum_{i=1}^n t_{ikj} log(t_{ikj})/(n * log(K))

• IDClassBar: entropy used to compute the discriminative power of variable: -\sum_{i=1}^n (1-t_{ikj}) log((1-t_{ikj}))/(n * log(K))

• delta: similarities between variables (see heatmapVar)

• completedProbabilityLogBurnIn: evolution of the completed log-probability during the burn-in period (can be used to check the convergence and determine the ideal number of iteration)

• completedProbabilityLogRun: evolution of the completed log-probability after the burn-in period (can be used to check the convergence and determine the ideal number of iteration)

• runTime: list containing the total execution time in seconds and the execution time of some subpart.

• lnProbaGivenClass: log-proportion + log-probability of x_i for each class

The algo list contains a copy of algo parameter with extra elements: nInd, nClass, mode ("learn" or "predict").

The variable list contains 3 lists : data, type and param. Each of these lists contains a list for each variable (the name of each list is the name of the variable) and for the class of samples (z_class). The type list contains the model used for each variable.

Each list of the data list contains the completed data in the completed element and some statistics about them (stat).

The estimated parameter can be found in the stat element in the param list (see Section View of an output object). For more details about the parameters of each model, you can refer to rnorm, rpois, rweibull, rnbinom, rmultinom, or references in the References section.

View of a MixtComp object

Example of output object with variables named "categorical", "gaussian", "rank", "functional", "poisson", "nBinom" and "weibull" with respectively Multinomial, Gaussian, Rank_ISR, Func_CS (or Func_SharedAlpha_CS), Poisson, NegativeBinomial and Weibull as model.

output
|_______	algo	__ nbBurnInIter
|		|_ nbIter
|		|_ nbGibbsBurnInIter
|		|_ nbGibbsIter
|		|_ nInitPerClass
|		|_ nSemTry
|		|_ ratioStableCriterion
|		|_ nStableCriterion
|		|_ confidenceLevel
|		|_ mode
|		|_ nInd
|		|_ nClass
|
|_______	mixture	__ BIC
|		|_ ICL
|		|_ lnCompletedLikelihood
|		|_ lnObservedLikelihood
|		|_ IDClass
|		|_ IDClassBar
|		|_ delta
|		|_ runTime
|		|_ nbFreeParameters
|		|_ completedProbabilityLogBurnIn
|		|_ completedProbabilityLogRun
|		|_ lnProbaGivenClass

|
|_______	variable	__ type	__ z_class
		|	|_ categorical
		|	|_ gaussian
		|	|_ ...
		|
		|_ data	__ z_class	__ completed
		|	|	|_ stat
		|	|_ categorical	__ completed
		|	|	|_ stat
		|	|_ ...
		|	|_ functional	__ data
		|		|_ time
		|
		|_ param	__ z_class	__ stat
			|	|_ log
			|	|_ paramStr
			|_ functional	__ alpha	__ stat
			|	|	|_ log
			|	|_ beta	__ stat
			|	|	|_ log
			|	|_ sd	__ stat
			|	|	|_ log
			|	|_ paramStr
			|_ rank	__ mu	__ stat
			|	|	|_ log
			|	|_ pi	__ stat
			|	|	|_ log
			|	|_ paramStr
			|
			|_ gaussian	__ stat
			|	|_ log
			|	|_ paramStr
			|_ poisson	__ stat
			|	|_ log
			|	|_ paramStr
			|_ ...

See the associated vignette for more details: RShowDoc("mixtCompObject", package = "RMixtComp")

MixtCompLearn object

The MixtCompLearn object is the result of a run of the mixtCompLearn function. It is a list containing nClass: the vector of number of classes given by user, res a list of MixtComp object (one per element of nbClass), criterion the criterion used to choose the best model, crit a matrix containing BIC and ICL for each run, totalTime, the total running time, and finally the elements of the MixtComp object with the best criterion value (algo, mixture, variable or warnLog).

Hierarchical Mode

When the model's parameter includes a functional model (Func_CS or Func_SharedAlpha_CS), the algorithm is automatically run in "Hierarchical Mode". In hierarchical mode, it first clusters the data in 2 classes. Then, it searches the best model in 3 classes by performing a clustering in 2 classes of each class of the previous step). The same process is used until the asked number (K) of classes is attained. All models from 2 to K classes are returned (even if the case nClass = K).

This strategy is used to solve some problem (initialization, empty classes...) when the number of classes is high with the functional model.

The user can control the activation of the hierarchical mode using the hierarchicalMode's parameter. Three values are possible: "no", the algorithm is never run in hierarchical mode, "yes", the algorithm is always run in hierarchical mode, and "auto", the algorithm is run in hierarchical mode only when there is at least one functional variable (default).

Author(s)

Quentin Grimonprez

References

Julien Jacques, Christophe Biernacki. Model-based clustering for multivariate partial ranking data. Journal of Statistical Planning and Inference, Elsevier, 2014, 149, pp.201-217.

Allou Samé, Faicel Chamroukhi, Gérard Govaert, Patrice Aknin. Model-based clustering and segmentation of time series with change in regime. Advances in Data Analysis and Classification, 2011, 5(4):301-321

See Also

Graphical and utility functions in RMixtCompUtilities. Other clustering packages: Rmixmod

Examples

data(simData)

# define the algorithm's parameters
algo <- list(
  nbBurnInIter = 50,
  nbIter = 50,
  nbGibbsBurnInIter = 50,
  nbGibbsIter = 50,
  nInitPerClass = 20,
  nSemTry = 20,
  confidenceLevel = 0.95
)

# run RMixtComp in unsupervised clustering mode + data as matrix
resLearn1 <- mixtCompLearn(simData$dataLearn$matrix, simData$model$unsupervised[1:3], algo,
  nClass = 1:2, nRun = 2, nCore = 1
)

# run RMixtComp in supervised clustering mode + data as matrix
resLearn2 <- mixtCompLearn(simData$dataLearn$data.frame, simData$model$supervised[1:3], algo,
  nClass = 1:2, nRun = 2, nCore = 1
)

# run RMixtComp in predict mode + data as list
resPredict <- mixtCompPredict(simData$dataPredict$list, simData$model$unsupervised[1:3], algo,
  resLearn1,
  nClass = 2, nCore = 1
)

RMixtComp documentation built on July 9, 2023, 6:06 p.m.