Probably the most important chapter in this section is about how to handle error and crashes. Because at the beginning you will run into a few.
For example:
string
as input, where a float
value is expected or you try to specify a parameter that doesn't exist. Be sure to use the right input type
and input name.[func1.nii, func2.nii, func3.nii]
to a node that only expects one input file . MapNode
is your solution.*.nii.gz
? SPM cannot handle that. Nipype's Gunzip
interface can help.Important note about crashfiles
. Crashfiles
are only created when you run a workflow, not during building a workflow. If you have a typo in a folder path, because they didn't happen during runtime, but still during workflow building.
In [ ]:
from nipype import SelectFiles, Node, Workflow
from os.path import abspath as opap
from nipype.interfaces.fsl import MCFLIRT, IsotropicSmooth
# Create SelectFiles node
templates={'func': '{subject_id}/ses-test/func/{subject_id}_ses-test_task-fingerfootlips_bold.nii.gz'}
sf = Node(SelectFiles(templates),
name='selectfiles')
sf.inputs.base_directory = opap('/data/ds000114')
sf.inputs.subject_id = 'sub-11'
# Create Motion Correction Node
mcflirt = Node(MCFLIRT(mean_vol=True,
save_plots=True),
name='mcflirt')
# Create Smoothing node
smooth = Node(IsotropicSmooth(fwhm=4),
name='smooth')
# Create a preprocessing workflow
wf = Workflow(name="preprocWF")
wf.base_dir = 'working_dir'
# Connect the three nodes to each other
wf.connect([(sf, mcflirt, [("func", "in_file")]),
(mcflirt, smooth, [("out_file", "in_file")])])
# Let's the workflow
wf.run()
Hidden, in the log file you can find the relevant information:
OSError: No files were found matching func template: /data/ds000114/sub-11/ses-test/func/sub-11_ses-test_task-fingerfootlips_bold.nii.gz
Interface SelectFiles failed to run.
170904-05:48:13,727 workflow INFO:
***********************************
170904-05:48:13,728 workflow ERROR:
could not run node: preprocWF.selectfiles
170904-05:48:13,730 workflow INFO:
crashfile: /repos/nipype_tutorial/notebooks/crash-20170904-054813-neuro-selectfiles-15f5400a-452e-4e0c-ae99-fc0d4b9a44f3.pklz
170904-05:48:13,731 workflow INFO:
***********************************
This part tells you that it's an OSError
and that it looked for the file /data/ds000114/sub-11/ses-test/func/sub-11_ses-test_task-fingerfootlips_bold.nii.gz
.
After the line ***********************************
, you can additional see, that it's the node preprocWF.selectfiles
that crasehd and that you can find a crashfile
to this crash under /opt/tutorial/notebooks
.
crashfile
To get the full picture of the error, we can read the content of the crashfile
(that has pklz
format by default) with the bash
command nipypecli crash
. We will get the same information as above, but additionally, we can also see directly the input values of the Node that crashed.
In [ ]:
!nipypecli crash $(pwd)/crash-*selectfiles-*.pklz
nipypecli
allows you to rerun the crashed node using an additional option -r
.
In [ ]:
!nipypecli crash -r $(pwd)/crash-*selectfiles-*.pklz
When running in terminal you can also try options that enable the Python or Ipython debugger when re-executing: -d
or -i
.
If you don't want to have an option to rerun the crashed workflow, you can change the format of crashfile to a text format. You can either change this in a configuration file (you can read more here), or you can directly change the wf.config
dictionary before running the workflow.
In [ ]:
wf.config['execution']['crashfile_format'] = 'txt'
wf.run()
Now you should have a new text file with your crash report.
In [ ]:
!cat $(pwd)/crash-*selectfiles-*.txt
In [ ]:
from nipype.interfaces.fsl import IsotropicSmooth
smooth = IsotropicSmooth(fwhm='4')
This will give you the error: TraitError
: The 'fwhm' trait of an IsotropicSmoothInput instance must be a float, but a value of '4' <type 'str'> was specified.
To make sure that you are using the right input types, just check the help
section of a given interface. There you can see fwhm: (a float)
.
In [ ]:
IsotropicSmooth.help()
In a similar way, you will also get an error message if the input type is correct but you have a type in the name:
TraitError: The 'output_type' trait of an IsotropicSmoothInput instance must be u'NIFTI_PAIR' or u'NIFTI_PAIR_GZ' or u'NIFTI_GZ' or u'NIFTI', but a value of 'NIFTIiii' <type 'str'> was specified.
In [ ]:
from nipype.interfaces.fsl import IsotropicSmooth
smooth = IsotropicSmooth(output_type='NIFTIiii')
As you an see in the MapNode example, if you try to feed an array as an input into a field that only expects a single file, you will get a TraitError
.
In [ ]:
from nipype.algorithms.misc import Gunzip
from nipype.pipeline.engine import Node
files = ['/data/ds000114/sub-01/ses-test/func/sub-01_ses-test_task-fingerfootlips_bold.nii.gz',
'/data/ds000114/sub-02/ses-test/func/sub-02_ses-test_task-fingerfootlips_bold.nii.gz']
gunzip = Node(Gunzip(), name='gunzip',)
gunzip.inputs.in_file = files
This can be solved by using a MapNode
:
In [ ]:
from nipype.pipeline.engine import MapNode
gunzip = MapNode(Gunzip(), name='gunzip', iterfield=['in_file'])
gunzip.inputs.in_file = files
Now, make sure that you specify files that actually exist, otherwise you can the same problem as in crash example 1, but this time labeled as TraitError
:
TraitError: Each element of the 'in_file' trait of a DynamicTraitedSpec instance must be an existing file name, but a value of '/data/ds102/sub-06/func/sub-06_task-flanker_run-1_bold.nii.gz' <type 'str'> was specified.
In [ ]:
files = ['/data/ds000114/sub-01/func/sub-01_task-fingerfootlips_bold.nii.gz',
'/data/ds000114/sub-03/func/sub-03_task-fingerfootlips_bold.nii.gz']
gunzip.inputs.in_file = files
By the way, not that those crashes don't create a crashfile
, because they didn't happen during runtime, but still during workflow building.
*.nii.gz
filesSPM12 cannot handle compressed NIfTI files (*nii.gz
). If you try to run the node nonetheless, it can give you different kind of problems:
*.nii.gz
filesSPM12 has a problem with handling *.nii.gz
files. For it a compressed functional image has no temporal dimension and therefore seems to be just a 3D file. So if we try to run the Realign
interface on a compressed file, we will get a TraitError
error.
In [ ]:
from nipype.interfaces.spm import Smooth
smooth = Smooth(in_files='/data/ds000114/sub-01/ses-test/anat/sub-01_ses-test_T1w.nii.gz')
smooth.run()
In [ ]:
from nipype.interfaces.spm import Realign
realign = Realign(in_files='/data/ds000114/sub-01/ses-test/func/sub-01_ses-test_task-fingerfootlips_bold.nii.gz')
realign.run()
This issue can be solved by unzipping the compressed NIfTI file before giving it as an input to an SPM node. This can either be done by using the Gunzip
interface from Nipype or even better, if the input is coming from a FSL interface, most of them have an input filed output_type='NIFTI'
, that you can set to NIFIT.
Especially at the beginning, just after installation, you sometimes forgot to specify some environment variables. If you try to use an interface where the environment variables of the software are not specified, e.g. if you try to run:
from nipype.interfaces.freesurfer import MRIConvert
convert = MRIConvert(in_file='/data/ds000114/sub-01/ses-test/anat/sub-01_ses-test_T1w.nii.gz',
out_type='nii')
you migh get an errors, such as:
IOError: command 'mri_convert' could not be found on host mnotter
Interface MRIConvert failed to run.
Or if you try to use SPM, but forgot to tell Nipype where to find it. If you forgot to tell the system where to find MATLAB (or MCR), than you will get same kind of error as above. But if you forgot to specify which SPM you want to use, you'll get the following RuntimeError
:
Standard error:
MATLAB code threw an exception:
SPM not in matlab path
You can solve this issue by specifying the path to your SPM version:
from nipype.interfaces.matlab import MatlabCommand
MatlabCommand.set_default_paths('/usr/local/MATLAB/R2017a/toolbox/spm12')
In [ ]:
from nipype.interfaces.spm import Realign
realign = Realign(register_to_mean=True)
realign.run()
This gives you the error:
ValueError: Realign requires a value for input 'in_files'. For a list of required inputs, see Realign.help()
As described by the error text, if we use the help()
function, we can actually see, which inputs are mandatory and which are optional.
In [ ]:
realign.help()
In [ ]:
from nipype.interfaces.afni import Despike
despike = Despike(in_file='/data/ds000114/sub-01/ses-test/func/sub-01_ses-test_task-fingerfootlips_bold.nii.gz',
output_type='NIFTI')
despike.run()
This results in the TraitError
:
TraitError: Cannot set the undefined 'output_type' attribute of a 'DespikeInputSpec' object.
So what went wrong? If you use the help()
function, you will see that the correct input filed is called outputtype
and not output_type
.
In [ ]:
from nipype import SelectFiles, Node, Workflow
from os.path import abspath as opap
from nipype.interfaces.fsl import MCFLIRT, IsotropicSmooth
# Create SelectFiles node
templates={'func': '{subject_id}/func/{subject_id}_task-fingerfootlips_bold.nii.gz'}
sf = Node(SelectFiles(templates),
name='selectfiles')
sf.inputs.base_directory = opap('/data/ds000114')
sf.inputs.subject_id = 'sub-01'
# Create Motion Correction Node
mcflirt = Node(MCFLIRT(mean_vol=True,
save_plots=True),
name='mcflirt')
# Create Smoothing node
smooth = Node(IsotropicSmooth(fwhm=4),
name='smooth')
# Create a preprocessing workflow
wf = Workflow(name="preprocWF")
wf.base_dir = 'working_dir'
# Connect the three nodes to each other
wf.connect([(sf, mcflirt, [("func", "in_file")]),
(mcflirt, smooth, [("out_file", "in_file")])])
Now, let's create a new node and connect it to the already occupied input field in_file
of the smooth
node:
In [ ]:
# Create a new node
mcflirt_NEW = Node(MCFLIRT(mean_vol=True),
name='mcflirt_NEW')
# Connect it to an already connected input field
wf.connect([(mcflirt_NEW, smooth, [("out_file", "in_file")])])
This will lead to the error:
Exception:
Trying to connect preprocWF.mcflirt_NEW:out_file to preprocWF.smooth:in_file but input 'in_file' of node 'preprocWF.smooth' is already connected.