mris_calc
mris_calc [OPTIONS] <file1> <ACTION> [<file2> | <floatNumber>]
'mris_calc' is a simple calculator that operates on FreeSurfer curvatures and volumes. In most cases, the calculator functions with three arguments: two inputs and an <ACTION> linking them. Some actions, however, operate with only one input <file1>. In all cases, the first input <file1> is the name of a FreeSurfer curvature overlay (e.g. rh.curv) or volume file (e.g. orig.mgz). For two inputs, the calculator first assumes that the second input is a file. If, however, this second input file doesn't exist, the calculator assumes it refers to a float number, which is then processed according to <ACTION>.Note: <file1> and <file2> should typically be generated on the same subject.
| Argument | Explanation |
|---|---|
| ACTION | The action to be perfomed on the two input files. This is a text string that defines the mathematical operation to execute. For two inputs, this action is applied in an indexed element-by-element fashion, i.e. <file3>[n] = <file1*gt;[n] <ACTION> <file2>[n] where 'n' is an index counter into the data space. |
| Argument | Explanation |
|---|---|
| add | 2 inputs and 1 output. <outputFile> = <file1> + <file2> |
| sub | 2 inputs and 1 output. <outputFile> = <file1> - <file2> |
| mul | 2 inputs and 1 output. <outputFile> = <file1> * <file2>. |
| div | 2 inputs and 1 output. <outputFile> = <file1> / <file2> |
| pow | 2 inputs and 1 output. <outputFile> = pow(<file1>,<file2>) |
| norm | 1 inputs and 1 output. <outputFile> = norm(<file1>). This creates an output file such that all values are constrained (normalized) between 0.0 and 1.0. |
For volume files, be very careful about data types! If the input volume is has data of type UCHAR (i.e. integers between zero and 255), the output will be constrained to this range and type as well! That means, simply, that if type UCHAR vols are multiplied together, the resultant output will itself be a UCHAR volume. This is probably not what you want. In order for calculations to evaluate correctly, especially 'mul', 'div', and 'norm', convert the input volumes to float format, i.e.: $>mri_convert -odt float input.mgz input.f.mgz $>mris_calc -o input_norm.mgz input.f.mgz norm will give correct results, while $>mris_calc -o input_norm.mgz input.mgz norm most likely be *not* what you are looking for. | |
| mod | 2 inputs and 1 output. <outputFile> = mod(<file1>, <file2>). The 'mod' operation is performed by a call to the C-function, fmod(), and accepts either integer or floats -- in fact, ints are converted to floats for this operation. Output sign convention and 0 handling follows that of fmod(): fmod ( ±0, y ) returns ±0 for y not zero. fmod ( x, y ) returns a NaN and raises the invalid floating-point exception for x infinite or y zero. fmod ( x, ±inf ) returns x for x not infinite. |
| sqd | 2 inputs and 1 output. <outputFile> = (<file1> - <file2>)^2. This stores the square difference between two inputs. |
| set | 2 inputs and 1 output. <file1> = <file2>This command overwrites its input data. It still requires a valid <file1> -- since in most instances the 'set' command is used to set input data values to a single float constant, i.e. $>mris_calc rh.area set 0.005 will set all values of rh.area to 0.005. It might be more meaningful to first make a copy of the input file, and set this. $>cp rh.area rh-0.005 $>mris_calc rh-0.005 set 0.005 Similarly for volumes $>cp orig.mgz black.mgz $>mris_calc black.mgz set 0 will result in the 'black.mgz' volume having all its intensity values set to 0. |
| atan2 | 2 inputs and 1 output. <outputFile> = atan2(<file1>,<file2>) |
| bcor | 2 inputs and 1 output. <outputFile> = -log10(1-(1-p)^N)*sign(sig) where p = 10^-abs(<file1>) and N = <file2> or constant. Can be used to bonferroni corrected sig file. |
| mag | 2 inputs and 1 output. <outputFile> = atan2(<file1>,<file2>) |
| sig2p | 1 input and 1 output. <outputFile> = 10^(-abs(<file1>) |
| sqr | 1 input and 1 output. <outputFile> = <file1> * <file1> |
| sqrt | 1 input and 1 output. <outputFile> = sqrt(<file1>) |
| abs | 1 input and 1 output. <outputFile> = abs(<file1>) |
| log10 | 1 input and 1 output. <outputFile> = log10(<file1>). If input=0, then output=0. Output is NaN if input less than zero |
| inv | 1 input and 1 output. <outputFile> = 1/(<file1>) |
| sign | 1 input and 1 output. <outputFile> = sign(<file1>). The 'sign' function returns at each index of an input file: -1 if <file1>[n] < 0 0 if <file1>[n] == 0 1 if <file1[n] > 0 |
| Argument | Explanation |
|---|---|
| eq | Equal to. 2 inputs and 1 output. <outputFile> = <file1> == <file2>. |
| lt | Less than. 2 inputs and 1 output. <outputFile> = <file1> < <file2>. |
| lte | Less than or equal to. 2 inputs and 1 output. <outputFile> = <file1> <= <file2>. |
| gt | Greater than. 2 inputs and 1 output. <outputFile> = <file1> > <file2>. |
| gte | Greater than or equal to. 2 inputs and 1 output. <outputFile> = <file1> >= <file2>. |
If the comparison is valid for a point in <file1> compared to corresponding point in <file2>, the <file1> value is retained; otherwise the <file1> value is set to zero. Thus, if we run 'mris_calc input1.mgz lte input2.mgz', the output volume 'out.mgz' will have all input1.mgz values that are not less than or equal to input2.mgz set to zero. | |
| upl | 2 inputs and 1 output. <outputFile> = <file1> upperlimit <file2>. For this command, any values in <file1> that are greater than or equal to corresponding data points in <file2> are limited to the values in <file2>. Essentially, 'upl' guarantees that all values in <file1> are less than or at most equal to corresponding values in <file2>. |
| lrl | 2 inputs and 1 output. <outputFile> = <file1> lowerlimit <file2>. For 'lpl', any <file1> values that are less than corresponding <file2> values are set to these <file2> values. It guarantees that all values in <file1> are greater than or at least equal to corresponding values in <file2>. |
| Argument | Explanation |
|---|---|
| and | 2 inputs and 1 output. <outputFile> = <file1> && <file2> |
| or | 2 inputs and 1 output. <outputFile> = <file1> || <file2> |
| andbw | 2 inputs and 1 output. <outputFile> = (int)<file1> & (int)<file2> |
| orbw | 2 inputs and 1 output. <outputFile> = (int)<file1> | (int)<file2> |
| not | 1 input and 1 output. <outputFile> = not <file1> |
| masked | 2 inputs and 1 output. <outputFile> = <file1> maskedby <file2> |
| The logical operations follow C convention, i.e. and is a logical 'and' equivalent to the C '&&' operator, similarly for 'or' which is evaluated with the C '||'. The 'andbw' and 'orbw' are bit-wise operators, evaluted with the C operators '&' and '|' respectively. |
| Argument | Explanation |
|---|---|
| ascii | 1 inputs and 1 output. <outputFile> = ascii <file1>. The 'ascii' command converts <file1> to a text format file, suitable for reading into MatLAB, for example. Note that for volumes data values are written out as a 1D linear array with looping order (slice, height, width). |
| Argument | Explanation |
|---|---|
| Note also that the standard deviation can suffer from float rounding errors and is only accurate to 4 digits of precision. If an output file is supplied, it will write the value to that file in ASCII format. | |
| size | 1 inputs and 0 output. print the size (number of elements) of <file1> |
| min | 1 inputs and 0 output. print the min value (and index) of <file1> |
| max | 1 inputs and 0 output. print the max value (and index) of <file1> |
| mean | 1 inputs and 0 output. print the mean value of <file1> |
| std | 1 inputs and 0 output. print the standard deviation of <file1> |
| sum | 1 inputs and 0 output. print the sum across all values of <file1> |
| prod | 1 inputs and 0 output. print the inner product across <file1> |
| stats | 1 inputs and 0 output. process 'size', 'min', 'max', 'mean', 'std' |
| Argument | Explanation |
|---|---|
| If a second input argument is specified, 'mris_calc' will attempt to open the argument following <ACTION> as if it were a curvature file. Should this file not exist, 'mris_calc' will attempt to parse the argument as if it were a float value. In such a case, 'mris_calc' will create a dummy internal array structure and set all its elements to this float value. |
| Argument | Explanation |
|---|---|
| --output <outputCurvFile>,-o <outputCurvFile> | By default, 'mris_calc' will save the output of the calculation to a file in the current working directory with filestem 'out'. The file extension is automatically set to the appropriate filetype based on the input. For any volume type, the output defaults to '.mgz' and for curvature inputs, the output defaults to '.crv'. |
| --label <FreeSurferLabelFile>,-l <FreeSurferLabelFile> | If specified, constraint the calculation to the vertices defined in the <FreeSurferLabelFile>. This is most useful for calculations relating to curvature and thickness files that are defined on a surface. Note that 'mris_calc' will apply a specified label filter to any inputs, i.e. surface related measures (thickness, curvatures) *and* volumes, if volumes are input. This means that if a surface label is applied to a volume, the corresponding volume indices will be tagged and used for calculations. Applying such a surface filter operation to volume indices might be somewhat meaningless. Also, if a label is specified, calculations outside of the label area are set to zero. That means if an addition operation is specified, only the input indices corresponding to the label will be operated on. The non-label indices in the output will be zero. |
| --version,-v | Print out version number. |
| --verbosity <value> | Set the verbosity of the program. Any positive value will trigger verbose output, displaying intermediate results. The <value> can be set arbitrarily. Useful mostly for debugging. |
$>mris_calc rh.area mul rh.thickness
Multiply each value in <rh.area> with the corresponding value in <rh.thickness>, creating a new file called 'out.crv' that contains the result.
$>mris_calc --output rh.weightedCortex rh.area mul rh.thickness
Same as above, but give the ouput file the more meaningful name of 'rh.weightedCortex'.
$>mris_calc rh.area max
Determine the maximum value in 'rh.area' and print to stdout. In addition to the max value, the index offset in 'rh.area' containing this value is also printed.
$>mris_calc rh.area stats
Determine the size, min, max, mean, and std of 'rh.area'.
$>mris_calc orig.mgz sub brainmask.mgz
Subtract the brainmask.mgz volume from the orig.mgz volume. Result is saved by default to out.mgz.
$>mris_calc -o ADC_masked.nii ADC.nii masked B0_mask.img
Mask a volume 'ADC.nii' with 'B0_mask.img', saving the output in 'ADC_masked.nii'. Note that the input volumes are different formats, but the same logical size.
Consider the case when calculating the right hemisphere pseudo volume formed by the FreeSurfer generated white matter 'rh.area' curvature file, and the cortical thickness, 'rh.thickness'. Imagine this is to be expressed as a percentage of intercranial volume. First, calculate the volume and store in a curvature format:
$>mris_calc -o rh.cortexVol rh.area mul rh.thickness
Now, find the intercranial volume (ICV) in the corresponding output file generated by FreeSurfer for this subject. Assume ICV = 100000.
$>mris_calc -o rh.cortexVolICV rh.cortexVol div 100000
Here the second <ACTION> argument is a number and not a curvature file.We could have achieved the same effect by first creating an intermediate curvature file, 'rh.ICV' with each element set to the ICV, and then divided by this curvature:
$>cp rh.area rh.ICV
$>mris_calc rh.ICV set 100000
$>mris_calc -o rh.cortexVolICV rh.cortexVol div rh.ICV
Report bugs to <freesurfer@nmr.mgh.harvard.edu>