MIAL Super-Resolution Toolkit

Latest released version: v2.1.0

This neuroimaging processing pipeline software is developed by the Medical Image Analysis Laboratory (MIAL) at the University Hospital of Lausanne (CHUV) for use within the lab, as well as for open-source software distribution.

GitHub release (latest by date including pre-releases)

Warning

THIS SOFTWARE IS FOR RESEARCH PURPOSES ONLY AND SHALL NOT BE USED FOR ANY CLINICAL USE. THIS SOFTWARE HAS NOT BEEN REVIEWED OR APPROVED BY THE FOOD AND DRUG ADMINISTRATION OR EQUIVALENT AUTHORITY, AND IS FOR NON-CLINICAL, IRB-APPROVED RESEARCH USE ONLY. IN NO EVENT SHALL DATA OR IMAGES GENERATED THROUGH THE USE OF THE SOFTWARE BE USED IN THE PROVISION OF PATIENT CARE.

Introduction

The Medical Image Analysis Laboratory Super-Resolution ToolKit (MIALSRTK) consists of a set of C++ and Python3 image processing and worflow tools necessary to perform motion-robust super-resolution fetal MRI reconstruction.

The original C++ MIALSRTK library includes all algorithms and methods for brain extraction, intensity standardization, motion estimation and super-resolution. It uses the CMake build system and depends on the open-source image processing Insight ToolKit (ITK) library, the command line parser TCLAP library and OpenMP for multi-threading.

MIALSRTK has been extended with the pymialsrtk Python3 library following recent advances in standardization of neuroimaging data organization and processing workflows (See BIDS and BIDS App standards). This library has a modular architecture built on top of the Nipype dataflow library which consists of (1) processing nodes that interface with each of the MIALSRTK C++ tools and (2) a processing pipeline that links the interfaces in a common workflow.

The processing pipeline with all dependencies including the C++ MIALSRTK tools are encapsulated in a Docker image container, which is now distributed as a BIDS App which handles datasets organized following the BIDS standard. See BIDS App usage for more details.

All these design considerations allow us not only to (1) represent the entire processing pipeline as an execution graph, where each MIALSRTK C++ tools are connected, but also to (2) provide a mecanism to record data provenance and execution details, and to (3) easily customize the BIDS App to suit specific needs as interfaces with new tools can be added with relatively little effort to account for additional algorithms.

New

You can now be aware about the adverse impact of your processing on the environment 🌍!

With the new --track_carbon_footprint option of the mialsuperresolutiontoolkit_docker and mialsuperresolutiontoolkit_singularity BIDS App python wrappers, you can use codecarbon to estimate the amount of carbon dioxide (CO2) produced to execute the code by the computing resources and save the results in <bids_dir>/code/emissions.csv.

Then, to visualize, interpret and track the evolution of the CO2 emissions incurred, you can use the visualization tool of codecarbon aka carbonboard that takes as input the csv created:

carbonboard --filepath="<bids_dir>/code/emissions.csv" --port=xxxx

Aknowledgment

If your are using MIALSRTK in your work, please acknowledge this software and its dependencies. See Citing for more details.

License information

This software is distributed under the open-source license Modified BSD. See license for more details.

All trademarks referenced herein are property of their respective holders.

Help/Questions

If you run into any problems or have any code bugs or questions, please create a new GitHub Issue.

Eager to contribute?

See Contributing for more details.

Funding

Originally supported by the Swiss National Science Foundation (grant SNSF-141283).

Contents

Installation Instructions for Users

Warning

This software is for research purposes only and shall not be used for any clinical use. This software has not been reviewed or approved by the Food and Drug Administration or equivalent authority, and is for non-clinical, IRB-approved Research Use Only. In no event shall data or images generated through the use of the Software be used in the provision of patient care.

Installation of the MIALSRTK processing tools and pipelines has been facilitated through the distribution of a BIDSApp relying on the Docker and Singularity software container technologies, so in order to run MIALSRTK, Docker or Singularity must be installed (see instructions in Prerequisites).

