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.

Input options

-scalars <name>

Name of input point data array. (default: active SCALARS array)

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)

-lb, -log2 [<threshold>]

Compute binary logarithm, alias for -log with base 2.

-ln, -loge [<threshold>]

Compute natural logarithm, alias for -log with base e.

-lg, -log10 [<threshold>]

Compute logarithm to base 10, alias for -log with base 10.

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.

Terminal options

-color, -nocolor

Enable/disable colored output. (default: off)

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!