EL command-line quick-guide:
EL data organization:
EL data and analyses are organized along three different axes: subjects, preprocessing pipelines, and models.
The functional data and analysis results are organized in a subject-centric manner, where all of the data associated with a given subject (or subject session) is organized under the same directory (even if different portions of these data may be used in different experiments) .
The directory where all of the subjects data are stored is called EL's root.subjects directory. This directory is initialized as .../conn/modules/el/root.subjects/. This may be either manually transformed into a symbolic link to point somewhere else, or it may also be defined programmatically (e.g. when multiple usergroups share the same software installation) by using the syntax:
Within this location, each subdirectory contains the data from a different subject. Subject directory names in this folder are referred to in EL as subject-ID's, and they need to be unique for each subject but are otherwise arbitrarily defined (without whitespaces or punctuation marks, e.g. valid subject IDs could be 835_FED_20200305a_3T2_PL2017, sub-LR01, or sub0001). All of the input and output data for an individual subject is located within this subject directory [root.subjects]/[subject_ID].
Each individual subject's functional and anatomical data can be preprocessed using multiple different preprocessing pipelines. Different pipelines are identified in EL by a pipeline-ID. Pipeline IDs need to be unique for each pipeline but are otherwise arbitrarily defined (without whitespaces or punctuation marks, e.g. valid pipeline IDs could be DefaultMNI, surface-space, or pipeline01).
Preprocessing description: The description and configuration options of all individual pipelines are grouped in the root.pipelines directory. This directory by default is initialized as .../conn/modules/el/ which contains a number of standard and commonly used preprocessing pipelines. You may specify a different directory programmatically using the syntax:
Each individual preprocessing pipeline in EL is fully defined by a single configuration file (e.g. in [root.pipelines]/pipeline_preproc_[pipeline_ID].cfg). In addition to the default pipelines in EL, users may manually edit these files or or create their own configuration files. Different pipelines or pipeline modules may also be applied sequentially. EL may use any combination of preprocessing steps implemented in CONN, including functional realignment, slice-timing correction, susceptibility distortion correction, outlier identification, functional/anatomical coregistration, MNI-space normalization, tissue class segmentation, masking, smoothing, etc. including steps focused on denoising the functional data, such as aCompCor, scrubbing, band-pass filtering, etc. offering a lot of flexibility to preprocess your functional and anatomical data. See the section Preprocessing pipeline files below for details about these files.
Preprocessing inputs: the input files of each preprocessing pipeline are the raw/original functional data (optionally also anatomical data, fieldmaps, etc.) stored within each subject directory.
Preprocessing outputs: the output files of a preprocessing pipeline are named following SPM prefix convention (see https://web.conn-toolbox.org/tutorials#h.p_Pk74qAeMP6Ml for details), and they are stored within each individual subject directory, specifically:
a) primary preprocessing pipeline: when using a command of the form el preprocessing.main ... to preprocess your data, the output files will be stored in the same folder as the original anatomical/functional data (note: if using DICOM to NIFTI conversion as part of preprocessing, this folder will be the NIFTI output folder, named nii)
or b) secondary preprocessing pipelines: when using a command of the form el preprocessing.alt ... to preprocess your data, the output files will be stored within a separate subfolder for each preprocessing pipeline
The former option is useful mainly when a single/common preprocessing pipeline is going to be run on all datasets, while the latter option is useful when multiple / different pipelines may be run on the same dataset. Both options may be used in isolation or simultaneously, for example to keep the primary preprocessing pipeline outputs in the same folder as your original files, while keeping the outputs of secondary pipelines separately. When referring to an already preprocessed dataset within the EL framework, use the keyword main to refer to the output of the primary preprocessing pipeline, or directly the [pipeline_ID] name to refer to the output of any secondary preprocessing pipeline.
Each preprocessed dataset can be analyzed using one or multiple different 1st/subject-level task activation models. Different models are identified in EL by a model-ID. Model IDs need to be unique for each model but are otherwise arbitrarily defined (without whitespaces or punctuation marks, e.g. valid model IDs could be LanglocSN, taskAB, or 139283). A separate 1st-level SPM analysis will be computed for each individual model-ID in order to estimate the model parameters (effects of interest such as task-related responses).
Model description: the information about all individual model definition and configuration options are grouped in EL's root.tasks directory. By default this directory is initialized as .../conn/modules/el/root.tasks/. This may be either manually transformed into a symbolic link to point somewhere else, or it may also be defined programmatically using the syntax:
Typically a model is fully defined by a combination of model-design files (.para), indicating the timing and sequence of events or blocks within each functional run, and model-association files (.cat), indicating the association between these experimental designs and the functional runs for each subject (see model-design files and model-association files sections below for details). In addition, a model may also specify details about the desired model-estimation options and the desired contrasts to be estimated by SPM (see model-estimation files and model-contrast files below for details)
Model outputs: First-level analysis outputs include all of the standard SPM analysis output files, such as an SPM.mat file containing the details of the estimated General Linear Model, beta_*.nii files containing maps of estimated effect-sizes for each model regressor, and con_*.nii and spmT_*.nii files containing maps of estimated contrast values and T-statistics, respectively, for each specified first-level contrast. These files will be stored in a directory named [root.subjects]/[subject_ID]/firstlevel_[model_ID] for primary preprocessing pipelines or [root.subjects]/[subject_ID]/[pipeline_ID]/results/firstlevel/[model_ID] for secondary preprocessing pipelines
EL configuration files:
All information regarding data/preprocessing/analysis options in EL is specified through configuration files. These include: subject files indicating the location and file names of each subject's original/raw data; preprocessing pipeline files indicating the steps and configuration options involved in each preprocessing pipeline; and several model files indicating the details of each subject experimental design as well as configuration options for SPM first-level analyses
Subject files (data.cfg)
Within each subject directory a file named data.cfg defines the location and source of the original/raw data files for this subject (e.g. functional and anatomical files). It is recommended that the raw data files are also located within the same subject directory but this is not necessary (e.g. in scenarios where the raw files may be read-only and shared among multiple groups/researchers). A typical data.cfg file may contain the following information, for example, if your original/raw data is in NIFTI format:
or something like the following information, for example, if your original/raw data is in DICOM format:
Subject definition files may also indicate the source of fieldmap files, as well as ROI files.
The full documentation of the information and format of data.cfg files can be found in here. Unless otherwise specified by a different extension (e.g. .json), data.cfg files are assumed to use the [.cfg] file format.
Preprocessing pipeline files (pipeline_preproc.cfg)
Within the root.pipelines directory a number of files named pipeline_preproc_[pipeline-ID].cfg define different preprocessing pipelines. Each pipeline file defines a list of preprocessing steps to be executed sequentially. In addition, pipeline files may also specify the individual parameters/options of each step, assign labels to the functional data output by each preprocessing step to be referred to later, or jump back to continue preprocessing the functional data output by a previous step. An example of a default preprocessing pipeline in EL is the following:
This pipeline uses direct-normalization to segment and normalize separately the functional and anatomical data. In addition it also realigns the data and applies spatial smoothing, it runs outlier identification in order to estimate potential outlier scans, and it estimates White matter and CSF components to be possibly used later for denoising.
The full documentation of the information and format of preprocessing pipeline files can be found in here. Unless otherwise specified by a different extension (e.g. .json), preprocessing pipeline files are assumed to use the [.cfg] file format.
Model pipeline files (pipeline_model.cfg)
Within the root.tasks directory a file named [model_ID].cfg (or when manually specifying model-options during runtime, within the root.pipelines directory a file named pipeline_model_[options_ID].cfg) describes the details of SPM 1st-level parameter-estimation procedure. An example of the default model pipeline file in EL is the following:
These files may specify the source of functional data (e.g. minimallysmoothed label in the example above), temporal basis modeling the expected hemodynamic response function shape (e.g. hrf+deriv option in the example above), high- or low-pass filters or noise covariates such as scrubbing or aCompCor factors to be included during model estimation, etc.
The full documentation of the information and format of these files can be found in here.
Model-design files (.para)
Within the root.tasks directory a series of files named [model-ID]_*.para (e.g. tasksAB_random1.para) contain the onset/duration/event-type information defining all individual events or blocks in one particular instantiation of an experimental design. A typical .para file may look like the following:
Design information .para files may also indicate the timing of individual scans/acquisitions (for sparse acquisition designs), parametric modulators of task effects (e.g. reaction time), temporal modulation effects, etc.
The full documentation of the information and format of these files can be found in here. The same .para file may apply to one or multiple subjects and one or multiple sessions, for example for different subjects or sessions where different variations or random orders of the same experimental tasks were used. The information of which .para files are associated with a particular subject/session is stored in subject-specific model-association files (see below). Unless otherwise specified by a different extension, .para files are assumed to use the [.cfg] file format.
Model-association files (.cat)
Within each subject directory a file named [model-ID].cat describes which experimental design should be used when analyzing a functional run. This association may possibly be different across different 1st-level analyses, for example when different 1st-level analyses require different ways to model the tasks or when different subset of functional runs are used in different analyses. A typical .cat association file may look like the following example, defining two functional runs and their associated model design files:
Model-contrast files (.con)
Within the root.tasks directory a series of text files named [model-ID].con define all of the contrasts that we would like to evaluate for each experimental design. Each contrast is defined in a separate line as a linear combination of modeled tasks (as defined in the #names fields of the model-design files for the same model-ID). A typical contrast file may contain the following information, for example:
The full documentation of the information and format of these files can be found in here. Unless otherwise specified by a different extension, .con files are assumed to use any standard .txt/.csv/.tsv convention for separating the different fields in each line/contrast (note: for back-compatibility, model-contrast information for multiple models can also be stored in a single contrasts_by_expt.txt file within the root.tasks folder).
preprocessing functional and anatomical images
A typical sequence of commands to preprocess your functional/anatomical data would look like the following:
Step 1) initialize EL and point to the location of root folders
Step 2) run one of EL's predefined preprocessing pipelines on subject 'sub0001' data
Step 3) create a series of Quality Assurance plots evaluating the results of the previous preprocessing pipeline on subject 'sub0001'
repeating steps 2) and 3) for any additional subjects.
If necessary, additional preprocessing steps can be run a posteriori on an already preprocessed dataset. For example, after step 2) above, using the following syntax would run and additional spatial smoothing step to a dataset which has already been preprocessed using the DefaultMNI pipeline:
EL preprocessing pipelines are defined through .cfg files, and may use any of the preprocessing and denoising options available in CONN. EL includes several standard preprocessing pipelines already defined and tailored for task activation analyses (see conn/modules/el/pipeline_preproc_[pipeline_ID].cfg files for details), and users may modify these files and/or create their own pipelines.
When using EL to preprocess your data, EL will create additional subdirectories within each subject directory containing the results of all preprocessing steps (these directories are named [pipeline_ID] after the name of preprocessing pipeline run).
(see "help el" and "help evlab17_run_preproc" for additional details)
model estimation (task activation analyses)
A typical sequence of commands to run first-level GLM task activation analyses of your functional data would look like the following:
Step 4) run model estimation on subject 'sub0001' preprocessed data using the 'tasksAB' experimental design
Step 5) create a series of Quality Assurance plots of model design, sample effect-sizes, and contrast estimability measures of the analyses of 'sub0001' data
repeating steps 4) and 5) for any additional subjects.
The results of the first-level analyses will be stored in a [subject_ID]/[preproc_ID]/results/firstlevel/[model_ID] directory named after the experimental design and contained within the results/firstlevel subdirectory of the preprocessed dataset. The contents of this directory are the standard SPM first-level analysis outputs, including an SPM.mat file containing the details of the estimated General Linear Model and which can be loaded in SPM, beta_*.nii files containing maps of estimated effect-sizes for each model regressor, as well as con_*.nii and spmT_*.nii files containing maps of estimated contrast values and T-statistics, respectively, for each specified first-level contrast. These results can be displayed using the syntax:
Additional first-level analysis details or options can be specified using a last argument to the "el model ..." command, pointing to a model configuration options file (either directly or indirectly to files located in conn/modules/el/pipeline_model_*.cfg), e.g.
(see "help el" and "help evlab17_run_model" for additional details)