Once Docker or Singularity is installed, the recommended way to run MIALSRTK is to use the corresponding mialsuperresolutiontoolkit wrapper. Installation instructions for the wrappers can be found in Wrappers Installation, which requires as prerequisites having Python3 (see Prerequisites) installed and an Internet connection.

If you need a finer control over the Docker/Singularity container execution, or you feel comfortable with the Docker/Singularity Engine, download instructions for the MIALSRTK BIDS App can be found in MIALSRTK Container Image Download.

Prerequisites

To run MIALSRTK you will need to have either Docker or Singularity containerization engine installed.

While Docker enables MIALSRTK to be run on all major operating systems where you have root privileges, Singularity allows you to run MIALSRTK on Linux systems where you might not have root privileges such as a High Performance Computing cluster.

Please check https://docs.docker.com/get-started/overview/ and https://sylabs.io/guides/3.7/user-guide/introduction.html If you want to learn more about Docker and Singularity.

Installation of Docker Engine

Install Docker Engine corresponding to your system:
- For Ubuntu 14.04/16.04/18.04, follow the instructions from https://docs.docker.com/install/linux/docker-ce/ubuntu/
- For Mac OSX (>=10.10.3), get the .dmg installer from https://store.docker.com/editions/community/docker-ce-desktop-mac
- For Windows (>=10), get the installer from https://store.docker.com/editions/community/docker-ce-desktop-windows

Note

The MIALSRTK BIDSApp has been tested only on Ubuntu and MacOSX. For Windows users, it might be required to make few patches in the Dockerfile.

Set Docker to be managed as a non-root user
- Open a terminal
- Create the docker group:
```
$ sudo groupadd docker
```
- Add the current user to the docker group:
```
$ sudo usermod -G docker -a $USER
```
- Reboot
  
  After reboot, test if docker is managed as non-root:
```
$ docker run hello-world
```

Installation of Singularity Engine

Install singularity following instructions from the official documentation webpage at https://sylabs.io/guides/3.7/user-guide/quick_start.html#quick-installation-steps

Note

If you need to make the request to install Singularity on your HPC, Singularity provides a nice template at https://singularity.lbl.gov/install-request#installation-request to facilitate it.

MIALSRTK Container Image Download

Running Docker?

Open a terminal

Get the latest release (v2.1.0) of the BIDS App:

$ docker pull sebastientourbier/mialsuperresolutiontoolkit:v2.1.0

To display all docker images available:
```
$ docker images
```

You should see the docker image “mialsuperresolutiontoolkit” with tag “v2.1.0” is now available.

You are ready to use the Docker image of MIALSRTK from the terminal. See its commandline usage.

Running Singularity?

Open a terminal

Get the latest release (v2.1.0) of the BIDS App:

$ singularity pull library://tourbier/default/mialsuperresolutiontoolkit:v2.1.0

You are ready to use the Singularity image of MIALSRTK. See its commandline usage.

The lightweight MIALSRTK wrappers

Prerequisites

The wrappers requires a Python3 environment. We recommend you tu use miniconda3 for which the installer corresponding to your 32/64bits MacOSX/Linux/Win system can be downloaded from https://conda.io/miniconda.html.

Wrappers Installation

Once Python3 is installed, the mialsuperresolutiontoolkit_docker and mialsuperresolutiontoolkit_singularity wrappers can be installed via pip as follows:

Open a terminal
Installation with pip:
```
$ pip install pymialsrtk==2.1.0
```
You are ready to use the mialsuperresolutiontoolkit_docker and mialsuperresolutiontoolkit_singularity wrappers. See their commandline usages.

Important

On Mac and Windows, if you want to track the carbon emission incurred by the processing with the --track_carbon_footprint option flag, you will need to install the Intel Power Gadget tool available here.

Help/Questions

