AFNI program: 1dmatcalc

Output of -help

Usage: 1dmatcalc [-verb] expression

Evaluate a space delimited RPN matrix-valued expression:

 * The operations are on a stack, each element of which is a
     real-valued matrix.
   * N.B.: This is a computer-science stack of separate matrices.
           If you want to join two matrices in separate files
           into one 'stacked' matrix, then you must use program
           1dcat to join them as columns, or the system program
           cat to join them as rows.
 * You can also save matrices by name in an internal buffer
     using the '=NAME' operation and then retrieve them later
     using just the same NAME.
 * You can read and write matrices from files stored in ASCII
     columns (.1D format) using the &read and &write operations.
 * The following 5 operations, input as a single string,
     '&read(V.1D) &read(U.1D) &transp * &write(VUT.1D)'
   - reads matrices V and U from disk (separately),
   - transposes U (on top of the stack) into U',
   - multiplies V and U' (the two matrices on top of the stack),
   - and writes matrix VU' out (the matrix left on the stack by '*').
 * Calculations are carried out in single precision ('float').
 * Operations mostly contain characters such as '&' and '*' that
   are special to Unix shells, so you'll probably need to put
   the arguments to this program in 'single quotes'.
 * You can use '%' or '@' in place of the '&' character, if you wish.

 STACK OPERATIONS
 -----------------
 number     == push scalar value (1x1 matrix) on stack;
                 a number starts with a digit or a minus sign
 =NAME      == save a copy matrix on top of stack as 'NAME'
 NAME       == push a copy of NAME-ed matrix onto top of stack;
                 names start with an alphabetic character
 &clear     == erase all named matrices (to save memory);
                 does not affect the stack at all
 &purge     == erase the stack;
                 does not affect named matrices
 &read(FF)  == read ASCII (.1D) file onto top of stack from file 'FF'
 &read4x4Xform(FF)
            == Similar to &read(FF), except that it expects data
               for a 12-parameter spatial affine transform.
               FF can contain 12x1, 1x12, 16x1, 1x16, 3x4, or
               4x4 values. 
               The read operation loads the data into a 4x4 matrix
                  r11   r12   r13   r14
                  r21   r22   r23   r24
                  r31   r32   r33   r34
                  0.0   0.0   0.0   1.0
               This option was added to simplify the combination of 
               linear spatial transformations. However, you are better 
               off using cat_matvec for that purpose.

 &write(FF) == write top matrix to ASCII file to file 'FF';
                 if 'FF' == '-', writes to stdout
 &transp    == replace top matrix with its transpose
 &ident(N)  == push square identity matrix of order N onto stack
                 N is an fixed integer, OR
                 &R to indicate the row dimension of the
                    current top matrix, OR
                 &C to indicate the column dimension of the
                    current top matrix, OR
                 =X to indicate the (1,1) element of the
                    matrix named X
 &Psinv     == replace top matrix with its pseudo-inverse
                 [computed via SVD, not via inv(A'*A)*A']
 &Sqrt      == replace top matrix with its square root
                 [computed via Denman & Beavers iteration]
               N.B.: not all real matrices have real square
                 roots, and &Sqrt will fail if you push it
               N.B.: the matrix must be square!
 &Pproj     == replace top matrix with the projection onto
                 its column space; Input=A; Output = A*Psinv(A)
               N.B.: result P is symmetric and P*P=P
 &Qproj     == replace top matrix with the projection onto
                 the orthogonal complement of its column space
                 Input=A; Output=I-Pproj(A)
 *          == replace top 2 matrices with their product;
  OR               stack = [ ... C A B ] (where B = top) goes to
 &mult             stack = [ ... C AB ]
                 if either of the top matrices is a 1x1 scalar,
                 then the result is the scalar multiplication of
                 the other matrix; otherwise, matrices must conform
 + OR &add  == replace top 2 matrices with sum A+B
 - OR &sub  == replace top 2 matrices with difference A-B
 &dup       == push duplicate of top matrix onto stack
 &pop       == discard top matrix
 &swap      == swap top two matrices (A <-> B)
 &Hglue     == glue top two matrices together horizontally:
                   stack = [ ... C A B ] goes to
                   stack = [ ... C A|B ]
                 this is like what program 1dcat does.
 &Vglue     == glue top two matrices together vertically:
                   stack = [ ... C A B ] goes to

                                    A
                   stack = [ ... C  - ]
                                    B

                 this is like what program cat does.

SIMPLE EXAMPLES
---------------
* Multiply each element of an input 1D file
  by a constant factor and write to disk.
    1dmatcalc "&read(in.1D) 3.1416 * &write(out.1D)"

* Subtract two 1D files
    1dmatcalc "&read(a.1D) &read(b.1D) - &write(stdout:)"
This page auto-generated on Tue Apr 9 00:02:42 EDT 2024