Nipype

Nipype interfaces are the building blocks used to wrap external software tools and internal utilities into a format compatible with Nipype workflows. They are categorized into two main groups:

In-house Interfaces

These are provided by Nipype for workflow management and basic data handling:

• Algorithms: For executing specific algorithmic tasks.
• Image manipulation: For basic image processing.
• I/O Operations: For filesystem and storage interactions.
• Self-reporting interfaces: Mixins for interface behavior.
• Utilities: General purpose utility tools.

Third-party Tool Interfaces

Nipype provides extensive support for neuroimaging software suites, including but not limited to:

• FSL, AFNI, ANTs, SPM: Major neuroimaging analysis suites.
• FreeSurfer: For brain MRI processing.
• DIPY, MRTrix3, Camino: Tools for diffusion MRI analysis.
• NiLearn, NiPy, Nitime: Python-based neuroimaging libraries.
• 3D Slicer, Connectome Workbench: Visualization and discovery tools.
• Matlab script wrapper: To integrate Matlab scripts into Nipype workflows.
• dcm2nii, Convert3D: Format conversion tools.

Nipype interfaces (such as fsl and spm interfaces) follow specific rules for handling infile and outfile parameters to ensure consistent filename generation and path management.

Filename Generation Rules

1. Absolute Path Override: If infile or outfile are provided as absolute paths, they are used exactly as-is without modification. This allows users to manually override any automatic generation.
2. Automatic outfile Generation: If outfile is not specified, Nipype generates a filename based on:
   • The infile filename (excluding its extension).
   • A specific suffix defined by the Interface (e.g., fsl.Bet uses the _brain suffix).
   • The current working directory (os.getcwd()).
   • Example: If infile is foo.nii and the CWD is /home/user, the generated outfile for fsl.Bet will be /home/user/foo_brain.nii.gz.
3. Path Resolution for Command Line: If outfile is not an absolute path (e.g., just a filename like bar.nii), Nipype uses os.path.realpath to generate an absolute path for the cmdline at runtime. This ensures the underlying package writes the output to the intended location.

Note: The generated absolute path used in the cmdline does not overwrite the value stored in self.inputs.outfile.

Nipype uses Enthought Traits to define the schema for interface inputs and outputs, providing automatic type checking.

• InputSpec: A class inheriting from TraitedSpec containing the required input fields.
• OutputSpec: A class inheriting from TraitedSpec containing the fields for generated results.
• Metadata:
  • desc: A human-readable description.
  • mandatory: If True, Nipype throws an exception if the input is not set.
  • exists: (For File traits only) Checks if the provided file exists on disk.

An interface class connects these by assigning them to the input_spec and output_spec attributes.

class ExampleInputSpec(TraitedSpec):
    input_volume = File(desc = "Input volume", exists = True,
                        mandatory = True)
    parameter = traits.Int(desc = "some parameter")

class ExampleOutputSpec(TraitedSpec):
    output_volume = File(desc = "Output volume", exists = True)

class Example(Interface):
    input_spec = ExampleInputSpec
    output_spec = ExampleOutputSpec

To wrap a command-line tool, your interface class should inherit from a command-line base class (e.g., FSLCommand) and implement the following:

Required:

• _cmd: The actual command-line string or executable name.

Optional/Advanced:

• _gen_filename(name): Override this to generate filenames for parameters that are derived from other inputs (e.g., generating an output name based on an input filename).
• _redirect_x: Set to True to automatically start Xvfb and redirect X output to it. Use this for command-line tools that spawn a GUI.
• _format_arg(name, spec, value): Use this for custom formatting of input values before they are passed to the generic _parse_inputs() method.

class FLIRTInputSpec(FSLCommandInputSpec):
    in_file = File(exists=True, argstr='-in %s', mandatory=True, position=0, desc='input file')
    reference = File(exists=True, argstr='-ref %s', mandatory=True, position=1, desc='reference file')
    out_file = File(argstr='-out %s', desc='registered output file', name_source=['in_file'], name_template='%s_flirt', position=2, hash_files=False)

class FLIRTOutputSpec(TraitedSpec):
    out_file = File(exists=True, desc='path/name of registered file (if generated)')

class Flirt(FSLCommand):
    _cmd = 'flirt'
    input_spec = FlirtInputSpec
    output_spec = FLIRTOutputSpec

Nipype is designed around several key principles that affect how users build and share pipelines:

• Provenance: It should be easy to determine exactly what steps were performed by a pipeline.
• Relocatability: Code and data should support relocation, potentially via URIs or relative paths.
• Thread Safety: Code should be thread-safe by default unless otherwise specified.
• Minimal Recomputation: The pipeline aims to allow changes to an analysis with minimal recomputation. Note that currently, changing a node's inputs may cause the entire node to be recomputed. Similarly, grouping multiple files into a single node (e.g., node([file1 ... file100])) means adding a single file will trigger a recomputation of the entire node.
• Ease of Cleanup: It should be easy to identify and delete unnecessary components.
• Portability: Pipelines and sub-sections of pipelines should be easy to share.
• Naming Consistency: Use consistent terminology across the pipeline. For interfaces, use infiles and outfile(s). If a file is both an input and an output, or is passed between interfaces, it should use the same name in both places.