func_processing.workflow package

Submodules

func_processing.workflow.control_afni module

Control module for running AFNI.

These functions will finish pre-processing following fMRIprep, and then deconvolve EPI data. Also supports resting state and group-level analyses.

func_processing.workflow.control_afni.control_deconvolution(afni_data, afni_dir, dset_dir, subj, sess, task, dur, decon_plan, kp_interm, decon_method='new')

Generate and run planned deconvolutions.

Use AFNI’s 3dDeconvolve and 3dREMLfit to deconvolve EPI timeseries. This is oriented from the <decon_json> input. First, a deconvolution script is generated, saved (decon_<task>_<decon_title>.sh), and ran to generate AFNI’s X.files and REML script (decon_<task>_<decon_title>_stats.REML_cmd). Then a nuissance file is generated, and finally 3dREMlfit deconvolves the EPI data.

Will make a nuissance file for each <task>, and condcut a deconvolution for each key (<decon_title>) in decon_json. See Notes below.

Parameters

  • afni_data (dict) – mapping of AFNI data, returned by control_preproc

  • afni_dir (str) – /path/to/BIDS/project/derivatives/afni

  • dset_dir (str) – /path/to/BIDS/project/dset

  • subj (str) – BIDS subject string (sub-1234)

  • sess (str) – BIDS session string (ses-S1)

  • task (str) – BIDS task string (task-test)

  • dur (int/float/str) – duration of task to model (2)

  • decon_plan (dict) –

    mapping of behvavior to timing files for planned deconvolutions, see notes below

    [default=None, yields decon_<task>_UniqueBehs]

  • kp_interm (bool) – [T/F] whether to keep (T) or remove (F) intemediates

Returns

afni_data – updated with decon output

added afni_data keys:

  • [dcn-<decon_title>] = decon_<task>_<decon_title>_stats.REML_cmd

  • [epi-nuiss] = nuissance signal file

  • [rml-<decon_title>] = deconvolved file (decon_<task>_<decon_title>_stats_REML+tlrc)

Return type

dict

Notes

Only onset timing files accepted, not married onset:duration! Timing files must be AFNI formatted, (one row/run for each beahvior). See example in qc/no_valence.

decon_plan should have the following format:

{“Decon Tile”: {

“BehA”: “/path/to/timing_behA.txt”,

“BehB”: “/path/to/timing_behB.txt”,

“BehC”: “/path/to/timing_behC.txt”}}

Example:

{“NegNeuPosTargLureFoil”: {

“negTH”: “/path/to/negative_target_hit.txt”,

“negTM”: “/path/to/negative_target_miss.txt”,

“negLC”: “/path/to/negative_lure_cr.txt”}}

func_processing.workflow.control_afni.control_preproc(prep_dir, afni_dir, subj, sess, task, tplflow_str, do_blur)

Move data through AFNI pre-processing.

Copy relevant files from derivatives/fmriprep to derivatives/afni, then blur and scale EPI data. Also creates EPI-T1 intersection and tissue class masks. Finally, generate motion mean, derivative, and censor files.

Parameters

  • prep_dir (str) – /path/to/BIDS/project/derivatives/fmriprep

  • afni_dir (str) – /path/to/BIDS/project/derivatives/afni

  • subj (str) – BIDS subject string (sub-1234)

  • sess (str) – BIDS session string (ses-S1)

  • task (str) – BIDS task string (task-test)

  • tplflow_str (str) – template ID string, for finding fMRIprep output in template space (space-MNIPediatricAsym_cohort-5_res-2)

  • do_blur (bool) – [T/F] whether to blur as part of pre-processing

Returns

afni_data – dictionary containing mappings for AFNI files

afni_data keys:

  • [struct-t1] = pre-processed T1w

  • [mask-brain] = brain mask

  • [mask-probGM] = gray matter probability label

  • [mask-probWM] = white matter probability label

  • [mask-erodedGM] = gray matter eroded mask

  • [mask-erodedWM] = white matter eroded mask

  • [mask-int] = EPI-structural intersection mask

  • [mask-min] = mask of EPI space with >minimum signal

  • [epi-preproc?] = pre-processed EPI run-?

  • [epi-blur?] = blurred/smoothed EPI run-?, if do_blur = T

  • [epi-scale?] = scaled EPI run-?

  • [mot-confound?] = confounds timeseries for run-?

  • [mot-mean] = mean motion for task (6dof)

  • [mot-deriv] = derivative motion for task (6dof)

  • [mot-censor] = binary censor vector for task

Return type

dict

func_processing.workflow.control_afni.control_resting(afni_data, afni_dir, subj, sess, coord_dict, kp_interm)

Generate and control resting state regressions.

Based on example 11 of afni_proc.py and s17.proc.FT.rest.11 of afni_data6. Projects regression matrix, and generates various metrics like SNR, GCOR, etc.

Parameters

  • afni_data (dict) – mapping of AFNI data, returned by control_preproc

  • afni_dir (str) – /path/to/BIDS/project/derivatives/afni

  • subj (str) – BIDS subject string (sub-1234)

  • sess (str) – BIDS session string (ses-S1)

  • coord_dict (dict) –

    seed name, coordinates

    {“rPCC”: “5 -55 25”}

  • kp_interm (bool) – [T/F] whether to keep (T) or remove (F) intemediates

