Nipype workflow to generate fieldmaps from EPI acquisitions with differing phase-encoding directions
Project description
nipype-generate-fieldmaps
Nipype workflow to generate fieldmaps from EPI acquisitions with differing phase-encoding directions
Installation
pip install nipype-generate-fieldmaps
Usage
As a stand-alone workflow
# create the workflow
wf = create_prepare_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_sidecar_pe1_file = my_se_epi_sidecar_pe1_file # type: str | Path
wf.inputs.inputnode.se_epi_sidecar_pe2_file = my_se_epi_sidecar_pe2_file # type: str | Path
# set the output directory
wf.base_dir = my_output_dir # type: str | Path
# run it
wf.run()
As a nested workflow
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_prepare_fieldmaps_wf
# parent workflow defined elsewhere
wf = Workflow(...)
# create the (sub-)workflow
fmap_wf = create_prepare_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_sidecar_pe1_file')
wf.connect(maybe_a_4th_node, 'sidecar_file', fmap_wf, 'inputnode.se_epi_sidecar_pe2_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.echospacing', epireg, 'echospacing')
wf.connect(fmap_wf, 'outputnode.pedir', epireg, 'pedir')
From the command line
$ 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
Prerequisites
This workflow has a few requirements:
-
There are two acquisitions (i.e.
.nii.gz
files) acquired with different phase encodings, usually opposite phase encodings. -
Num volumes in acquisition 1 equals Num volumes in acquisition 2
-
Each acquisition has a JSON sidecar. Specifically, this workflow only 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
andTotalReadoutTime
, orPhaseEncodingDirection
,ReconMatrixPE
, andEffectiveEchoSpacing
, orPhaseEncodingDirection
,ReconMatrixPE
, andBandwidthPerPixelPhaseEncode
If either JSON sidecar does not contain one of these three sets of parameters the workflow will produce an error.
I/O
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_sidecar_pe1_file
The JSON sidecar for the first spin-echo EPI file
-
se_epi_sidecar_pe2_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 oftopup
-
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for nipype-generate-fieldmaps-0.2.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 822c1b5c2f83495065f8a404ff735dc5478bc2997ebf301dd6821b9092b268fa |
|
MD5 | 9787f80a4dae94a46708005dfa59268c |
|
BLAKE2b-256 | c0aaf32dabf8441b2e57520aeffc4f06841f7a12247ae909b2c7c4e80536c4e5 |
Hashes for nipype_generate_fieldmaps-0.2.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ada928943c55bb79df0d6aec65f21516e70fd5952de5262bd26596ba99c544a5 |
|
MD5 | 3a0400407d7be9689c1e839d59413844 |
|
BLAKE2b-256 | 5c5d2457ce3606a67b7e9a6e1a8c4af3378f6173ae435fbfc1bd659889b90daf |