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.