Nipype workflow to generate fieldmaps from EPI acquisitions with differing phase-encoding directions

pip install nipype-generate-fieldmaps

# create the workflow wf = create_generate_fieldmaps_wf() # wire-up the inputs wf.inputs.inputnode.se_epi_pe1_file = my_se_epi_pe1_file # type: str | Path wf.inputs.inputnode.se_epi_pe2_file = my_se_epi_pe2_file # type: str | Path wf.inputs.inputnode.se_epi_pe1_sidecar_file = my_se_epi_pe1_sidecar_file # type: str | Path wf.inputs.inputnode.se_epi_pe2_sidecar_file = my_se_epi_pe2_sidecar_file # type: str | Path # set the output directory wf.base_dir = my_output_dir # type: str | Path # run it wf.run()

The nodes node1, node2, some_other_node, maybe_a_4th_node, epi_node, and anat_node are made up for demonstration purposes

from nipype import Workflow from nipype.interfaces.fsl import EpiReg from nipype_generate_fieldmaps import create_generate_fieldmaps_wf # parent workflow defined elsewhere wf = Workflow(...) # create the (sub-)workflow fmap_wf = create_generate_fieldmaps_wf() # connect the various nodes form the parent workflow to the nested fieldmap workflow wf.connect(node1, 'out_file', fmap_wf, 'inputnode.se_epi_pe1_file') wf.connect(node2, 'out', fmap_wf, 'inputnode.se_epi_pe2_file') wf.connect(some_other_node, 'output_file', fmap_wf, 'inputnode.se_epi_pe1_sidecar_file') wf.connect(maybe_a_4th_node, 'sidecar_file', fmap_wf, 'inputnode.se_epi_pe2_sidecar_file') # connect the fieldmap workflow outputs to one (or more) node(s) in the parent workflow # for example: EpiReg() epireg = Node(EpiReg(out_base='epi2str.nii.gz'), name='epi_reg') # from elsewhere wf.connect(epi_node, 'my_epi_file' epireg, 'epi') wf.connect(anat_node, 'my_t1_file', epireg, 't1_head') wf.connect(anat_node, 'my_t1_brain_file', epireg, 't1_brain') # from the fieldmap workflow! wf.connect(fmap_wf, 'outputnode.fmap_rads_file', epireg, 'fmap') wf.connect(fmap_wf, 'outputnode.fmap_mag_file', epireg, 'fmapmag') wf.connect(fmap_wf, 'outputnode.fmap_mag_brain_file', epireg, 'fmapmagbrain') wf.connect(fmap_wf, 'outputnode.echo_spacing', epireg, 'echospacing') wf.connect(fmap_wf, 'outputnode.pe1_pedir', epireg, 'pedir')

$ nipype-generate-fieldmaps --help usage: nipype-generate-fieldmaps [-h] [-v] se_epi_pe1 se_epi_pe2 se_epi_pe1_sidecar se_epi_pe2_sidecar out_dir Generate fieldmaps from EPI acquisitions with differing phase-encoding directions positional arguments: se_epi_pe1 The spin-echo EPI file acquired in the 'first' phase-encoding direction se_epi_pe2 The spin-echo EPI file acquired in the 'second' phase-encoding direction se_epi_pe1_sidecar The JSON sidecar for the first spin-echo EPI file se_epi_pe2_sidecar The JSON sidecar for the second spin-echo EPI file out_dir The directory into which outputs are written optional arguments: -h, --help show this help message and exit -v, --version show program's version number and exit

This workflow has a few requirements:

1. There are two acquisitions (i.e. .nii.gz files) acquired with different phase encodings, usually opposite phase encodings but this need not be the case.

2. The number of volumes in acquisition 1 (the first phase encoding direction) equals the number of volumes in acquisition 2 (the second phase encoding direction)

3. Each acquisition has a JSON sidecar. Specifically, this workflow requires that each sidecar contain one of the following sets of properties. These properties are listed in the order in which the workflow will search:

   • PhaseEncodingDirection and TotalReadoutTime, or
   • PhaseEncodingDirection, ReconMatrixPE, and EffectiveEchoSpacing, or
   • PhaseEncodingDirection, ReconMatrixPE, and BandwidthPerPixelPhaseEncode

   If either JSON sidecar fails to contain at least one of the above sets of parameters the workflow will produce an error.

This workflow requires 4 inputs to be connected to the node named inputnode:

• se_epi_pe1_file

  The spin-echo EPI file acquired in the 'first' phase-encoding direction

• se_epi_pe2_file

  The spin-echo EPI file acquired in the 'second' phase-encoding direction

• se_epi_pe1_sidecar_file

  The JSON sidecar for the first spin-echo EPI file

• se_epi_pe2_sidecar_file

  The JSON sidecar for the second spin-echo EPI file

This workflow also exposes the following outputs via the node named outputnode:

• acq_params_file

  The computed file passed to the --datain option of topup

• corrected_se_epi_file

  The .nii.gz image containing all distortion corrected volumes from the two input acquisitions

• fmap_hz_file

  The fieldmap in hertz (Hz)

• fmap_rads_file

  The fieldmap in radians per second (rad/s)

• fmap_mag_file

  The 'magnitude' image (mean image) computed by averaging all volumes in corrected_se_epi_file

• fmap_mag_brain_file

  The result of applying brain-extraction to fmap_mag_file

• fmap_mag_brain_mask_file

  The brain mask produced during the brain-extraction of fmap_mag_file

1. Have or install a recent version of poetry (version >= 1.1)
2. Fork the repo
3. Setup a virtual environment (however you prefer)
4. Run poetry install
5. Run pre-commit install
6. Add your changes
7. Commit your changes + push to your fork
8. Open a PR