calcBrainMask: Brain-Background discrimination

Description

Seek to form two groups of observations (brain observations and background observations) using a threshold approach or a k-means algorithm.

Usage

"calcBrainMask"(object, param, type = "kmeans", th.breaks = 100,  th.smoothing = TRUE, th.select_optima = 1, th.upper = TRUE, plot = TRUE, kmeans.n_groups = 2:4, kmeans.Neighborhood = 3, skull.param = NULL, 
		 skull.n_groups = 3,
		 filename = paste("calcBrainMask", type, object@identifier, sep = "_"), update.object = FALSE, overwrite = FALSE, ...)

Arguments

object

an object of class MRIaggr. REQUIRED.

param

the contrast parameter(s) that should be used to identify the brain observations. character vector. REQUIRED.

type

the method to use. Can be "threshold" or "kmeans".

th.breaks

the number of thresholds to use. postive integer.

th.smoothing

should the derivative be smoothed ? logical.

th.select_optima

the rank of the optimum to retain. postive integer.

th.upper

should the observations above the selected threshold be retained ? Else the observations bellow will the selected threshold be retained. logical.

plot

should the results be plotted ? logical.

kmeans.n_groups

the number of groups to use in the kmeans algorithm. postive integer vector.

kmeans.Neighborhood

the range of the neighbourhood. postive integer.

skull.param

the parameter used to identify the skull. character.

skull.n_groups

the number of groups to use in the kmeans algorithm to obtain the skull.

filename

the name of the file used to export the plot. character.

update.object

should the resulting mask be stored in object as a "mask" parameter ? logical.

overwrite

if a mask is already stored in object@data, can it be overwritten ? logical.

...

additional arguments to be passed to optionsMRIaggr for specifying the graphical parameters.

Value

If type is "threshold", a list containing :

[[analysis]] : A matrix containing the parameter thresholds (column "threshold"), the number of observations inside the mask (column "Nb"), the first and its smoothed version (column "dNb" and "dNb.filtered") and indicator of optima (column "optima"). matrix.
[[th_opt]] : A matrix containing the number of observations inside the mask and its derivative (in lines) for each optimum (in columns).
[[best_group]] : An indicator variable giving the observations that belong to the mask. logical vector.
[[mask_name]] : the mask name. character.

If type is "kmeans", a list containing :

[[kmeans]] : the optimal kmeans partition (result of the kmeans function). list.
[[potential]] : the spatial potential for the various brain partitions. matrix.
[[best_V]] : the highest potential. numeric.
[[best_group]] : An indicator variable giving the observations that belong to the mask. logical vector.
[[mask_name]] : the mask name. character.
[[potential_skull]] : the spatial potential for the various skull partitions (only if skull.param is not NULL). matrix.

Details

ARGUMENTS:

Argument(s) ... must correspond to some of the following arguments : height, numeric2logical, path, res, unit, verbose, width, window. Setting skull.param to NULL leads to skip the skull stripping step.

FUNCTION: The threshold approach searches the best break point of the function that maps thresholds to the number of observations. For this, it find the optima of the first derivative of this function (possibly smoothed). The arguments th.breaks, th.smoothing, th.select_optima and th.upper are only active if type is "threshold". th.smoothing can be set to an integer to specify the width of the smoothing kernel.

The k-means approach seeks the most spatially coherent partition of the observations, among the possible partitions defined by the kmeans.n_groups argument. The mean number of neighbors averaged over observations (spatial potential) is used as a metric of the spatial coherence of the partition. The arguments kmeans.n_groups, kmeans.Neighborhood and upper are only active if type is "kmeans".

The skull step consists in identifying the skull with an additionnal parameter (T1 sequence appears well suited for this purpose), and remove the corresponding observations from the brain mask. It is the partition that gives the best spatial coherence for the final brain mask that is retained, leaving the posibility of no skull stripping.

The plot is active only if type is "threshold".

Examples

Run this code

## load NIFTI files and convert them to MRIaggr
path.Pat1 <- system.file(file.path("nifti"), package = "MRIaggr")
ls.array <- list(readMRI(file.path(path.Pat1, "T1_t0"), format = "nifti"),
                 readMRI(file.path(path.Pat1, "T2_GRE_t0"), format = "nifti"))
MRIaggr.Pat1 <- constMRIaggr(ls.array, identifier = "Pat1", param = c("T1_t0","T2_GRE_t0"))

#### 1- thresholding approach ####
res <- calcBrainMask(MRIaggr.Pat1, param = "T2_GRE_t0", type = "threshold",
                     th.select_optima = 2)

breaks <- res$analysis[,"threshold"]
res <- calcBrainMask(MRIaggr.Pat1, param = "T2_GRE_t0", type = "threshold",
                     th.breaks = breaks[breaks > 50], th.select_optima = 1,
                     overwrite = TRUE, update.object = TRUE)

## display
multiplot(MRIaggr.Pat1, param = "mask")

multiplot(MRIaggr.Pat1, param = "T2_GRE_t0", index1 = "mask")

## other parameter 
## Not run: 
# res <- calcBrainMask(MRIaggr.Pat1, param = "T1_t0", type = "threshold",
#                      th.breaks = 200)
# 
# res <- calcBrainMask(MRIaggr.Pat1, param = "T1_t0", type = "threshold",
#                      th.breaks = seq(0, 400, length.out = 50), th.select_optima = 2,
#                      overwrite = TRUE, update.object = TRUE)
# 
# multiplot(MRIaggr.Pat1, param = "mask")
# ## End(Not run)

#### 2- k-means approach ####
## Not run: 
# res <- calcBrainMask(MRIaggr.Pat1, param = "T2_GRE_t0", type = "kmeans",
#                      kmeans.n_groups = 2:4,
#                      update.object = TRUE, overwrite = TRUE)
# ## End(Not run)
					 
## display
multiplot(MRIaggr.Pat1, param = "T2_GRE_t0", index1 = "mask")
multiplot(MRIaggr.Pat1, param = "mask")