Command Line Tools

The following section outlines the CLI of shimming-toolbox.

Field mapping

st_prepare_fieldmap

Creates fieldmap (in Hz) from phase images.

This function accommodates multiple echoes (2 or more) and phase difference. It 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. The BIDS metadata JSON file associated with each phase file is required, it will be fetched automatically using the same name as the NIfTI file.

Example of use (Multiple echoes) : st_prepare_fieldmap phase_echo1.nii.gz phase_echo2.nii.gz phase_echo3.nii.gz --mag mag.nii.gz

Example of use (Phase difference): st_prepare_fieldmap phasediff.nii.gz --mag mag.nii.gz

Usage

st_prepare_fieldmap [OPTIONS] PHASE...

Options

--mag <fname_mag>

Required Input path of mag nifti file

--unwrapper <unwrapper>

Algorithm for unwrapping. skimage is installed by default, prelude requires FSL to be installed.

Default:

'prelude'

Options:

prelude | skimage

-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.

--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

Default:

Sentinel.UNSET

--sigma <sigma>

Standard deviation of gaussian filter. Used for: gaussian_filter

--2d <process_in_2d>

Unwrap and filter slice by slice. Defaults to False, which unwraps the whole 3D volume at once.

Default:

False

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

Arguments

PHASE

Required argument(s)

st_unwrap

Unwraps images. This program assumes wraps occur at min() and max() of the data. The unwrapper tries to correct 2npi ambiguity when unwrapping by bringing the mean closest to 0 in increments of 2pi jumps.

Usage

st_unwrap [OPTIONS]

Options

-i, --input <fname_data>

Required Input path of data nifti file

--mag <fname_mag>

Required Input path of mag nifti file

-o, --output <fname_output>

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

Default:

'./unwrapped.nii.gz'

--unit <unit>

Unit of the input data. Used along with --dte to scale the input data.

Options:

Hz | rad/s | T | mT | G

--dte <dte>

Delta TE (in seconds). Used along with --unit to scale the input data.

--range <extent>

Range of the input data. Data that can range from [1000, 4095] would have a --range of 3095.

--mask <fname_mask>

Input path for a mask.

--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

--unwrapper <unwrapper>

Algorithm for unwrapping. skimage is installed by default, prelude requires FSL to be installed.

Default:

'prelude'

Options:

prelude | skimage

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

Shimming

st_b0shim

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

Usage

st_b0shim [OPTIONS] COMMAND [ARGS]...

add-shim-coefs

Combine the shim coefficients from two files into a single file.

Usage

st_b0shim add-shim-coefs [OPTIONS]

Options

-i, --input <fname_input>

Required Text file containing the shim coefficients. Supported formats: .txt

-i2, --input2 <fname_input2>

Required Text file containing the shim coefficients. Supported formats: .txt

-o, --output <fname_output>

Filename to output shim text file.

Default:

'/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/632/docs/source/shim_coefs.txt'

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

convert-shim-coefs-format

Convert the shim coefficients from one format to another.

Usage

st_b0shim convert-shim-coefs-format [OPTIONS]

Options

-i, --input <fname_input>

Required Text file containing the shim coefficients. Supported formats: .txt

--input-file-format <i_format>

Required Syntax used to describe the sequence of shim events for a coil or coil channel. Use 'slicewise' if the inputs in row 1, 2, 3, etc. are the shim coefficients for slice 1, 2, 3, etc. Use 'chronological' if the inputs in row 1, 2, 3, etc. are 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 volume if the intput is a single set of shim coefficients.

Options:

volume | slicewise | chronological

--output-file-format <o_format>

Required Syntax used to describe the sequence of shim events for a coil or coil channel. 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. 'custom-cl' is a custom format for a collaborator. Use volume to output a single set of shim coefficients.

Options:

volume | slicewise | chronological | custom-cl

--target <fname_target>

