-
Notifications
You must be signed in to change notification settings - Fork 5
resources afni
Under construction. A description of afni resources.
The sub-package afni contains a number of modules:
- copy
- deconvolve
- group
- masks
- motion
- process
- submit
These modules are organized, largely, according to the type of work performed. That is, any functions that deal with mask generation are located in the module masks. Together, these modules are capable of conducting resting state and task-based EPI analyses.
copy contains a single function, copy_data. It is the role of this module to (a) copy structural, functional, and motion files needed by AFNI, and (b) to start and populate the afni_data dictionary that will be used to pass files to various modules.
The deconvolve module currently contains four functions used for preparing and conducting deconvolutions of the EPI time series:
- write_decon
- run_reml
- timing_files
- regress_resting
write_decon constructs a 3dDeconvolve command that incorporates censor files, motion (mean and derivative) baseline regressors, and task timing files for the various pre-processed (scaled) EPI runs.
Currently, only a two gamma basis function is supported, AFNI is allowed to determine the number of polynomial regressors (using local times), and output names follow traditional AFNI formatting. The AFNI naming convention is due to the fact that 3dDeconvolve is employed to generate (a) the deconvolution matrices and (b) the 3dREMLfit command.
The generated 3dDeconvolve command is saved to a script in the subject's func directory, for review, and then the command is executed in order to generate the files listed above.
run_reml has two parts. First, a white matter time series is constructed from an eroded white matter mask. Then the foo.REML_cmd generated by write_decon is executed with the addition of the white matter time series as a nuissance regressor.
The timing_files function is specific to the EMU project, but could easily be updated for other projects. When user-specified timing files/deconvolution are supplied, the timing_files module is not used. timing_files will orient to the foo_events.tsv BIDS files that accompany each EPI run in func. From these events files all unique behaviors will be identified (ref. the "trial_type" column). These unique behaviors will then be used to construct AFNI-styled timing files using onset times only and the asterisk "*" holding for runs in which a certain behavior does not occur. This could be updated to construct onset:duration, but is not supported currently.
The decon_plan nested dictionary is constructed by the timing_files module, where the parent key is the deconvolution name, child key is the behavior (<8 characters!), and value is the path to the timing file. The behavior name is embedded in the file name as a description. For example:
{
"UniqueBehs": {
"behA": "/path/to/foo_desc-behA_events.1D",
"behB": "/path/to/foo_desc-behB_events.1D",
"behC": "/path/to/foo_desc-behC_events.1D",
}
}
With the decon_plan above, an output file "decon_task-foo_UniqueBehs_stats_REML+tlrc" will be generated by modeling three behaviors, behA-C, and "behA" etc will be used to label the coefficient and statistics sub-bricks of the deconvolved file.
The regress_resting function is used to project a regression matrix for resting state analyses. It is currently written for only a single pre-processed (scaled) EPI file, but this could be updated. There are three main steps.
First, a principal components analysis is conducted on an eroded CSF mask in order to identify a nuissance time series. Second, a deconvolution via 3dDeconvolve is conducted. Here, only the censor file and nuissance regressors (CSF timeseries, mean motion, derivative motion) are included in the model, and so 3dDeconvolve is actually being used to "clean" the data, producing a set of nuissance models on the main output file (foo_stats+tlrc) and the remaining "clean" data as a residual (foo_errts+tlrc). As in write_decon, the deconvolution command is written as a shell script to the participant's func directory for review.
Third, the "no censor" matrix produced by 3dDeconvolve is used to project a correlation matrix using the pre-processed (scaled) EPI file as input. By default, the function will use the "anaticor" method, where the time series of an eroded white matter mask will be included in the projection as a nuissance regressor.
The group module currently contains three functions used for preparing and conducting group-level analyses:
- int_mask
- resting_etac
- task_etac
The int_mask function constructs a group-level gray matter intersection mask. That is, each participants' EPI-anat intersection mask is combined (union/frac=1) to construct a group intersection mask. This mask indicates which voxels have meaningful signal across all participants. The group intersection mask is then multiplied by a template gray matter mask. This helps focus analyses to cortical and sub-cortical regions (excluding white matter, CSF) and also serves to reduce the multiple comparison correction as fewer voxels are being included in models of spurious results.
The resting_etac function constructs an "A vs not-A" comparison, or a test against zero. Z-transformed correlation matrices are used as input, and analyses are constrained to gray matter voxels via the group-level gray matter intersection mask (above). With ETAC (equitable thresholding and clustering), a variety of p-value threshold are used in order to detect both large clusters of a "smaller" statistic and smaller clusters with a "larger" statistic. Here, default options are NN=2, two-sided, p-values = .01, .005, .002, .0001.
TBC