MRIaggr-calcBrainMask: Brain-Background discrimination
In bozenne/MRIaggr: Management, Display, and Processing of Medical Imaging Data

Description Usage Arguments Details Value See Also Examples

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

## S4 method for signature 'MRIaggr'
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, ...)

`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.

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".

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.

selectContrast to select the mask parameter.
calcSmoothMask to spatially regularized the obtained mask.

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