Target image the text file is based on. This is used to infer slice timing information when converting between 'slicewise' and 'chronological'. It is also used to infer the number of slices when converting from volume to any other format. Supported formats: .nii, .nii.gz

--reverse-slice-order

Reverse the order of the slices. Only relevant for 'custom-cl'

--add-channels <to_add_channels>

Add channels to the text file that are 0s.

-o, --output <fname_output>

Filename to output shim text file.

Default:

'/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/632/docs/source/shim_coefs.txt'

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

dynamic

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_constraints.json --coil coil2.nii coil2_constraints.json --fmap fmap.nii --target target.nii --mask mask.nii --optimizer-method least_squares

Usage

st_b0shim dynamic [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/envs/632/lib/python3.10/site-packages/shimmingtoolbox/config/custom_coil_constraints.json

--fmap <fname_fmap>

Required Static B0 fieldmap.

--target <fname_target>

Required Target image to apply the correction onto.

--mask <fname_mask_target>

Mask defining the spatial region to shim.

--scanner-coil-order <scanner_coil_order>

Spherical harmonics orders to be used in optimization. Available orders: [-1, 0, 1, 2, 3]. Orders should be writen with a coma separating the values. (i.e. 0,1,2)The 0th order is the f0 frequency.

Default:

'-1'

--scanner-coil-constraints <fname_sph_constr>

Constraints for the scanner coil. Example file located: /home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/envs/632/lib/python3.10/site-packages/shimmingtoolbox/config/scanner_coil_constraints.json

--slices <slices>

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

Default:

'auto'

Options:

interleaved | ascending | descending | 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 ('ascending' or 'descending'), 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 and QP will respect the constraints, BFGS method only accepts constraints for each channel (not constraints on the total current), PS will not respect any constraints

Default:

'quad_prog'

Options:

least_squares | pseudo_inverse | quad_prog | bfgs

--regularization-factor <reg_factor>

Regularization factor for the current when optimizing. A higher coefficient will penalize higher current values while 0 provides no regularization. Not relevant for 'pseudo-inverse' optimizer_method.

Default:

0.0

--optimizer-criteria <opt_criteria>

Criteria of optimization for the optimizer 'least_squares' and 'bfgs'. mse: Mean Squared Error, mae: Mean Absolute Error, ps_huber: pseudo huber cost function, grad: Signal Loss, grad: mse of Bz + weighting X mse of Grad Z, relevant for signal recovery, rmse: Root Mean Squared Error. Not relevant for 'pseudo_inverse' --optimizer-method.

Default:

'mse'

Options:

mse | mae | rmse | grad | ps_huber

--weighting-signal-loss <w_signal_loss>

weighting for signal loss recovery. Since there is generally a compromise between B0 inhomogeneity and gradient in z direction (i.e., signal loss recovery), a higher coefficient will put more weights to recover the signal loss over the B0 inhomogeneity. This parameter can be used with the Least Squares optimization and the mse or rmse criteria. The optimal value for mse is around 0.01 The optimal value for rmse is around 10

--weighting-signal-loss-xy <w_signal_loss_xy>

weighting for signal loss recovery for the X and Y gradients. Since there is generally a compromise between B0 inhomogeneity and Gradient in z (through slice), x, y (phase and readout) direction (i.e., signal loss recovery), a higher coefficient will put more weights to recover the signal loss over the B0 inhomogeneity.

--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/632/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 target 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 '-hrd' to output a human readable file.

Default:

'slicewise-coil'

Options:

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

--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

max-intensity

Find indexes of the 4th dimension of the input volume that has the highest signal intensity for each slice. Based on: https://onlinelibrary.wiley.com/doi/10.1002/hbm.26018

Usage

st_b0shim max-intensity [OPTIONS]

Options

-i, --input <fname_input>

Required 4d volume where 4th dimension was acquired with different shim values

--mask <fname_mask>

Mask defining the spatial region to shim. If no mask is provided, all voxels of the input will be considered.

-o, --output <fname_output>

Filename to output shim text file.

Default:

'/home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/checkouts/632/docs/source/shim_index.txt'

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

realtime-dynamic

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_constraints.json --coil coil2.nii coil2_constraints.json --fmap fmap.nii --target target.nii --mask-static mask.nii --resp trace.resp --optimizer-method least_squares

Usage

st_b0shim realtime-dynamic [OPTIONS]

Options

--coil <coils_static>

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/envs/632/lib/python3.10/site-packages/shimmingtoolbox/config/custom_coil_constraints.json

--coil-riro <coils_riro>

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 this option is used, these coil profiles will be used for the RIRO optimization, otherwise, the coils from the --coil options will be used.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/envs/632/lib/python3.10/site-packages/shimmingtoolbox/config/custom_coil_constraints.json

--fmap <fname_fmap>

Required Timeseries of B0 fieldmap.

--target <fname_target>

Required Target image to apply the correction onto.

--resp <fname_resp>

Required Siemens respiratory file containing pressure data.

--time-offset <time_offset>

Time offset (ms) between the respiratory recording and the acquired time in the DICOMs.

--mask-static <fname_mask_target_static>

Mask defining the static spatial region to shim.

--mask-riro <fname_mask_target_riro>

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

--scanner-coil-order <scanner_coil_order_static>

Spherical harmonics orders to be used in static optimization. Available orders: [-1, 0, 1, 2, 3]. Orders should be writen with a coma separating the values. (i.e. 0,1,2)The 0th order is the f0 frequency.

Default:

'-1'

--scanner-coil-order-riro <scanner_coil_order_riro>

Spherical harmonics orders to be used in RIRO optimization. If not set, the same orders as --scanner-coil-order will be used for RIROAvailable orders: [-1, 0, 1, 2, 3]. Orders should be writen with a coma separating the values. (i.e. 0,1,2)The 0th order is the f0 frequency.

--scanner-coil-constraints <fname_sph_constr>

Constraints for the scanner coil. Example file located: /home/docs/checkouts/readthedocs.org/user_builds/shimming-toolbox-py/envs/632/lib/python3.10/site-packages/shimmingtoolbox/config/scanner_coil_constraints.json

--slices <slices>

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

Default:

'auto'

Options:

interleaved | ascending | descdending | 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' ('ascending' or 'descending') 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 and QP will respect the constraints, BFGS method only accepts constraints for each channel (not constraints on the total current), PS will not respect any constraints

Default:

'quad_prog'

Options:

least_squares | pseudo_inverse | quad_prog | bfgs

--optimizer-criteria <opt_criteria>

Criteria of optimization for the optimizer 'least_squares' and 'bfgs'. mse: Mean Squared Error, mae: Mean Absolute Error, ps_huber: pseudo huber cost function, rmse: Root Mean Squared Error. Not relevant for 'pseudo_inverse' or 'quad_prog' --optimizer-method.

Default:

'mse'

Options:

mse | mae | grad | rmse

--regularization-factor <reg_factor>

Regularization factor for the current when optimizing. A higher coefficient will penalize higher current values while 0 provides no regularization. Not relevant for 'pseudo-inverse' optimizer_method.

Default:

0.0

--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/632/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 'XXXXX-ch', 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. For XXXXX-coil, there will be a single file per coil. The static and time-varying coefficients are encoded one after the other as columns (static-ch1, rt-ch1, static-ch2, rt-ch2, etc.). The mean pressure is encoded as the last row.

Default:

'slicewise-ch'

Options:

slicewise-ch | chronological-ch | chronological-coil | slicewise-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 target 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 '-hrd' to output a human readable file.

Default:

'slicewise-ch'

Options:

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

--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

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.

Usage

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').

Usage

st_mask [OPTIONS] COMMAND [ARGS]...

bet

Wrapper for BET, please see https://fsl.fmrib.ox.ac.uk/fsl/docs/#/structural/bet. Create a brain mask in the coordinates of the input file. The mask is stored by default under the name 'mask.nii.gz' in the output folder.

Usage

st_mask bet [OPTIONS]

Options

-i, --input <fname_input>

Required Input path of the nifti file to mask. This nifti file must be 3D. Supported extensions are .nii or .nii.gz.

-o, --output <fname_output>

Name of output mask. Do not add extension

Default:

'./mask'

-f, --f_param <f_param>

fractional intensity threshold (0->1); default=0.5; smaller values give larger brain outline estimates

-g, --g_param <g_param>

vertical gradient in fractional intensity threshold (-1->1); positive values give larger brain outline at bottom, smaller at top

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

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.

Usage

st_mask box [OPTIONS]

Options

-i, --input <fname_input>

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

-o, --output <output>

Name of output mask. Supported extensions are .nii or .nii.gz.

Default:

'./mask.nii.gz'

--size <size>

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

--center <center>

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)

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

