Provided by: minc-tools_2.3.00+dfsg-3build2_amd64 bug

NAME

       minccalc - perform complex math operations on minc files

SYNOPSIS

       mincalc [<options>] <in1>.mnc [<in2>.mnc...] <out>.mnc

DESCRIPTION

       Minccalc  will  perform  complex,  voxel-by-voxel  math operations, on one or more minc files of the same
       shape and having the same coordinate sampling, producing a single  output  file.  The  operations  to  be
       performed  are input using the -expression argument (see EXPRESSIONS). By default, the output file is the
       last non-option argument. However, if the -outfile option is used,  then  all  non-option  arguments  are
       considered  input  files  and the output file names come from the -outfile options, of which there can be
       more than one.

OPTIONS

       Note that options can be specified in abbreviated form (as long as they are  unique)  and  can  be  given
       anywhere on the command line.

       -2     Create MINC 2.0 format output files.

       -help  Print summary of command-line options and exit.

       -version
              Print the program's version number and exit.

       -clobber
              Overwrite an existing file.

       -noclobber
              Don't overwrite an existing file (default).

       -no_clobber
              Synonym for -noclobber.

       -verbose
              Print out progress information for each chunk of data copied (default).

       -quiet Do not print out progress information.

       -debug Print out debugging information.

       -copy_header
              Copy all of the header information from the first input file (default for one input file).

       -nocopy_header
              Do not copy all of the header from the first input file; copy only coordinate information (default
              for more than one input file).

       -filetype
              Create an output file with the same type as the first input file (default).

       -byte  Store output voxels in 8-bit integer format.

       -short Store output voxels in 16-bit integer format.

       -int   Store output voxels in 32-bit integer format.

       -long  Superseded by -int.

       -float Store output voxels in 32-bit floating point format.

       -double
              Store output voxels in 64-bit floating point format.

       -signed
              Use signed, two's complement integer format. Applies only if the output voxel type is specified to
              be an integer type (one of -byte, -short, -int or -long).

       -unsigned
              Use  unsigned  integer format. Applies only if the output voxel type is specified to be an integer
              type (one of -byte, -short, -int or -long).

       -range min max
              Restrict the valid range of integer data.  Applies only if one of the -byte, -short, -int or -long
              options is specified.

       -max_buffer_size_in_kb size
              Specify the maximum size of the internal buffers (in kbytes). Default is 4096 (4MB).

       -dimension dimname
              Specify a dimension along which we wish to perform a cumulative operation.

       -check_dimensions
              Check that all input files have matching sampling in world dimensions (default).

       -nocheck_dimensions
              Ignore any differences in world dimensions sampling for input files.

       -propagate_nan
              For  cumulative  vector operations (sum, prod and avg), invalid data  (Not-A-Number or NaN) in any
              element of the vector will produce invalid data in the result (default).

       -ignore_nan
              For cumulative vector operations, invalid data (NaN) in the vector  is  ignored,  ie.  treated  as
              though it is not present.

       -nan   When  an illegal operation is attempted at a voxel (such as divide by zero), the result is invalid
              data (NaN) (default). Having no valid input data for a cumulative operation is also considered  an
              illegal operation when -ignore_nan is used.

       -zero  When  an  illegal  operation is attempted at a voxel (such as divide by zero), the result is value
              zero.

       -illegal_value value
              When an illegal operation is attempted at a voxel (such as divide by  zero),  the  result  is  the
              value specified by this option.

       -expression string
              Specify the expression to evaluate at each voxel (see EXPRESSIONS).

       -expfile filename
              Specify  a  file containing an expression to evaluate at each voxel (see EXPRESSIONS). If filename
              ``-'' is given, then the expression is read from stdin.  The  only  difference  from  command-line
              expressions  is  that  comments can be given in the file. A comment line is specified by placing a
              ``#'' as the first non-whitespace character of the  line.  Minccalc  scripts  can  be  created  by
              setting the first line to

                 #! /usr/local/mni/bin/minccalc -expfile

       -outfile symbol output-file
              Specify  that  output should be written to the specified file, taking values from the symbol which
              should be created in the expression (see the EXAMPLES section). If this option is given, then  all
              non-option arguments are taken as input files. This option can be used multiple times for multiple
              output files.

       -eval_width value
              Specify the number of voxels to process in parallel. Default is 200.

