Command Line Tools

The following section outlines the CLI of shimming-toolbox.

Fieldmapping

st_prepare_fieldmap

Creates fieldmap (in Hz) from phase images.

This function accommodates multiple echoes (2 or more) and phase difference. This function also accommodates 4D phase inputs, where the 4th dimension represents the time, in case multiple field maps are acquired across time for the purpose of real-time shimming experiments. For non Siemens phase data, see --autoscale-phase option.

PHASE: Input path of phase nifti file(s), in ascending order: echo1, echo2, etc.

st_prepare_fieldmap [OPTIONS] PHASE...

Options

--mag <fname_mag>

Required Input path of mag nifti file

--unwrapper <unwrapper>

Algorithm for unwrapping

Default

prelude

Options

prelude

-o, --output <fname_output>

Output filename for the fieldmap, supported types : '.nii', '.nii.gz'

Default

./fieldmap.nii.gz

--autoscale-phase <autoscale>

Tells whether to auto rescale phase inputs according to manufacturer standards. If you have non standard data, it would be preferable to set this option to False and input your phase data from -pi to pi to avoid unwanted rescaling

Default

True

--mask <fname_mask>

Input path for a mask. Mask must be the same shape as the array of each PHASE input.

--threshold <threshold>

Threshold for masking if no mask is provided. Allowed range: [0, 1] where all scaled values lower than the threshold are set to 0.

Default

0.05

--savemask <fname_save_mask>

Filename of the mask calculated by the unwrapper

--gaussian-filter <gaussian_filter>

Gaussian filter for B0 map

--sigma <sigma>

Standard deviation of gaussian filter. Used for: gaussian_filter

-v, --verbose <verbose>

Be more verbose

Options

info | debug

Arguments

PHASE

Required argument(s)

Shimming

st_b0shim

Shim according to the specified algorithm as an argument e.g. st_b0shim xxxxx

st_b0shim [OPTIONS] COMMAND [ARGS]...

dynamic-cli

Static shim by fitting a fieldmap. Use the option --optimizer-method to change the shimming algorithm used to optimize. Use the options --slices and --slice-factor to change the shimming order/size of the slices.

Example of use: st_b0shim dynamic --coil coil1.nii coil1_config.json --coil coil2.nii coil2_config.json --fmap fmap.nii --anat anat.nii --mask mask.nii --optimizer-method least_squares

st_b0shim dynamic-cli [OPTIONS]

Options

--coil <coils>

Pair of filenames containing the coil profiles followed by the filename to the constraints e.g. --coil a.nii cons.json. If you have more than one coil, use this option more than once. The coil profiles and the fieldmaps (--fmap) must have matching units (if fmap is in Hz, the coil profiles must be in Hz/unit_shim). If using the scanner's gradient/shim coils, the coil profiles must be in Hz/unit_shim and fieldmaps must be in Hz. If you want to shim using the scanner's gradient/shim coils, use the --scanner-coil-order option. For an example of a constraint file, see: /home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/latest/config/coil_config.json

--fmap <fname_fmap>

Required Static B0 fieldmap.

--anat <fname_anat>

Required Anatomical image to apply the correction onto.

--mask <fname_mask_anat>

Mask defining the spatial region to shim.

--scanner-coil-order <scanner_coil_order>

Maximum order of the shim system. Note that specifying 1 will return orders 0 and 1. The 0th order is the f0 frequency.

Default

-1

Options

-1 | 0 | 1 | 2

--scanner-coil-constraints <fname_sph_constr>

Constraints for the scanner coil.

Default

/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/latest/config/coil_config.json

--slices <slices>

Define the slice ordering. If set to 'auto', automatically parse the target image.

Default

auto

Options

interleaved | sequential | volume | auto

--slice-factor <slice_factor>

Number of slices per shimmed group. Used when '--slices' is not set to 'auto'. For example, if the '--slice-factor' value is '3', then with the 'sequential' mode, shimming will be performed independently on the following groups: {0,1,2}, {3,4,5}, etc. With the mode 'interleaved', it will be: {0,2,4}, {1,3,5}, etc.

Default

1

--optimizer-method <method>

Method used by the optimizer. LS will respect the constraints, PS will not respect the constraints

Default

least_squares

Options

least_squares | pseudo_inverse

--mask-dilation-kernel-size <dilation_kernel_size>

Number of voxels to consider outside of the masked area. For example, when doing dynamic shimming with a linear gradient, the coefficient corresponding to the gradient orthogonal to a single slice cannot be estimated: there must be at least 2 (ideally 3) points to properly estimate the linear term. When using 2nd order or more, more dilation is necessary.