Code bugs can be reported by creating a new GitHub Issue.

BIDS and BIDS App standards

MIALSRTK BIDS App adopts the BIDS standard for data organization and is developed following the BIDS App standard. This means that MIALSRTK BIDS App handles dataset formatted following the BIDS App standard and provides a processing workflow containerized in Docker container image (promoting portability and reproduciblity) that can be run with a set of arguments defined by the BIDS App standard directly from the terminal or a script (See Commandline Usage section for more details).

For more information about BIDS and BIDS-Apps, please consult the BIDS Website, the Online BIDS Specifications, and the BIDSApps Website. HeuDiConv can assist you in converting DICOM brain imaging data to BIDS. A nice tutorial can be found @ BIDS Tutorial Series: HeuDiConv Walkthrough .

BIDS dataset schema

The BIDS App accepts BIDS datasets that adopt the following organization, naming, and file formats:

ds-example/

    README
    CHANGES
    participants.tsv
    dataset_description.json

    sub-01/
        anat/
            sub-01_run-1_T2w.nii.gz
            sub-01_run-1_T2w.json
            sub-01_run-2_T2w.nii.gz
            sub-01_run-2_T2w.json
            ...

    ...

    sub-<subject_label>/
        anat/
            sub-<subject_label>_run-1_T2w.nii.gz
            sub-<subject_label>_run-1_T2w.json
            sub-<subject_label>_run-2_T2w.nii.gz
            sub-<subject_label>_run-2_T2w.json
            ...
        ...
    ...

    code/
        participants_params.json

where participants_params.json is the MIALSRTK BIDS App configuration file, which follows a specific schema (See config schema), and which defines multiple processing parameters (such as the ordered list of scans or the weight of regularization).

Important

Before using any BIDS App, we highly recommend you to validate your BIDS structured dataset with the free, online BIDS Validator.

Commandline Usage

MIALSRTK adopts the BIDS standard for data organization and takes as principal input the path of the dataset that is to be processed. The input dataset is required to be in valid BIDS format, and it must include at least one T2w scan with anisotropic resolution per anatomical direction. See BIDS and BIDS App standards page that provides links for more information about BIDS and BIDS-Apps as well as an example for dataset organization and naming.

Commandline Arguments

The command to run the MIALSRTK follows the BIDS-Apps definition standard with an additional option for loading the pipeline configuration file.

Argument parser of the MIALSRTK BIDS App

usage: mialsuperresolutiontoolkit-bidsapp [-h] [--run_type {sr,preprocessing}]
                                          [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
                                          [--param_file PARAM_FILE]
                                          [--openmp_nb_of_cores OPENMP_NB_OF_CORES]
                                          [--nipype_nb_of_cores NIPYPE_NB_OF_CORES]
                                          [--memory MEMORY]
                                          [--masks_derivatives_dir MASKS_DERIVATIVES_DIR]
                                          [--labels_derivatives_dir LABELS_DERIVATIVES_DIR]
                                          [--all_outputs] [-v] [--verbose]
                                          bids_dir output_dir {participant}

Positional Arguments

bids_dir

The directory with the input dataset formatted according to the BIDS standard.

output_dir

The directory where the output files should be stored. If you are running group level analysis this folder should be prepopulated with the results of the participant level analysis.

analysis_level

Possible choices: participant

Level of the analysis that will be performed. Only participant is available

Named Arguments

--run_type

Possible choices: sr, preprocessing

Type of pipeline that is run. Can choose between running the super-resolution pipeline (sr) or only preprocessing (preprocessing).

Default: “sr”

--participant_label

The label(s) of the participant(s) that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“). If this parameter is not provided all subjects should be analyzed. Multiple participants can be specified with a space separated list.

--param_file

Path to a JSON file containing subjects’ exams information and super-resolution total variation parameters.

Default: “/bids_dir/code/participants_params.json”

--openmp_nb_of_cores