modify-binary-mask

Wrapper for modify_binary_mask. Lets the user dilate or erode their masks

Usage

st_mask modify-binary-mask [OPTIONS]

Options

-i, --input <fname_input>

Required Input path of the nifti file to mask. This nifti file must be 3D. Supported extensions are .nii or .nii.gz.

-o, --output <fname_output>

Name of output mask. Supported extensions are .nii or .nii.gz.

Default:

'./mask.nii.gz'

--shape <shape>

3d kernel to perform the dilation. Allowed shapes are: 'sphere', 'cross', 'line', 'cube', 'None'.

Options:

sphere | cross | line | cube | None

--size <size>

Required Kernel size for the dilation or erosion. Must be odd.

--operation <operation>

Required operation to perform. Allowed operations are: 'dilate', 'erode'.

Options:

erode | dilate

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

mrs

Create a mask to shim single voxel MRS. Voxel position and size can be directly given or these info can be read from the siemens raw-data. The mask is stored by default under the name 'mask_mrs.nii.gz' in the output folder. Return an output nifti file to be used as a mask for MRS shimming.

Usage

st_mask mrs [OPTIONS]

Options

-i, --input <fname_input>

Required Input path of the fieldmap to be shimmed.

-r, --raw <raw_data>

Input path of the raw-data (supported extention .rda)