EXPRESSIONS

       The -expression argument is a single string that  describes  the  function  to  evaluate.   The  function
       expression is typically written in terms of the vector A.

       For example, the following expression will sum the first two input files together:

          A[0] + A[1]

       Multiple  expressions  can  be  given  separated  by semicolons, in which case only the value of the last
       expression is used. These expression lists can be used with assignment expressions  to  make  the  syntax
       very C-like:

          ratio = A[0]/A[1]; A[2]*exp(-ratio)

       An  expression  list  in curly brackets is a valid expression and returns the value of last expression in
       the list. This is particularly useful in for and if expressions (see below).

       There are two types of values in the language: vectors and scalars.  Scalars literals are floating  point
       numbers or may appear as symbols whose name starts with a lowercase letter.

       Besides  normal  scalar  operators such as +, -, * and /, the expression language also supports the infix
       exponentiation operator ^ , the usual relational operators <, <=, >, >=, ==, != as well  as  the  boolean
       operators  &&  (and), || (or) and ! (not). Note that the && and || boolean operators always evaluate both
       operands, unlike C. Scalar mathematical functions include abs, sqrt, exp, log, sin, cos, tan, asin,  acos
       and atan. There are also some specialized functions:

          isnan(v) - 1 if v is invalid and 0 otherwise
          clamp(v1,v2,v3) - v1 bounded by [v2, v3]
          segment(v1,v2,v3) - tests if v1 is in [v2, v3]

       The scalar constant NaN is defined such that isnan(NaN) return 1.

       Vectors can be written in the following `extensional' form

          [ value1, value2, ... ]

       or by using the following range-generating notations:

          [ a : b ]     generates {a, a+1, ..., b-1, b}
          [ a : b )     generates {a, a+1, ..., b-1}
          ( a : b ]     generates {a+1, ..., b-1, b}
          ( a : b )     generates {a+1, ..., b-1}

       or be generated, by `intension'. The following intension expression generates the vector {3,2,1}:

          { i in [1:3] | 4 - i }

       Vectors may also appear as symbols whose name starts with an uppercase letter.

       In addition to the scalar operators, the following vector operators are supplied:

          avg  - the average value of the scalars in vector
          len  - the length of
          sum  - the sum of the elements of
          prod - the product of the elements of
          max  - the maximum value of
          min  - the minimum value of
          imax - the index of the maximum value of
          imin - the index of the minimum value of
          V[s] - the s'th element of vector V with origin 0.

       Symbol names are introduced into a global symbol table by assignment expressions of the form

          a = A[2] * log(2)

       Symbols  starting with a lowercase letter represent scalars while those starting with an uppercase letter
       represent vectors. Since = is an operator, its result can be used in an expression (as in C).

       A few control constructs are provided:

       For loops can be created to loop over a vector, assigning each value to a symbol and then  evaluating  an
       expression. This is done with expressions of the form

          total=0; for{i in [0:len(A))} total=total+A[i]; total

       which is equivalent to sum(A). Note that this is similar to using

          total=0; len{i in [0:len(A)) | total=total+A[i]}; total

       since  the  for  construct  is actually an operator (although it is usually only used for changing symbol
       values). Note also that without the final "total", the expression would not be very useful since it would
       only return the length of the vector.

       As in C, a list of expressions can be specified in curlies:

          total=total2 = 0;
          for {i in [0:len(A))} {
             total  = total  + A[i];
             total2 = total2 + A[i]^2
          }

       There are also a few forms of the if-then-else construct:

          A[0]<0 ? 0 : A[0]

          if (A[0]<0) result=0 else result=A[0]

       The  else  is  optional.  Again, the if construct is an operator, and the then or else expressions can be
       expression lists in curlies, in which  case the value of the last expression is  returned.  If  the  else
       expression is missing, then the value 0 is returned when the test expression is 0 (false).

       The  principal  oddity with the for and if constructs is that unlike C statements, they must be separated
       from the next expression by a semicolon even when an expression list in curlies is used:

          for i in [0:len(A)) {total=total+A[i]} ; total/len(A)
          if (A[i]>0) {result=2;} else {result=1} ; result*5

       An alternative way to introduce symbol names is through  let-expressions.   For  example,  the  following
       expression will always evaluate to 3:

          let a = 1, b = 2 in a + b

       These   were  originally  designed  to  create  variables  only  within  the  evaluated  expression,  but
       modifications have been made so that the global symbol table is changed.