Returns

afni_data – updated with generated files

added keys to afni_data:

  • [reg-matrix] = epi projection matrix

  • [S<seed>-ztrans] = Z-transformed seed-based correlation matrix

Return type

dict

func_processing.workflow.control_afni.control_resting_group(seed, task, deriv_dir, group_dir, group_data, do_blur)

Conduct group-level analyses.

Construct group GM intersection mask, then run on subject correlation matrices.

Parameters

  • seed (str) – seed name (rPCC)

  • task (str) – BIDS string (task-rest)

  • deriv_dir (str) – location of project AFNI derivatives

  • group_dir (str) – output location of work

  • group_data (dict) –

    contains keys pointing to required files

    required keys:

    • [mask-gm] = gray matter mask

    • [subj-list] = list of subjects

    • [all-ztrans] = list of Ztrans files

  • do_blur (bool) – [T/F] whether blur was done in pre-processing

Returns

group_data – updated with the fields for generated files

added afni_data keys:

  • [mask-int] = gray matter intersection mask

  • [S<seed>-etac] = seed stat output

Return type

dict

func_processing.workflow.control_afni.control_task_group(beh_list, task, sess, deriv_dir, group_dir, group_data, do_blur)

Conduct group-level analyses.

Construct group GM intersection mask, then run A-vs-B ETAC.

Parameters

  • beh_list (list) –

    list of 2 behaviors which match sub-brick name

    e.g. neg for neg#0_Coef

  • task (str) – BIDS string (task-test)

  • sess (str) – BIDS session (ses-S2)

  • deriv_dir (str) – location of project AFNI derivatives

  • group_dir (str) – output location of work

  • group_data (dict) –

    contains keys pointing to required files

    required keys:

    • [mask-gm] = gray matter mask

    • [subj-list] = list of subjects

    • [dcn-file] = decon file string

  • do_blur (bool) – [T/F] whether blur was done in pre-processing

Returns

group_data – updated with keys for generated files

added group_data keys:

  • [mask-int] = gray matter intersection mask

  • [behAB-etac] = etac stat output

Return type

dict

func_processing.workflow.control_ashs module

Control module for running ASHS.

These functions will use T1- and T2-weighted files to produce hippocampal subfield labels.

func_processing.workflow.control_ashs.control_hipseg(t1_dir, t2_dir, deriv_dir, work_dir, atlas_dir, sing_img, subj, t1_file, t2_file, atlas_str)

Segment hippocampal subfields via ASHS.

Use the singularity of docker://nmuncy/ashs to produce hippocampal subfield labels in <deriv_dir>. Requires native T1- and T2-weighted NIfTI files (ref <anat_dir>). Segmentation intermediates are written to <work_dir>, and then removed after copyfing <work_dir>/final contents to <deriv_dir>.

This work is equal to merely calling the resources.ashs.hipseg module, but written as a workflow for the sake of consistency.

Parameters

  • t1_dir (str) – absolute path to directory containing T1-weighted file

  • t2_dir (str) – absolute path to directory containing T2-weighted file

  • deriv_dir (str) – absolute path to desired output location

  • work_dir (str) – absolute path to desired working directory, relevant files are copied to deriv_dir

  • atlas_dir (str) – absolute path to directory containing ASHS atlas

  • sing_img (str) – /path/to/ashs_singularity.simg

  • subj (str) – BIDs subject (sub-1234)

  • t1_file (str) – file name of T1-weighted file (sub-1234_ses-S1_T1w.nii.gz)

  • t2_file (str) – file name of T2-weighted file (sub-1234_ses-S1_T2w.nii.gz)

  • atlas_str (str) – ASHS atlas directory, found within atlas_dir (ashs_atlas_magdeburg)

Returns

ashs_out – final ASHS labels

Return type

list

func_processing.workflow.control_fmriprep module

Control module for running fMRIprep.

Orients to the data, runs FreeSurfer if needed, and then runs fMRIprep.

func_processing.workflow.control_fmriprep.control_fmriprep(subj, proj_dir, scratch_dir, sing_img, tplflow_dir, fs_license)

Control fMRIprep resources.

First, run subject data through FreeSurfer. Then, run fMRIprep.

Parameters

  • subj (str) – BIDS subject string

  • proj_dir (str) – Path to BIDS project directory

  • scratch_dir (str) – Path to working/scratch directory

  • sing_img (str) – Path to fmriprep singularity iamge

  • tplflow_dir (str) – Path to templateflow directory

  • fs_license (str) – Path to FreeSurfer license

Returns

path_dict – paths for ease of copying, cleaning

Return type

dict

func_processing.workflow.control_reface module

Control module for running AFNI’s reface.

Replaces subject T1w face with composite.

func_processing.workflow.control_reface.control_reface(subj, sess, t1_file, proj_dir, method)

Control de/refacing of T1-weighted files.

Parameters

  • subj (str) – BIDS subject string (sub-1234)

  • sess (str) – BIDS session string (ses-A)

  • t1_file (str) – file name of T1-weighted file (sub-1234_ses-A_T1w.nii.gz)

  • proj_dir (str) – path to BIDS project dir (/path/to/BIDS/proj)

  • method (str) – “deface”, “reface”, or “reface_plus” method

Returns

msg_out – Success message

Return type

str

Module contents