niworkflows.func.util module

Utility workflows.

niworkflows.func.util.init_bold_reference_wf(omp_nthreads, bold_file=None, pre_mask=False, name='bold_reference_wf', gen_report=False)[source]

Build a workflow that generates reference BOLD images for a series.

The raw reference image is the target of HMC, and a contrast-enhanced reference is the subject of distortion correction, as well as boundary-based registration to T1w and template spaces.

Workflow Graph
../_images/niworkflows-func-util-1.png

(Source code, png, svg, pdf)

Parameters
  • bold_file (str) – BOLD series NIfTI file

  • omp_nthreads (int) – Maximum number of threads an individual process may use

  • name (str) – Name of workflow (default: bold_reference_wf)

  • gen_report (bool) – Whether a mask report node should be appended in the end

Inputs
  • bold_file (str) – BOLD series NIfTI file

  • bold_mask (bool) – A tentative brain mask to initialize the workflow (requires pre_mask parameter set True).

  • dummy_scans (int or None) – Number of non-steady-state volumes specified by user at beginning of bold_file

  • sbref_file (str) – single band (as opposed to multi band) reference NIfTI file

Outputs
  • bold_file (str) – Validated BOLD series NIfTI file

  • raw_ref_image (str) – Reference image to which BOLD series is motion corrected

  • skip_vols (int) – Number of non-steady-state volumes selected at beginning of bold_file

  • algo_dummy_scans (int) – Number of non-steady-state volumes agorithmically detected at beginning of bold_file

  • ref_image (str) – Contrast-enhanced reference image

  • ref_image_brain (str) – Skull-stripped reference image

  • bold_mask (str) – Skull-stripping mask of reference image

  • validation_report (str) – HTML reportlet indicating whether bold_file had a valid affine

Subworkflows
  • init_enhance_and_skullstrip_wf()

niworkflows.func.util.init_enhance_and_skullstrip_bold_wf(name='enhance_and_skullstrip_bold_wf', pre_mask=False, omp_nthreads=1)[source]

Enhance and run brain extraction on a BOLD EPI image.

This workflow takes in a BOLD fMRI average/summary (e.g., a reference image averaging non-steady-state timepoints), and sharpens the histogram with the application of the N4 algorithm for removing the INU bias field and calculates a signal mask.

Steps of this workflow are:

  1. Calculate a tentative mask by registering (9-parameters) to fMRIPrep’s EPI -boldref template, which is in MNI space. The tentative mask is obtained by resampling the MNI template’s brainmask into boldref-space.

  2. Binary dilation of the tentative mask with a sphere of 3mm diameter.

  3. Run ANTs’ N4BiasFieldCorrection on the input BOLD average, using the mask generated in 1) instead of the internal Otsu thresholding.

  4. Calculate a loose mask using FSL’s bet, with one mathematical morphology dilation of one iteration and a sphere of 6mm as structuring element.

  5. Mask the INU-corrected image with the latest mask calculated in 3), then use AFNI’s 3dUnifize to standardize the T2* contrast distribution.

  6. Calculate a mask using AFNI’s 3dAutomask after the contrast enhancement of 4).

  7. Calculate a final mask as the intersection of 4) and 6).

  8. Apply final mask on the enhanced reference.

Step 1 can be skipped if the pre_mask argument is set to True and a tentative mask is passed in to the workflow throught the pre_mask Nipype input.

Workflow graph
../_images/niworkflows-func-util-2.png

(Source code, png, svg, pdf)

Parameters
  • name (str) – Name of workflow (default: enhance_and_skullstrip_bold_wf)

  • pre_mask (bool) – Indicates whether the pre_mask input will be set (and thus, step 1 should be skipped).

  • omp_nthreads (int) – number of threads available to parallel nodes

Inputs
  • in_file (str) – BOLD image (single volume)

  • pre_mask (bool) – A tentative brain mask to initialize the workflow (requires pre_mask parameter set True).

Outputs
  • bias_corrected_file (str) – the in_file after N4BiasFieldCorrection

  • skull_stripped_file (str) – the bias_corrected_file after skull-stripping

  • mask_file (str) – mask of the skull-stripped input file

  • out_report (str) – reportlet for the skull-stripping

niworkflows.func.util.init_skullstrip_bold_wf(name='skullstrip_bold_wf')[source]

Apply skull-stripping to a BOLD image.

It is intended to be used on an image that has previously been bias-corrected with init_enhance_and_skullstrip_bold_wf()

Workflow Graph
../_images/niworkflows-func-util-3.png

(Source code, png, svg, pdf)

Inputs

in_file (str) – BOLD image (single volume)

Outputs
  • skull_stripped_file (str) – the in_file after skull-stripping

  • mask_file (str) – mask of the skull-stripped input file

  • out_report (str) – reportlet for the skull-stripping