-o, --output <output>

Name of the output mask. Supported extensions are .nii or .nii.gz.

Default:

'./mask_mrs.nii.gz'

-c, --center <center>

Voxel's center position in mm of the x, y and z of the scanner's coordinate

-s, --size <size>

Voxel size in mm of the x, y and z of the scanner's coordinate

--verbose <verbose>

Be more verbose

Options:

info | debug

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.

Usage

st_mask rect [OPTIONS]

Options

-i, --input <fname_input>

Required 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>

Name of output mask. Supported extensions are .nii or .nii.gz.

Default:

'./mask.nii.gz'

--size <size>

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

--center <center>

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)

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

sct

Create 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.

Usage

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

softmask

Create a soft mask by creating a blur zone around the binary mask.

Usage

st_mask softmask [OPTIONS]

Options

-i, --input <fname_input_binmask>

Required Path to the binary mask. Supported extensions are .nii or .nii.gz.

-s, --input-softmask <fname_input_softmask>

Path to an existing soft mask. Use only on sum-type softmask. Supported extensions are .nii or .nii.gz.

-o, --output <fname_output_softmask>

Path to the output soft mask. Supported extensions are .nii or .nii.gz.

Default:

'./softmask.nii.gz'

-t, --type <type>

Type of soft mask :

  • 2levels: All blur zone coefficients have the same value. Specify blur_value (-b)

  • linear: Radial linear gradient, from 1 to 0.

  • gaussian: Gaussian distribution.

  • sum: Sum of the binary mask and an existing softmask. Specify the existing softmask (-s).

Options:

2levels | linear | gaussian | sum

-w, --blur-width <blur_width>

