introducing_nipype.Rmd

---
jupyter:
  jupytext:
    notebook_metadata_filter: all,-language_info
    split_at_heading: true
    text_representation:
      extension: .Rmd
      format_name: rmarkdown
      format_version: '1.2'
      jupytext_version: 1.10.3
  kernelspec:
    display_name: Python 3
    language: python
    name: python3
  orphan: true
---

# Introducing nipype

[Nipype](http://nipy.org/nipype) is a Python module that provides Python
interfaces to many imaging tools, including SPM, AFNI and FSL.

We install it with `pip` in the usual way:

```
pip3 install --user nipype
```

After this has run, check that you can import nipype with:

```{python}
import nipype
```

We are interested in the nipype `interfaces` sub-package.  Specifically,
we want the interfaces to the SPM routines:

```{python}
from nipype.interfaces import spm
from nipype.interfaces import matlab as nim
```

Our first job is to make sure that nipype can run MATLAB. Let’s check
with a test call:

If `nipype` does not have the right command to start MATLAB, this will
fail with an error. We can set the command to start MATLAB like this:

```{python}
nim.MatlabCommand.set_default_matlab_cmd('/Applications/MATLAB_R2022b.app/bin/matlab')
```

where `/Applications/MATLAB_R2022b.app/bin/matlab` is the path to the
MATLAB application file.

Check this is working by running the code above.

Next we need to make sure that nipype has SPM on the MATLAB path when it
is running MATLAB. Try running this command to get the SPM version.

If this gives an error message, you may not have SPM set up on your
MATLAB path by default. You can use Nipype to add SPM to the MATLAB path
like this:

```{python}
nim.MatlabCommand.set_default_paths('/Users/mb312/dev_trees/spm12')
```

Another option is to use the MATLAB GUI to add this directory to the
MATLAB path, and save this path for future sessions.

Now try running the `spm ver` command again:

We are going to put the setup we need into a Python file we can import
from any script that we write that uses nipype.

In your current directory, make a new file called `nipype_settings.py`
with contents like this:

```python
""" Defaults for using nipype
"""
import nipype.interfaces.matlab as nim
# If you needed to set the default matlab command above
nim.MatlabCommand.set_default_matlab_cmd('/Applications/MATLAB_R2022b.app/bin/matlab')
# If you needed to set the SPM path above.
nim.MatlabCommand.set_default_paths('/Users/mb312/dev_trees/spm12')
```

Now try:

```python
import nipype_settings
import nipype.interfaces.matlab as nim
mlab = nim.MatlabCommand()
mlab.inputs.script = "spm ver"  # get SPM version
mlab.run()
```

These should run without error.

## Nipype example using Matlab and SPM

See the example files in:

* {download}`nipype_settings.py`
* {download}`nipype_ds114_sub009_t2r1.py`.


## Installing packages for use with Nipype

You can script various imaging packages with Nipype.  Consider installing one or more of these packages:

* [SPM](https://www.fil.ion.ucl.ac.uk/spm/software).  SPM also needs an installation of Matlab.
* [FSL](https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FslInstallation)
* [AFNI](https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/background_install/install_instructs/index.html)