-
Notifications
You must be signed in to change notification settings - Fork 5
Workflow
Workflow modules coordinate the various resource modules to construct the actual pipeline used on MRI data. Currently three workflows exist, one for controlling AFNI resources, one for ASHS, and one for refacing T1w files (for NDA submissions). It is planned to add workflows for FreeSurfer and fMRIprep.
ASHS and reface modules/pipelines are simply a call for their respective resource module, but are included here despite their redundancy for project consistency.
Detailed descriptions are available here, assuming sphinx is cooperative.
Automated segmentation of hippocampal subfields for a single subject is controlled by control_ashs.control_hippseg. While not interacting with EPI data, these masks will likely be used to target HC subfield regions for functional analyses. Requires a singularity image of this container. Final files are written to project_dir/derivatives/ashs.
This workflow supports defacing, refacing (default), or reface_plus (so special) of T1w files. We currently do not incorporate de/re/plus facing in our pre-processing pipelines, hence the separate workflow, but reface T1w files for NDA hosting. Final files are written to project_dir/derivatives/<reface_method>.
The control_fmriprep workflow has three main sections. First, data is copied from dset to /scratch due to read/write issues on the HPC. This is done on scheduled resources to avoid "researcher wait time". Second, FreeSurfer is conducted, if the output does not already exist, via the resources.fmriprep.preprocess.run_freesurfer module. If this is successful, a singularity file (sif) of fMRIprep is used to pre-process participant structural and functional data via resources.fmriprep.preprocess.run_fmriprep. Final files are written to project_dir/derivatives/freesurfer and project_dir/derivatives/fmriprep.
A number of AFNI-based pipelines are available in this workflow module, both for single-subject and group-level analyses and also for task-based and resting state analyses. The various pipelines use fMRIprep to do the initial pre-processing, but then AFNI takes over for some additional steps in preparation for the AFNI-based deconvolution. BIDS formatting and file names are assumed and largely employed, but some reversion to AFNI naming convention occurs. Final files are written to project_dir/derivatives/afni.
The various AFNI functions operate by creating, passing, and updating a dictionary (afni_data) between the various modules. This dictionary employs a {key: file_path} format (e.g. {struct-t1: /path/to/subj/t1.nii.gz}), and it is via this dictionary that the various modules will orient to required files. Required afni_data keys are specified in the docstrings for each module.
Post fMRIprep AFNI-based pre-processing for task and resting state analyses is controlled by this function. The steps involve an optional blur/smoothing via a boolean do_blur option (ETAC blurring in the group-level analyses accounts for this toggle), the construction of EPI-anatomic intersection, tissue (ATROPOS), and minimum EPI masks. EPI data is then scaled, and motion and censor files are generated in AFNI format.
Both task and resting state pipelines use control_preproc (hence the option to blur), and control_preproc constructs the initial afni_data dictionary for use in subsequent modules.
Task-based deconvolution is available via this function. By default, regressors will consist of unique behaviors for the session/task, referencing the BIDS foo_events.tsv available for each run. User-specified timing files can be injected via the decon_plan option (see the function notes). An example of such an injection can be found in the qc directory (no_valence).
Two methods for conducting deconvolution are currently supported, the new method (default, write_new_decon) and the traditional AFNI approach (write_decon). In the new method, the motion censor file is used to remove behaviors that occur in the same volume as the motion event prior to creating behavioral regressors for the deconvolution, and the motion events are included as a baseline regressor. In the traditional approach, the motion censor file removes volumes from the deconvolution matrix, resulting in a discontinuous timeseries and matrices that differ in size between participants.
Currently, a stripped-down version of 3dDeconvolve is supported, with a default duration (2s) and two gamma basis function. Future updates to resources.afni.deconvolve may increase the flexibility of this workflow. 3dDeconvolve is used to generate the deconvolution matrices, and deconvolution is accomplished via 3dREMLfit.
The bolus of the resting state pipeline involves setting up for and projecting a correlation matrix. First a principal components analysis is conducted to identify the CSF timeseries. Next a deconvolution is employed, utilizing only nuissance regressors (polynomials, motion, and CSF timeseries) to produce "cleaned" signal (which loads on the model residual). Finally, two correlation projections are supported, traditional and anaticor (default). If anaticor is selected an eroded white matter mask is generated from which another nuissnace timeseries is extracted and incorporated into the regression projection. Additionally, this workflow also produces metrics of TSNR, GCOR, and total noise estimations.
A seed-based correlation matrix (Z-transformed) will be generated from the projected regression matrix above. Currently only a coordinate-based seed is supported, but resources.afni.process.resting_seed could be updated to accept an ROI mask.
First a group gray matter intersection mask is constructed. This is the product of (a) every participants' EPI-T1w intersection mask with (b) a template gray matter mask. This helps constrain analyses to only gray matter regions for which meaningful signal exists across all participants.
Next, an "A vs not-A" test is conducted via 3dttest++ (using the ETAC updates). This will test at various p-values and conduct noise simulations to arrive at the ideal FWE=0.05. Recommendations are to let ETAC manage blurring, so if you follow this don't blur as part of the pre-processing. Updates to resource.afni.group.resting_etac could update this test for other hypotheses.
As in control_resting_group, first a group gray matter intersection mask is constructed. This mask is then used to limit the number of voxels being tested to those that are relevant, which helps constrain the multiple comparison correction.
An "A vs B" test will then be conducted with ETAC methods via 3dttest++. Behaviors A and B will be supplied by the list beh_list, and the module will identify the appropriate sub-bricks for the corresponding behaviors in each subject's deconvolved file for 3dttest++ inclusion; only subjects with both behaviors will be included in the model. Again, this could be updated in resources.afni.group.task_etac.