MRIaggr (version 1.1.5)

launcher_fMM: A user frendly interface to fMMalgo

Description

A more user frendly interface to the segmentation algorithm despite more limited options compared to fMMalgo

Usage

launcher_fMM(G, data, Wweight_SR=NULL, distband.SR=NA, Wdist_LR=NULL, distband.LR=NA,
    var_reg, family=gaussian(link="identity"), prior_theta="kmeans", posterior_proba=NULL,
    var_group=NULL, prior_prevalence=FALSE,
    test.GR=FALSE, seed=NULL,
    test.ICM=FALSE, rho_ICM="auto", G_ICM=1:G, update_rho=FALSE,
    test.ICMregional=FALSE, coords=NULL, distance_ref=NULL, multiV=FALSE,
    epsilon=10^(-3), epsilon_corrSpat=epsilon*10, iter_max=100, trace_iter=FALSE)

Arguments

G

The number of groups to be considered for the mixture. integer.

data

A dataframe containing the data. data.frame[n,p].

Wweight_SR

The local neighborhood matrix. dgCMatrix[n,n]. Should be normalized by row (i.e. rowSums(Wweight_SR)=1). Only used if test.GR or test.ICM is true.

distband.SR

distband for automatic computation of Wdist_SR. numeric. Ignored if Wweight_SR is specified.

Wdist_LR

The regional neighborhood matrix. dgCMatrix[n,n]. Should contain the distances between the observations (0 indicating infinite distance). Only used if both test.ICM and test.ICMregional are true

distband.LR

distband for automatic computation of Wdist_LR. numeric. Ignored if Wdist_LR is specified.

var_reg

A vector indicating the names of the response variables. character vector[g].

family

A list of G families indicating the distribution of each response variable. list[[family]].

prior_theta

Initialisation of the means of each group means by random sampling (NULL), kmeans ("kmeans") or user defined values (list[[M]][G]).

posterior_proba

Initialisation of the posterior membership probabilities to user defined values (matrix[n,g]). Ignored if NULL.

var_group

A vector indicating the names of the concomittant variables. character vector[g].

prior_prevalence

Should a prior based on the prevalence of each group be used ? logical.

test.GR

Should Growing Region algorithm be performed ? logical.

seed

An indicator of the seeds to be used in the GR algorithm. logical vector[n]. Can alternatively contains the name of a column in data (character).

test.ICM

Should local/regional regularization be performed ? logical.

rho_ICM

Value of the spatial regularisation parameters : can be fixed a priori (numeric if test.ICMregional=F and numeric vector[2] if test.ICMregional=T) or estimated ("init")

G_ICM

Potential group merging for the regularization step (interger vector[G]) where each element must be inferior or equal to G.

update_rho

Should rho be re-estimated using the posterior probabilites at each step ? logical.

test.ICMregional

Should regional regularization be performed ? logical. test.ICM must be also T to be active.

coords

Coordinates (matrix[n,.]) or the name of columns in data (character vector[.]) giving the observation coordinates.

distance_ref

The distance defining the several neighborhood orders relatively to Wdist_LR. numeric vector[.].

multiV

Should the regional potential range be specific to each spatial group ? logical. Default is FALSE.

epsilon

Convergence occurs when the relative variation of the log-likelihood or of the parameter values between two iterations is below epsilon. numeric.

epsilon_corrSpat

Spatial regularization begins when the relative variation of the log-likelihood or of the parameter values between two iterations is below epsilon_corrSpat. numeric.

iter_max

Maximum number of EM iterations. integer

trace_iter

Should estimation be displayed at each EM iteration ? logical.

Value

• A list containing :
• Y
  a data.frame containing the response variables.
• Id
  a data.frame containing, if any the coordinates of the observations.
• theta
  a list containing the estimated regressors of the response models.
• sigma
  a list containing the estimated dispersion coefficient of the response models.
• reg
  a list containing the adjusted response ($Y) and concomittant ($groupe) models.
• beta
  a vector containing the estimated regressors of the concomittant models.
• rho_ICM
  if any, a vector containing the regularization parameters.
• posterior_proba
  a matrix containing the posterior probabilities of the observations.
• prior_proba
  a matrix containing the prior probabilities of the observations.
• proba_priorReg
  if any, a matrix containing the spatial prior probabilities of the observations.
• radius
  if any, a vector indicating the radius of the spatial groups of group G
• group
  a list indicating for each group the most probable index of observations that belong to the group.
• family
  a list containing the family used in the response models.
• critere_cv
  a list containing the convergence criteria.
• cv
  a logical indicating whether convergence occured.
• tps
  a list indicating the time at which the algorithm started and stopped.

Details

This function require the following packages : Matrix, nnet and spam, Rcpp, RcppArmadillo in case of spatial regularization. See fMMalgo for other details.

See Also

fMMalgo for a more options, plotCv_fMM to plot the convergence criteria, calcW_fMM to compute the neighborhood matrix, rhoMF to estimate the regularization parameters on external data.

Examples

data(Simulation_data,package="fMMseg")
n <- nrow(Simulation_data)

#### fMM non spatial ####
res_EMbase <- launcher_fMM(G=3,data=Simulation_data,
                            var_reg="Y_artlinear",family=gaussian(link="identity"),
                            epsilon=5*10^{-3})

#### fMM local regularization ####
 res_EMICM <-  launcher_fMM(G=3,data=Simulation_data,coords=c("i","j"),distband.SR=sqrt(2),
                            var_reg="Y_artlinear",family=gaussian(link="identity"),
                            test.ICM=TRUE,rho_ICM=c(6,0),
                            epsilon=5*10^{-3})
  
#### fMM local and regional regularization ####
system.time(
  res_EMICMlocreg <-  launcher_fMM(G=3,data=Simulation_data,coords=c("i","j"),distband.SR=sqrt(2),distband.LR=10,
                               var_reg="Y_artlinear",family=gaussian(link="identity"),
                               test.ICM=TRUE,rho_ICM=c(6,6),
                               test.ICMregional=TRUE,
                               epsilon=5*10^{-3})
)

 if(try(require(fields))){
  par(mfrow=c(2,2),mar=rep(1.5,4))
 image.plot(x=1:sqrt(n),y=1:sqrt(n),xlab="",ylab="",axes=FALSE,
            z=matrix(Simulation_data[,"Y_artlinear"],sqrt(n),sqrt(n)),
            main="Dataset")
 image.plot(x=1:sqrt(n),y=1:sqrt(n),xlab="",ylab="",axes=FALSE,
            z=matrix(res_EMbase$posterior_proba[,3],sqrt(n),sqrt(n)),
            main=expression(fMM[ns]))
 image.plot(x=1:sqrt(n),y=1:sqrt(n),xlab="",ylab="",axes=FALSE,
            z=matrix(res_EMICM$posterior_proba[,3],sqrt(n),sqrt(n)),
            main=expression(paste(fMM[Loc],"- weak",sep="")))
 image.plot(x=1:sqrt(n),y=1:sqrt(n),xlab="",ylab="",axes=FALSE,
            z=matrix(res_EMICMlocreg$posterior_proba[,3],sqrt(n),sqrt(n)),
            main=expression(fMM[LocReg]))
 }

## for other examples see the demo files : 
??fMMEvaluation # line 65 to 102 (simulated data)   
??fMMLesionSegmentation # line 55-67, 86-100 and 121-135  (real example)