Default

3

--fatsat <fatsat>

Describe what to do with a fat saturation pulse. 'auto': It will parse the NIfTI file for a fat-sat pulse and add shim coefficients of 0s before every shim group when using 'chronological-...' output-file-format-coil. 'no': It will not add 0s. 'yes': It will add 0s.

Default

auto

Options

auto | yes | no

-o, --output <path_output>

Directory to output coil text file(s).

Default

/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/latest/docs/source

--output-file-format-coil <o_format_coil>

Syntax used to describe the sequence of shim events for custom coils. Use 'slicewise' to output in row 1, 2, 3, etc. the shim coefficients for slice 1, 2, 3, etc. Use 'chronological' to output in row 1, 2, 3, etc. the shim value for trigger 1, 2, 3, etc. The trigger is an event sent by the scanner and captured by the controller of the shim amplifier. Use 'ch' to output one file per coil channel (coil1_ch1.txt, coil1_ch2.txt, etc.). Use 'coil' to output one file per coil system (coil1.txt, coil2.txt). In the latter case, all coil channels are encoded across multiple columns in the text file.

Default

slicewise-coil

Options

slicewise-ch | slicewise-coil | chronological-ch | chronological-coil

--output-file-format-scanner <o_format_sph>

Syntax used to describe the sequence of shim events for scanner coils. Use 'slicewise' to output in row 1, 2, 3, etc. the shim coefficients for slice 1, 2, 3, etc. Use 'chronological' to output in row 1, 2, 3, etc. the shim value for trigger 1, 2, 3, etc. The trigger is an event sent by the scanner and captured by the controller of the shim amplifier. If there is a fat saturation pulse in the anat sequence, shim weights of 0s are included in the output text file before each slice coefficients. Use 'ch' to output one file per coil channel (coil1_ch1.txt, coil1_ch2.txt, etc.). Use 'coil' to output one file per coil system (coil1.txt, coil2.txt). In the latter case, all coil channels are encoded across multiple columns in the text file. Use 'gradient' to output the 1st order in the Gradient CS, otherwise, it outputs in the Shim CS.

Default

slicewise-coil

Options

slicewise-ch | slicewise-coil | chronological-ch | chronological-coil | gradient

--output-value-format <output_value_format>

Coefficient values for the scanner coil. delta: Outputs the change of shim coefficients. absolute: Outputs the absolute coefficient by taking into account the current shim settings. This is effectively initial + shim. Scanner coil coefficients will be in the Shim coordinate system unless the option --output-file-format is set to gradient. The delta value format should be used in that case.

Default

delta

Options

delta | absolute

-v, --verbose <verbose>

Be more verbose

Options

info | debug

realtime-cli

Realtime shim by fitting a fieldmap to a pressure monitoring unit. Use the option --optimizer-method to change the shimming algorithm used to optimize. Use the options --slices and --slice-factor to change the shimming order/size of the slices.

Example of use: st_b0shim realtime-dynamic --coil coil1.nii coil1_config.json --coil coil2.nii coil2_config.json --fmap fmap.nii --anat anat.nii --mask-static mask.nii --resp trace.resp --optimizer-method least_squares

st_b0shim realtime-cli [OPTIONS]

Options

--coil <coils>

Pair of filenames containing the coil profiles followed by the filename to the constraints e.g. --coil a.nii cons.json. If you have more than one coil, use this option more than once. The coil profiles and the fieldmaps (--fmap) must have matching units (if fmap is in Hz, the coil profiles must be in Hz/unit_shim). If you only want to shim using the scanner's gradient/shim coils, use the --scanner-coil-order option. For an example of a constraint file, see: /home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/latest/config/coil_config.json

--fmap <fname_fmap>

Required Timeseries of B0 fieldmap.

--anat <fname_anat>

Required Anatomical image to apply the correction onto.

--resp <fname_resp>

Required Siemens respiratory file containing pressure data.

--mask-static <fname_mask_anat_static>

Mask defining the static spatial region to shim.

--mask-riro <fname_mask_anat_riro>

Mask defining the time varying (i.e. RIRO, Respiration-Induced Resonance Offset) region to shim.

--scanner-coil-order <scanner_coil_order>

Maximum order of the shim system. Note that specifying 1 will return orders 0 and 1. The 0th order is the f0 frequency.

Default

-1

Options

-1 | 0 | 1 | 2

--scanner-coil-constraints <fname_sph_constr>

Constraints for the scanner coil.

Default

/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/latest/config/coil_config.json

--slices <slices>

Define the slice ordering. If set to 'auto', automatically parse the target image.

Default

auto

Options

