a1_fclust: Main MixfMRI function

In MixfMRI: Mixture fMRI Clustering Analysis

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

}

MixfMRI documentation built on Sept. 8, 2023, 5:06 p.m.