Specify number of cores used by OpenMP threads Especially useful for NLM denoising and slice-to-volume registration. (Default: 0, meaning it will be determined automatically)

Default: 0

--nipype_nb_of_cores

Specify number of cores used by the Niype workflow library to distribute the execution of independent processing workflow nodes (i.e. interfaces) (Especially useful in the case of slice-by-slice bias field correction and intensity standardization steps for example). (Default: 0, meaning it will be determined automatically)

Default: 0

--memory

Limit the workflow to using the amount of specified memory [in gb] (Default: 0, the workflow memory consumption is not limited)

Default: 0

--masks_derivatives_dir

Use manual brain masks found in <output_dir>/<masks_derivatives_dir>/ directory

--labels_derivatives_dir

Use low-resolution labelmaps found in <output_dir>/<labels_derivatives_dir>/ directory.

--all_outputs

Whether or not all outputs should be kept(e.g. preprocessed LR images)

Default: False

-v, --version

show program’s version number and exit

--verbose

Verbose mode

Default: False

BIDS App configuration file

The BIDS App configuration file specified by the input flag –param_file adopts the following JSON schema:

{
  "01": [
    { "sr-id": 1,
      ("session": 01,)
      "stacks": [1, 3, 5, 2, 4, 6],
      "paramTV": {
        "lambdaTV": 0.75,
        "deltatTV": 0.01 }
    },
    { "sr-id": 2,
      ("session": 01,)
      "stacks": [2, 3, 5, 4],
      "ga": 25,
      "paramTV": {
        "lambdaTV": 0.75,
        "deltatTV": 0.01 },
      "custom_interfaces":
        {
        "skip_svr": true,
        "do_refine_hr_mask": false,
        "skip_stacks_ordering": false,
        "do_anat_orientation": true
        }
    }]
  "02": [
    { "sr-id": 1,
      ("session": 01,)
      "stacks": [3, 1, 2, 4],
      "paramTV": {
        "lambdaTV": 0.7,
        "deltatTV": 0.01 }
    }]
  ...
}

where:

"sr-id" (mandatory) allows to distinguish between runs with different configurations of the same acquisition set.
"stacks" (optional) defines the list of scans to be used in the reconstruction. The specified order is considered if "skip_stacks_ordering" is False
"paramTV" (optional): "lambdaTV" (regularization), "deltaTV" (optimization time step),

"num_iterations", "num_primal_dual_loops", "num_bregman_loops", "step_scale", "gamma" are parameters of the TV super-resolution algorithm.

"session" (optional) It MUST be specified if you have a BIDS dataset composed of multiple sessions with the sub-XX/ses-YY structure.

"ga" (optional but mandatory when do_anat_orientation is true) subject’s gestational age in weeks.

"run_type" (optional): defines the type of run that should be done. It can be set between sr (super-resolution) and preprocessing (preprocessing-only). (default is "sr")

"custom_interfaces" (optional): indicates whether optional interfaces of the pipeline should be performed.

"skip_svr" (optional) the Slice-to-Volume Registration should be skipped in the image reconstruction. (default is False)

"do_refine_hr_mask" (optional) indicates whether a refinement of the HR mask should be performed. (default is False)

"skip_preprocessing" (optional) indicates whether the preprocessing stage should be skipped. A minimal preprocessing is still computed: the field-of-view is reduced based on the brain masks and the LR series are masked on the ROI. (default is False)

Note

This option requires input images to be normalised in the range [0,255] prior to running the code with this option. The projection step of the TV algorithm will otherwise clip values to 255.

"do_nlm_denoising" (optional) indicates whether the NLM denoising preprocessing should be performed prior to motion estimation. (default is False)

"do_reconstruct_labels" (optional) indicates whether the reconstruction of LR label maps should be performed together with T2w images. (default is False)

"skip_stacks_ordering" (optional) indicates whether the order of stacks specified in "stacks" should be kept or re-computed. (default is False)