interleaved | sequential | volume | auto

--slice-factor <slice_factor>

Number of slices per shimmed group. Used when '--slices' is not set to 'auto'. For example, if the '--slice-factor' value is '3', then with the 'sequential' mode, shimming will be performed independently on the following groups: {0,1,2}, {3,4,5}, etc. With the mode 'interleaved', it will be: {0,2,4}, {1,3,5}, etc.

Default

1

--optimizer-method <method>

Method used by the optimizer. LS will respect the constraints, PS will not respect the constraints

Default

least_squares

Options

least_squares | pseudo_inverse

--mask-dilation-kernel-size <dilation_kernel_size>

Number of voxels to consider outside of the masked area. For example, when doing dynamic shimming with a linear gradient, the coefficient corresponding to the gradient orthogonal to a single slice cannot be estimated: there must be at least 2 (ideally 3) points to properly estimate the linear term. When using 2nd order or more, more dilation is necessary.

Default

3

--fatsat <fatsat>

Describe what to do with a fat saturation pulse. 'auto': It will parse the NIfTI file for a fat-sat pulse and add shim coefficients of 0s before every shim group when using 'chronological-...' output-file-format-coil. 'no': It will not add 0s. 'yes': It will add 0s.

Default

auto

Options

auto | yes | no

-o, --output <path_output>

Directory to output coil text file(s).

Default

/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/latest/docs/source

--output-file-format-coil <o_format_coil>

Syntax used to describe the sequence of shim events. Use 'slicewise' to output in row 1, 2, 3, etc. the shim coefficients for slice 1, 2, 3, etc. Use 'chronological' to output in row 1, 2, 3, etc. the shim value for trigger 1, 2, 3, etc. The trigger is an event sent by the scanner and captured by the controller of the shim amplifier. For both 'slicewice' and 'chronological', there will be one output file per coil channel (coil1_ch1.txt, coil1_ch2.txt, etc.). The static, time-varying and mean pressure are encoded in the columns of each file.

Default

slicewise-ch

Options

slicewise-ch | chronological-ch

--output-file-format-scanner <o_format_sph>

Syntax used to describe the sequence of shim events. Use 'slicewise' to output in row 1, 2, 3, etc. the shim coefficients for slice 1, 2, 3, etc. Use 'chronological' to output in row 1, 2, 3, etc. the shim value for trigger 1, 2, 3, etc. The trigger is an event sent by the scanner and captured by the controller of the shim amplifier. In both cases, there will be one output file per coil channel (coil1_ch1.txt, coil1_ch2.txt, etc.). The static, time-varying and mean pressure are encoded in the columns of each file. Use 'gradient' to output the scanner 1st order in the Gradient CS, otherwise, it outputs in the Shim CS.

Default

slicewise-ch

Options

slicewise-ch | chronological-ch | gradient

--output-value-format <output_value_format>

Coefficient values for the scanner coil. delta: Outputs the change of shim coefficients. absolute: Outputs the absolute coefficient by taking into account the current shim settings. This is effectively initial + shim. Scanner coil coefficients will be in the Shim coordinate system unless the option --output-file-format is set to gradient. The delta value format should be used in that case.

Default

delta

Options

delta | absolute

-v, --verbose <verbose>

Be more verbose

Options

info | debug

realtime-shim-cli

Perform gradient realtime xyz-shimming. This function will generate text files containing static and dynamic (due to respiration) Gx, Gy, Gz components based on a fieldmap time series and respiratory trace information obtained from Siemens bellows (PMUresp_signal.resp). An additional multi-gradient echo (MGRE) magnitude image is used to resample the static and dynamic Gx, Gy, Gz component maps to match the MGRE image. Lastly the mean Gx, Gy, Gz values within the ROI are computed for each slice. The mean pressure is also generated in the text file to be used to shim.

st_b0shim realtime-shim-cli [OPTIONS]

Options

--fmap <fname_fmap>

