sct_extract_metric¶
This program extracts metrics (e.g., DTI or MTR) within labels. Labels could be a single file or a folder generated with ‘sct_warp_template’ containing multiple label files and a label description file (info_label.txt). The labels should be in the same space coordinates as the input image.
The labels used by default are taken from the PAM50 template. To learn about the available PAM50 white/grey matter atlas labels and their corresponding ID values, please refer to: https://spinalcordtoolbox.com/overview/concepts/pam50.html#white-and-grey-matter-atlas-pam50-atlas
To compute FA within labels 0, 2 and 3 within vertebral levels C2 to C7 using binary method:
sct_extract_metric -i dti_FA.nii.gz -l 0,2,3 -vert 2:7 -method bin
To compute average MTR in a region defined by a single label file (could be binary or 0-1 weighted mask) between slices 1 and 4:
sct_extract_metric -i mtr.nii.gz -f my_mask.nii.gz -z 1:4 -method wa
usage: sct_extract_metric -i <file> [-h] [-f <folder>] [-l <str>] [-list-labels]
[-method {ml,map,wa,bin,median,max}] [-append {0,1}]
[-combine {0,1}] [-o <file>] [-output-map <file>]
[-z <str>] [-perslice {0,1}] [-vert <str>]
[-vertfile <file>] [-perlevel <int>] [-v <int>]
[-param <str>] [-fix-label <list>] [-norm-file <file>]
[-norm-method {sbs,whole}] [-mask-weighted <file>]
[-discard-neg-val {0,1}]
MANDATORY ARGUMENTS¶
- -i
Image file to extract metrics from. Example:
FA.nii.gz
OPTIONAL ARGUMENTS¶
- -f
Single label file, or folder that contains WM tract labels. Example: /home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/checkouts/stable/data/PAM50/atlas
Default: “label/atlas”
- -l
Label IDs to extract the metric from. Default = all labels. Separate labels with
,
. To select a group of consecutive labels use:
. Example:1:3
is equivalent to1,2,3
. Maximum Likelihood (or MAP) is computed using all tracts, but only values of the selected tracts are reported.Default: “”
- -list-labels
List available labels. These labels are defined in the file
info_label.txt
located in the folder specified by the flag-f
.- -method
Possible choices: ml, map, wa, bin, median, max
Method to extract metrics.
ml
: maximum likelihood: This method is recommended for large labels and low noise. Also, this method should only be used with the PAM50 white/gray matter atlas, or with any custom atlas as long as the sum across all labels equals 1, in each voxel part of the atlas.map
: maximum a posteriori: Mean priors are estimated by maximum likelihood within three clusters (white matter, gray matter and CSF). Tract and noise variance are set with flag-p
. This method should only be used with the PAM50 white/gray matter atlas, or with any custom atlas as long as the sum across all labels equals 1, in each voxel part of the atlas.wa
: weighted averagebin
: binarize mask (threshold=0.5)median
: weighted median: This implementation of the median treats quantiles as a continuous (vs. discrete) function. For more details, see https://pypi.org/project/wquantiles/max
: for each z-slice of the input data, extract the max value for each slice of the input data.
Default: “wa”
- -append
Possible choices: 0, 1
Whether to append results as a new line in the output csv file instead of overwriting it. 0 = no, 1 = yes
Default: 0
- -combine
Possible choices: 0, 1
Whether to combine multiple labels into a single estimation.
0
= no,1
= yesDefault: 0
- -o
File name of the output result file collecting the metric estimation results. Include the
.csv
file extension in the file name. Example:extract_metric.csv
Default: “extract_metric.csv”
- -output-map
File name for an image consisting of the atlas labels multiplied by the estimated metric values yielding the metric value map, useful to assess the metric estimation and especially partial volume effects.
Default: “”
- -z
Slice range to estimate the metric from. First slice is 0. Example:
5:23
You can also select specific slices using commas. Example:
0,2,3,5,12
Default: “”
- -perslice
Possible choices: 0, 1
Whether to output one metric per slice instead of a single output metric.
0
= no,1
= yes.Please note that when methods ml or map are used, outputting a single metric per slice and then averaging them all is not the same as outputting a single metric at once across all slices.
- -vert
Vertebral levels to compute the metrics across. Example: 2:9 for C2 to T2. If you also specify a range of slices with flag
-z
, the intersection between the specified slices and vertebral levels will be considered.Default: “”
- -vertfile
Vertebral labeling file. Only use with flag
-vert
.The input Image and the vertebral labelling file must in the same voxel coordinate system and must match the dimensions between each other.
Default: “./label/template/PAM50_levels.nii.gz”
- -perlevel
Whether to output one metric per vertebral level instead of a single output metric.
0
= no,1
= yes.Please note that this flag needs to be used with the -vert option.
Default: 0
- -v
Possible choices: 0, 1, 2
Verbosity. 0: Display only errors/warnings, 1: Errors/warnings + info messages, 2: Debug mode
Default: 1
FOR ADVANCED USERS¶
- -param
Advanced parameters for the
map
method. All values must be provided, and separated with,
.First value: standard deviation of metrics across labels
Second value: standard deviation of the noise (assumed Gaussian)
Default: “”
- -fix-label
When using ML or MAP estimations, if you do not want to estimate the metric in one label and fix its value to avoid effects on other labels, specify <label_ID>,<metric_value. Example: -fix-label 36,0 (Fix the CSF value)
Default: “”
- -norm-file
Filename of the label by which the user wants to normalize.
Default: “”
- -norm-method
Possible choices: sbs, whole
Method to use for normalization:
sbs
: normalization slice-by-slicewhole
: normalization by the metric value in the whole label for all slices.
Default: “”
- -mask-weighted
Nifti mask to weight each voxel during ML or MAP estimation. Example: PAM50_wm.nii.gz
Default: “”
- -discard-neg-val
Possible choices: 0, 1
Whether to discard voxels with negative value when computing metrics statistics. 0 = no, 1 = yes
Default: “0”