calculate-element-wise

Synopsis

calculate-element-wise <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-element-wise -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-element-wise -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-element-wise -append instead. For a more machine readable output, e.g., as comma separated values (CSV), specify a delimiting string using calculate-element-wise -delimiter. In this case, a header line is also printed when calculate-element-wise -header is given with optional user specified column names for the individual output values.

Input options

-pd, -point-data, -scalars <name>

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

-cd, -cell-data <name>

Name of input cell data array. Overrides -pd.

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 <value>... | <file> [<scalars>] [<value>]

Exclude values equal a given threshold or with specified input mask <value>. The default mask value of values to be excluded is zero. When the input file is a point set file (e.g., .vtk, .vtp), the optional <scalars> argument can be used to specify the name of the point/cell data array to use as mask. Note that this operation 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 constant 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].

-map <from> <to>...

Replaces values equal to <from> by the specified <to> value. Multiple pairs of <from> and <to> value replacements can be specified in order to perform the substitutions in one step. For example, to swap the two values 1 and 2, use -map 1 2 2 1.

Arithmetic operation options

-add, -plus <value> | <file> [<scalars>]

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> [<scalars>]

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> [<scalars>]

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> | sum | <file> [<scalars>]

Divide by constant value or data sequence read from specified file. When the argument is “sum”, the divisor is the sum of the values. 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> | sum | <file> [<scalars>]

Same as -div, but set result to zero in case of division by zero.

-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>] [<name>]

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. The optional <name> argument can be used to save the modified data of an input point set data array with a different name along with the input data. Otherwise, the input data values are replaced by the modified values and stored with point data array name is unchanged. Another name for this option is the ‘=’ sign, but the optional arguments are are not supported by this alternative notation. See Examples for usage.

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)

-median

Print median value, i.e., 50th percentile. (default: off)

-mean, -avg, -average

Print mean value. (default: on)

-variance, -var

Print variance of values. (default: off)

-sigma, -std, -stddev, -stdev, -sd

Print standard deviation of values. (default: on)

-normal-distribution

Print mean and standard deviation of values. Other option names: -mean+sigma, -mean+sd, -avg+std,... (default: off)

-mad, -mean-absolute-difference, -mean-absolute-deviation

Print mean absolute difference/deviation around the mean. (default: off)

-mad-median, -median-absolute-difference, -median-absolute-deviation

Print mean absolute difference/deviation around the median. (default: off)

-minimum, -min

Print minimum value. (default: off)

-maximum, -max

Print maximum value. (default: off)

-extrema, -minmax

Print minimum and maximum value. (default: on)

-range

Print range of 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)

-sum

Print sum of values. Can be used to count values within a certain range using a thresholding followed by -set 1 before summing these values. (default: off)

-count

Print number of values inside the mask, i.e., values not currently excluded. (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-element-wise mni305.nii.gz

Output/Description:

    Mean = 26.9753
    Standard deviation = 50.3525
    Extrema = [0, 254]
    Range = 254

calculate-element-wise mni305.nii.gz -pct 77
    77th percentile = 25

calculate-element-wise 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-element-wise mni305.nii.gz -d , -prefix MNI305
    MNI305,26.9753,50.3525,0,254,254 [no newline at end of line]

calculate-element-wise mni305.nii.gz -d , -prefix MNI305 -header
    ,Mean,Sigma,Min,Max,Range
    MNI305,26.9753,50.3525,0,254,254

calculate-element-wise 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-element-wise a.nii.gz + b.nii.gz = c.nii.gz

calculate-element-wise 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!