"do_anat_orientation" (optional) indicates whether the alignement into anatomical planes should be performed. If True, path to a directory containing STA atlas (Gholipour et al., 2017 1, 2) must be mounted to /sta. (default is False)

"preproc_do_registration" (optional) indicates whether the Slice-to-Volume Registration should be computed in the "preprocessing" run (default is False).

"do_multi_parameters" (optional) enables running the super-resolution reconstruction with lists of parameters. The algorithm will

then run a grid search over all combinations of parameters. (default is False)

"do_srr_assessment" (optional) enables comparing the quality of the super-resolution reconstruction with a reference image. (default is False)

If True, it will require a reference isotropic T2w image, mask and labels located in the data folder.

References

1: Gholipour et al.; A normative spatiotemporal MRI atlas of the fetal brain for automatic segmentation and analysis of early brain growth, Scientific Reports 7, Article number: 476 (2017). `(link to article)<http://www.nature.com/articles/s41598-017-00525-w>`_ .
2: (link to download)

Important

Before using any BIDS App, we highly recommend you to validate your BIDS structured dataset with the free, online BIDS Validator.

Running MIALSRTK

You can run the MIALSRTK using the lightweight Docker or Singularity wrappers we created for convenience or you can interact directly with the Docker / Singularity Engine via the docker or singularity run command. (See Installation Instructions for Users)

New

You can now be aware about the adverse impact of your processing on the environment 🌍!

With the new –track_carbon_footprint option of the mialsuperresolutiontoolkit_docker and mialsuperresolutiontoolkit_singularity BIDS App python wrappers, you can use codecarbon to estimate the amount of carbon dioxide (CO2) produced to execute the code by the computing resources and save the results in <bids_dir>/code/emissions.csv.

Then, to visualize, interpret and track the evolution of the CO2 emissions incurred, you can use the visualization tool of codecarbon aka carbonboard that takes as input the .csv created:

carbonboard --filepath="<bids_dir>/code/emissions.csv" --port=xxxx

With the wrappers

When you run mialsuperresolutiontoolkit_docker, it will generate a Docker command line for you, print it out for reporting purposes, and then execute it without further action needed, e.g.:

$ mialsuperresolutiontoolkit_docker \
     /home/localadmin/data/ds001 /media/localadmin/data/ds001/derivatives \
     participant --participant_label 01 \
     --param_file /home/localadmin/data/ds001/code/participants_params.json \
     --track_carbon_footprint \
     (--openmp_nb_of_cores 4) \
     (--nipype_nb_of_cores 4)

When you run mialsuperresolutiontoolkit_singularity, it will generate a Singularity command line for you, print it out for reporting purposes, and then execute it without further action needed, e.g.:

$ mialsuperresolutiontoolkit_singularity \
     /home/localadmin/data/ds001 /media/localadmin/data/ds001/derivatives \
     participant --participant_label 01 \
     --param_file /home/localadmin/data/ds001/code/participants_params.json \
     --track_carbon_footprint \
     (--openmp_nb_of_cores 4) \
     (--nipype_nb_of_cores 4)

With the Docker / Singularity Engine

If you need a finer control over the container execution, or you feel comfortable with the Docker or Singularity Engine, avoiding the extra software layer of the wrapper might be a good decision.

For instance, the previous call to the mialsuperresolutiontoolkit_docker wrapper corresponds to:

$ docker run -t --rm -u $(id -u):$(id -g) \
        -v /home/localadmin/data/ds001:/bids_dir \
        -v /media/localadmin/data/ds001/derivatives:/output_dir \
        (-v /path/to/CRL_Fetal_Brain_Atlas:/sta \)
        sebastientourbier/mialsuperresolutiontoolkit:v2.1.0 \
        /bids_dir /output_dir participant --participant_label 01 \
        --param_file /bids_dir/code/participants_params.json \
        (--openmp_nb_of_cores 4) \
        (--nipype_nb_of_cores 4)