Width of the blurred zone.

-u, --width-unit <width_unit>

Unit of the blur width. Can be in pixels (px) or in millimeters (mm).

Options:

mm | px

-b, --blur-value <blur_value>

Value of the coefficients in the blurred zone. Use only on 2levels-type softmask

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

sphere

Create a spherical mask in the coordinates of the input file. The mask is stored by default under the name 'mask.nii.gz' in the output folder.

Usage

st_mask sphere [OPTIONS]

Options

-i, --input <fname_input>

Required Input path of the nifti file to mask. This nifti file must be 3D. Supported extensions are .nii or .nii.gz.

-o, --output <fname_output>

Name of output mask. Supported extensions are .nii or .nii.gz.

Default:

'./mask.nii.gz'

-r, --radius <radius>

Required Number of pixels for the radius of the sphere.

--center <center>

Center of the sphere along first, second and third dimension (in pixels). If no center is provided, the middle is used.

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

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.

Usage

st_mask threshold [OPTIONS]

Options

-i, --input <fname_input>

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

-o, --output <output>

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

Default:

'./mask.nii.gz'

--thr <thr>

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

Default:

30.0

--scaled-thr

Indicate whether the --thr option is scaled from 0 to 1 (True) or according to the values within the input (False). Default: False

Default:

False

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

File Conversion

st_dicom_to_nifti

Converts DICOM files into NIfTI files by calling dcm2bids.

Usage

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/envs/632/lib/python3.10/site-packages/shimmingtoolbox/config/dcm2bids.json'

--rm-tmp

Remove tmp folder

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

Coil Profile Generation

st_create_coil_profiles

Create coil profiles according to the specified algorithm as an argument e.g. st_create_coil_profiles xxxxx. A constraint file can also be generated using the constraint command.

Usage

st_create_coil_profiles [OPTIONS] COMMAND [ARGS]...

constraint-file

Create a constraint file for the coil profiles

Usage

st_create_coil_profiles constraint-file [OPTIONS]

Options

--name <name>

Name of the coil

--channels <channels>

Required Number of channels in the coil

--min <min_current>

Required Minimum coefficient possible

--max <max_current>

Required Maximum coefficient possible

--max-sum <max_sum>

Required Maximum sum of coefficient possible

--units <units>

Units of the coefficients e.g. 'A'

-o, --output <fname_output>

Output filename of the coil profiles constraint file. Supported types : '.json''

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

from-cad

Create ΔB₀ coil profiles from CAD wire geometries.

Usage

st_create_coil_profiles from-cad [OPTIONS]

Options

-i, --input <fname_txt>

Required Input filename of wires' geometry text file.

--fmap <fname_fmap>

Required Static ΔB₀ fieldmap on which to calculate coil profiles. Only FOV and affine are used.

--offset <offset>

XYZ offset: The difference between the coil’s isocenter position and the field map's isocenterposition (in mm). Input should be --offset x y z. Defaulted to 0 0 0

--flip <dims_to_flip>

Dimensions (XYZ order) to flip in the wires' geometry (1 for no flip, -1 for flip). Input should be --flip x y z. Defaulted to 1 1 1.

--software <software>

Software from which the geometries were extracted.

Options:

autocad

--coil_name <coil_name>

Name of the coil. If not provided, "new" will be used.

--min <min_current>

The minimum current in amps going through each channel. Defaulted to -1 A.

--max <max_current>

The maximum current in amps going through each channel. Defaulted to 1 A.

--max_sum <max_current_sum>

The maximum sum of currents in amps going through all loops. Defaulted to the number of channel.

-o, --output <fname_output>

Output filename of the coil profiles NIfTI file. Supported types : '.nii', '.nii.gz'

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

from-field-maps

Create ΔB₀ coil profiles from acquisitions defined in the input json file. The output is in Hz/<current> where current depends on the value in the configuration file

Usage

st_create_coil_profiles from-field-maps [OPTIONS]

