MEICA

From Brain Mapping Unit

About

MEICA is the Multi-Echo Independent Component Analysis package created by Prantik Kundu during his PhD at Cambridge. It can be applied to fMRI datasets that have been acquired with at least 3 different echo times (TE). The working principle behind MEICA is that genuine BOLD signal depends on TE but artifacts don't. The ICA part of MEICA is used to define a set of components which are individually classified as BOLD or non-BOLD based on their TE dependence (quantified using two variables kappa and rho). See Kundu et al 2012.

Please refer to the Bitbucket repository for the source code and all the gory implementation details.

Usage

Usage: meica.py [options]

Options:

 -h, --help            show this help message and exit
 -e TES                ex: -e 14.5,38.5,62.5  Echo times (in ms)
 -d DSINPUTS           ex: -d RESTe1.nii.gz,RESTe2.nii.gz,RESTe3.nii.gz
 -a ANAT               ex: -a mprage.nii.gz  Anatomical dataset (optional)
 -b BASETIME           ex: -b 10s OR -b 10v  Time to steady-state
                       equilibration in seconds(s) or volumes(v). Default 0.
 --MNI                 Warp to MNI space using high-resolution template
 Additional processing options:
   --qwarp             Nonlinear anatomical normalization to MNI (or --space
                       template) using 3dQWarp, after affine
   --fres=FRES         Specify functional voxel dim. in mm (iso.) for
                       resampling during preprocessing. Default none. ex:
                       --fres=2.5
   --space=SPACE       Path to specific standard space template for affine
                       anatomical normalization
   --no_skullstrip     Anatomical is already intensity-normalized and skull-
                       stripped (if -a provided)
   --no_despike        Do not de-spike functional data. Default is to de-
                       spike, recommended.
   --no_axialize       Do not re-write dataset in axial-first order. Default
                       is to axialize, recommended.
   --mask_mode=MASK_MODE
                       Mask functional with help from anatomical or standard
                       space images: use 'anat' or 'template'
   --coreg_mode=COREG_MODE
                       Coregistration with Local Pearson and T2* weights
                       (default), or use align_epi_anat.py (edge method): use
                       'lp-t2s' or 'aea'
   --smooth=FWHM       Data FWHM smoothing (3dBlurInMask). Default off. ex:
                       --smooth 3mm
   --align_base=ALIGN_BASE
                       Explicitly specify base dataset for volume
                       registration
   --TR=TR             The TR. Default read from input dataset header
   --tpattern=TPATTERN
                       Slice timing (i.e. alt+z, see 3dTshift -help). Default
                       from header. (N.B. This is important!)
   --align_args=ALIGN_ARGS
                       Additional arguments to anatomical-functional co-
                       registration routine
   --seed=SEED         Seed used for ICA. Default 42.
   --ted_args=TED_ARGS
                       Additional arguments to TE-dependence analysis routine
 Run options:
   --prefix=PREFIX     Prefix for final ME-ICA output datasets.
   --cpus=CPUS         Maximum number of CPUs (OpenMP threads) to use.
                       Default 2.
   --label=LABEL       Label to tag ME-ICA analysis folder.
   --test_proc         Align and preprocess 1 dataset then exit, for testing
   --script_only       Generate script only, then exit
   --pp_only           Preprocess only, then exit.
   --keep_int          Keep preprocessing intermediates. Default delete.
   --skip_check        Skip dependency checks during initialization.
   --OVERWRITE         If meica.xyz directory exists, overwrite.

Example

A typical meica invokation might look like this:

python -u ~/me-ica/meica.py -d "rest_e[0,1,2].nii.gz" -e 15,34,54 -a mprage.nii.gz --qwarp --space /usr/local/afni/MNI152_T1_2009c+tlrc --fres=2.33 --cpus=12 2>&1 | tee my_meica.log

Arguments explained

-d "rest_e[0,1,2].nii.gz"
input files rest_e0.nii.gz rest_e1.nii.gz rest_e2.nii.gz
-e 15,34,54
echo times TE in milli-seconds for the three input files respectively
-a mprage.nii.gz
anatomical image of the same subject for co-registration
--qwarp --space /usr/local/afni/MNI152_T1_2009c+tlrc
will use the lores MNI152 template that comes with afni as reference space into which the output is warped
--fres=2.33
resample to 2.33mm iso voxel size
--cpu=12
use parallel processing for warping and the internal PCA and ICA calculations
| tee my_meica.log
save output to my_meica.log while also writing it out to the terminal

See also

The actual component identification is performed by the tedana.py subroutine which is called from within meica.py at the end of the afni based preprocessing.