Note

We use the -v /path/to/local/folder:/path/inside/container docker run option to access local files and folders inside the container such that the local directory of the input BIDS dataset (here: /home/localadmin/data/ds001) and the output directory (here: /media/localadmin/data/ds001/derivatives) used to process are mapped to the folders /bids_dir and /output_dir in the container respectively.

The previous call to the mialsuperresolutiontoolkit_singularity wrapper corresponds to:

$ singularity run --containall \
        --bind /home/localadmin/data/ds001:/bids_dir \
        --bind /media/localadmin/data/ds001/derivatives:/output_dir \
        library://tourbier/default/mialsuperresolutiontoolkit:v2.1.0 \
        /bids_dir /output_dir participant --participant_label 01 \
        --param_file /bids_dir/code/participants_params.json \
        (--openmp_nb_of_cores 4) \
        (--nipype_nb_of_cores 4)

Note

Similarly as with Docker, we use the –bind /path/to/local/folder:/path/inside/container singularity run option to access local files and folders inside the container such that the local directory of the input BIDS dataset (here: /home/localadmin/data/ds001) and the output directory (here: /media/localadmin/data/ds001/derivatives) used to process are mapped to the folders /bids_dir and /output_dir in the container respectively.

Debugging

Logs are outputted into <output dir>/nipype/sub-<participant_label>/anatomical_pipeline/rec<srId>/pypeline.log.

Support, bugs and new feature requests

All bugs, concerns and enhancement requests for this software are managed on GitHub and can be submitted at https://github.com/Medical-Image-Analysis-Laboratory/mialsuperresolutiontoolkit/issues.

Not running on a local machine? - Data transfer

If you intend to run MIALSRTK on a remote system, you will need to make your data available within that system first. Comprehensive solutions such as Datalad will handle data transfers with the appropriate settings and commands. Datalad also performs version control over your data.

Outputs of MIALSRTK BIDS App

Processed, or derivative, data are outputed to <bids_dataset/derivatives>/ and follow the BIDS v1.4.1 standard (see BIDS Derivatives) whenever possible.

BIDS derivatives entities

Entity	Description
`sub-<label>`	Distinguish different subjects
`ses-<label>`	Distinguish different T2w scan acquisition sessions
`run-<label>`	Distinguish different T2w scans
`rec-<label>`	Distinguish images reconstructed using scattered data interpolation (SDI) or super-resolution (SR) methods
`id-<label>`	Distinguish outputs of reconstructions run multiple times with different configuration

See Original BIDS Entities Appendix for more description.

Note

A new entity id- has been introduced to distinguish between outputs when the pipeline is run with multiple configurations (such a new order of scans) on the same subject.

Main MIALSRTK BIDS App Derivatives

