CLI Reference¶

The following section outlines the CLI of shimming-toolbox.

Fieldmapping
- st_prepare_fieldmap
Shimming
- st_realtime_shim
Masking
- st_mask
File Conversion
- st_dicom_to_nifti
Image manipulation
- st_image
- st_maths
Miscellaneous
- st_download_data
System Tools
- st_check_dependencies
- st_dump_env_info

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.

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

st_prepare_fieldmap [OPTIONS] PHASE...

Options

--mag <fname_mag>¶: Input path of mag nifti file

--unwrapper <unwrapper>¶

Algorithm for unwrapping

Options: prelude

-o, --output <fname_output>¶: Output filename for the fieldmap, supported types : ‘.nii’, ‘.nii.gz’

--mask <fname_mask>¶: Input path for a mask. Used for PRELUDE

--threshold <threshold>¶: Threshold for masking. Used for: PRELUDE

--gaussian-filter <gaussian_filter>¶: Gaussian filter for B0 map

--sigma <sigma>¶: Standard deviation of gaussian filter. Used for: gaussian_filter

Arguments

PHASE¶: Required argument(s)

Shimming ¶

st_realtime_shim ¶

Perform realtime z-shimming. This function will generate textfile containing static and dynamic (due to respiration) 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) magnitiude image is used to resample the static and dynamic Gz component maps to match the MGRE image. Lastly the mean 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_realtime_shim [OPTIONS]

Options

--fmap <fname_fmap>¶: Required B0 fieldmap. 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.

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: (os.curdir, ‘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: (os.curdir, ‘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’))

--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 of dicom folder

-o, --output <path_nifti>¶: Output path for niftis

--subject <subject>¶: Required Name of the patient

--config <fname_config>¶: Full file path and name of the bids config file

--remove-tmp, --dont-remove-tmp¶: Specifies if tmp folder will be deleted after processing

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)

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

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]