HeuDiConv

Abstract

pl-heudiconv is a ChRIS ds plugin that organizes brain imaging data into structured directory layouts.

Description

The original heudiconv CLI tool is a flexible DICOM converter for organizing brain imaging data into structured directory layouts. This pl-heudiconv plugin is a wrapper that makes the heudiconf CLI tool available as a ChRIS plugin.

When running the pl-heudiconv plugin, you must specify two directories:

• The input directory, where the brain imaging data is stored in DICOM files.

• The output directory, where the structured directory layouts are generated.

Both of these directories must already exist before you run the plugin.

The documentation for the original heudiconv CLI tool is available from the following website: https://heudiconv.readthedocs.io/en/latest/index.html

Note	In the original heudiconv CLI tool, the input and output directories are named arguments, but ChRIS plugins expect them to be positional arguments. As a result of this translation, some other arguments might be missing, or structured or named differently.

Note	You can use the docker command as an alternative to the podman command in these instructions.

Installation

pl-heudiconv is a ChRIS plugin, meaning that it can run either from within ChRIS or from the command-line.

Local Usage

podman run --rm
    -v <path_to_input_dir_containing_DICOM_files>:/incoming:z
    -v <path_to_output_dir>:/outgoing:z
    quay.io/rh-impact/pl-heudiconv pl-heudiconv
        [-h|--help]
        [--json] [--man] [--meta]
        [--savejson <DIR>]
        [-v|--verbosity <level>]
        [--version]
        /incoming /outgoing

Arguments

[-h] [--help]
If specified, show help message and exit.

[--json]
If specified, show json representation of app and exit.

[--man]
If specified, print the man page and exit.

[--meta]
If specified, print plugin meta data and exit.

[--savejson <DIR>]
If specified, save json representation file to DIR and exit.

[-v <level>] [--verbosity <level>]
Verbosity level for app. Not used currently.

[--version]
If specified, print version number and exit.

To show inline help, run the following command:

podman run --rm quay.io/rh-impact/pl-heudiconv pl-heudiconv --man

Run

You must specify input and output directories using the -v flag in the podman run command, as follows:

podman run --rm                              \
    -v <path_to_input_dir_containing_DICOM_files>:/incoming    \
    -v <path_to_output_dir>:/outgoing      \
    quay.io/rh-impact/pl-heudiconv pl-heudiconv                        \
        /incoming /outgoing

Development

Build the Docker container:

podman build -t local/pl-heudiconv .

Run unit tests:

podman run --rm local/pl-heudiconv nosetests

Examples

Example 1

podman run --rm -v ./my_input:/incoming:z -v ./my_output:/outgoing:z \
    quay.io/rh-impact/pl-heudiconv pl-heudiconv /incoming /outgoing

$ tree my_output/
my_output/
└── Halchenko
    └── Yarik
        └── 950_bids_test4
            └── phantom1sid1
                └── sub-phantom1sid1
                    └── fmap
                        ├── sub-phantom1sid1_acq-3mm_phasediff_dicom
                        │   └── 1.3.12.2.1107.5.2.43.66112.2016101409263663466202201.dcm
                        └── sub-phantom1sid1_acq-3mm_phasediff.nii.gz

7 directories, 2 files

Example 2

podman run --rm -v /home/my_name/my_project/my_input:/in:z \
    -v /home/my_name/my_project/my_output/heudiconv_output:/out:z \
    quay.io/rh-impact/pl-heudiconv pl-heudiconv /in /out

$ tree heudiconv_output
heudiconv_output
└── Knee
    └── (R)
        ├── CHANGES
        ├── dataset_description.json
        ├── participants.json
        ├── participants.tsv
        ├── README
        └── scans.json

2 directories, 6 files

Troubleshooting

As stated in the original heudiconv documentation, "The heuristic file controls how information about the DICOMs is used to convert to a file system layout …​ However, there is a large variety of data out there, and not all DICOMs will be covered by the existing heuristics." For more information about heudiconv heuristics, see Heuristic.

If you do not get the expected output when using this plugin, but you do get the expected output when using the original heudiconv tool independently, please log an issue here.

If you see the following error, rerun the command with docker instead of podman:

Error: writing blob: adding layer with blob "sha256:<value>": processing tar file(potentially insufficient UIDs or GIDs available in user namespace (requested 0:42 for /etc/gshadow): Check /etc/subuid and /etc/subgid if configured locally and run podman-system-migrate: lchown /etc/gshadow: invalid argument): exit status 1

image::https://raw.githubusercontent.com/FNNDSC/cookiecutter-chrisapp/master/doc/assets/badge/light.png[link=https://chrisstore.co]

If the scan name contains non-alphanumberic characters, the output directory structure might not be as expected. The following example shows the output when the scan name is MR-Brain w/o contrast:

$ tree my_output/
my_output/
└── MR
    └── Brain
        └── w
            └── o Contrast
                ├── CHANGES
                ├── dataset_description.json
                ├── participants.json
                ├── participants.tsv
                ├── README
                └── scans.json

4 directories, 6 files