Required B0 fieldmap in Hertz. This should be a 4d file (4th dimension being time

--anat <fname_anat>

Required Filename of the anatomical image to apply the correction.

--resp <fname_resp>

Required Siemens respiratory file containing pressure data.

--mask-static <fname_mask_anat_static>

3D nifti file used to define the static spatial region to shim. The coordinate system should be the same as anat's coordinate system.

--mask-riro <fname_mask_anat_riro>

3D nifti file used to define the time varying (i.e. RIRO, Respiration-Induced Resonance Offset) spatial region to shim. The coordinate system should be the same as anat's coordinate system.

-o, --output <fname_output>

Directory to output gradient text file and figures.

Default

/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/latest/docs/source

st_b1shim

Perform static B1+ shimming over the volume defined by the mask. This function will generate a text file containing shim weights for each transmit element.

st_b1shim [OPTIONS]

Options

--b1 <fname_b1>

Required Complex 3D B1+ map.

--mask <fname_mask>

3D boolean mask.

--algo <algorithm>
Number specifying the B1+ shimming algorithm:
1 - Reduce the coefficient of variation of the B1+ field. Favors high B1+ efficiency.
2 - Target a specified B1+ value. Target value required.
3 - Maximize minimum B1+ for higher signal.
4 - Phase-only shimming.
Default

1

Options

1 | 2 | 3 | 4

--target <target>

B1+ value (nT/V) targeted by algorithm 2.

--vop <fname_vop>

SarDataUser.mat file containing VOP matrices used for SAR constraint. Found on the scanner in C:/Medcom/MriProduct/PhysConfig.

--sar_factor <sar_factor>

Factor (=> 1) to which the shimmed max local SAR can exceed the phase-only shimming max local SAR.Values between 1 and 1.5 should work with Siemens scanners. High factors allow more shimming liberty but are more likely to result in SAR excess at the scanner.

-o, --output <path_output>

Output directory for shim weights, B1+ maps and figures.

Default

./b1_shim_results

Masking

st_mask

Create a mask based on a specified shape (box, rectangle, SpinalCord Toolbox mask) or based on the thresholding of an input image. Callable with the prefix 'st' in front of 'mask'. (Example: 'st_mask -h').

st_mask [OPTIONS] COMMAND [ARGS]...

box

Create a box mask from the input file. The nifti file is converted to a numpy array. If this array is in 3D dimensions, then a binary mask is created from this array in the form of a box with lengths defined in 'size'. This box is centered according to the 3 dimensions indicated in 'center'. The mask is stored by default under the name 'mask.nii.gz' in the output folder.Return the filename for the output mask.

st_mask box [OPTIONS]

Options

-i, --input <fname_input>

Required (str): Input path of the nifti file to mask. This nifti file must have 3D. Supported extensions are .nii or .nii.gz.

-o, --output <output>

(str): Name of output mask. Supported extensions are .nii or .nii.gz.

Default

./mask.nii.gz

--size <size>

Required (int): Length of the side of the box along first, second and third dimension (in pixels). (nargs=3)

--center <center>

(int): Center of the box along first, second and third dimension (in pixels). If no center is provided (None), the middle is used. (nargs=3) (default: None, None, None)

rect

Create a rectangle mask from the input file. The nifti file is converted to a numpy array. If this array is in 2 dimensions, then a binary mask is created from this array in the form of a rectangle of lengths defined in 'size'. This rectangle is centered according to the 2 dimensions indicated in 'center'. If this array is in 3 dimensions, a binary mask is created in the shape of rectangle for each slice of the 3rd dimension of the array, in the same way as for a 2D array. The masks of all these slices are grouped in an array to form a binary mask in 3 dimensions. The mask is stored by default under the name 'mask.nii.gz' in the output folder.Return an output nifti file with square mask.

st_mask rect [OPTIONS]

Options

-i, --input <fname_input>

Required (str): Input path of the nifti file to mask. This nifti file must have 2D or 3D. Supported extensions are .nii or .nii.gz.

-o, --output <output>

(str): Name of output mask. Supported extensions are .nii or .nii.gz.

Default

./mask.nii.gz

--size <size>

Required (int): Length of the side of the box along first and second dimension (in pixels). (nargs=2)

--center <center>

(int): Center of the box along first and second dimension (in pixels). If no center is provided (None), the middle is used. (nargs=2) (default: None, None)

sct

Creates a mask around the spinal cord using the Spinal Cord Toolbox (SCT). The mask, which size can be specified, requires to identify the spinal cord centerline. The method of identification is specified by the flag '--centerline'. The output of this function is a NIfTI file containing the mask.

st_mask sct [OPTIONS]

Options

-i, --input <fname_input>

Required Input nifti file to mask. Must be 3D. Supported extensions are .nii or .nii.gz. Example: data.nii.gz

-o, --output <fname_output>

Name of output mask. Supported extensions are .nii or .nii.gz. Example: data.nii.

Default

./mask.nii.gz

--size <size>

Size of the mask in the axial plane, given in pixel (Example: 35) or in millimeter (Example: 35mm). If shape=gaussian, size corresponds to sigma (Example: 45).

Default

20

--shape <shape>

Shape of the mask.

Options

cylinder | box | gaussian

--contrast <contrast>

Type of image contrast.

Default

t2s

Options

t1 | t2 | t2s | dwi

--centerline <centerline>

Method used for extracting the centerline: - svm: Automatic detection using Support Vector Machine algorithm. - cnn: Automatic detection using Convolutional Neural Network. - viewer: Semi-automatic detection using manual selection of a few points with an interactive viewer followed by regularization. - file: Use an existing centerline (use with flag --file_centerline)

Default

svm

Options

svm | cnn | viewer | file

--file-centerline <file_centerline>

Input centerline file. This option is only valid with '--centerline file'. Example: t2_centerline_manual.nii.gz

--brain <brain>

Set to 1 if the image contains the brain (or part of it), set to 0 otherwise (to speed up the segmentation). This option is only valid with '--centerline cnn'.

--kernel <kernel>

Choice of kernel shape for the CNN. Segmentation with 3D kernels is slower than with 2D kernels.

Default

2d

Options

2d | 3d

--remove-tmp <remove_tmp>

Remove temporary files.

Default

True

--verbose <verbose>

Verbose: 0 = nothing, 1 = classic, 2 = expended.

Default

1

threshold

Create a threshold mask from the input file. The nifti file is converted into a numpy array. A binary mask is created from the thresholding of the array. The mask is stored by default under the name 'mask.nii.gz' in the output folder. Return an output nifti file with threshold mask.

st_mask threshold [OPTIONS]

Options

-i, --input <fname_input>

Required (str): Input path of the nifti file to mask. Supported extensions are .nii or .nii.gz.

-o, --output <output>

(str): Name of output mask. Supported extensions are .nii or .nii.gz. (default: (os.curdir, 'mask.nii.gz'))

Default

./mask.nii.gz

--thr <thr>

(int): Value to threshold the data: voxels will be set to zero if their value is equal or less than this threshold. (default: 30)

File Conversion

st_dicom_to_nifti

Converts DICOM files into NIfTI files by calling dcm2bids.

st_dicom_to_nifti [OPTIONS]

Options

-i, --input <path_dicom>

Required Input path to DICOM folder

--subject <subject>

Required Name of the imaged subject

-o, --output <path_nifti>

Output path to BIDS folder

--config <fname_config>

Path to dcm2bids config file

Default

/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/latest/config/dcm2bids.json

--rm-tmp

Remove tmp folder

Image manipulation

st_image

Perform manipulations on images

st_image [OPTIONS] COMMAND [ARGS]...

concat

Concatenate NIfTIs along the specified dimension.

INPUT: Input paths of the files to concatenate. Separate the files by a space.

st_image concat [OPTIONS] INPUT...

Options

-o, --output <fname_output>

Output filename, supported extensions: .nii, .nii.gz

Default

./concat.nii.gz

--axis <axis>

Dimension of the array to concatenate

Default

3

Options

0 | 1 | 2 | 3 | 4

--pixdim <pixdim>

Pixel resolution to join to image header

Arguments

INPUT

Required argument(s)

logical-and

Calculate the logical and for a number of NIfTIs

INPUTS: Input paths of the files to apply the logical and. Separate the files by a space. If the volumes do not have the same orientations, they will be resampled on the last volume.

st_image logical-and [OPTIONS] INPUTS...

Options

-o, --output <fname_output>

Output filename, supported extensions: .nii, .nii.gz

Default

./logical_and.nii.gz

Arguments

INPUTS

Required argument(s)

st_maths

Perform mathematical operations on images.

st_maths [OPTIONS] COMMAND [ARGS]...

mean

Average NIfTI data across dimension.

st_maths mean [OPTIONS]

Options

-i, --input <fname_input>

Required Input filename, supported extensions: .nii, .nii.gz

-o, --output <fname_output>

Output filename, supported extensions: .nii, .nii.gz

--axis <axis>

Axis of the array to calculate the average [default: ./input_mean.nii.gz]

Default

3

Options

0 | 1 | 2 | 3 | 4

Miscellaneous

st_download_data

Download data from the internet.

DATA: The data to be downloaded. Select a dataset from the list:

  • testing_data: Light-weighted dataset for testing purpose.

  • prelude: Binary for prelude software

  • data_dynamic_shimming: B0 dynamic shimming dataset.

  • data_b1_shimming: Static B1+ shimming dataset.

st_download_data [OPTIONS] DATA

Options

--verbose

Be more verbose.

-o, --output <output>

Output folder.

Arguments

DATA

Required argument

System Tools

st_check_dependencies

Verify that the dependencies are installed and available to the toolbox.

st_check_dependencies [OPTIONS]

st_dump_env_info

Dumps environment and package details into stdout for debugging purposes.

st_dump_env_info [OPTIONS]