Options

-i, --input <fname_json>

Required Input filename of the JSON coil profile creation configuration file. See the tutorial for more details.

--relative-path <path_relative>

Path to add before each file in the configuration file. This allows to have relative paths in the configuration file. If this option is not specified, absolute paths must be provided in the configuration file.

-o, --output <fname_output>

Output filename of the coil profiles NIfTI file. Supported types : '.nii', '.nii.gz'

--threshold <threshold>

Threshold for masking. Allowed range: [0, 1] where all scaled values lower than the threshold areset to 0.

--mask <fname_mask>

Input path for a mask.

--gaussian-filter <gaussian_filter>

Gaussian filter for B0 maps

Default:

Sentinel.UNSET

--sigma <sigma>

Standard deviation of gaussian filter. Used for: gaussian_filter

--unwrapper <unwrapper>

Algorithm for unwrapping

Default:

'prelude'

Options:

prelude | skimage

--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

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

Image manipulation

st_image

Perform manipulations on images

Usage

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.

Usage

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.

Usage

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.

Usage

st_maths [OPTIONS] COMMAND [ARGS]...

div

Divide NIfTI input by NIfTI input 2.

Usage

st_maths div [OPTIONS]

Options

-i, --input <fname_input>

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

-d, --denominator <fname_denom>

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

-o, --output <fname_output>

Output filename, supported extensions: .nii, .nii.gz. [default: ./input_div.nii.gz]

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

mag

Compute the magnitude data from real and imaginary data, or complex data.

Usage

st_maths mag [OPTIONS]

Options

--real <fname_real>

Input filename of a real image. Must be used with '--imaginary'. Supported extensions: .nii, .nii.gz

--imaginary <fname_im>

Input filename of a imaginary image. Must be used with '--real'. Supported extensions: .nii, .nii.gz

--complex <fname_complex>

Input filename of a complex image. Supported extensions: .nii, .nii.gz

-o, --output <fname_output>

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

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

mean

Average NIfTI data across dimension.

Usage

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. [default: ./input_mean.nii.gz]

--axis <axis>

Axis of the array to calculate the average

Default:

'-1'

Options:

-1 | 0 | 1 | 2 | 3 | 4 | 5 | 6

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

phase

Compute the phase data from real and imaginary data, or complex data.

Usage

st_maths phase [OPTIONS]

Options

--real <fname_real>

Input filename of a real image. Must be used with '--imaginary'. Supported extensions: .nii, .nii.gz

--imaginary <fname_im>

Input filename of a imaginary image. Must be used with '--real'. Supported extensions: .nii, .nii.gz

--complex <fname_complex>

Input filename of a complex image. Supported extensions: .nii, .nii.gz

-o, --output <fname_output>

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

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

std

Compute the STD from NIfTI data across an axis.

Usage

st_maths std [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. [default: ./input_std.nii.gz]

--axis <axis>

Axis of the array to calculate the average

Default:

'-1'

Options:

-1 | 0 | 1 | 2 | 3 | 4 | 5 | 6

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

Miscellaneous

st_download_data

Download data from the internet.

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

Usage

st_download_data [OPTIONS] DATA

Options

--verbose

Be more verbose.

-o, --output <output>

Output folder.

Arguments

DATA

Required argument

st_sort_dicoms

Usage

st_sort_dicoms [OPTIONS]

Options

-i, --input <path_input>

Input folder.

-r, --recursive

Specifies to look into sub-folders. See also the --recursive-depth option.

Default:

False

--recursive-depth <recursive_depth>

Depth of the recursive search.

Default:

5

-o, --output <path_output>

Output folder.

-v, --verbose <verbose>

Be more verbose

Options:

info | debug

System Tools

st_check_dependencies

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

Usage

st_check_dependencies [OPTIONS]

st_dump_env_info

Dumps environment and package details into stdout for debugging purposes.

Usage

st_dump_env_info [OPTIONS]