---
# System prepended metadata

title: How to run MRIQC on a BIDS dataset with nipoppy

---

# How to run MRIQC on a BIDS dataset with nipoppy

## Requirements

- Python>=3.9
- Apptainer
- Get the BIDS dataset (https://www.fil.ion.ucl.ac.uk/spm/download/data/MoAEpilot/MoAEpilot.bids.zip) and unzip it.

## Starting point

```
├── MoAEpilot.bids
│   └── MoAEpilot
│       ├── CHANGES
│       ├── dataset_description.json
│       ├── README
│       ├── sub-01
│       │   ├── anat
│       │   │   └── sub-01_T1w.nii
│       │   └── func
│       │       ├── sub-01_task-auditory_bold.nii
│       │       └── sub-01_task-auditory_events.tsv
│       └── task-auditory_bold.json
├── MoAEpilot.bids.zip
├── README.md
└── requirements.txt
```

## Install Nipoppy

```bash
$ cat requirements.txt
nipoppy==0.3.1
```

```bash
pip install -r requirements.txt
```

## Init nipoppy layout

```bash
nipoppy init --bids-source ./MoAEpilot.bids/MoAEpilot --verbosity 3 nipoppy
```

Notice:
- the default layout generated by nipoppy
- the BIDS dataset has been copied
- the manifest has been updated to match the content of the BIDS dataset

```
├── MoAEpilot.bids
│   └── MoAEpilot
│       ├── CHANGES
│       ├── dataset_description.json
│       ├── README
│       ├── sub-01
│       │   ├── anat
│       │   │   └── sub-01_T1w.nii
│       │   └── func
│       │       ├── sub-01_task-auditory_bold.nii
│       │       └── sub-01_task-auditory_events.tsv
│       └── task-auditory_bold.json
├── MoAEpilot.bids.zip
├── nipoppy
│   ├── bids
│   │   ├── CHANGES
│   │   ├── dataset_description.json
│   │   ├── README
│   │   ├── README.md
│   │   ├── sub-01
│   │   │   ├── anat
│   │   │   │   └── sub-01_T1w.nii
│   │   │   └── func
│   │   │       ├── sub-01_task-auditory_bold.nii
│   │   │       └── sub-01_task-auditory_events.tsv
│   │   └── task-auditory_bold.json
│   ├── code
│   ├── containers
│   ├── derivatives
│   ├── global_config.json
│   ├── logs
│   │   └── README.md
│   ├── manifest.tsv -> .manifests/manifest-20241118_1910.tsv
│   ├── pipelines
│   │   ├── bidscoin-4.3.2
│   │   ├── dcm2bids-3.1.0
│   │   ├── fmriprep-20.2.7
│   │   ├── fmriprep-23.1.3
│   │   ├── fmriprep-24.1.1
│   │   ├── freesurfer-6.0.1
│   │   ├── freesurfer-7.3.2
│   │   ├── heudiconv-0.12.2
│   │   ├── mriqc-23.1.0
│   │   │   ├── descriptor.json
│   │   │   ├── invocation.json
│   │   │   └── tracker_config.json
│   │   └── README.md
│   ├── scratch
│   ├── sourcedata
│   └── tabular
├── README.md
└── requirements.txt
```

```bash
$ cat nipoppy/manifest.tsv 
participant_id  visit_id        session_id      datatype
01      unnamed unnamed ['anat', 'func']
```

## Build the apptainer image of the MRIQC cntainer

```bash
apptainer build nipoppy/containers/mriqc_23.1.0.sif docker://nipreps/mriqc:23.1.0
```

## Update the configurations

Edit `nipoppy/global_config.json` to point to containers
and make sure that TamplateFlow atlases are stored in a "meaningful" place:

```json
    "SUBSTITUTIONS": {
        "[[NIPOPPY_DPATH_CONTAINERS]]": "[[NIPOPPY_DPATH_CONTAINERS]]",
        "[[HEUDICONV_HEURISTIC_FILE]]": "<PATH_TO_HEURISTIC_FILE>",
        "[[DCM2BIDS_CONFIG_FILE]]": "<PATH_TO_CONFIG_FILE>",
        "[[FREESURFER_LICENSE_FILE]]": "<PATH_TO_FREESURFER_LICENSE_FILE>",
        "[[TEMPLATEFLOW_HOME]]": "tmp"
    }
````

Edit `nipoppy/pipelines/mriqc-23.1.0/invocation.json` to update command passed to MRIQC:
- remove session argument
- run on T1 and bold


```json
{
    "bids_dir": "[[NIPOPPY_DPATH_BIDS]]",
    "output_dir": "[[NIPOPPY_DPATH_PIPELINE_OUTPUT]]",
    "analysis_level": "participant",
    "participant_label": [
        "[[NIPOPPY_PARTICIPANT_ID]]"
    ],
    "modalities": [
        "T1w",
        "bold"
    ],
    "bids_database_dir": "[[NIPOPPY_DPATH_PIPELINE_BIDS_DB]]",
    "nprocs": "4",
    "work_dir": "[[NIPOPPY_DPATH_PIPELINE_WORK]]",
    "no_sub": true
}
```

## Run

```bash
nipoppy run --pipeline mriqc --pipeline-version 23.1.0 nipoppy 
```

```
├── MoAEpilot.bids
├── MoAEpilot.bids.zip
├── nipoppy
│   ├── bids
│   ├── code
│   │   └── README.md
│   ├── containers
│   │   ├── mriqc_23.1.0.sif
│   │   └── README.md
│   ├── derivatives
│   │   ├── mriqc
│   │   │   └── 23.1.0
│   │   │       └── output
│   │   │           ├── dataset_description.json
│   │   │           ├── logs
│   │   │           ├── sub-01
│   │   │           │   ├── anat
│   │   │           │   │   └── sub-01_T1w.json
│   │   │           │   ├── figures
│   │   │           │   │   ├── sub-01_desc-background_T1w.svg
│   │   │           │   │   ├── sub-01_desc-zoomed_T1w.svg
│   │   │           │   │   ├── sub-01_task-auditory_desc-carpet_bold.svg
│   │   │           │   │   ├── sub-01_task-auditory_desc-mean_bold.svg
│   │   │           │   │   └── sub-01_task-auditory_desc-stdev_bold.svg
│   │   │           │   └── func
│   │   │           │       └── sub-01_task-auditory_bold.json
│   │   │           ├── sub-01_T1w.html
│   │   │           └── sub-01_task-auditory_bold.html
│   │   └── README.md
│   ├── global_config.json
│   ├── logs
│   │   ├── README.md
│   │   └── run
│   │       └── mriqc-23.1.0
│   │           └── mriqc-23.1.0-20241119_0956.log
│   ├── manifest.tsv -> .manifests/manifest-20241119_0947.tsv
│   ├── pipelines
│   ├── scratch
│   ├── sourcedata
│   └── tabular
├── README.md
├── requirements.txt
└── tmp
```

## Progress report

```bash
nipoppy track --pipeline mriqc --pipeline-version 23.1.0 nipoppy
```

```
├── MoAEpilot.bids
├── MoAEpilot.bids.zip
├── nipoppy
│   ├── bids
│   ├── code
│   ├── containers
│   ├── derivatives
│   │   ├── imaging_bagel.tsv -> .imaging_bagels/imaging_bagel-20241119_1007.tsv
│   │   ├── mriqc
│   │   └── README.md
│   ├── global_config.json
│   ├── logs
│   │   ├── README.md
│   │   ├── run
│   │   │   └── mriqc-23.1.0
│   │   │       └── mriqc-23.1.0-20241119_0956.log
│   │   └── track
│   │       └── mriqc-23.1.0
│   │           └── mriqc-23.1.0-20241119_1007.log
│   ├── manifest.tsv -> .manifests/manifest-20241119_0947.tsv
│   ├── pipelines
│   ├── scratch
│   ├── sourcedata
│   └── tabular
├── README.md
├── requirements.txt
└── tmp
```

Upload here: https://github.com/neurobagel/digest

## Summary


- install nipoppy
- nipoppy init --bids-source ./MoAEpilot.bids/MoAEpilot --verbosity 3 nipoppy
- get container if you don't have it
- edit config
- nipoppy run --pipeline mriqc --pipeline-version 23.1.0 nipoppy
- nipoppy track --pipeline mriqc --pipeline-version 23.1.0 nipoppy


## Bugs

- digest expects CSV

## Friction log

- what versions of what pipelines are suppported? maybe from the `nipoppy run --help` command 
- debugging session argument in invocation was a bit tricky: it is passed by the default MRIQC invocation, but the dataset has no session. I had to open the MRIQC log to find out (oh the horror! :wink:)
- track command should finish by giving URL to the digest website