MRIaggr (version 1.1.5)

selectContrast: Extract contrast parameters

Description

Extract the contrast parameters from a Carto3D or a MRIaggr object.

Usage

"selectContrast"(object, num = NULL, na.rm = FALSE, coords = FALSE, format = "data.frame")
			
"selectContrast"(object, param = NULL, num = NULL, format = "data.frame", slice_var = "k", coords = FALSE, hemisphere = "both", 
		 norm_mu = FALSE, norm_sigma = FALSE, na.rm = FALSE, subset = NULL)

Arguments

object

an object of class Carto3D or MRIaggr. REQUIRED.

param

the contrast parameters to extract. character vector or NULL.

num

the slices to extract. numeric vector or NULL.

format

the format of the output. Can be "matrix", "data.frame" or "vector".

slice_var

the type of slice to extract. "i" for sagittal, "j" for coronal and "k" for transverse. character.

coords

the coordinates that sould be extracted. logical or any of "i" "j" "k".

hemisphere

the hemisphere to extract. character. See the details section.

norm_mu

the type of centering to apply on the parameter values. character. See the details section.

norm_sigma

the type of scaling to apply on the parameter values. character. See the details section.

na.rm

should observations with missing values be removed ? logical.

subset

the subset of observations to extract. positive integer vector or NULL leading to use all observations

Value

A "vector", matrix or a data.frame. In the latter two cases, each row corresponds to a voxel and each column to a coordinate.

Details

ARGUMENTS: Information about the param argument can be found in the details section of initParameter.

Information about the num argument can be found in the details section of initNum.

Possible values for the hemisphere argument are:

• "both" : select all the observations.
• "left" : select the observations from the left hemisphere.
• "right" : select the observations from the right hemisphere.
• "lesion" : select the observations belonging to the hemisphere(s) that contain(s) the lesion (if any).
• "contralateral" : select the observations belonging to the hemisphere(s) that do not contain(s) the lesion (if any).

To select observations from a given hemisphere (all values except "both"), the parameter hemisphere must have been allocated to the object using, for instance, calcHemisphere. In addition for "lesion" and "contralateral" values, the slot @hemispheres has to be filled using, for instance, calcHemisphere.

Possible values for the centering argument (norm_mu) and the scaling argument (norm_sigma) are:

• "FALSE" : no normalization
• "global" : the centering or scaling value is computed using all the observations.
• "global_1slice" : the centering or scaling value is computed using all the observations that belong to the slice of the observation to normalize.
• "global_3slices" : the centering or scaling value is computed using all the observations that belong to the slice of the observation to normalize, the slice above (if any) and the slice below (if any).
• "contralateral" : the centering or scaling value is computed using the observations from the contralateral hemisphere.
• "contralateral_1slice" : the centering or scaling value is computed using the observations from the contralateral hemisphere that belong to the slice of the observation to normalize.
• "contralateral_3slices" : the centering or scaling value is computed using the observations from the contralateral hemisphere that belong to the slice of the observation to normalize, the slice above (if any) and the slice below (if any).
• "default_value" : the default value of the parameter stored in the slot @default_value is used for the centering (for norm_mu only).

If coords is set to TRUE the dataset containing the contrast parameters values will also contains all the coordinates. If coords is set to FALSE, it will not contain any coordinates.

Argument subset can be a character value that refers to a logical parameter in the object defining the subset of observation to extract.

FUNCTION: Each of the num, hemisphere and subset argument define a subset of the total set of observations. It is the intersection of all these three subsets that is extracted.

When a normalisation is requested to center (resp. scale) the data, the normalisation value is extracted for each parameter in the element of the slot normalization that match the argument norm_mu (resp. norm_sigma). The parameters values are first centered by substraction with the value returned by norm_mu. Then they are scaled by division with the value returned by norm_sigma.

See Also

calcContralateral, calcRegionalContrast, calcFilter and calcTissueType to retreat and allocate the modified contrast parameters. allocContrast<- to allocate new contrast parameters. calcNormalization to compute and allocate the normalisation values. allocNormalization<- to allocate the normalization values when obtained from an external source. calcHemisphere and calcContralateral to compute and allocate the hemispheres. allocHemisphere<- and allocContrast<- to allocate hemispheres obtained from an external source.

Examples

#### 1- Carto3D method ####
## load nifti files and convert them to Carto3D
path.Pat1 <- system.file("nifti", package = "MRIaggr")
nifti.Pat1_TTP_t0 <- readMRI(file.path(path.Pat1, "TTP_t0"), format = "nifti")
Carto3D.Pat1_TTP_t0 <- constCarto3D(nifti.Pat1_TTP_t0, identifier = "Pat1", param = "TTP_t0")

## select all observations
carto1 <- selectContrast(Carto3D.Pat1_TTP_t0)
dim(carto1)

## select observations from slices 1 to 3 and return the result into a data.frame
carto2 <- selectContrast(Carto3D.Pat1_TTP_t0, num = 1:3, coords = FALSE, format = "data.frame")
dim(carto2)

## select observations from slices 1 to 3 and return the result into a vector
carto3 <- selectContrast(Carto3D.Pat1_TTP_t0, num = 1:3, coords = FALSE)
length(carto3)

#### 2- MRIaggr method ####
## load a MRIaggr object
data("MRIaggr.Pat1_red", package = "MRIaggr")

## select all parameters and all observations
carto <- selectContrast(MRIaggr.Pat1_red)
dim(carto)
head(carto)

## select a subset of parameters
carto <- selectContrast(MRIaggr.Pat1_red, param = c("DWI_t0","T2_FLAIR_t2"))
dim(carto)
head(carto)

## select a subset of parameters on slices 1 to 3
carto <- selectContrast(MRIaggr.Pat1_red, num=1:3, param=c("DWI_t0","T2_FLAIR_t2"))
dim(carto)
head(carto)

## select a subset of parameters on slices 1 to 3 and normalized the center 
## the values using the contralateral
carto <- selectContrast(MRIaggr.Pat1_red, num=1:3, param=c("DWI_t0","T2_FLAIR_t2"),
                        norm_mu = "contralateral")
dim(carto)
head(carto)

## select only observations which are lesioned at admission (i.e. MASK_DWI_t0 = TRUE)
carto <- selectContrast(MRIaggr.Pat1_red, subset = "MASK_DWI_t0",
                        param = c("DWI_t0","T2_FLAIR_t2","MASK_DWI_t0"))
dim(carto)
head(carto)

## select only observations which are lesioned at admission (i.e. MASK_DWI_t0 = TRUE) 
## with coordinates
carto <- selectContrast(MRIaggr.Pat1_red, subset = "MASK_DWI_t0",
                        param = c("DWI_t0","T2_FLAIR_t2","MASK_DWI_t0"), coords = TRUE)
dim(carto)
head(carto)

## select only observations for which i = 55
carto <- selectContrast(MRIaggr.Pat1_red, slice_var = "i", 
                        num = 55, coords = TRUE)
dim(carto)
head(carto)