Main outputs produced by MIALSRTK BIDS App are written to <bids_dataset/derivatives>/pymialsrtk-<variant>/sub-<label>/(_ses-<label>/). The execution log of the full workflow is saved as sub-<label>(_ses-<label>)_id-<label>_log.txt`.

Anatomical derivatives

Anatomical derivatives are placed in each subject’s anat/ subfolder, including:
- The brain masks of the T2w scans:
  anat/sub-<label>(_ses-<label>)_run-01_id-<label>_desc-brain_mask.nii.gz
  
  anat/sub-<label>(_ses-<label>)_run-02_id-<label>_desc-brain_mask.nii.gz
  
  anat/sub-<label>(_ses-<label>)_run-03_id-<label>_desc-brain_mask.nii.gz
  
  …
- The preprocessed T2w scans used for slice motion estimation and scattered data interpolation (SDI) reconstruction:
  anat/sub-<label>(_ses-<label>)_run-01_id-<label>_desc-preprocSDI_T2w.nii.gz
  
  anat/sub-<label>(_ses-<label>)_run-02_id-<label>_desc-preprocSDI_T2w.nii.gz
  
  anat/sub-<label>(_ses-<label>)_run-03_id-<label>_desc-preprocSDI_T2w.nii.gz
  
  …
- The preprocessed T2w scans used for super-resolution reconstruction:
  anat/sub-<label>(_ses-<label>)_run-01_id-<label>_desc-preprocSR_T2w.nii.gz
  
  anat/sub-<label>(_ses-<label>)_run-02_id-<label>_desc-preprocSR_T2w.nii.gz
  
  anat/sub-<label>(_ses-<label>)_run-03_id-<label>_desc-preprocSR_T2w.nii.gz
  
  …
- The high-resolution image reconstructed by SDI:
  anat/sub-<label>(_ses-<label>)_rec-SDI_id-<label>_T2w.nii.gz
  
  anat/sub-<label>(_ses-<label>)_rec-SDI_id-<label>_T2w.json
- The high-resolution image reconstructed by SDI:
  anat/sub-<label>(_ses-<label>)_rec-SR_id-<label>_T2w.nii.gz
  
  anat/sub-<label>(_ses-<label>)_rec-SR_id-<label>_T2w.json
The slice-by-slice transforms of all T2W scans estimated during slice motion estimation and SDI reconstruction and used in the super-resolution forward model are placed in each subject’s xfm/ subfolder:
- xfm/sub-<label>(_ses-<label>)_run-1_id-<label>_T2w_from-origin_to-SDI_mode-image_xfm.txt
- xfm/sub-<label>(_ses-<label>)_run-2_id-<label>_T2w_from-origin_to-SDI_mode-image_xfm.txt
- xfm/sub-<label>(_ses-<label>)_run-3_id-<label>_T2w_from-origin_to-SDI_mode-image_xfm.txt
- …
The pipeline execution log file can be found in each subject’s logs/ subfolder as:
- logs/sub-01_rec-SR_id-1_log.txt
The HTML processing report which provides in one place: pipeline/workflow configuration summary, Nipype workflow execution graph, links to the log and the profiling output report, plots for the quality check of the automatic reordering step based on the motion index, three orthogonal cuts of the reconstructed image, and computing environment summary. It is placed in each subject’s report/ subfolder:
- report/sub-<label>.html
The PNG image generated by the stack auto-reordering node and used in the HTML processing report can be found in each subject’s figures/ subfolder as:
- figures/sub-01_rec-SR_id-1_desc-motion_stats.png
The Nipype workflow execution graph used in the HTML processing report, which summarizes all processing nodes involves in the given processing pipeline, can be found in each subject’s figures/ folder as sub-01_rec-SR_id-1_desc-processing_graph.png:

Nipype Workflow Derivatives

The execution of the Nipype workflow (pipeline) involves the creation of a number of intermediate outputs for each subject sub- and each run rec- which are written to <bids_dataset/derivatives>/nipype/sub-<label>/rec-<id_label>/srr_pipeline where <id_label> corresponds to the label used previously for the entity id-:

Execution details (data provenance) of each interface (node) of a given pipeline are reported in srr_pipeline/<interface_name>/_report/report.rst

Command-line interface (CLI) module

This module defines the mialsuperresolutiontoolkit_bidsapp_docker script that wraps calls to the Docker BIDS APP image.

pymialsrtk.cli.mialsuperresolutiontoolkit_docker.create_docker_cmd(args)[source]

Function that creates and returns the BIDS App docker run command.

Parameters

args (dict) –

Dictionary of parsed input argument in the form:

{
    'bids_dir': "/path/to/bids/dataset/directory",
    'output_dir': "/path/to/output/directory",
    'param_file': "/path/to/configuration/parameter/file",
    'analysis_level': "participant",
    'participant_label': ['01', '02', '03'],
    'openmp_nb_of_cores': 1,
    'nipype_nb_of_cores': 1,
    'masks_derivatives_dir': 'manual_masks'
}

Returns

cmd – String containing the command to be run via subprocess.run()

Return type

string

pymialsrtk.cli.mialsuperresolutiontoolkit_docker.main()[source]

Main function that creates and executes the BIDS App docker command.

Returns

exit_code –

An exit code given to sys.exit() that can be:

’0’ in case of successful completion

’1’ in case of an error

Return type

{0, 1}

This module defines the mialsuperresolutiontoolkit_bidsapp_singularity script that wraps calls to the Singularity BIDS APP image.

pymialsrtk.cli.mialsuperresolutiontoolkit_singularity.create_singularity_cmd(args)[source]

Function that creates and returns the BIDS App singularity run command.

Parameters

args (dict) –

Dictionary of parsed input argument in the form:

{
    'bids_dir': "/path/to/bids/dataset/directory",
    'output_dir': "/path/to/output/directory",
    'param_file': "/path/to/configuration/parameter/file",
    'analysis_level': "participant",
    'participant_label': ['01', '02', '03'],
    'openmp_nb_of_cores': 1,
    'nipype_nb_of_cores': 1,
    'masks_derivatives_dir': 'manual_masks'
}

Returns

cmd – String containing the command to be run via subprocess.run()

Return type

string

pymialsrtk.cli.mialsuperresolutiontoolkit_singularity.main()[source]

Main function that creates and executes the BIDS App singularity command.

Returns

exit_code –

An exit code given to sys.exit() that can be:

’0’ in case of successful completion

’1’ in case of an error

Return type

{0, 1}

Preprocess module

PyMIALSRTK preprocessing functions.

It includes BTK Non-local-mean denoising, slice intensity correction slice N4 bias field correction, slice-by-slice correct bias field, intensity standardization, histogram normalization and both manual or deep learning based automatic brain extraction.

MIAL Super-Resolution Toolkit

Introduction

Aknowledgment

License information

Help/Questions

Eager to contribute?

Funding

Contents

Installation Instructions for Users

Prerequisites

Installation of Docker Engine

Installation of Singularity Engine

MIALSRTK Container Image Download

Running Docker?

Running Singularity?

The lightweight MIALSRTK wrappers

Prerequisites

Wrappers Installation

Help/Questions

BIDS and BIDS App standards

BIDS dataset schema

Commandline Usage

Commandline Arguments

Positional Arguments

Named Arguments

BIDS App configuration file

References

Running MIALSRTK

With the wrappers

With the Docker / Singularity Engine

Debugging

Support, bugs and new feature requests

Not running on a local machine? - Data transfer

Outputs of MIALSRTK BIDS App

BIDS derivatives entities

Main MIALSRTK BIDS App Derivatives

Anatomical derivatives

Nipype Workflow Derivatives

Command-line interface (CLI) module

Preprocess module

ApplyAlignmentTransform

BrainExtraction

BtkNLMDenoising

CheckAndFilterInputStacks

ComputeAlignmentToReference

ListsMerger

MialsrtkCorrectSliceIntensity

MialsrtkHistogramNormalization

MialsrtkIntensityStandardization

MialsrtkMaskImage

MialsrtkSliceBySliceCorrectBiasField

MialsrtkSliceBySliceN4BiasFieldCorrection

ReduceFieldOfView

ResampleImage

SplitLabelMaps

StacksOrdering

Postprocess module

BinarizeImage

ConcatenateImageMetrics

FilenamesGeneration

ImageMetrics

MergeMajorityVote

MialsrtkN4BiasFieldCorrection

MialsrtkRefineHRMaskByIntersection

ReportGeneration

Reconstruction module

MialsrtkImageReconstruction

MialsrtkSDIComputation

MialsrtkTVSuperResolution

Utility (utils) module

Pipelines module

Workflows module

BSD 3-Clause License

Citing

Changes

Version 2.0.3

New feature

More…

Version 2.0.2

New feature

How to install `pyMIALSTK` locally