EXAMPLES

       Here is an expression for calculating standard deviation, taking into account the possibility of  invalid
       input data, which is ignored:

            s0 = s1 = s2 = 0;

            for { i in [0:len(A)) } {
               v=A[i];
               if (!isnan(v)) {
                  s0 = s0 + 1;
                  s1 = s1 + v;
                  s2 = s2 + v*v;
               }
            };

            if (s0 > 1) {
               sqrt((s2 - s1*s1/s0) / (s0-1));
            }
            else {
               NaN;
            };

       The last if could be changed to return 0 if s0 is > 0 but <= 1. We also drop the curly brackets, but then
       there must not be a ";" between the if and the else

            if (s0 > 1)
               sqrt((s2 - s1*s1/s0) / (s0-1))
            else if (s0 > 0)
               0
            else
               NaN

       If we want both the mean and the standard deviation, we can use the -outfile option, invoking the command
       with

            minccalc -expfile stdev \
               -outfile mean mean.mnc \
               -outfile stdev stdev.mnc \
               infile1.mnc infile2.mnc ...

       And using the expression file (with yet another form of if expression):

            s0 = s1 = s2 = 0;

            for {i in [0:len(A))} {
               v=A[i];
               if (!isnan(v)) {
                  s0 = s0 + 1;
                  s1 = s1 + v;
                  s2 = s2 + v*v;
               }
            };

            stdev = (s0 > 1) ? sqrt((s2 - s1*s1/s0) / (s0-1)) :
                                 (s0 > 0) ? 0 : NaN ;
            mean  = (s0 > 0) ? s1 / s0 : NaN ;

CAVEATS

       A few things you should remember...

       Vector variables must start with an uppercase letter.

       Vector variable names must not be one of the function keywords,
        sum, len, prod, ... etc

       For loops and if expressions always need to be separated from the next expression by a semicolon.

       The symbol table is global.

       Boolean operators && and || always evaluate both operands.

       A note on parallelism: For efficiency reasons, evaluations are done on many voxels at once (the number of
       voxels is referred to as the width of the evaluation and is changed with the -eval_width option). An  odd
       consequence   of this is that both sides of an if-else statement are always evaluated  (unless all voxels
       give the same test result), but statements within each consequent are only evaluated on  the  appropriate
       voxels.  In particular, entries in the symbol table are only modified according to a voxel mask.  A side-
       effect of this is that any vector symbol set in an if-else consequent must not change the length  of  the
       symbol  (although  it  can  create  it)  and both sides of the consequent must agree on the length of any
       vector symbols that they both modify. If this is not clear, just try it - the program will complain if it
       is not happy.

AUTHOR

       Andrew Janke - a.janke@gmail.com

COPYRIGHTS

       Copyright © 2000 by Andrew Janke

SEE ALSO

       mincmath(1)

                                          $Date: 2008-01-11 04:24:16 $                               MINCCALC(1)