resources afni

Under construction. A description of afni resources.

Description

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 analyses.

Copy

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.

Deconvolve

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

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

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.

timing_files

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 file all unique behaviors will be identified (ref. "trial_type"). These unique behaviors will then be used to construct AFNI-styeld timing files using onset times only, with the asterisk "*" holding for runs in which a certain behavior does not occur.

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 sub-brick of the deconvolved file for the coefficients and test statistics.

regress_resting

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.