Main functions {MixfMRI}

Main MixfMRI function

Description

Main MixfMRI functions.

Usage

  fclust(X.gbd, PV.gbd, K = 2,
    PARAM.init = NULL,
    min.1st.prop = .FC.CT$INIT$min.1st.prop,
    max.PV = .FC.CT$INIT$max.PV,
    class.method = .FC.CT$INIT$class.method[1],
    RndEM.iter = .FC.CT$CONTROL$RndEM.iter,
    algorithm = .FC.CT$algorithm[1],
    model.X = .FC.CT$model.X[1],
    ignore.X = .FC.CT$ignore.X,
    stop.unstable = TRUE,
    MPI.gbd = .FC.CT$MPI.gbd, common.gbd = .FC.CT$common.gbd)

  set.global(X.gbd, PV.gbd, K = 2,
    min.1st.prop = .FC.CT$INIT$min.1st.prop,
    max.PV = .FC.CT$INIT$max.PV,
    class.method = .FC.CT$INIT$class.method[1],
    RndEM.iter = .FC.CT$CONTROL$RndEM.iter,
    algorithm = .FC.CT$algorithm[1],
    model.X = .FC.CT$model.X[1],
    ignore.X = .FC.CT$ignore.X,
    check.X.unit = .FC.CT$check.X.unit,
    MPI.gbd = .FC.CT$MPI.gbd, common.gbd = .FC.CT$common.gbd)

Arguments

X.gbd

a data matrix of N voxel locations. dim(X.gbd) = N x 3 for 3D data and N x 2 for 2D data.

PV.gbd

a p-value vector of signals associated with voxels. length(PV.gbd) = N.

K

number of clusters to be estimated.

PARAM.init

initial parameters.

min.1st.prop

lower bound of mixing proportion (ETA) of the 1st cluster (uniform).

max.PV

upper bound of p-values where initializations pick from.

class.method

classification method for initializations.

RndEM.iter

number of RndEM iterations.

algorithm

either “ecm” (ECM), “apecma” (APECMa) or “em” (EM) algorithm.

model.X

either “I” or “V” for covariance matrix.

ignore.X

if X.gbd used in model, TRUE for PV.gbd only.

check.X.unit

if X.gbd are all in [0, 1].

stop.unstable

if fclust stops if unstable results occur.

MPI.gbd

if MPI (“EGM” algorithm) is used.

common.gbd

if X.gbd and PV.gbd are in common across all ranks when MPI.gbd = TRUE.

Details

The fclust() contains initialization and EM algorithms for clustering fMRI signal data which have two parts: X.gbd for voxel information either 2D or 3D, PV.gbd for p-value of signals associated with voxels. Each signal is assumed as a mixture distribution with K components with mixing proportion ETA, and each component has two independent coordinates with density functions: Beta and multivariate Normal distributions.

Beta density: The 1st component is restricted by min.1st.prop and Beta(1, 1) distribution. The other K - 1 components have Beta(alpha, beta) distribution with alpha < 1 < beta.

Multivariate Normal density: model.X = "I" is for diagonal cov matrix of multivariate Normal distribution, and "V" for unstructured cov matrix. ignore.X = TRUE is to ignore X.gbd and normal density, i.e. only Beta density is used.

Currently, APECMa and EM algorithms are implemented with EGM algorithm to speed up convergence if MPI is available. RndEM initialization is also implemented for better chance of good initial values for convergence.

The set.global() has purposes: create a template/storage of parameters, save configurations, and called by fclust() to initial the parameters, such as initial.em.gbd() or initial.RndEM.gbd().

Value

A list with class fclust by fclust() is returned which can be summarized by print.fclust().

A list PARAM or PARAM.org is returned by set.global():

N.gbd

number of observations (within the rank), and should be equal to N.all if MPI.gbd = FALSE.

N.all

numbers of observations (of all ranks if MPI.gbd = TRUE).

N

total number of observations (sum(N.all)).

p

dimension of an observation (3 for 2D signals, 4 for 3D signals), equivalent to total number of coordinates.

p.X

dimension of X.gbd (2 for 2D signals, 3 for 3D signals, 0 when ignore.X = TRUE, number of voxel coordinates.

K

number of clusters.

ETA

mixing proportion, length K.

log.ETA

log(ETA).

BETA

a list of length K containing parameters (alpha, beta) of Beta density.

MU

a matrix of dimension p.X by K.

SIGMA

a list of length K, and each is of dimension K x K.

logL

log likelihood value.

min.1st.prop

carried from input.

max.PV

carried from input.

class.method

classification method of initializations.

min.N.CLASS

p + 1.

model.X

carried from input.

Author(s)

Wei-Chen Chen and Ranjan Maitra.

References

Chen, W.-C. and Maitra, R. (2021) “A Practical Model-based Segmentation Approach for Accurate Activation Detection in Single-Subject functional Magnetic Resonance Imaging Studies”, arXiv:2102.03639.

See Also

print.fclust().

Examples

library(MixfMRI, quietly = TRUE)
library(EMCluster, quietly = TRUE)
# .FC.CT$algorithm <- "em"
# .FC.CT$model.X <- "V"
# .FC.CT$ignore.X <- TRUE
.FC.CT$check.X.unit <- FALSE
set.seed(1234)

### Test toy1.
X.gbd <- toy1$X.gbd[, -3]
PV.gbd <- toy1$PV.gbd
PARAM <- fclust(X.gbd, PV.gbd, K = 2)
print(PARAM)
id.toy1 <- .MixfMRIEnv$CLASS.gbd
print(RRand(toy1$CLASS.gbd, id.toy1))


.rem <- function(){

  ### Test toy2.
  X.gbd <- toy2$X.gbd[, -3]
  PV.gbd <- toy2$PV.gbd
  PARAM <- fclust(X.gbd, PV.gbd, K = 3)
  print(PARAM)
  id.toy2 <- .MixfMRIEnv$CLASS.gbd
  print(RRand(toy2$CLASS.gbd, id.toy2))

}