calculate¶
Synopsis¶
calculate <input> [options]
Description¶
This tool can be used for basic calculations from a sequence of data values read
either from an image or a VTK pointset. It can be used, for example, to add two
data sequences and to divide the result by a constant. The current sequence can
be written to an output file again using calculate -out
. Additionally, statistics
of the current data sequence can be computed such as the mean or variance.
The order of the data transformations and calculation of statistics is determined
by the order of the command-line arguments.
The data mask is used to include/exclude values from subsequent operations.
Initially, all NaN values in the input data sequence are excluded.
Further values can be excluded using one or more of the masking operations.
Using the mask, operations can be performed on only a subset of the data,
and the mask then reset using calculate -reset-mask
.
By default, data statistics are printed to STDOUT in a human readable format.
This output can be appended to a text file using calculate -append
instead.
For a more machine readable output, e.g., as comma separated values (CSV),
specify a delimiting string using calculate -delimiter
. In this case, a header
line is also printed when calculate -header
is given with optional user
specified column names for the individual output values.
Data masking options¶
-
-even
¶
Exclude values which are not an even number when cast to an integer.
-
-odd
¶
Exclude values which are not an odd number when cast to an integer.
-
-label
<value|lower..upper>...
¶ Include data points with a value equal to either one of the given values. Closed intervals of values can be specified as “lower..upper”. For example, “-label 1 3 5..6 10 20..50”. This option is a shorthand for
-mask-all
-threshold-inside
<lower> <upper>-invert-mask
where one-threshold-inside
operation is performed for each argument.
-
-mask
<float|file>
¶ Exclude values equal a given threshold or with zero input mask value. Note that this does not modify the data values, but only marks them to be ignored from now on. Use
-pad
following this operation to replace these values by a background value.
-
-mask-all
¶
Exclude all values.
-
-reset-mask
¶
Reset mask to include all values again.
-
-invert-mask
¶
Invert mask to include all values that where excluded before and exclude all values that were included before.
-
-set
,
-inside
<value>
¶ Set new value for all currently included data values.
-
-pad
,
-outside
<value>
¶ Set new value for all currently excluded data values.
Data thresholding options¶
-
-threshold
<lower> [<upper>]
¶ This masking operation is equivalent to
-threshold-outside
. When no upper threshold is specified, it defaults to +inf. Therefore, “-threshold 0” will exclude all negative values.
-
-percentile-threshold
,
-pct-threshold
<lower>
¶ This masking operation is equivalent to
-threshold-outside-percentiles
. with an upper threshold of +inf. Therefore, “-threshold 0” excludes all negative values.
-
-threshold-percentiles
,
-threshold-pcts
<lower> <upper>
¶ This masking operation is equivalent to
-threshold-outside-percentiles
.
-
-threshold-inside
,
-mask-inside
<lower> <upper>
¶ Exclude values which are inside a given closed interval. When the lower threshold is greater than the upper threshold, values less than or equal to the upper threshold and values greater than or equal to the lower threshold are excluded.
-
-threshold-inside-percentiles
,
-threshold-inside-pcts
,
-mask-inside-percentiles
,
-mask-inside-pct
<lower> <upper>
¶ Exclude values which are inside a given closed interval of percentiles. When the lower percentile is greater than the upper percentile, values less than or equal to the upper percentile and values greater than or equal to the lower percentile are excluded.
-
-threshold-outside
,
-mask-outside
<lower> <upper>
¶ Exclude values which are outside a given open interval. When the lower threshold is greater than the upper threshold, values inside the closed interval <upper>..<lower> are excluded.
-
-threshold-outside-percentiles
,
-threshold-outside-pcts
,
-mask-outside-percentiles
,
-mask-outside-pcts
<lower> <upper>
¶ Exclude values which are outside a given open interval of percentiles. When the lower percentile is greater than the upper percentile, values inside the closed interval <upper>..<lower> are excluded.
-
-threshold-lt
,
-lower-threshold
,
-mask-lt
<value>
¶ Exclude values less than a given threshold.
-
-threshold-lt-percentile
,
-threshold-lt-pct
,
-lower-percentile-threshold
,
-lower-pct-threshold
,
-mask-lt-percentile
,
-mask-lt-pct
<value>
¶ Exclude values less than a given precentile.
-
-threshold-le
,
-mask-le
,
-mask-below
<value>
¶ Exclude values less than or equal to a given threshold.
-
-threshold-le-percentile
,
-threshold-le-pct
,
-mask-le-percentile
,
-mask-le-pct
,
-mask-below-percentile
,
-mask-below-pct
<value>
¶ Exclude values less than or equal to a given percentile.
-
-threshold-ge
,
-mask-ge
,
-mask-above
<value>
¶ Exclude values greater than or equal to a given threshold.
-
-threshold-ge-percentile
,
-threshold-ge-pct
,
-mask-ge-percentile
,
-mask-ge-pct
,
-mask-above-percentile
,
-mask-above-pct
<value>
¶ Exclude values greater than or equal to a given percentile.
-
-threshold-gt
,
-upper-threshold
,
-mask-gt
<value>
¶ Exclude values greater than a given threshold.
-
-threshold-gt-percentile
,
-threshold-gt-pct
,
-upper-percentile-threshold
,
-upper-pct-threshold
,
-mask-gt-percentile
,
-mask-gt-pct
<value>
¶ Exclude values greater than a given percentile.
Data rescaling options¶
-
-binarize
<lower> [<upper>]
¶ Set values inside the closed interval <lower>..<upper> to one, and all other values to zero. The default upper threshold is +inf. When the lower threshold is greater than the upper threshold, values inside the closed interval <upper>..<lower> are set to zero and all other values to one instead. This operation is short for:
-threshold-inside
<lower> <upper>-set
1-pad
0
-
-clamp
<lower> <upper>
¶ Clamp values which are less than a lower or greater than an upper threshold.
-
-clamp-percentiles
,
-clamp-pcts
<lower> <upper>
¶ Clamp values which are less than a lower percentile or greater than an upper percentile.
-
-clamp-below
,
-clamp-lt
<value>
¶ Clamp values less than a given threshold.
-
-clamp-below-percentile
,
-clamp-below-pct
,
-clamp-lt-percentile
,
-clamp-lt-pct
<value>
¶ Clamp values less than a given percentile.
-
-clamp-above
,
-clamp-gt
<value>
¶ Clamp values greater than a given threshold.
-
-clamp-above-percentile
,
-clamp-above-pct
,
-clamp-gt-percentile
,
-clamp-gt-pct
<value>
¶ Clamp values greater than a given percentile.
-
-rescale
<min> <max>
¶ Linearly rescale values to the interval [min, max].
Arithmetic operation options¶
-
-add
,
-plus
<value|file>
¶ Add constant value or data sequence read from specified file. Another name for this option is the ‘+’ sign, see Examples.
-
-sub
,
-subtract
,
-minus
<value|file>
¶ Subtract constant value or data sequence read from specified file. Another name for this option is the ‘-‘ sign, see Examples.
-
-mul
,
-multiply-with
,
-times
<value|file>
¶ Multiply by constant value or data sequence read from specified file. Another name for this option is the ‘*’ sign, see Examples.
-
-div
,
-divide-by
,
-over
<value|file>
¶ Divide by constant value or data sequence read from specified file. When dividing by zero values in the input file, the result is NaN. Use
-mask
with argument NaN and-pad
to replace these undefined values by a constant such as zero. Another name for this option is the ‘/’ sign, see Examples.
-
-div-with-zero
<value|file>
¶ Same as
-div
but set result to zero instead of NaN in case of a division by zero due to a zero value in the specified file.
-
-abs
¶
Replace values by their respective absolute value.
-
-pow
,
-power
<exponent>
¶ Raise values to the power of the given exponent.
-
-sq
,
-square
¶
Raise values to the power of 2 (i.e, -pow 2).
-
-sqrt
¶
Calculate square root of each value (i.e, -pow .5).
-
-exp
¶
Calculate exponential of data sequence.
-
-log
[<threshold>] [<base>]
¶ Compute logarithm after applying an optional threshold. (default threshold: min double, default base: e)
Data output options¶
-
-out
,
-o
,
-output
<file> [<type>]
¶ Write current data sequence to file in the format of the input file. Output data type can be: uchar, short, ushort, int, uint, float, double. Another name for this option is the ‘=’ sign, see Examples.
Data statistics options¶
-
-append
<file>
¶ Append output to a file. (default: STDOUT)
-
-delimiter
,
-delim
,
-d
,
-sep
¶
Delimiting character(s). (default: ‘’)
-
-header
[<name>...]
¶ Request output of header line if delimiter was specified as well. If the output is appended to a text file, the header is only printed if it does not exist. If no or fewer custom column names are given, the default names for each statistic are printed. (default: none)
-
-prefix
<str>...
¶ One or more prefix strings to print. If no delimiter is specified, the concatenated strings are printed before each line of the output. Otherwise, each prefix string is printed as entry for the first columns in the delimited output row, separated by the specified delimiter. (default: none)
-
-precision
,
-digits
<int>
¶ Number of significant digits. (default: 5)
-
-mean
,
-avg
,
-average
¶
Print mean intensity. (default: on)
-
-variance
,
-var
¶
Print variance of intensity values. (default: off)
-
-sigma
,
-std
,
-stddev
,
-stdev
,
-sd
¶
Print standard deviation of intensity values. (default: on)
-
-normal-distribution
¶
Print mean intensity and standard deviation of intensity values. Other option names: -mean+sigma, -mean+sd, -avg+std,... (default: off)
-
-minimum
,
-min
¶
Print minimum intensity value. (default: off)
-
-maximum
,
-max
¶
Print maximum intensity value. (default: off)
-
-extrema
,
-minmax
¶
Print minimum and maximum intensity value. (default: on)
-
-range
¶
Print range of intensity values (i.e., max - min). (default: off)
-
-percentile
,
-pct
,
-p
<n>...
¶ Print n-th percentile. (default: none)
-
-lower-percentile-mean
,
-lpctavg
<n>
¶ Print mean intensity of values less than or equal to the n-th percentile. (default: off)
-
-upper-percentile-mean
,
-upctavg
<n>
¶ Print mean intensity of values greater than or equal to the n-th percentile. (default: off)
Standard options¶
-
-v
,
-verbose
[n]
¶ Increase/Set verbosity of output messages. (default: 0)
-
-debug
[level]
¶ Increase/Set debug level for output of intermediate results. (default: 0)
-
-version
[major.minor]
¶ Print version and exit or set version to emulate.
-
-revision
¶
Print revision (or version) number only and exit.
-
-h
,
-help
¶
Print help and exit.
Examples¶
Example 1¶
Command:
calculate mni305.nii.gz
Output/Description:
Mean = 26.9753
Standard deviation = 50.3525
Extrema = [0, 254]
Range = 254
calculate mni305.nii.gz -pct 77
77th percentile = 25
calculate mni305.nii.gz -padding 25 -range -percentile 25 50 75 -prefix MNI305 '[>25]'
MNI305 [>25] range = 254
MNI305 [>25] 25th percentile = 69
MNI305 [>25] 50th percentile = 113
MNI305 [>25] 75th percentile = 150
calculate mni305.nii.gz -d , -prefix MNI305
MNI305,26.9753,50.3525,0,254,254 [no newline at end of line]
calculate mni305.nii.gz -d , -prefix MNI305 -header
,Mean,Sigma,Min,Max,Range
MNI305,26.9753,50.3525,0,254,254
calculate mni305.nii.gz -d , -prefix MNI305 -header ID Mean SD
ID,Mean,SD,Min,Max,Range
MNI305,26.9753,50.3525,0,254,254
calculate a.nii.gz + b.nii.gz = c.nii.gz
calculate a.vtk + b.nii.gz - 10 / c.nii = d.vtk
Adds data values at identical sequential memory indices in a and b,
subtracts the constant 10, and then divides by the values in image c.
Note: Operations are always executed from left to right,
i.e., no mathematical operator precedence is considered!