All AFNI program -help files

This page auto-generated on Tue Dec 11 18:12:32 EST 2018



AFNI program: 1dAstrip
Usage: 1dAstrip < input > output

This very simple program strips non-numeric characters
from a file, so that it can be processed by other AFNI
1d programs.  For example, if your input is
  x=3.6 y=21.6 z=14.2
then your output would be
    3.6   21.6   14.2

* Non-numeric characters are replaced with blanks.
* The letter 'e' is preserved if it is preceeded
  or followed by a numeric character.  This is
  to allow for numbers like '1.2e-3'.
* Numeric characters, for the purpose of this
  program, are defined as the digits '0'..'9',
  and '.', '+', '-'.
* The program is simple and can easily end up leaving
  undesired junk characters in the output.  Sorry.
* This help string is longer than the rest of the
  source code to this program!



AFNI program: 1dBandpass
Usage: 1dBandpass [options] fbot ftop infile

 * infile is an AFNI *.1D file; each column is processed
 * fbot = lowest frequency in the passband, in Hz
          [can be 0 if you want to do a lowpass filter only,]
           but the mean and Nyquist freq are always removed ]
 * ftop = highest frequency in the passband (must be > fbot)
          [if ftop > Nyquist freq, then we have a highpass filter only]
 * You cannot construct a 'notch' filter with this program!
 * Output vectors appear on stdout; redirect as desired
 * Program will fail if fbot and ftop are too close for comfort
 * The actual FFT length used will be printed, and may be larger
   than the input time series length for the sake of efficiency.

Options:
  -dt dd     = set time step to 'dd' sec [default = 1.0]
  -ort f.1D  = Also orthogonalize input to columns in f.1D
               [only one '-ort' option is allowed]
  -nodetrend = Skip the quadratic detrending of the input
  -norm      = Make output time series have L2 norm = 1

Example:
  1deval -num 1000 -expr 'gran(0,1)' > r1000.1D
  1dBandpass 0.025 0.20 r1000.1D  > f1000.1D
  1dfft f1000.1D - | 1dplot -del 0.000977 -stdin -plabel 'Filtered |FFT|'

Goal:
 * Mostly to test the functions in thd_bandpass.c -- RWCox -- May 2009

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dBport
Usage: 1dBport [options]

Creates a set of columns of sines and cosines for the purpose of
bandpassing via regression (e.g., in 3dDeconvolve).  Various option
are given to specify the duration and structure of the time series
to be created.  Results are written to stdout, and usually should be
redirected appropriately (cf. EXAMPLES, infra).  The file produced
could be used with the '-ortvec' option to 3dDeconvolve, for example.

OPTIONS
-------
 -band fbot ftop  = Specify lowest and highest frequencies in the passband.
                    fbot can be 0 if you want to do a highpass filter only;
                    on the other hand, if ftop > Nyquist frequency, then
                    it's a lowpass filter only.
                  ** This 'option' is actually mandatory! (At least once.)
                   * For the un-enlightened, the Nyquist frequency is the
                     highest frequency supported on the given grid, and
                     is equal to 0.5/TR (units are Hz if TR is in s).
                   * The lowest nonzero frequency supported on the grid
                     is equaly to 1/(N*TR), where N=number of time points.
                  ** Multiple -band options can be used, if needed.
                     If the bands overlap, regressors will NOT be duplicated.
                   * That is, '-band 0.01 0.05 -band 0.03 0.08' is the same
                     as using '-band 0.01 0.08'.
                  ** Note that if fbot==0 and ftop>=Nyquist frequency, you
                     get a 'complete' set of trig functions, meaning that
                     using these in regression is effectively a 'no-pass'
                     filter -- probably not what you want!
                  ** It is legitimate to set fbot = ftop.
                  ** The 0 frequency (fbot = 0) component is all 1, of course.
                     But unless you use the '-quad' option, nothing generated
                     herein will deal well with linear-ish or quadratic-ish
                     trends, which fall below the lowest nonzero frequency
                     representable in a full cycle on the grid:
                        f_low = 1 / ( NT * TR )
                     where NT = number of time points.
                  ** See the fourth EXAMPLE to learn how to use 3dDeconvolve
                     to generate a file of polynomials for regression fun.

 -invert          = After computing which frequency indexes correspond to the
                    input band(s), invert the selection -- that is, output
                    all those frequencies NOT selected by the -band option(s).
                    See the fifth EXAMPLE.

 -nozero          } Do NOT generate the 0 frequency (constant) component
   *OR            } when fbot = 0; this has the effect of setting fbot to
 -noconst         } 1/(N*TR), and is essentially a convenient way to say
                    'eliminate all oscillations below the ftop frequency'.

 -quad            = Add regressors for linear and quadratic trends.
                    (These will be the last columns in the output.)

 -input dataset   } One of these options is used to specify the number of
   *OR*           } time points to be created, as in 3dDeconvolve.
 -input1D 1Dfile  } ** '-input' allow catenated datasets, as in 3dDeconvolve.
   *OR*           } ** '-input1D' assumes TR=1 unless you use the '-TR' option.
 -nodata NT [TR]  } ** One of these options is mandatory, to specify the length
                       of the time series file to generate.

 -TR del          = Set the time step to 'del' rather than use the one
                    given in the input dataset (if any).
                   ** If TR is not specified by the -input dataset or by
                      -nodata or by -TR, the program will assume it is 1.0 s.

 -concat rname    = As in 3dDeconvolve, used to specify the list of start
                    indexes for concatenated runs.
                   ** Also as in 3dDeconvolve, if the -input dataset is auto-
                      catenated (by providing a list of more than one dataset),
                      the run start list is automatically generated.  Otherwise,
                      this option is needed if more than one run is involved.

EXAMPLES
--------
 The first example provides basis functions to filter out all frequency
 components from 0 to 0.25 Hz:
   1dBport -nodata 100 1 -band 0 0.25   > highpass.1D

 The second example provides basis functions to filter out all frequency
 components from 0.25 Hz up to the Nyquist freqency:
   1dBport -nodata 100 1 -band 0.25 666 > lowpass.1D

 The third example shows how to examine the results visually, for fun:
   1dBport -nodata 100 1 -band 0.41 0.43 | 1dplot -stdin -thick

 The fourth example shows how to use 3dDeconvolve to generate a file of
 polynomial 'orts', in case you find yourself needing this ability someday
 (e.g., when stranded on a desert isle, with Gilligan, the Skipper, et al.):
   3dDeconvolve -nodata 100 1 -polort 2 -x1D_stop -x1D stdout: | 1dcat stdin: > pol3.1D

 The fifth example shows how to use 1dBport to generate a set of regressors to
 eliminate all frequencies EXCEPT those in the selected range:
   1dBport -nodata 100 1 -band 0.03 0.13 -nozero -invert | 1dplot -stdin
 In this example, the '-nozero' flag is used because the next step will be to
 3dDeconvolve with '-polort 2' and '-ortvec' to get rid of the undesirable stuff.

ETYMOLOGICAL NOTES
------------------
 * The word 'ort' was coined by Andrzej Jesmanowicz, as a shorthand name for
   a timeseries to which you want to 'orthogonalize' your data.
 * 'Ort' actually IS an English word, and means 'a scrap of food left from a meal'.
   As far as I know, its only usage in modern English is in crossword puzzles,
   and in Scrabble.
 * For other meanings of 'ort', see http://en.wikipedia.org/wiki/Ort
 * Do not confuse 'ort' with 'Oort': http://en.wikipedia.org/wiki/Oort_cloud

AUTHOR -- RWCox -- Jan 2012

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dCorrelate
Usage: 1dCorrelate [options] 1Dfile 1Dfile ...
------
 * Each input 1D column is a collection of data points.
 * The correlation coefficient between each column pair is computed, along
   with its confidence interval (via a bias-corrected bootstrap procedure).
 * The minimum sensible column length is 7.
 * At least 2 columns are needed [in 1 or more .1D files].
 * If there are N input columns, there will be N*(N-1)/2 output rows.
 * Output appears on stdout; redirect ('>' or '>>') as needed.
 * Only one correlation method can be used in one run of this program.
 * This program is basically the basterd offspring of program 1ddot.
 * Also see http://en.wikipedia.org/wiki/Confidence_interval

-------
Methods   [actually, only the first letter is needed to choose a method]
-------   [and the case doesn't matter: '-P' and '-p' both = '-Pearson']

 -Pearson  = Pearson correlation                    [the default method]
 -Spearman = Spearman (rank) correlation      [more robust vs. outliers]
 -Quadrant = Quadrant (binarized) correlation  [most robust, but weaker]
 -Ktaub    = Kendall's tau_b 'correlation'    [popular somewhere, maybe]

-------------
Other Options  [these options cannot be abbreviated!]
-------------

 -nboot B  = Set the number of bootstrap replicates to 'B'.
             * The default value of B is 4000.
             * A larger number will give somewhat more accurate
               confidence intervals, at the cost of more CPU time.

 -alpha A  = Set the 2-sided confidence interval width to '100-A' percent.
             * The default value of A is 5, giving the 2.5..97.5% interval.
             * The smallest allowed A is 1 (0.5%..99.5%) and the largest
               allowed value of A is 20 (10%..90%).
             * If you are interested assessing if the 'p-value' of a
               correlation is smaller than 5% (say), then you should use
               '-alpha 10' and see if the confidence interval includes 0.

 -block    = Attempt to allow for serial correlation in the data by doing
   *OR*      variable-length block resampling, rather than completely
 -blk        random resampling as in the usual bootstrap.
             * You should NOT do this unless you believe that serial
               correlation (along each column) is present and significant.
             * Block resampling requires at least 20 data points in each
               input column.  Fewer than 20 will turn off this option.
-----
Notes
-----
* For each pair of columns, the output include the correlation value
  as directly calculated, plus the bias-corrected bootstrap value, and
  the desired (100-A)% confidence interval [also via bootstrap].

* The primary purpose of this program is to provide an easy way to get
  the bootstrap confidence intervals, since people almost always seem to use
  the asymptotic normal theory to decide if a correlation is 'significant',
  and this often seems misleading to me [especially for short columns].

* Bootstrapping confidence intervals for the inverse correlations matrix
  (i.e., partial correlations) would be interesting -- anyone out there
  need this ability?

-------------
Sample output  [command was '1dCorrelate -alpha 10 A2.1D B2.1D']
-------------
# Pearson correlation [n=12 #col=2]
# Name      Name       Value   BiasCorr   5.00%   95.00%  N: 5.00% N:95.00%
# --------  --------  -------- -------- -------- -------- -------- --------
  A2.1D[0]  B2.1D[0]  +0.57254 +0.57225 -0.03826 +0.86306 +0.10265 +0.83353

* Bias correction of the correlation had little effect; this is very common.
  ++ To be clear, the bootstrap bias correction is to allow for potential bias
     in the statistical estimate of correlation when the sample size is small.
  ++ It cannot correct for biases that result from faulty data (or faulty
     assumptions about the data).

* The correlation is NOT significant at this level, since the CI (confidence
  interval) includes 0 in its range.

* For the Pearson method ONLY, the last two columns ('N:', as above) also
  show the widely used asymptotic normal theory confidence interval.  As in
  the example, the bootstrap interval is often (but not always) wider than
  the theoretical interval.

* In the example, the normal theory might indicate that the correlation is
  significant (less than a 5% chance that the CI includes 0), but the
  bootstrap CI shows that is not a reasonable statistical conclusion.
  ++ The principal reason that I wrote this program was to make it easy
     to check if the normal (Gaussian) theory for correlation significance
     testing is reasonable in any given case -- for small samples, it often
     is NOT reasonable!

* Using the same data with the '-S' option gives the table below, again
  indicating that there is no significant correlation between the columns
  (note also the lack of the 'N:' results for Spearman correlation):

# Spearman correlation [n=12 #col=2]
# Name      Name       Value   BiasCorr   5.00%   95.00%
# --------  --------  -------- -------- -------- --------
  A2.1D[0]  B2.1D[0]  +0.46154 +0.42756 -0.23063 +0.86078

-------------
SAMPLE SCRIPT
-------------
This script generates random data and correlates it until it is
statistically significant at some level (default=2%).  Then it
plots the data that looks correlated.  The point is to show what
purely random stuff that appears correlated can look like.
(Like most AFNI scripts, this is written in tcsh, not bash.)

#!/bin/tcsh
set npt = 20
set alp = 2
foreach fred ( `count -dig 1 1 1000` )
  1dcat jrandom1D:${npt},2 > qqq.1D
  set aabb = ( `1dCorrelate -spearman -alpha $alp qqq.1D  | grep qqq.1D | colrm 1 42` )
  set ab = `ccalc -form rint "1000 * $aabb[1] * $aabb[2]"`
  echo $fred $ab
  if( $ab > 1 )then
    1dplot -one -noline -x qqq.1D'[0]' -xaxis -1:1:20:5 -yaxis -1:1:20:5            \
           -DAFNI_1DPLOT_BOXSIZE=0.012                                              \
           -plabel "N=$npt trial#=$fred \alpha=${alp}% => r\in[$aabb[1],$aabb[2]]"  \
           qqq.1D'[1]'
    break
  endif
end
\rm qqq.1D

----------------------------------------------------------------------
*** Written by RWCox (AKA Zhark the Mad Correlator) -- 19 May 2011 ***

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dDW_Grad_o_Mat
  
Simple function to manipulate DW gradient vector files, b-value
files, and b-/g-matrices. Let: g_i be one of Ng spatial gradients
in three dimensions; the g-matrix is G_{ij} = g_i*g_j (i.e., dyad
of gradients, without b-value included); and the DW-scaled
b-matrix is B_{ij} = b*g_i*g_j.

  **NB: please consider using the newer function '1dDW_Grad_o_Mat++'
        instead of this one, as modern thinking means much of the
        defaults (such as averaging reference b0 volumes together
        and functionality here is not really in vogue anymore.
        At some point, the present program will go the way of the
        Silesauridae.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

As of right now, one can input:
  + 3 rows of gradients (as output from dcm2nii, for example);
  + 3 columns of gradients;
  + 6 columns of g- or b-matrices, in `diagonal-first' order:
         Bxx, Byy, Bzz, Bxy, Bxz, Byz,
    which is used in 3dDWItoDT, for example;
  + 6 columns of g- or b-matrices, in `row-first' order:
         Bxx, 2*Bxy, 2*Bxz, Byy, 2*Byz, Bzz, 
    which is output by TORTOISE, for example;

  + when specifying input file, one can use the brackets '{ }'
    in order to specify a subset of rows to keep (NB: probably
    can't use this grad-filter when reading in row-data right
    now).
During processing, one can:
  + flip the sign of any of the x-, y- or z-components, which
    may be necessary to do to make the scanned data and tracking
    work happily together;
  + filter out all `zero' rows of recorded reference images;
  
One can then output:
  + 3 columns of gradients;
  + 6 columns of g- or b-matrices, in 'diagonal-first' order;
  + 6 columns of g- or b-matrices, in 'row-first' order;
  + as well as including a column of b-values (such as used in;
    DTI-Studio);
  + as well as including a row of zeros at the top;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

 + RUNNING:
    1dDW_Grad_o_Mat                                                 \
         { -in_grad_cols  | -in_grad_cols_bwt |                     \
           -in_gmatT_cols | -in_gmatA_cols |                        \
           -in_bmatT_cols | -in_gmatA_cols |                        \
           -in_grad_rows }  INFILE                                  \
         { -flip_x | -flip_y | -flip_z }                            \
         { -keep_b0s } { -put_zeros_top } { -out_bval_col }         \
         { -bref_mean_top }                                         \
         { -in_bvals BVAL_IN }                                      \
         { -bmax_ref THRESH }                                       \
         { -out_grad_cols  | -out_grad_cols_bwt |                   \
           -out_gmatT_cols | -out_gmatA_cols |                      \
           -out_bmatT_cols | -out_gmatA_cols |                      \
           -out_grad_rows }  OUTFILE                                \
         { -out_bval_row_sep | -out_bval_col_sep BB }               

    where:
        (one of the following six formats of input must be given):
    -in_grad_rows  INFILE :input file of 3 rows of gradients (e.g., dcm2nii-
                           format output).
    -in_grad_cols  INFILE :input file of 3 columns of gradients.  
 -in_grad_cols_bwt INFILE :input file of 3 columns of gradients, each
                           weighted by the b-value.
    -in_gmatA_cols INFILE :input file of 6 columns of g-matrix in 'A(FNI)'
                           `diagonal first'-format. (See above.)
    -in_gmatT_cols INFILE :input file of 6 columns of g-matr in 'T(ORTOISE)'
                           `row first'-format. (See above.)
    -in_bmatA_cols INFILE :input file of 6 columns of b-matrix in 'A(FNI)'
                           `diagonal first'-format. (See above.)
    -in_bmatT_cols INFILE :input file of 6 columns of b-matr in 'T(ORTOISE)'
                           `row first'-format. (See above.)
        (one of the following five formats of output must be given):

   -out_grad_cols OUTFILE :output file of 3 columns of gradients.  
 -out_grad_cols_bwt OUTFILE :output file of 3 columns of gradients, each  
                           weighted by the b-value.
  -out_gmatA_cols OUTFILE :output file of 6 columns of g-matrix in 'A(FNI)'
                           `diagonal first'-format. (See above.)
  -out_gmatT_cols OUTFILE :output file of 6 cols of g-matr in 'T(ORTOISE)'
                           `row first'-format. (See above.)
  -out_bmatA_cols OUTFILE :output file of 6 columns of b-matrix in 'A(FNI)'
                           `diagonal first'-format. (See above.)
  -out_bmatT_cols OUTFILE :output file of 6 cols of b-matr in 'T(ORTOISE)'
                          `row first'-format. (See above.)
  -out_grad_rows  OUTFILE :output file of 3 rows of gradients.

        (and any of the following options may be used):
    -proc_dset    DSET    :input a dataset DSET of X 'b=0' and Y DWI bricks,
                           matching the X zero- and Y nonzero-gradient 
                           entries in the INFILE. The 'processing' will:
                                  1) extract all the 'b=0' bricks,
                                  2) average them,
                                  3) store the result in the zeroth brick of
                                     the output PREFIX data set, and
                                  4) place the DWIs (kept in their original
                                     order) as the next Y bricks of PREFIX.
                           This option cannot be used with '-keep_b0s'.
                           The output set has Y+1 bricks.  The option is
                           probably mostly useful only if X>1.
    -pref_dset    PREFIX  :output dataset filename prefix (required and iff
                           using '-proc_dset', above).
    -dwi_comp_fac N_REP   :option for averaging DWI bricks in DSET that have
                           been acquired with exactly N_REP repeated sets of
                           gradients. *You* the user must know how many
                           repetitions have been performed (this program
                           will perform a simplistic gradient comparison
                           using dot products to flag possible errors, but
                           this is by no means bulletproof.  Use wisely.

    -flip_x               :change sign of first column of gradients
    -flip_y               :change sign of second column of gradients
    -flip_z               :change sign of third column of gradients

    -bref_mean_top        :when averaging the reference X 'b0' values (which
                           is default behavior), have the mean of the X 
                           values be represented in the top row; default 
                           behavior is to have nothing representing the b0
                           information in the top row (for historical
                           functionality reasons).  NB: if your reference
                           'b0' actually has b>0, you might not want to 
                           average the b0 refs together, because their
                           images could have differing contrast if the
                           same reference vector wasn't used for each.
    -keep_b0s             :default function is to get rid of all reference
                           image, but this option acts as switch to keep
                           them.
    -put_zeros_top        :whatever the output format is, add a row at the
                           top with all zeros.
    -bmax_ref THRESH      :THRESH is a scalar number below which b-values
                           (in BVAL_IN) are considered `zero' or reference.
                           Sometimes, for the reference images, the scanner
                           has a value like b=5 s/mm^2, instead of strictly
                           b=0 strictly. One can still flag such values as
                           being associated with a reference image and
                           trim it out, using, for the example case here, 
                           '-bmax_ref 5.1'.

    -in_bvals BVAL_IN     :BVAL_IN is a file of b-values, such as the 'bval'
                           file generated by dcm2nii.
    -out_bval_col         :switch to put a column of the bvalues as the
                           first column in the output data.
    -out_bval_row_sep BB  :output a file BB of bvalues in a single row.
    -out_bval_col_sep BB  :output a file BB of bvalues in a single row.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  If you use this program, please reference the introductory/description
  paper for the FATCAT toolbox:
        Taylor PA, Saad ZS (2013).  FATCAT: (An Efficient) Functional
        And Tractographic Connectivity Analysis Toolbox. Brain 
        Connectivity 3(5):523-535.
____________________________________________________________________________



AFNI program: 1dDW_Grad_o_Mat++
  
  Simple function to manipulate DW gradient vector files, b-value
  files, and b- or g-matrices. Let: g_i be one of Ng spatial gradients
  in three dimensions; |g_i| = 1, and the g-matrix is G_{ij} = g_i * g_j
  (i.e., dyad of gradients, without b-value included); and the DW-scaled
  b-matrix is B_{ij} = b * g_i * g_j.

  **This new version of the function** will replace the original/older 
  version (1dDW_Grad_o_Mat).  The new has similar functionality, but
  improved defaults:
     + it does not average b=0 volumes together by default;
     + it does not remove top b=0 line from top by default;
     + output has same scaling as input by default (i.e., by bval or not);
       and a switch is used to turn *off* scaling, for unit magn output
       (which is cleverly concealed under the name '-unit_mag_out').

  Wherefore, you ask?  Well, times change, and people change.
  The above functionality is still available, but each just requires
  selection with command line switches.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

As of right now, one can input:
  + 3 rows of gradients (as output from dcm2nii, for example);
  + 3 columns of gradients;
  + 6 columns of g- or b-matrices, in `diagonal-first' (-> matA) order:
         Bxx, Byy, Bzz, Bxy, Bxz, Byz,
    which is used in 3dDWItoDT, for example;
  + 6 columns of g- or b-matrices, in `row-first' (-> matT) order:
         Bxx, 2*Bxy, 2*Bxz, Byy, 2*Byz, Bzz, 
    which is output by TORTOISE, for example;

  + when specifying input file, one can use the brackets '{ }'
    in order to specify a subset of rows to keep (NB: probably
    can't use this grad-filter when reading in row-data right
    now).
During processing, one can:
  + flip the sign of any of the x-, y- or z-components, which
    may be necessary to do to make the scanned data and tracking
    work happily together;
  + filter out all `zero' rows of recorded reference images, 
    THOUGH this is not really recommended.
  
One can then output:
  + 3 columns of gradients;
  + 6 columns of g- or b-matrices, in 'diagonal-first' order;
  + 6 columns of g- or b-matrices, in 'row-first' order;
  + as well as including a column of b-values (such as used in, e.g.,
    DSI-Studio);
  + as well as explicitly include a row of zeros at the top;

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

 + RUNNING:
    1dDW_Grad_o_Mat++                                               \
         { -in_row_vec  | -in_col_vec  |                            \
           -in_col_matA | -in_col_matT }  INFILE                    \
         { -flip_x | -flip_y | -flip_z | -no_flip }                 \
         { -out_row_vec  | -out_col_vec  |                          \
           -out_col_matA | -out_col_matT }  OUTFILE                 \
         { -in_bvals BVAL_FILE }                                    \
         { -out_col_bval }                                          \
         { -out_row_bval_sep BB | -out_col_bval_sep BB }            \
         { -unit_mag_out }                                          \
         { -bref_mean_top }                                         \
         { -bmax_ref THRESH }                                       \
         { -put_zeros_top   }                                       \
    where:
        (one of the following formats of input must be given):
    -in_row_vec   INFILE  :input file of 3 rows of gradients (e.g.,
                           dcm2nii-format output).
    -in_col_vec   INFILE  :input file of 3 columns of gradients.  
    -in_col_matA  INFILE  :input file of 6 columns of b- or g-matrix in
                           'A(FNI)' `diagonal first'-format. (See above.)
    -in_col_matT  INFILE  :input file of 6 columns of b- or g-matrix in 
                           'T(ORTOISE)' `row first'-format. (See above.)

        (one of the following formats of output must be given):
    -out_row_vec  OUTFILE :output file of 3 rows of gradients.
    -out_col_vec  OUTFILE :output file of 3 columns of gradients.
    -out_col_matA OUTFILE :output file of 6 columns of b- or g-matrix in
                           'A(FNI)' `diagonal first'-format. (See above.)
    -out_col_matT OUTFILE :output file of 6 cols of b- or g-matrix in
                           'T(ORTOISE)' `row first'-format. (See above.)

        (and any of the following options may be used):

    -in_bvals  BVAL_FILE  :BVAL_FILE is a file of b-values, either a single
                           row (such as the 'bval' file generated by
                           dcm2nii) or a single column of numbers.  Must
                           have the same number of entries as the number
                            of grad vectors or matrices.
    -out_col_bval         :switch to put a column of the bvalues as the
                           first column in the output data.
    -out_row_bval_sep BB  :output a file BB of bvalues in a single row.
    -out_col_bval_sep BB  :output a file BB of bvalues in a single column.

    -unit_mag_out         :switch so that each vector/matrix from the INFILE
                           is scaled to either unit or zero magnitude.
                           (Supplementary input bvalues would be ignored
                           in the output matrix/vector, but not in the
                           output bvalues themselves.)  The default
                           behavior of the function is to leave the output
                           scaled however it is input (while also applying
                           any input BVAL_FILE). 

    -flip_x               :change sign of first column of gradients (or of
                           the x-component parts of the matrix)
    -flip_y               :change sign of second column of gradients (or of
                           the y-component parts of the matrix)
    -flip_z               :change sign of third column of gradients (or of
                           the z-component parts of the matrix)
    -no_flip              :don't change any gradient/matrix signs.  This
                           is an extraneous switch, as the default is to
                           not flip any signs (this is mainly used for
                           some scripting convenience

    -check_abs_min VVV    :By default, this program checks input matrix 
                           formats for consistency (having positive semi-
                           definite diagonal matrix elements).  It will fail
                           if those don't occur. However, sometimes there is
                           just a tiny values <0, like a rounding error; 
                           you can specify to push throughfor negative 
                           diagonal elements with magnitude <VVV, with those
                           values getting replaced by zero.  Be judicious
                           with this power! (E.g., maybe VVV ~ 0.0001 might
                           be OK... but if you get looots of negatives, then
                           you really, really need to check your data for
                           badness.

       (and the follow options are probably mainly extraneous, nowadays)
    -bref_mean_top        :when averaging the reference X 'b0' values (the
                           default behavior), have the mean of the X 
                           values be represented in the top row; default 
                           behavior is to have nothing representing the b0
                           information in the top row (for historical
                           functionality reasons).  NB: if your reference
                           'b0' actually has b>0, you might not want to 
                           average the b0 refs together, because their
                           images could have differing contrast if the
                           same reference vector wasn't used for each.
    -put_zeros_top        :whatever the output format is, add a row at the
                           top with all zeros.
    -bmax_ref THRESH      :THRESH is a scalar number below which b-values
                           (in BVAL_IN) are considered `zero' or reference.
                           Sometimes, for the reference images, the scanner
                           has a value like b=5 s/mm^2, instead of strictly
                           b=0 strictly. One can still flag such values as
                           being associated with a reference image and
                           trim it out, using, for the example case here, 
                           '-bmax_ref 5.1'.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  EXAMPLES

   # An example of type-conversion from a TORTOISE-style matrix to column
   # gradients (if the matT file has bweights, so will the grad values):

   1dDW_Grad_o_Mat++                                    \
      -in_col_matT   BMTXT_TORT.txt                     \
      -out_col_vec   GRAD.dat                           


   # An example of filtering (note the different styles of parentheses
   # for the column- and row-type files) and type-conversion (to an
   # AFNI-style matrix that should have the bvalue weights afterwards):

   1dDW_Grad_o_Mat++                                    \
      -in_col_vec    GRADS_col.dat'{0..10,12..30}'      \
      -in_bvals      BVALS_row.dat'[0..10,12..30]'      \
      -out_col_matA  FILT_matA.dat                      


   # An example of filtering *without* type-conversion.  Here, note
   # the '-unit_mag_out' flag is used so that the output row-vec does
   # not carry the bvalue weight with it;  it does not affect the output
   # bval file.  As Levon might say, the '-unit_mag_out' option acts to
   #   'Take a load off bvecs, take a load for free;
   #    Take a load off bvecs, and you put the load right on bvals only.'
   # This example might be useful for working with dcm2nii* output:

   1dDW_Grad_o_Mat++                                      \
      -in_row_vec        ap.bvec'[0..10,12..30]'          \
      -in_bvals          ap.bval'[0..10,12..30]'          \
      -out_row_vec       FILT_ap.bvec                     \
      -out_row_bval_sep  FILT_ap.bval                     \
      -unit_mag_out

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *


  If you use this program, please reference the introductory/description
  paper for the FATCAT toolbox:
        Taylor PA, Saad ZS (2013).  FATCAT: (An Efficient) Functional
        And Tractographic Connectivity Analysis Toolbox. Brain 
        Connectivity 3(5):523-535.
___________________________________________________________________________



AFNI program: 1dFlagMotion
Usage: 1dFlagMotion [options] MotionParamsFile 

   Produces an list of time points that have more than a 
   user specified amount of motion relative to the previous 
   time point. 
 Options:
  -MaxTrans    maximum translation allowed in any direction 
                 [defaults to 1.5mm]
  -MaxRot      maximum rotation allowed in any direction 
                  [defaults to 1.25 degrees]

** The input file must have EXACTLY 6 columns of input, in the order:
     roll pitch yaw delta-SI delta-LR delta-AP
   (angles in degrees first, then translations in mm)

** The program does NOT accept column '[...]' selectors on the input
   file name, or comments in the file itself.  As a palliative, if the
   input file name is '-', then the input numbers are read from stdin,
   so you could do something like the following:
     1dcat mfile.1D'[1..6]' | 1dFlagMotion -
   e.g., to work with the output from 3dvolreg's '-dfile' option
   (where the first column is just the time index).

** The output is in a 1D format, with comments on '#' comment lines,
   and the list of points exceeding the motion bounds listed being
   intercalated on normal (non-comment) lines.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dMarry
Usage: 1dMarry [options] file1 file2 ...

  Joins together 2 (or more) ragged-right .1D files, for use with
    3dDeconvolve -stim_times_AM2.
 **_OR_**
  Breaks up 1 married file into 2 (or more) single-valued files.

OPTIONS:
=======
 -sep abc  == Use the first character (e.g., 'a') as the separator
              between values 1 and 2, the second character (e.g., 'b')
              as the separator between values 2 and 3, etc.
            * These characters CANNOT be a blank, a tab, a digit,
              or a non-printable control character!
            * Default separator string is '*,' which will result
              in output similar to '3*4,5,6'

 -divorce  == Instead of marrying the files, assume that file1
              is already a married file: split time*value*value... tuples
              into separate files, and name them in the pattern
              'file2_A.1D' 'file2_B.1D' et cetera.

If not divorcing, the 'married' file is written to stdout, and
probably should be captured using a redirection such as '>'.

NOTES:
=====
* You cannot use column [...] or row {...} selectors on
    ragged-right .1D files, so don't even think about trying!
* The maximum number of values that can be married is 26.
    (No polygamy or polyandry jokes here, please.)
* For debugging purposes, with '-divorce', if 'file2' is '-',
    then all the divorcees are written directly to stdout.

-- RWCox -- written hastily in March 2007 -- hope I don't repent
         -- modified to deal with multiple marriages -- December 2008

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dNLfit

Program to fit a model to a vector of data.  The model is given by a
symbolic expression, with parameters to be estimated.

Usage: 1dNLfit OPTIONS

Options: [all but '-meth' are actually mandatory]
--------

 -expr eee   = The expression for the fit.  It must contain one symbol from
               'a' to 'z' which is marked as the independent variable by
               option '-indvar', and at least one more symbol which is
               a parameter to be estimated.
               ++ Expressions use the same syntax as 3dcalc, ccalc, and 1deval.
               ++ Note: expressions and symbols are not case sensitive.

 -indvar c d = Indicates which variable in '-expr' is the independent
               variable.  All other symbols are parameters, which are
               either fixed (constants) or variables to be estimated.
               ++ Then, read the values of the independent variable from
                  1D file 'd' (only the first column will be used).
               ++ If the independent variable has a constant step size,
                  you can input it via with 'd' replaced by a string like
                    '1D: 100%0:2.1'
                  which creates an array with 100 value, starting at 0,
                  then adding 2.1 for each step:
                    0 2.1 4.2 6.3 8.4 ...

 -param ppp  = Set fixed value or estimating range for a particular
               symbol.
               ++ For a fixed value, 'ppp' takes the form 'a=3.14', where the
                  first letter is the symbol name, which must be followed by
                  an '=', then followed by a constant expression.  This
                  expression can be symbolic, as in 'a=cbrt(3)'.
               ++ For a parameter to be estimated, 'ppp' takes the form of
                  two constant expressions separated by a ':', as in
                  'q=-sqrt(2):sqrt(2)'.
               ++ All symbols in '-expr' must have a corresponding '-param'
                  option, EXCEPT for the '-indvar' symbol (which will be set
                  by its data file).

 -depdata v  = Read the values of the dependent variable (to be fitted to
               '-expr') from 1D file 'v'.
               ++ File 'v' must have the same number of rows as file 'd'
                  from the '-indvar' option!
               ++ File 'v' can have more than one column; each will be fitted
                  separately to the expression.

 -meth m     = Set the method for fitting: '1' for L1, '2' for L2.
               (The default method is L2, which is usually better.)

Example:
--------
Create a sin wave corrupted by logistic noise, to file ss.1D.
Create a cos wave similarly, to file cc.1D.
Put these files together into a 2 column file sc.1D.
Fit both columns to a 3 parameter model and write the fits to file ff.1D.
Plot the data and the fit together, for fun and profit(?).

1deval -expr 'sin(2*x)+lran(0.3)' -del 0.1 -num 100 > ss.1D
1deval -expr 'cos(2*x)+lran(0.3)' -del 0.1 -num 100 > cc.1D
1dcat ss.1D cc.1D > sc.1D ; \rm ss.1D cc.1D
1dNLfit -depdata sc.1D -indvar x '1D: 100%0:0.1' -expr 'a*sin(b*x)+c*cos(b*x)' \
        -param a=-2:2 -param b=1:3 -param c=-2:2  > ff.1D
1dplot -one -del 0.1 -ynames sin:data cos:data sin:fit cos:fit - sc.1D ff.1D

Notes:
------
* PLOT YOUR RESULTS!  There is no guarantee that you'll get a good fit.

* This program is not particularly efficient, so using it on a large
  scale (e.g., for lots of columns, or in a shell loop) will be slow.

* The results (fitted time series models) are written to stdout,
  and should be saved by '>' redirection (as in the example).
  The first few lines of the output from the example are:
   # 1dNLfit output (meth=L2)
   # expr = a*sin(b*x)+c*cos(b*x)
   # Fitted parameters:
   # A =      1.0828     0.12786
   # B =      1.9681      2.0208
   # C =     0.16905      1.0102
   #     ----------- -----------
             0.16905      1.0102
             0.37753      1.0153
             0.57142     0.97907

* Coded by Zhark the Well-Fitted - during Snowzilla 2016.




AFNI program: 1dRplot

Usage:
------ 
 1dRplot is a program for plotting a 1D file
Options in alphabetical order:
------------------------------

   -TR TR: Sampling period, in seconds. 

   -addavg:  Add line at average of column

   -col.color COL1 [COL2 ...]: Colors for each column in -input.
                             COL? are integers for now.

   -col.grp 1Dfile or Rexp: integer labels defining column grouping

   -col.line.type LT1 [LT2 ...]: Line type for each column in -input.
                             LT? are integers for now.

   -col.name NAME1 [NAME2 ...]: Name of each column in -input. 
        Special flags:
             VOLREG: --> 'Roll Pitch Yaw I-S R-L A-P'

   -col.name.show : Show names of column in -input.

   -col.nozeros:  Do not plot all zeros columns

   -col.plot.char CHAR1 [CHAR2 ...] : Symbols for each column in -input.
                             CHAR? are integers (usually 0-127), or
                             characters + - I etc.
      See the following link for what CHAR? values you can use:
 http://stat.ethz.ch/R-manual/R-patched/library/graphics/html/points.html

   -col.plot.type PLOT_TYPE: Column plot type. 
                          'l' for line, 'p' for points, 'b' for both

   -col.text.lym LYM_TEXT: Text to be placed at left Y margin.
                         You need one string per column.
         Special Flags: You can also use COL.NAME to use column
                         names for the margin text, or you can use
                         COL.IND to use the colum's index in the file

   -col.text.rym RYM_TEXT: Text to be placed at right Y margin.
                         You need one string per column.
        See also Special Flags section under -col.text.lym

   -col.ystack:  Scale each column and offset it based on its
                column index. This is useful for stacking
                a large number of columns on one plot.
               It is only carried out when graphing more
               than one series with the -one option.

   -grid.show : Show grid.

   -grp.label GROUP1 [GROUP2 ...]: Labels assigned to each group.
                          Default is no labeling

   -help: this help message

   -i 1D_INPUT: file to plot. This field can have multiple
                  formats. See Data Strings section below.
              1dRplot will automatically detect certain
              1D files ouput by some programs such as 3dhistog
              or 3ddot and adjust parameters accordingly.

   -input 1D_INPUT: Same as -i

   -input_delta 1D_INPUT: file containing value for error bars

   -input_type 1D_TYPE: Type of data in 1D file.
             Choose from 'VOLREG', or 'XMAT'

   -leg.fontsize : fontsize for legend text.

   -leg.line.color : Color to use for items in legend.
              Default is taken from column line color.

   -leg.line.type : Line type to use for items in legend.
              Default is taken from column line types.
              If you want no line, set -leg.line.type = 0

   -leg.names : Names to use for items in legend.
              Default is taken from column names.

   -leg.ncol : Number of columns in legend.

   -leg.plot.char : plot characters to use for items in legend.
              Default is taken from column plot character (-col.plot.char).

   -leg.position : Legend position. Choose from:
                 bottomright, bottom, bottomleft
                 left, topleft, top, topright, right,
                 and center

   -leg.show : Show legend.

   -load.Rdat RDAT: load data list from save.Rdat for reproducing plot.
                  Note that you cannot override the settings in RDAT,
                  unless you run in the interactive R mode. For example,
                  say you have dice.Rdat saved from a previous command
                  and you want to change P$nodisp to TRUE:
               load('dice.Rdat'); P$nodisp <- TRUE; plot.1D.eng(P)

   -mat:  Display as matrix

   -matplot:  Display as matrix

   -msg.trace: Output trace information along with errors and notices

   -multi:  Put columns in separate graphs

   -multiplot:  Put columns in separate graphs

   -nozeros:  Do not plot all zeros time series

   -one:  Put all columns on one graph

   -oneplot:  Put all columns on one graph

   -prefix PREFIX: Output prefix. See also -save. 

   -row.name NAME1 [NAME2 ...]: Name of each row in -input. 
        For the moment, this is only used with -matplot

   -rowcol.name NAME1 [NAME2 ...]: Names of rows, same as name of columns.
        For the moment, this is only used with -matplot.

   -run_examples: Run all examples, one after the other.

   -save PREFIX: Save plot and quit
                    No need for -prefix with this option

   -save.Rdat : Save data list for reproducing plot in R.
              You need to specify -prefix or -save
              along with this option to set the prefix.
              See also -load.Rdat

   -save.size width height: Save figure size in pixels
                    Default is 2000 2000

   -show_allowed_options: list of allowed options

   -title TITLE: Graph title. File name is used by default.
               Use NONE to be sure no title is used.

   -verb VERB: VERB is an integer specifying verbosity level.
             0 for quiet (Default). 1 or more: talkative.

   -x 1D_INPUT: x axis. You can also use the string 'ENUM'
              to indicate that the x axis should go from
              1 to N, the number of samples in -input

   -xax.label XLABEL: Label of X axis 

   -xax.lim MIN MAX [STEP]: Range of X axis, STEP is optional

   -xax.tic.text XTTEXT: X tics text

   -yax.label YLABEL: Label of Y axis

   -yax.lim MIN MAX [STEP]: Range of X axis, STEP is optional

   -yax.tic.text YTTEXT: Y tics text 

   -zeros:  Do  plot all zeros time series


Data Strings:
-------------
You can specify input matrices and vectors in a variety of
ways. The simplest is by specifying a .1D file with all 
the trimmings of column and row selectors. You can also
specify a string that gets evaluated on the fly. 
For example: '1D: 1 4 8' evaluates to a vector of values 1 4 and 8.
Also, you can use R expressions such as: 'R: seq(0,10,3)'   


To download demo data from AFNI's website run this command:
-----------------------------------------------------------
curl -o demo.X.xmat.1D afni.nimh.nih.gov/pub/dist/edu/data/samples/X.xmat.1D
curl -o demo.motion.1D afni.nimh.nih.gov/pub/dist/edu/data/samples/motion.1D


Example 1 --- :
-------------------------------- 
1dRplot -input demo.X.xmat.1D'[5..10]'



Example 2 --- :
-------------------------------- 
1dRplot  -input demo.X.xmat.1D'[5..10]' \
         -input_type XMAT



Example 3 --- :
-------------------------------- 
1dRplot  -input demo.motion.1D \
         -input_type VOLREG



Example 4 --- :
-------------------------------- 
1dRplot -input 'R:plot.1D.testmat(100, 10)'



Example 5 --- :
-------------------------------- 
1dRplot  -input 'R:plot.1D.testmat(100, 5)' \
         -one 



Example 6 --- :
-------------------------------- 
1dRplot -input 'R:plot.1D.testmat(100, 10)' \
         -one \
         -col.ystack



Example 7 --- :
-------------------------------- 
1dRplot -input 'R:plot.1D.testmat(100, 10)' \
         -one \
         -col.ystack \
         -col.grp '1D:1 1 1 2 2 2 3 3 3 3'  \
         -grp.label slow medium fast \
         -prefix ta.jpg \
         -yax.lim 0 18 \
         -leg.show \
         -leg.position top 



Example 8 --- :
-------------------------------- 
1dRplot -input 'R:plot.1D.testmat(100, 10)' \
         -one \
         -col.ystack \
         -col.grp '1D:1 1 1 2 2 2 3 3 3 3'  \
         -grp.label slow medium fast \
         -prefix tb.jpg \
         -yax.lim 0 18 \
         -leg.show \
         -leg.position top \
         -nozeros \
         -addavg 



Example 9 --- :
-------------------------------- 
1dRplot -input 'R:plot.1D.testmat(100, 10)' \
         -one \
         -col.ystack \
         -col.grp '1D:1 1 1 2 2 2 3 3 3 3'  \
         -grp.label slow medium fast \
         -prefix tb.jpg \
         -yax.lim 0 18 \
         -leg.show \
         -leg.position top \
         -nozeros \
         -addavg \
         -col.text.lym Tutti mi chiedono tutti mi vogliono \
                       Donne ragazzi vecchi fanciulle \
         -col.text.rym "R:paste('Col',seq(1,10), sep='')" 



Example 10 --- :
-------------------------------- 
1dRplot  -input 'R:plot.1D.testmat(100, 2)' \
         -one \
         -col.plot.char 2 \
         -col.plot.type p  



Example 11 --- :
-------------------------------- 
1dRplot  -input 'R:plot.1D.testmat(100, 2)' \
         -one \
         -col.line.type 3 \
         -col.plot.type l 



Example 12 --- :
-------------------------------- 
1dRplot  -input 'R:plot.1D.testmat(100, 2)' \
         -one \
         -col.plot.char 2 \
         -col.line.type 3 \
         -col.plot.type b 



Example 13 --- :
-------------------------------- 
1dRplot  -input 'R:plot.1D.testmat(100, 2)' \
         -one \
         -col.plot.char 2 5\
         -col.line.type 3 4\
         -col.plot.type b \
         -TR 2 



Example 14 --- :
-------------------------------- 
1dRplot  -input 'R:plot.1D.testmat(100, 2)' \
         -one -col.plot.char 2 -col.line.type 3 \
         -col.plot.type b -TR 2 \
         -yax.tic.text 'numa numa numa numaei' \
         -xax.tic.text 'Alo'  'Salut' 'sunt eu' 'un haiduc'






AFNI program: 1dSEM
Usage: 1dSEM [options] -theta 1dfile -C 1dfile -psi 1dfile -DF nn.n
Computes path coefficients for connection matrix in Structural Equation
    Modeling (SEM)
 The program takes as input :
    1. A 1D file with an initial representation of the connection matrix
       with a 1 for each interaction component to be modeled and a 0 if
       if it is not to be modeled. This matrix should be PxP rows and column
    2. A 1D file of the C, correlation matrix, also with dimensions PxP
    3. A 1D file of the residual variance vector, psi
    4. The degrees of freedom, DF

    Output is printed to the terminal and may be redirected to a 1D file
    The path coefficient matrix is printed for each matrix computed
 Options:
   -theta file.1D = connection matrix 1D file with initial representation
   -C file.1D = correlation matrix 1D file
   -psi file.1D = residual variance vector 1D file
   -DF nn.n = degrees of freedom
   -max_iter n = maximum number of iterations for convergence (Default=10000).
    Values can range from 1 to any positive integer less than 10000.
   -nrand n = number of random trials before optimization (Default = 100)
   -limits m.mmm n.nnn = lower and upper limits for connection coefficients
    (Default = -1.0 to 1.0)
   -calccost = no modeling at all, just calculate the cost function for the
    coefficients as given in the theta file. This may be useful for verifying
    published results
   -verbose nnnnn = print info every nnnnn steps

 Model search options:
 Look for best model. The initial connection matrix file must follow these
   specifications. Each entry must be 0 for entries excluded from the model,
   1 for each required entry in the minimum model, 2 for each possible path
   to try.
   -tree_growth or 
   -model_search = search for best model by growing a model for one additional
    coefficient from the previous model for n-1 coefficients. If the initial
    theta matrix has no required coefficients, the initial model will grow from
    the best model for a single coefficient
   -max_paths n = maximum number of paths to include (Default = 1000)
   -stop_cost n.nnn = stop searching for paths when cost function is below
    this value (Default = 0.1)
   -forest_growth or 
   -grow_all = search over all possible models by comparing models at
    incrementally increasing number of path coefficients. This
    algorithm searches all possible combinations; for the number of coeffs
    this method can be exceptionally slow, especially as the number of
    coefficients gets larger, for example at n>=9.
   -leafpicker = relevant only for forest growth searches. Expands the search
    optimization to look at multiple paths to avoid local minimum. This method
    is the default technique for tree growth and standard coefficient searches
 This program uses a Powell optimization algorithm to find the connection
   coefficients for any particular model.

 References:
   Powell, MJD, "The NEWUOA software for unconstrained optimization without
    derivatives", Technical report DAMTP 2004/NA08, Cambridge University
    Numerical Analysis Group -- http://www.damtp.cam.ac.uk/user/na/reports.html

   Bullmore, ET, Horwitz, B, Honey, GD, Brammer, MJ, Williams, SCR, Sharma, T,
    How Good is Good Enough in Path Analysis of fMRI Data?
    NeuroImage 11, 289-301 (2000)

   Stein, JL, et al., A validated network of effective amygdala connectivity,
    NeuroImage (2007), doi:10.1016/j.neuroimage.2007.03.022

 The initial representation in the theta file is non-zero for each element
   to be modeled. The 1D file can have leading columns for labels that will
   be used in the output. Label rows must be commented with the # symbol
 If using any of the model search options, the theta file should have a '1' for
   each required coefficient, '0' for each excluded coefficient, '2' for an
   optional coefficient. Excluded coefficients are not modeled. Required
   coefficients are included in every computed model.

 N.B. - Connection directionality in the path connection matrices is from 
   column to row of the output connection coefficient matrices.

   Be very careful when interpreting those path coefficients.
   First of all, they are not correlation coefficients. Suppose we have a
   network with a path connecting from region A to region B. The meaning
   of the coefficient theta (e.g., 0.81) is this: if region A increases by 
   one standard deviation from its mean, region B would be expected to increase
   by 0.81 its own standard deviations from its own mean while holding all other
   relevant regional connections constant. With a path coefficient of -0.16, 
   when region A increases by one standard deviation from its mean, region B 
   would be expected to decrease by 0.16 its own standard deviations from its
   own mean while holding all other relevant regional connections constant.

   So theoretically speaking the range of the path coefficients can be anything,
   but most of the time they range from -1 to 1. To save running time, the
   default values for -limits are set with -1 and 1, but if the result hits
   the boundary, increase them and re-run the analysis.

 Examples:
   To confirm a specific model:
    1dSEM -theta inittheta.1D -C SEMCorr.1D -psi SEMvar.1D -DF 30
   To search models by growing from the best single coefficient model
     up to 12 coefficients
    1dSEM -theta testthetas_ms.1D -C testcorr.1D -psi testpsi.1D \ 
    -limits -2 2 -nrand 100 -DF 30 -model_search -max_paths 12
   To search all possible models up to 8 coefficients:
    1dSEM -theta testthetas_ms.1D -C testcorr.1D -psi testpsi.1D \ 
    -nrand 10 -DF 30 -stop_cost 0.1 -grow_all -max_paths 8 | & tee testgrow.txt

   For more information, see https://afni.nimh.nih.gov/sscc/gangc/PathAna.html
    and our HBM 2007 poster at
   https://afni.nimh.nih.gov/sscc/posters/file.2007-06-07.0771819246
 If you find this program useful, please cite:
   G Chen, DR Glen, JL Stein, AS Meyer-Lindenberg, ZS Saad, RW Cox,
   Model Validation and Automated Search in FMRI Path Analysis:
   A Fast Open-Source Tool for Structural Equation Modeling,
   Human Brain Mapping Conference, 2007




AFNI program: 1dTsort
Usage: 1dTsort [options] file.1D
Sorts each column of the input 1D file and writes result to stdout.

Options
-------
 -inc     = sort into increasing order [default]
 -dec     = sort into decreasing order
 -flip    = transpose the file before OUTPUT
            * the INPUT can be transposed using file.1D\'
            * thus, to sort each ROW, do something like
               1dTsort -flip file.1D\' > sfile.1D
 -col j   = sort only on column #j (counting starts at 0),
            and carry the rest of the columns with it.
 -imode   = typecast all values to integers, return the mode in
            the input then exit. No sorting results are returned.

N.B.: Data will be read from standard input if the filename IS stdin,
      and will also be row/column transposed if the filename is stdin\'
      For example:
        1deval -num 100 -expr 'uran(1)' | 1dTsort stdin | 1dplot stdin


++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dUpsample
Program 1dUpsample:
Upsamples a 1D time series (along the column direction)
to a finer time grid.
Usage:  1dUpsample [options] n fred.1D > ethel.1D

Where 'n' is the upsample factor (integer from 2..32)

NOTES:
------
* Interpolation is done with 7th order polynomials.
   (Why 7? It's a nice number, and the code already existed.)
* The only option is '-1' or '-one', to use 1st order
   polynomials instead (i.e., linear interpolation).
* Output is written to stdout.
* If you want to interpolate along the row direction,
   transpose before input, then transpose the output.
* Example:
   1dUpsample 5 '1D: 4 5 4 3 4' | 1dplot -stdin -dx 0.2 
* If the input has M time points, the output will
   have n*M time points.  The last n-1 of them
   will be past the end of the original time series.
* This program is a quick hack for Gang Chen.
   Where are my Twizzlers?




AFNI program: 1d_tool.py

=============================================================================
1d_tool.py      - for manipulating and evaluating 1D files

---------------------------------------------------------------------------
purpose: ~1~

   This program is meant to read/manipulate/write/diagnose 1D datasets.
   Input can be specified using AFNI sub-brick[]/time{} selectors.

---------------------------------------------------------------------------
examples (very basic for now): ~1~

   Example 1.  Select by rows and columns, akin to 1dcat. ~2~

         1d_tool.py -infile 'data/X.xmat.1D[0..3]{0..5}' -write t1.1D

   Example 2.  Compare with selection by separate options. ~2~

         1d_tool.py -infile data/X.xmat.1D                  \
                    -select_cols '0..3' -select_rows '0..5' \
                    -write t2.1D
         diff t1.1D t2.1D

   Example 2b. Select or remove columns by label prefixes. ~2~

       Keep only bandpass columns:

         1d_tool.py -infile X.xmat.1D -write X.bandpass.1D    \
                    -label_prefix_keep bandpass

       Remove only bandpass columns (maybe for 3dRFSC):

         1d_tool.py -infile X.xmat.1D -write X.no.bandpass.1D \
                    -label_prefix_drop bandpass

       Keep polort columns (start with 'Run') motion shifts ('d') and labels
       starting with 'a' and 'b'.  But drop 'bandpass' columns:

         1d_tool.py -infile X.xmat.1D -write X.weird.1D   \
                    -label_prefix_keep Run d a b          \
                    -label_prefix_drop bandpass

   Example 2c. Select columns by group values, 3 examples. ~2~

       First be sure of what the group labels represent.

         1d_tool.py -infile X.xmat.1D -show_group_labels

       i) Select polort (group -1) and other baseline (group 0) terms.

         1d_tool.py -infile X.xmat.1D -select_groups -1 0 -write baseline.1D

       ii) Select everything but baseline groups (anything positive).

         1d_tool.py -infile X.xmat.1D -select_groups POS -write regs.of.int.1D

       iii) Reorder to have rests of interest, then motion, then polort.

         1d_tool.py -infile X.xmat.1D -select_groups POS 0, -1 -write order.1D

   Example 2d. Select specific runs from the input. ~2~

        Note that X.xmat.1D may have runs defined automatically, but for an
        arbitrary input, they may need to be specified via -set_run_lengths.

        i) .... apparently I forgot to do this...


         1d_tool.py -infile X.xmat.1D -write X.bandpass.1D    \

   Example 3.  Transpose a dataset, akin to 1dtranspose. ~2~

         1d_tool.py -infile t3.1D -transpose -write ttr.1D

   Example 4a. Zero-pad a single-run 1D file across many runs. ~2~

       Given a file of regressors (for example) across a single run (run 2),
       created a new file that is padded with zeros, so that it now spans
       many (7) runs.  Runs are 1-based here.

         1d_tool.py -infile ricor_r02.1D -pad_into_many_runs 2 7 \
                    -write ricor_r02_all.1D

   Example 4b. Similar to 4a, but specify varying TRs per run. ~2~

       The number of runs must match the number of run_lengths parameters.

         1d_tool.py -infile ricor_r02.1D -pad_into_many_runs 2 7 \
                    -set_run_lengths 64 61 67 61 67 61 67        \
                    -write ricor_r02_all.1D

   Example 5.  Display small details about a 1D dataset: ~2~

       a. Display number of rows and columns for a 1D dataset.

          Note: to display them "quietly" (only the numbers), add -verb 0.
                This is useful for setting a script variable.

         1d_tool.py -infile X.xmat.1D -show_rows_cols
         1d_tool.py -infile X.xmat.1D -show_rows_cols -verb 0

       b. Display indices of regressors of interest.

         1d_tool.py -infile X.xmat.1D -show_indices_interest

       c. Display labels by group.

         1d_tool.py -infile X.xmat.1D -show_group_labels

   Example 6a.  Show correlation matrix warnings for this matrix. ~2~

         1d_tool.py -infile X.xmat.1D -show_cormat_warnings

   Example 6b.  Show entire correlation matrix. ~2~

         1d_tool.py -infile X.xmat.1D -show_cormat

   Example 7a. Output temporal derivative of motion regressors. ~2~

       There are 9 runs in dfile_rall.1D, and derivatives are applied per run.

         1d_tool.py -infile dfile_rall.1D -set_nruns 9 \
                    -derivative -write motion.deriv.1D

   Example 7b. Similar to 7a, but let the run lengths vary. ~2~

       The sum of run lengths should equal the number of time points.

         1d_tool.py -infile dfile_rall.1D                       \
                    -set_run_lengths 64 64 64 64 64 64 64 64 64 \
                    -derivative -write motion.deriv.rlens.1D

   Example 7c. Use forward differences. ~2~

       instead of the default backward differences...

         1d_tool.py -infile dfile_rall.1D                       \
                    -set_run_lengths 64 64 64 64 64 64 64 64 64 \
                    -forward_diff -write motion.deriv.rlens.1D

   Example 8.  Verify whether labels show slice-major ordering.

       This is where all slice0 regressors come first, then all slice1
       regressors, etc.  Either show the labels and verify visually, or
       print whether it is true.

         1d_tool.py -infile scan_2.slibase.1D'[0..12]' -show_labels
         1d_tool.py -infile scan_2.slibase.1D -show_labels
         1d_tool.py -infile scan_2.slibase.1D -show_label_ordering

   Example 9a. Given motion.1D, create an Enorm time series. ~2~

       Take the derivative (ignoring run breaks) and the Euclidean Norm,
       and write as e.norm.1D.  This might be plotted to show show sudden
       motion as a single time series.

         1d_tool.py -infile motion.1D -set_nruns 9              \
                    -derivative  -collapse_cols euclidean_norm  \
                    -write e.norm.1D

   Example 9b. Like 9a, but supposing the run lengths vary (still 576 TRs). ~2~

         1d_tool.py -infile motion.1D                           \
                    -set_run_lengths 64 61 67 61 67 61 67 61 67 \
                    -derivative  -collapse_cols euclidean_norm  \
                    -write e.norm.rlens.1D

   Example 9c. Like 9b, but weight the rotations as 0.9 mm. ~2~

         1d_tool.py -infile motion.1D                           \
                    -set_run_lengths 64 61 67 61 67 61 67 61 67 \
                    -derivative  -collapse_cols weighted_enorm  \
                    -weight_vec .9 .9 .9 1 1 1                  \
                    -write e.norm.weighted.1D

  Example 10.  Given motion.1D, create censor files to use in 3dDeconvolve. ~2~
    
       Here a TR is censored if the derivative values have a Euclidean Norm
       above 1.2.  It is common to also censor each previous TR, as motion may
       span both (previous because "derivative" is actually a backward
       difference).

       The file created by -write_censor can be used with 3dD's -censor option.
       The file created by -write_CENSORTR can be used with -CENSORTR.  They
       should have the same effect in 3dDeconvolve.  The CENSORTR file is more
       readable, but the censor file is better for plotting against the data.
 
       a. general example ~3~

          1d_tool.py -infile motion.1D -set_nruns 9     \
                     -derivative -censor_prev_TR        \
                     -collapse_cols euclidean_norm      \
                     -moderate_mask -1.2 1.2            \
                     -show_censor_count                 \
                     -write_censor subjA_censor.1D      \
                     -write_CENSORTR subjA_CENSORTR.txt

       b. using -censor_motion ~3~

          The -censor_motion option is available, which implies '-derivative',
          '-collapse_cols euclidean_norm', 'moderate_mask -LIMIT LIMIT', and the
          prefix for '-write_censor' and '-write_CENSORTR' output files.  This
          option will also result in subjA_enorm.1D being written, which is the
          euclidean norm of the derivative, before the extreme mask is applied.

          1d_tool.py -infile motion.1D -set_nruns 9     \
                     -show_censor_count                 \
                     -censor_motion 1.2 subjA           \
                     -censor_prev_TR

       c. allow the run lengths to vary ~3~

          1d_tool.py -infile motion.1D                           \
                     -set_run_lengths 64 61 67 61 67 61 67 61 67 \
                     -show_censor_count                          \
                     -censor_motion 1.2 subjA_rlens              \
                     -censor_prev_TR

       Consider also '-censor_prev_TR' and '-censor_first_trs'.

  Example 11.  Demean the data.  Use motion parameters as an example. ~2~

       The demean operation is done per run (default is 1 when 1d_tool.py
       does not otherwise know).

       a. across all runs (if runs are not known from input file)

         1d_tool.py -infile dfile_rall.1D -demean -write motion.demean.a.1D

       b. per run, over 9 runs of equal length

         1d_tool.py -infile dfile_rall.1D -set_nruns 9      \
                -demean -write motion.demean.b.1D

       c. per run, over 9 runs of varying length

         1d_tool.py -infile dfile_rall.1D                   \
                -set_run_lengths 64 61 67 61 67 61 67 61 67 \
                -demean -write motion.demean.c.1D

  Example 12.  "Uncensor" the data, zero-padding previously censored TRs. ~2~

       Note that an X-matrix output by 3dDeconvolve contains censor
       information in GoodList, which is the list of uncensored TRs.

       a. if the input dataset has censor information

         1d_tool.py -infile X.xmat.1D -censor_fill -write X.uncensored.1D

       b. if censor information needs to come from a parent

         1d_tool.py -infile sum.ideal.1D -censor_fill_parent X.xmat.1D \
                    -write sum.ideal.uncensored.1D

       c. if censor information needs to come from a simple 1D time series

         1d_tool.py -censor_fill_parent motion_FT_censor.1D \
                    -infile cdata.1D -write cdata.zeropad.1D

  Example 13. Show whether the input file is valid as a numeric data file. ~2~

       a. as any generic 1D file

          1d_tool.py -infile data.txt -looks_like_1D

       b. as a 1D stim_file, of 3 runs of 64 TRs (TR is irrelevant)

          1d_tool.py -infile data.txt -looks_like_1D \
                     -set_run_lengths 64 64 64

       c. as a stim_times file with local times

          1d_tool.py -infile data.txt -looks_like_local_times \
                     -set_run_lengths 64 64 64 -set_tr 2

       d. as a 1D or stim_times file with global times

          1d_tool.py -infile data.txt -looks_like_global_times \
                     -set_run_lengths 64 64 64 -set_tr 2

       e. report modulation type (amplitude and/or duration)

          1d_tool.py -infile data.txt -looks_like_AM 

       f. perform all tests, reporting all errors

          1d_tool.py -infile data.txt -looks_like_test_all \
                     -set_run_lengths 64 64 64 -set_tr 2

   Example 14. Split motion parameters across runs. ~2~

       Split, but keep them at the original length so they apply to the same
       multi-run regression.  Each file will be the same as the original for
       the run it applies to, but zero across all other runs.

       Note that -split_into_pad_runs takes the output prefix as a parameter.

         1d_tool.py -infile motion.1D                   \
                    -set_run_lengths 64 64 64           \
                    -split_into_pad_runs mot.padded

       The output files are:
          mot.padded.r01.1D   mot.padded.r02.1D   mot.padded.r03.1D

       If the run lengths are the same -set_nruns is shorter...

         1d_tool.py -infile motion.1D                   \
                    -set_nruns 3                        \
                    -split_into_pad_runs mot.padded

   Example 15a. Show the maximum pairwise displacement. ~2~

       Show the max pairwise displacement in the motion parameter file.
       So over all TRs pairs, find the biggest displacement.

       In one direction it is easy (AP say).  If the minimum AP shift is -0.8
       and the maximum is 1.5, then the maximum displacement is 2.3 mm.  It
       is less clear in 6-D space, and instead of trying to find an enveloping
       set of "coordinates", distances between all N choose 2 pairs are
       evaluated (brute force).

        1d_tool.py -infile dfile_rall.1D -show_max_displace

   Example 15b. Like 15a, but do not include displacement from censored TRs. ~2~

        1d_tool.py -infile dfile_rall.1D -show_max_displace \
                   -censor_infile motion_censor.1D

   Example 16. Randomize a list of numbers, say, those from 1..40. ~2~

       The numbers can come from 1deval, with the result piped to
       '1d_tool.py -infile stdin -randomize_trs ...'.

        1deval -num 40 -expr t+1 |   \
           1d_tool.py -infile stdin -randomize_trs -write stdout

        See also -seed.

   Example 17. Display min, mean, max, stdev of 1D file. ~2~

        1d_tool.py -show_mmms -infile data.1D

       To be more detailed, get stats for each of x, y, and z directional
       blur estimates for all subjects.  Cat(enate) all of the subject files
       and pipe that to 1d_tool.py with infile - (meaning stdin).

        cat subject_results/group.*/sub*/*.results/blur.errts.1D \
                | 1d_tool.py -show_mmms -infile -

   Example 18. Just output censor count for default method. ~2~

       This will output nothing but the number of TRs that would be censored,
       akin to using -censor_motion and -censor_prev_TR.

        1d_tool.py -infile dfile_rall.1D -set_nruns 3 -quick_censor_count 0.3

        1d_tool.py -infile dfile_rall.1D -set_run_lengths 100 80 120 \
                   -quick_censor_count 0.3

   Example 19. Compute GCOR from some 1D file. ~2~

       * Note, time should be in the vertical direction of the file
         (else use -transpose).

        1d_tool.py -infile data.1D -show_gcor

       Or get some GCOR documentation and many values.
        
        1d_tool.py -infile data.1D -show_gcor_doc
        1d_tool.py -infile data.1D -show_gcor_all

   Example 20. Display censored or uncensored TRs lists (for use in 3dTcat). ~2~

       TRs which were censored:

          1d_tool.py -infile X.xmat.1D -show_trs_censored encoded

       TRs which were applied in analysis (those NOT censored):

          1d_tool.py -infile X.xmat.1D -show_trs_uncensored encoded

       Only those applied in run #2 (1-based).

          1d_tool.py -infile X.xmat.1D -show_trs_uncensored encoded \
                     -show_trs_run 2

   Example 21. Convert to rank order. ~2~

       a. show rank order of slice times from a 1D file

         1d_tool.py -infile slice_times.1D -rank -write -

       b. show rank order of slice times piped directly from 3dinfo

         3dinfo -slice_timing epi+orig | 1d_tool.py -infile - -rank -write -

       c. show rank order using 'competition' rank, instead of default 'dense'

         3dinfo -slice_timing epi+orig \
                | 1d_tool.py -infile - -rank_style competition -write -

   Example 22. Guess volreg base index from motion parameters. ~2~

         1d_tool.py -infile dfile_rall.1D -collapse_cols enorm -show_argmin

   Example 23. Convert volreg parameters to those suitable for 3dAllineate. ~2~

         1d_tool.py -infile dfile_rall.1D -volreg2allineate \
                    -write allin_rall_aff12.1D

   Example 24. Show TR counts per run. ~2~

        a. list the number of TRs in each run

          1d_tool.py -infile X.xmat.1D -show_tr_run_counts trs

        b. list the number of TRs censored in each run

          1d_tool.py -infile X.xmat.1D -show_tr_run_counts trs_cen

        c. list the number of TRs prior to censoring in each run

          1d_tool.py -infile X.xmat.1D -show_tr_run_counts trs_no_cen

        d. list the fraction of TRs censored per run

          1d_tool.py -infile X.xmat.1D -show_tr_run_counts frac_cen

        e. list the fraction of TRs censored in run 3

          1d_tool.py -infile X.xmat.1D -show_tr_run_counts frac_cen \
                     -show_trs_run 3

   Example 25. Show number of runs. ~2~

          1d_tool.py -infile X.xmat.1D -show_num_runs

   Example 26. Convert global index to run and TR index. ~2~

       Note that run indices are 1-based, while TR indices are 0-based,
       as usual.  Confusion is key.

       a. explicitly, given run lengths

          1d_tool.py -set_run_lengths 100 80 120 -index_to_run_tr 217

       b. implicitly, given an X-matrix (** be careful about censoring **)

          1d_tool.py -infile X.nocensor.xmat.1D -index_to_run_tr 217

   Example 27. Display length of response curve. ~2~

          1d_tool.py -show_trs_to_zero -infile data.1D

       Print out the length of the input (in TRs, say) until the data
       values become a constant zero.  Zeros that are followed by non-zero
       values are irrelevant.

   Example 28. Convert slice order to slice times. ~2~

       A slice order might be the sequence in which slices were acquired.
       For example, with 33 slices, perhaps the order is:

          set slice_order = ( 0 6 12 18 24 30 1 7 13 19 25 31 2 8 14 20 \
                              26 32 3 9 15 21 27 4 10 16 22 28 5 11 17 23 29 )

       Put this in a file:

          echo $slice_order > slice_order.1D
          1d_tool.py -set_tr 2 -slice_order_to_times \
                     -infile slice_order.1D -write slice_times.1D

       Or as a filter:

          echo $slice_order | 1d_tool.py -set_tr 2 -slice_order_to_times \
                                         -infile - -write -

   Example 29. Display minimum cluster size from 3dClustSim output. ~2~

       Given a text file output by 3dClustSim, e.g. ClustSim.ACF.NN1_1sided.1D,
       and given both an uncorrected (pthr) and a corrected (alpha) p-value,
       look up the entry that specifies the minimum cluster size needed for
       corrected p-value significance.

       If requested in afni_proc.py, they are under files_ClustSim.

       a. with modestly verbose output (default is -verb 1)

          1d_tool.py -infile ClustSim.ACF.NN1_1sided.1D -csim_show_clustsize

       b. quiet, to see just the output value

          1d_tool.py -infile ClustSim.ACF.NN1_1sided.1D -csim_show_clustsize \
                     -verb 0

       c. quiet, and capture the output value (tcsh syntax)

          set clustsize = `1d_tool.py -infile ClustSim.ACF.NN1_1sided.1D \
                                      -csim_show_clustsize -verb 0`

---------------------------------------------------------------------------
command-line options: ~1~
---------------------------------------------------------------------------
basic informational options: ~2~

   -help                        : show this help
   -hist                        : show the module history
   -show_valid_opts             : show all valid options
   -ver                         : show the version number

----------------------------------------
required input: ~2~

   -infile DATASET.1D           : specify input 1D file

----------------------------------------
general options: ~2~

   -add_cols NEW_DSET.1D        : extend dset to include these columns

   -backward_diff               : take derivative as first backward difference

        Take the backward differences at each time point.  For each index > 0,
        value[index] = value[index] - value[index-1], and value[0] = 0.

        This option is identical to -derivative.

        See also -forward_diff, -derivative, -set_nruns, -set_run_lens.

   -collapse_cols METHOD        : collapse multiple columns into one, where

        METHOD is one of: min, max, minabs, maxabs, euclidean_norm,
                          weighted_enorm.

        Consideration of the euclidean_norm method:

           For censoring, the euclidean_norm method is used (sqrt(sum squares)).
           This combines rotations (in degrees) with shifts (in mm) as if they
           had the same weight.

           Note that assuming rotations are about the center of mass (which
           should produce a minimum average distance), then the average arc
           length (averaged over the brain mask) of a voxel rotated by 1 degree
           (about the CM) is the following (for the given datasets):

              TT_N27+tlrc:        0.967 mm (average radius = 55.43 mm)
              MNIa_caez_N27+tlrc: 1.042 mm (average radius = 59.69 mm)
              MNI_avg152T1+tlrc:  1.088 mm (average radius = 62.32 mm)

           The point of these numbers is to suggest that equating degrees and
           mm should be fine.  The average distance caused by a 1 degree
           rotation is very close to 1 mm (in an adult human).

         * 'enorm' is short for 'euclidean_norm'.

         * Use of weighted_enorm requires the -weight_vec option.

              e.g. -collapse_cols weighted_enorm -weight_vec .9 .9 .9 1 1 1 

   -censor_motion LIMIT PREFIX  : create censor files

        This option implies '-derivative', '-collapse_cols euclidean_norm',
        'moderate_mask -LIMIT LIMIT' and applies PREFIX for '-write_censor'
        and '-write_CENSORTR' output files.  It also outputs the derivative
        of the euclidean norm, before the limit it applied.

        The temporal derivative is taken with run breaks applied (derivative
        of the first run of a TR is 0), then the columns are collapsed into
        one via each TR's vector length (Euclidean Norm: sqrt(sum of squares)).
        After that, a mask time series is made from TRs with values outside
        (-LIMIT,LIMIT), i.e. if >= LIMIT or <= LIMIT, result is 1.

        This binary time series is then written out in -CENSORTR format, with
        the moderate TRs written in -censor format (either can be applied in
        3dDeconvolve).  The output files will be named PREFIX_censor.1D,
        PREFIX_CENSORTR.txt and PREFIX_enorm.1D (e.g. subj123_censor.1D,
        subj123_CENSORTR.txt and subj123_enorm.1D).

        Besides an input motion file (-infile), the number of runs is needed
        (-set_nruns or -set_run_lengths).

        Consider also '-censor_prev_TR' and '-censor_first_trs'.
        See example 10.

   -censor_fill                 : expand data, filling censored TRs with zeros
   -censor_fill_parent PARENT   : similar, but get censor info from a parent

        The output of these operation is a longer dataset.  Each TR that had
        previously been censored is re-inserted as a zero.

        The purpose of this is to make 1D time series data properly align
        with the all_runs dataset, for example.  Otherwise, the ideal 1D data
        might have missing TRs, and so will align worse with responses over
        the duration of all runs (it might start aligned, but drift earlier
        and earlier as more TRs are censored).

        See example 12.

   -censor_infile CENSOR_FILE   : apply censoring to -infile dataset

        This removes TRs from the -infile dataset where the CENSOR_FILE is 0.
        The censor file is akin to what is used with "3dDeconvolve -censor",
        where TRs with 1 are kept and those with 0 are excluded from analysis.

        See example 15b.

   -censor_first_trs N          : when censoring motion, also censor the first
                                  N TRs of each run

   -censor_next_TR              : for each censored TR, also censor next one
                                  (probably for use with -forward_diff)

   -censor_prev_TR              : for each censored TR, also censor previous

   -cormat_cutoff CUTOFF        : set cutoff for cormat warnings (in [0,1])

   -csim_show_clustsize         : for 3dClustSim input, show min clust size

       Given a 3dClustSim table output (e.g. ClustSim.ACF.NN1_1sided.1D),
       along with uncorrected (pthr) and corrected (alpha) p-values, show the
       minimum cluster size to achieve significance.

       The pthr and alpha values can be controlled via the options -csim_pthr
       and -csim_alpha (with defaults of 0.001 and 0.05, respectively).

       The -verb option can be used to provide additional or no details
       about the clustering method.

       See Example 29, along with options -csim_pthr, -csim_alpha and -verb.

   -csim_pthr THRESH            : specify uncorrected threshold for csim output

       e.g. -csim_pthr 0.0001

       This option implies -csim_show_clustsize, and is used to specify the
       uncorrected p-value of the 3dClustSim output.

       See also -csim_show_clustsize.

   -csim_alpha THRESH           : specify corrected threshold for csim output

       e.g. -csim_alpha 0.01

       This option implies -csim_show_clustsize, and is used to specify the
       corrected, cluster-wise p-value of the 3dClustSim output.

       See also -csim_show_clustsize.

   -demean                      : demean each run (new mean of each run = 0.0)

   -derivative                  : take the temporal derivative of each vector
                                  (done as first backward difference)

        Take the backward differences at each time point.  For each index > 0,
        value[index] = value[index] - value[index-1], and value[0] = 0.

        This option is identical to -backward_diff.

        See also -backward_diff, -forward_diff, -set_nruns, -set_run_lens.

   -extreme_mask MIN MAX        : make mask of extreme values

        Convert to a 0/1 mask, where 1 means the given value is extreme
        (outside the (MIN, MAX) range), and 0 means otherwise.  This is the
        opposite of -moderate_mask (not exactly, both are inclusive).

        Note: values = MIN or MAX will be in both extreme and moderate masks.

        Note: this was originally described incorrectly in the help.

   -forward_diff                : take first forward difference of each vector

        Take the first forward differences at each time point.  For index<last,
        value[index] = value[index+1] - value[index], and value[last] = 0.

        The difference between -forward_diff and -backward_diff is a time shift
        by one index.

        See also -backward_diff, -derivative, -set_nruns, -set_run_lens.

   -index_to_run_tr INDEX       : convert global INDEX to run and TR indices

        Given a list of run lengths, convert INDEX to a run and TR index pair.

        This option requires -set_run_lens or maybe an Xmat.
        
        See also -set_run_lens example 26.

   -moderate_mask MIN MAX       : make mask of moderate values

        Convert to a 0/1 mask, where 1 means the given value is moderate
        (within [MIN, MAX]), and 0 means otherwise.  This is useful for
        censoring motion (in the -censor case, not -CENSORTR), where the
        -censor file should be a time series of TRs to apply.

        See also -extreme_mask.

   -label_prefix_drop prefix1 prefix2 ... : remove labels matching prefix list

        e.g. to remove motion shift (starting with 'd') and bandpass labels:

             -label_prefix_drop d bandpass

        This is a type of column selection.

        Use this option to remove columns from a matrix that have labels
        starting with any from the given prefix list.

        This option can be applied along with -label_prefix_keep.

        See also -label_prefix_keep and example 2b.

   -label_prefix_keep prefix1 prefix2 ... : keep labels matching prefix list

        e.g. to keep only motion shift (starting with 'd') and bandpass labels:

             -label_prefix_keep d bandpass

        This is a type of column selection.

        Use this option to keep columns from a matrix that have labels starting
        with any from the given prefix list.

        This option can be applied along with -label_prefix_drop.

        See also -label_prefix_drop and example 2b.

   "Looks like" options:

        These are terminal options that check whether the input file seems to
        be of type 1D, local stim_times or global stim_times formats.  The only
        associated options are currently -infile, -set_run_lens, -set_tr and
        -verb.

        They are terminal in that no other 1D-style actions are performed.
        See 'timing_tool.py -help' for details on stim_times operations.

   -looks_like_1D               : is the file in 1D format

        Does the input data file seem to be in 1D format?

            - must be rectangular (same number of columns per row)
            - duration must match number of rows (if run lengths are given)

   -looks_like_AM               : does the file have modulators?

        Does the file seem to be in local or global times format, and
        do the times have modulators?

            - amplitude modulators should use '*' format (e.g. 127.3*5.1)
            - duration modulators should use trailing ':' format (12*5.1:3.4)
            - number of amplitude modulators should be constant

   -looks_like_local_times      : is the file in local stim_times format

        Does the input data file seem to be in the -stim_times format used by
        3dDeconvolve (and timing_tool.py)?  More specifically, is it the local
        format, with one scanning run per row.

            - number of rows must match number of runs
            - times cannot be negative
            - times must be unique per run (per row)
            - times cannot exceed the current run time

   -looks_like_global_times     : is the file in global stim_times format

        Does the input data file seem to be in the -stim_times format used by
        3dDeconvolve (and timing_tool.py)?  More specifically, is it the global
        format, either as one long row or one long line?

            - must be one dimensional (either a single row or column)
            - times cannot be negative
            - times must be unique
            - times cannot exceed total duration of all runs

   -looks_like_test_all         : run all -looks_like tests

        Applies all "looks like" test options: -looks_like_1D, -looks_like_AM,
        -looks_like_local_times and -looks_like_global_times.

   -overwrite                   : allow overwriting of any output dataset

   -pad_into_many_runs RUN NRUNS : pad as current run of num_runs

        e.g. -pad_into_many_runs 2 7

        This option is used to create a longer time series dataset where the
        input is consider one particular run out of many.  The output is
        padded with zero for all run TRs before and after this run.

        Given the example, there would be 1 run of zeros, then the input would
        be treated as run 2, and there would be 5 more runs of zeros.

   -quick_censor_count LIMIT    : output # TRs that would be censored

        e.g. -quick_censor_count 0.3

        This is akin to -censor_motion, but it only outputs the number of TRs
        that would be censored.  It does not actually create a censor file.

        This option essentially replaces these:

           -derivative -demean -collapse_cols euclidean_norm
           -censor_prev_TR -verb 0 -show_censor_count 
           -moderate_mask 0 LIMIT

   -rank                        : convert data to rank order
                                  0-based index order of small to large values
                                  The default rank STYLE is 'dense'.

        See also -rank_style.

   -rank_style STYLE            : convert to rank using the given style

        The STYLE refers to what to do in the case of repeated values.
        Assuming inputs 4 5 5 9...

            dense      - repeats get same rank, no gaps in rank
                        - same a "3dmerge -1rank"
                        - result: 0 1 1 2

            competition - repeats get same rank, leading to gaps in rank
                        - same a "3dmerge -1rank"
                        - result: 0 1 1 3
                          (case '2' is counted, though no such rank occurs)

        Option '-rank' uses style 'dense'.

        See also -rank.

   -reverse_rank                : convert data to reverse rank order
                                  (large values come first)

   -reverse                     : reverse data over time
   -randomize_trs               : randomize the data over time
   -seed SEED                   : set random number seed (integer)
   -select_groups g0 g1 ...     : select columns by group numbers

        e.g. -select groups 0
        e.g. -select groups POS 0

        An X-matrix dataset (e.g. X.xmat.1D) often has columns partitioned by
        groups, such as:
                -1  : polort regressors
                 0  : motion regressors and other (non-polort) baseline terms
                 N>0: regressors of interest

        This option can be used to select columns by integer groups, with
        special cases of POS (regs of interest), NEG (probably polort).
        Note that NONNEG is unneeded as it is the pair POS 0.

        See also -show_group_labels.

   -select_cols SELECTOR        : apply AFNI column selectors, [] is optional
                                  e.g. '[5,0,7..21(2)]'
   -select_rows SELECTOR        : apply AFNI row selectors, {} is optional
                                  e.g. '{5,0,7..21(2)}'
   -select_runs r1 r2 ...       : extract the given runs from the dataset
                                  (these are 1-based run indices)
                                  e.g. 2
                                  e.g. 2 3 1 1 1 1 1 4
   -set_nruns NRUNS             : treat the input data as if it has nruns
                                  (e.g. applies to -derivative and -demean)

        See examples 7a, 10a and b, and 14.

   -set_run_lengths N1 N2 ...   : treat as if data has run lengths N1, N2, etc.
                                  (applies to -derivative, for example)

        Notes:  o  option -set_nruns is not allowed with -set_run_lengths
                o  the sum of run lengths must equal NT

        See examples 7b, 10c and 14.

   -set_tr TR                   : set the TR (in seconds) for the data
   -show_argmin                 : display the index of min arg (of first column)
   -show_censor_count           : display the total number of censored TRs
                           Note : if input is a valid xmat.1D dataset, then the
                                  count will come from the header.  Otherwise
                                  the input is assumed to be a binary censor
                                  file, and zeros are simply counted.
   -show_cormat                 : display correlation matrix
   -show_cormat_warnings        : display correlation matrix warnings
   -show_gcor                   : display GCOR: the average correlation
   -show_gcor_all               : display many ways of computing (a) GCOR
   -show_gcor_doc               : display descriptions of those ways
   -show_group_labels           : display group and label, per column
   -show_indices_baseline       : display column indices for baseline
   -show_indices_motion         : display column indices for motion regressors
   -show_indices_interest       : display column indices for regs of interest
   -show_label_ordering         : display the labels
   -show_labels                 : display the labels
   -show_max_displace           : display max displacement (from motion params)
                                  - the maximum pairwise distance (enorm)
   -show_mmms                   : display min, mean, max, stdev of columns
   -show_num_runs               : display number of runs found
   -show_rows_cols              : display the number of rows and columns
   -show_tr_run_counts STYLE    : display TR counts per run, according to STYLE
                                  STYLE can be one of:
                                     trs        : TR counts
                                     trs_cen    : censored TR counts
                                     trs_no_cen : TR counts, as if no censoring
                                     frac_cen   : fractions of TRs censored
        See example 24.

   -show_trs_censored STYLE     : display a list of TRs which were censored
   -show_trs_uncensored STYLE   : display a list of TRs which were not censored
                                  STYLE can be one of:
                                     comma      : comma delimited
                                     space      : space delimited
                                     encoded    : succinct selector list
                                     verbose    : chatty
        See example 20.

   -show_trs_run RUN            : restrict -show_trs_[un]censored to the given
                                  1-based run
   -show_trs_to_zero            : display number of TRs before final zero value
                                  (e.g. length of response curve)

   -slice_order_to_times        : convert a list of slice indices to times

        Programs like to3d, 3drefit3dTcat and 3dTshift expect slice timing
        to be a list of slice times over the sequential slices.  But in some
        cases, people have an ordered list of slices.  So the sorting needs
        to change.

        If TR=2 and the slice order is:  0  2  4  6  8  1  3  5  7  9

        Then the slices/times ordered by time (as input) are:

           slices: 0    2    4    6    8    1    3    5    7    9
           times:  0.0  0.2  0.4  0.6  0.8  1.0  1.2  1.4  1.6  1.8

        And the slices/times ordered instead by slice index are:

           slices: 0    1    2    3    4    5    6    7    8    9
           times:  0.0  1.0  0.2  1.2  0.4  1.4  0.6  1.6  0.8  1.8

        It is this final list of times that is output.

        See example 28.

   -sort                        : sort data over time (smallest to largest)
                                  - sorts EVERY vector
                                  - consider the -reverse option

   -split_into_pad_runs PREFIX  : split input into one padded file per run

        e.g. -split_into_pad_runs motion.pad

        This option is used for breaking a set of regressors up by run.  The
        output would be one file per run, where each file is the same as the
        input for the run it corresponds to, and is padded with 0 across all
        other runs.

        Assuming the 300 row input dataset spans 3 100-TR runs, then there
        would be 3 output datasets created, each still be 300 rows:

            motion.pad.r01.1D   : 100 rows as input, 200 rows of 0
            motion.pad.r02.1D   : 100 rows of 0, 100 rows as input, 100 of 0
            motion.pad.r03.1D   : 200 rows of 0, 100 rows as input

        This option requires either -set_nruns or -set_run_lengths.

        See example 14.

   -transpose                   : transpose the input matrix (rows for columns)
   -transpose_write             : transpose the output matrix before writing
   -volreg2allineate            : convert 3dvolreg parameters to 3dAllineate

        This option should be used when the -infile file is a 6 column file
        of motion parameters (roll, pitch, yaw, dS, dL, dP).  The output would
        be converted to a 12 parameter file, suitable for input to 3dAllineate
        via the -1Dparam_apply option.

        volreg:     roll, pitch, yaw,   dS,    dL,     dP
        3dAllinate: -dL,  -dP,   -dS,   roll,  pitch,  yaw,  0,0,0,  0,0,0

        These parameters would be to correct the motion, akin to what 3dvolreg
        did (i.e. they are the negative estimates of how the subject moved).

        See example 23.

   -write FILE                  : write the current 1D data to FILE

   -weight_vec v1 v2 ...        : supply weighting vector

        e.g. -weight_vec 0.9 0.9 0.9 1 1 1

        This vector currently works only with the weighted_enorm method for
        the -collapse_cols option.  If supplied (as with the example), it will
        weight the angles at 0.9 times the weights of the shifts in the motion
        parameters output by 3dvolreg.

        See also -collapse_cols.

   -write_censor FILE           : write as boolean censor.1D

        e.g. -write_censor subjA_censor.1D

        This file can be given to 3dDeconvolve to censor TRs with excessive
        motion, applied with the -censor option.

            e.g. 3dDeconvolve -censor subjA_censor.1D

        This file works well for plotting against the data, where the 0 entries
        are removed from the regression of 3dDeconvolve.  Alternatively, the
        file created with -write_CENSORTR is probably more human readable.

   -write_CENSORTR FILE         : write censor times as CENSORTR string

        e.g. -write_CENSORTR subjA_CENSORTR.txt

        This file can be given to 3dDeconvolve to censor TRs with excessive
        motion, applied with the -CENSORTR option.

            e.g. 3dDeconvolve -CENSORTR `cat subjA_CENSORTR.txt`

        Which might expand to:

                 3dDeconvolve -CENSORTR '1:16..19,44 3:28 4:19,37..39'

        Note that the -CENSORTR option requires the text on the command line.

        This file is in the easily readable format applied with -CENSORTR.
        It has the same effect on 3dDeconvolve as the sister file from
        -write_censor, above.

   -verb LEVEL                  : set the verbosity level

-----------------------------------------------------------------------------
R Reynolds    March 2009
=============================================================================




AFNI program: 1dcat

Usage: 1dcat [options] a.1D b.1D ...

  where each file a.1D, b.1D, etc. is a 1D file.
  In the simplest form, a 1D file is an ASCII file of numbers
  arranged in rows and columns.

1dcat takes as input one or more 1D files, and writes out a 1D file
containing the side-by-side concatenation of all or a subset of the
columns from the input files.

* Output goes to stdout (the screen); redirect (e.g., '>') to save elsewhere.
* All files MUST have the same number of rows!
* Any header lines (i.e., lines that start with '#') will be lost.
* For generic 1D file usage help and information, see '1dplot -help'

-----------
 TSV files: [Sep 2018]
-----------
* 1dcat can now also read .tsv files, which are columns of values separated
  by tab characters (tsv = tab separated values). The first row of a .tsv 
  file is a set of column labels. After the header row, each column is either
  all numbers, or is a column of strings. For example
     Col 1 Col 2 Col 3
     3.2 7.2 Elvis
     8.2 -1.2 Sinatra
     6.66  33.3 20892
  In this example, the column labels contain spaces, which are NOT separators;
  the only column separator used in a .tsv file is the tab character.
  The first and second columns are converted to number columns, since every
  value (after the label/header row) is a numeric string. The third column
  is stored as strings, since some of the entries are not valid numbers.

* 1dcat can deal with a mix of .1D and .tsv files. The .tsv file header
  rows are NOT output by default, since .1D files don't have such headers.

* The usual output from 1dcat is NOT a .tsv file - blanks are used for
  separators. You can use the '-tsvout' option to get TSV formatted output.

* If you mix .1D and .tsv files, the number of data rows in each file
  must be the same. Since the header row in a .tsv file is NOT used here,
  the total number of lines in a .tsv file must be 1 more than the number
  of lines in a .1D file for the two files to match in this program.

* The purpose of supporting .tsv files is for eventual compatibility with
  the BIDS format http://bids.neuroimaging.io - which uses .tsv files
  extensively to provide auxiliary information for (F)MRI datasets.

* Column selectors (like '[0,3]') can be used on .tsv files, but row selectors
  (like '{0,3..5}') cannot be used on .tsv files - at this time :(

* You can also select a column in a .tsv file by using the label at the top of
  of the column. A BIDS-related example:
    1dcat sub-666_task-XXX_events.tsv'[onset,duration,trial_type,reaction_time]'
  A similar example, which outputs a list of the trial types in an imaging run:
    1dcat sub-666_task-XXX_events.tsv'[trial_type]' | sort | uniq

* Since .1D files don't have headers, the label method of column selection
  doesn't work with such inputs; you must use integer column selectors
  on .1D files.

* NOTE WELL: The string 'N/A' or 'n/a' in a column that is otherwise numeric
             will be considered to be a number, and will be replaced on input
             with the mean of the "true" numbers in the column -- there is
             no concept of missing data in an AFNI .1D file.
           ++ If you don't like this, well ... too bad for you.

--------
OPTIONS:
--------
  -tsvout   = Output in a TSV (.tsv) format, where the values in each row
              are separated by tabs, not blanks. Also, a header line will
              be provided, as TSV files require.

  -nonconst = Columns that are identically constant should be omitted
              from the output.

  -nonfixed = Keep only columns that are marked as 'free' in the 
              3dAllineate header from '-1Dparam_save'.
              If there is no such header, all columns are kept.
           * NOTE: -nconst and -nonfixed don't have any effect on
                   .tsv files, and the use of these options
                   has NOT been tested at all when the inputs
                   are mixture of .tsv and .1D files.

  -form FORM = Format of the numbers to be output.
               You can also substitute -form FORM with shortcuts such 
               as -i, -f, or -c.
               For help on -form's usage, and its shortcut versions
               see ccalc's help for the option of the same name. 

  -stack = Stack the columns of the resultant matrix in the output.
             You can't use '-stack' with .tsv files :(

  -sel SEL = Apply the same column/row selection string to all filenames
             on the command line.
             For example:
               1dcat -sel '[0,2]' f1.1D f2.1D
             is the same as: 1dcat f1.1D'[1,2]' f2.1D'[1,2]'
             The advantage of the option is that it allows wildcard use
             in file specification so that you can run something like:
               1dcat -sel '[0,2]' f?.1D

EXAMPLE:
--------
  Input file 1:
   1
   2
   3
   4
  Input file 2:
   5
   6
   7
   8

  1dcat data1.1D data2.1D > catout.1D
  Output file: 
   1 5
   2 6
   3 7
   4 8


++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1ddot
Usage: 1ddot [options] 1Dfile 1Dfile ...
* Prints out correlation matrix of the 1D files and
  their inverse correlation matrix.
* Output appears on stdout.
* Program 1dCorrelate does something similar-ish.

Options:
 -one  =  Make 1st vector be all 1's.
 -dem  =  Remove mean from all vectors (conflicts with '-one')
 -cov  =  Compute with covariance matrix instead of correlation
 -inn  =  Computed with inner product matrix instead
 -rank =  Compute Spearman rank correlation instead
          (also implies '-terse')
 -terse=  Output only the correlation or covariance matrix
          and without any of the garnish. 
 -okzero= Do not quit if a vector is all zeros.
          The correlation matrix will have 0 where NaNs ought to go.
          Expect rubbish in the inverse matrices if all zero 
          vectors exist.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1deval
Usage: 1deval [options] -expr 'expression'
Evaluates an expression that may include columns of data
from one or more text files and writes the result to stdout.

** Only a single column can be used for each input 1D file. **
*  Simple multiple column operations (e.g., addition, scaling)
    can be done with program 1dmatcalc.
*  Any single letter from a-z can be used as the independent
    variable in the expression.
*  Unless specified using the '[]' notation (cf. 1dplot -help),
    only the first column of an input 1D file is used, and other
    columns are ignored.
*  Only one column of output will be produced -- if you want to
    calculate a multi-column output file, you'll have to run 1deval
    separately for each column, and then glue the results together
    using program 1dcat.  [However, see the 1dcat example combined
    with the '-1D:' option, infra.]

Options:
--------
  -del d     = Use 'd' as the step for a single undetermined variable
                 in the expression [default = 1.0]
                 SYNONYMS: '-dx' and '-dt'

  -start s   = Start at value 's' for a single undetermined variable
                 in the expression [default = 0.0]
                 That is, for the indeterminate variable in the expression
                 (if any), the i-th value will be s+i*d for i=0, 1, ....
                 SYNONYMS: '-xzero' and '-tzero'

  -num n     = Evaluate the expression 'n' times.
                 If -num is not used, then the length of an
                 input time series is used.  If there are no
                 time series input, then -num is required.

  -a q.1D    = Read time series file q.1D and assign it
                 to the symbol 'a' (as in 3dcalc).
               * Letters 'a' to 'z' may be used as symbols.
               * You can use the filename 'stdin:' to indicate that
               the data for 1 symbol comes from standard input:
     1dTsort q.1D stdout: | 1deval -a stdin: -expr 'sqrt(a)' | 1dplot stdin:

  -a=NUMBER   = set the symbol 'a' to a fixed numerical value
                rather than a variable value from a 1D file.
             * Letters 'a' to 'z' may be used as symbols.
             * You can't assign the same symbol twice!

  -index i.1D = Read index column from file i.1D and
                 write it out as 1st column of output.
                 This option is useful when working with
                 surface data.

  -1D:       = Write output in the form of a single '1D:'
                 string suitable for input on the command
                 line of another program.
                 [-1D: is incompatible with the -index option!]
                 [This won't work if the output string is very long,]
                 [since the maximum command line length is limited. ]

Examples:
---------
 * 't' is the indeterminate variable in the expression below:
     1deval -expr 'sin(2*PI*t)' -del 0.01 -num 101 > sin.1D
 * Multiply two columns of data (no indeterminate variable):
     1deval -expr 'a*b' -a fred.1D -b ethel.1D > ab.1D
 * Compute and plot the F-statistic corresponding to p=0.001 for
   varying degrees of freedom given by the indeterminate variable 'n':
     1deval -start 10 -num 90 -expr 'fift_p2t(0.001,n,2*n)' | 1dplot -xzero 10 -stdin
 * Compute the square root of some numbers given in '1D:' form
   directly on the command line:
     1deval -x '1D: 1 4 9 16' -expr 'sqrt(x)'

Examples using '-1D:' as the output format:
-------------------------------------------
The examples use the shell backquote `xxx` operation, where the
command inside the backquotes is executed, its stdout is captured
into a string, and placed back on the command line. When you have
mastered this idea, you have taken another step towards becoming
a Jedi AFNI Master!

 1dplot `1deval -1D: -num 71 -expr 'cos(t/2)*exp(-t/19)'`
 1dcat `1deval -1D: -num 100 -expr 'cos(t/5)'` \
       `1deval -1D: -num 100 -expr 'sin(t/5)'` > sincos.1D
 3dTfitter -quiet -prefix -                                     \
           -RHS `1deval -1D: -num 30 -expr 'cos(t)*exp(-t/7)'`  \
           -LHS `1deval -1D: -num 30 -expr 'cos(t)'`            \
                `1deval -1D: -num 30 -expr 'sin(t)'`              

Notes:
------
* Program 3dcalc operates on 3D and 3D+time datasets in a similar way.

* Program ccalc can be used to evaluate a single numeric expression.

* If I had any sense, THIS program would have been called 1dcalc!

* For generic 1D file usage help, see '1dplot -help'

* For help with expression format, see '3dcalc -help', or type
   'help' when using ccalc in interactive mode.

* 1deval only produces a single column of output.  3dcalc can be
   tricked into doing multi-column 1D format output by treating
   a 1D file as a 3D dataset and auto-transposing it with \'
   For example:
     3dcalc -a '1D: 3 4 5 | 1 2 3'\' -expr 'cbrt(a)' -prefix -
   The input has 2 'columns' and so does the output.
   Note that the 1D 'file' is transposed on input to 3dcalc!
   This is essential, or 3dcalc will not treat the 1D file as
   a dataset, and the results will be very different.  Recall that
   when a 1D file is read as an 3D AFNI dataset, the row direction
   corresponds to the sub-brick (e.g., time) direction, and the
   column direction corresponds to the voxel direction.

A Dastardly Trick:
------------------
If you use some other letter than 'z' as the indeterminate variable
in the calculation, and if 'z' is not assigned to any input 1D file,
then 'z' in the expression will be the previous value computed.
This trick can be used to create 1 point recursions, as in the
following command for creating a AR(1) noise time series:
    1deval -num 500 -expr 'gran(0,1)+(i-i)+0.7*z' > g07.1D
Note the use of '(i-i)' to intoduce the variable 'i' so that 'z'
would be used as the previous output value, rather than as the
indeterminate variable generated by '-del' and '-start'.
The initial value of 'z' is 0 (for the first evaluation).
* [02 Apr 2010] You can set the initial value of 'z' to a nonzero
  value by using the environment variable AFNI_1DEVAL_ZZERO, as in
    1deval -DAFNI_1DEVAL_ZZERO=1 -num 10 -expr 'i+z'

-- RW Cox --

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dfft

Usage: 1dfft [options] infile outfile
where infile is an AFNI *.1D file (ASCII list of numbers arranged
in columns); outfile will be a similar file, with the absolute
value of the FFT of the input columns.  The length of the file
will be 1+(FFT length)/2.

Options:
  -ignore sss = Skip the first 'sss' lines in the input file.
                [default = no skipping]
  -use uuu    = Use only 'uuu' lines of the input file.
                [default = use them all, Frank]
  -nfft nnn   = Set FFT length to 'nnn'.
                [default = length of data (# of lines used)]
  -tocx       = Save Re and Im parts of transform in 2 columns.
  -fromcx     = Convert 2 column complex input into 1 column
                  real output.
                [-fromcx will not work if the original]
                [data FFT length was an odd number! :(]
  -hilbert    = When -fromcx is used, the inverse FFT will
                  do the Hilbert transform instead.
  -nodetrend  = Skip the detrending of the input.

Nota Bene:
 * Each input time series has any quadratic trend of the
     form 'a+b*t+c*t*t' removed before the FFT, where 't'
     is the line number.
 * The FFT length can be any positive even integer, but
   the Fast Fourier Transform algorithm will be slower if
   any prime factors of the FFT length are large (say > 997)
   Unless you are applying this program to VERY long files,
   this slowdown will probably not be appreciable.
 * If the FFT length is longer than the file length, the
     data is zero-padded to make up the difference.
 * Do NOT call the output of this program the Power Spectrum!
     That is something else entirely.
 * If 'outfile' is '-' (or missing), the output appears on stdout.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dgenARMA11
Program to generate an ARMA(1,1) time series, for simulation studies.
Results are written to stdout.

Usage: 1dgenARMA11 [options]

Options:
========
 -num N  }  These equivalent options specify the length of the time
 -len N  }  series vector to generate.

 -nvec M  = The number of time series vectors to generate;
            if this option is not given, defaults to 1.

 -a a     = Specify ARMA(1,1) parameters 'a'.
 -b b     = Specify ARMA(1,1) parameter 'b' directly.
 -lam lam = Specify ARMA(1,1) parameter 'b' indirectly.
 -sig ss  = Set standard deviation of results [default=1].
 -norm    = Normalize time series so sum of squares is 1.
 -seed dd = Set random number seed.

  * The correlation coefficient r(k) of noise samples k units apart in time,
     for k >= 1, is given by r(k) = lam * a^(k-1)
     where                   lam  = (b+a)(1+a*b)/(1+2*a*b+b*b)
     (N.B.: lam=a when b=0 -- AR(1) noise has r(k)=a^k for k >= 0)
     (N.B.: lam=b when a=0 -- MA(1) noise has r(k)=b for k=1, r(k)=0 for k>1)
  * lam can be bigger or smaller than a, depending on the sign of b:
     b > 0 means lam > a;  b < 0 means lam < a.
  * What I call (a,b) here is sometimes called (p,q) in the ARMA literature.
  * For a noise model which is the sum of AR(1) and white noise, 0 < lam < a
     (i.e., a > 0  and  -a < b < 0 ).

 -CORcut cc = The exact ARMA(1,1) correlation matrix (for a != 0)
              has no non-zero entries.  The calculations in this
              program set correlations below a cutoff to zero.
              The default cutoff is 0.00010, but can be altered with
              this option.  The usual reason to use this option is
              to test the sensitivity of the results to the cutoff.

Author: RWCox [for his own demented purposes]

Examples:
  1dgenARMA11 -num 200 -a .8 -lam 0.7 | 1dplot -stdin
  1dgenARMA11 -num 2000 -a .8 -lam 0.7 | 1dfft -nodetrend stdin: stdout: | 1dplot -stdin




AFNI program: 1dgrayplot
Usage: 1dgrayplot [options] tsfile
Graphs the columns of a *.1D type time series file to the screen,
sort of like 1dplot, but in grayscale.

Options:
 -install   = Install a new X11 colormap (for X11 PseudoColor)
 -ignore nn = Skip first 'nn' rows in the input file
                [default = 0]
 -flip      = Plot x and y axes interchanged.
                [default: data columns plotted DOWN the screen]
 -sep       = Separate scales for each column.
 -use mm    = Plot 'mm' points
                [default: all of them]
 -ps        = Don't draw plot in a window; instead, write it
              to stdout in PostScript format.
              N.B.: If you view this result in 'gv', you should
                    turn 'anti-alias' off, and switch to
                    landscape mode.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dmatcalc
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
 &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:)"



AFNI program: 1dnorm
Usage: 1dnorm [options] infile outfile
where infile is an AFNI *.1D file (ASCII list of numbers arranged
in columns); outfile will be a similar file, with each column being
L_2 normalized (sum of squares = 1).
* If 'infile'  is '-', it will be read from stdin.
* If 'outfile' is '-', it will be written to stdout.

Options:
--------
 -norm1  = Normalize so sum of absolute values is 1 (L_1 norm)
 -normx  = So that max absolute value is 1 (L_infinity norm)

 -demean = Subtract each column's mean before normalizing
 -demed  = Subtract each column's median before normalizing
            [-demean and -demed are mutually exclusive!]

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dplot
++ 1dplot: AFNI version=AFNI_18.3.16 (Dec 11 2018) [64-bit]
++ Authored by: RWC et al.
Usage: 1dplot [options] tsfile ...
Graphs the columns of a *.1D time series file to the X11 screen.

-------
OPTIONS
-------
 -install   = Install a new X11 colormap.
 -sep       = Plot each column in a separate sub-graph.
 -one       = Plot all columns together in one big graph.
                [default = -sep]
 -sepscl    = Plot each column in a separate sub-graph
              and allow each sub-graph to have a different
              y-scale.  -sepscl is meaningless with -one!
 -noline    = Don't plot the connecting lines (also implies '-box').
 -NOLINE    = Same as '-noline', but will not try to plot values outside
              the rectangular box that contains the graph axes.
 -box       = Plot a small 'box' at each data point, in addition
              to the lines connecting the points.
             * The box size can be set via the environment variable
               AFNI_1DPLOT_BOXSIZE; the value is a fraction of the
               overall plot size.  The standard box size is 0.006.
               Example with a bigger box:
                 1dplot -DAFNI_1DPLOT_BOXSIZE=0.01 -box A.1D
             * The box shapes are different for different time
               series columns.  At present, there is no way to
               control which shape is used for what column
               (unless you modify the source code, that is).
             * You can set environment variable AFNI_1DPLOT_RANBOX
               to YES to get the '-noline' boxes plotted in a
               pseudo-random order, so that one particular color
               doesn't dominate just because it is last in the
               plotting order; for example:
        1dplot -DAFNI_1DPLOT_RANBOX=YES -one -x X.1D -noline Y1.1D Y2.1D Y3.1D

 -hist      = Plot graphs in histogram style (i.e., vertical boxes).
             * Histograms can be generated from 3D or 1D files using
               program 3dhistog; for example
                3dhistog -nbin 50 -notitle -min 0 -max .04 err.1D > eh.1D
                1dplot -hist -x eh.1D'[0]' -xlabel err -ylabel hist eh.1D'[1]'
               or, for something a little more fun looking:
                1dplot -one -hist -dashed 1:2 -x eh.1D'[0]' \
                       -xlabel err -ylabel hist eh.1D'[1]' eh.1D'[1]'

           ** The '-norm' options below can be useful for plotting data
               with different value ranges on top of each other via '-one':
 -norm2     = Independently scale each time series plotted to
              have L_2 norm = 1 (sum of squares).
 -normx     = Independently scale each time series plotted to
              have max absolute value = 1 (L_infinity norm).
 -norm1     = Independently scale each time series plotted to
              have max sum of absolute values = 1 (L_1 norm).
 -demean    = This option will remove the mean from each time series
              (before normalizing).  The combination '-demean -normx -one'
              can be useful when plotting disparate data together.
             * If you use '-demean' twice, you will get linear detrending.
             * Et cetera (e.g,, 4 times gives you cubic detrending.)

 -x  X.1D   = Use for X axis the data in X.1D.
              Note that X.1D should have one column
              of the same length as the columns in tsfile. 
            ** Coupled with '-box -noline', you can use '-x' to make
               a scatter plot, as in graphing file A1.1D along the
               x-axis and file A2.1D along the y-axis:
                 1dplot -box -noline -x A1.1D -xlabel A1 -ylabel A2 A2.1D
            ** '-x' will override -dx and -xzero; -xaxis still works

 -xl10 X.1D = Use log10(X.1D) as the X axis.

 -xmulti X1.1D X2.1D ...
              This new [Oct 2013] option allows you to plot different
              columns from the data with different values along the
              x-axis.  You can supply one or more 1D files after the
              '-xmulti' option.  The columns from these files are
              catenated, and then the first xmulti column is used as
              as x-axis values for the first data column plotted, the
              second xmulti column gives the x-axis values for the
              second data column plotted, and so on.
           ** The command line arguments after '-xmulti' are taken
              as 1D filenames to read, until an argument starts with
              a '-' character -- this would either be another option,
              or just a single '-' to separate the xmulti 1D files
              from the data files to be plotted.
           ** If you don't provide enough xmulti columns for all the
              data files, the last xmulti column will be re-used.
           ** Useless but fun example:
               1deval -num 100 -expr '(i-i)+z+gran(0,6)' > X1.1D
               1deval -num 100 -expr '(i-i)+z+gran(0,6)' > X2.1D
               1dplot -one -box -xmulti X1.1D X2.1D - X2.1D X1.1D

 -dx xx     = Spacing between points on the x-axis is 'xx'
                [default = 1] SYNONYMS: '-dt' and '-del'
 -xzero zz  = Initial x coordinate is 'zz' [default = 0]
                SYNONYMS: '-tzero' and '-start'
 -nopush    = Don't 'push' axes ranges outwards.
 -ignore nn = Skip first 'nn' rows in the input file
                [default = 0]
 -use mm    = Plot 'mm' points [default = all of them]
 -xlabel aa = Put string 'aa' below the x-axis
                [default = no axis label]
 -ylabel aa = Put string 'aa' to the left of the y-axis
                [default = no axis label]
 -plabel pp = Put string 'pp' atop the plot.
              Some characters, such as '_' have
              special formatting effects. You 
              can escape that with ''. For example:
        echo 2 4.5 -1 | 1dplot -plabel 'test_underscore' -stdin
              versus
        echo 2 4.5 -1 | 1dplot -plabel 'test\_underscore' -stdin
 -title pp = Same as -plabel, but only works with -ps/-png/-jpg/-pnm options.
 -wintitle pp = Set string 'pp' as the title of the frame 
                containing the plot. Default is based on input.

 -naked     = Do NOT plot axes or labels, just the graph(s).
              You might want to use '-nopush' with '-naked'.
 -aspect A  = Set the width-to-height ratio of the plot region to 'A'.
              Default value is 1.3. Larger 'A' means a wider graph.

 -stdin     = Don't read from tsfile; instead, read from
              stdin and plot it. You cannot combine input
              from stdin and tsfile(s).  If you want to do so,
              use program 1dcat first.

 -ps        = Don't draw plot in a window; instead, write it
              to stdout in PostScript format.
             * If you view the result in 'gv', you should turn
               'anti-alias' off, and switch to landscape mode.
             * You can use the 'gs' program to convert PostScript
               to other formats; for example, a .bmp file:
            1dplot -ps ~/data/verbal/cosall.1D | 
             gs -r100 -sOutputFile=fred.bmp -sDEVICE=bmp256 -q -dBATCH -

 -jpg fname  } = Render plot to an image and save to a file named
 -jpeg fname } = 'fname', in JPEG mode or in PNG mode or in PNM mode.
 -png fname  } = The default image width is 1024 pixels; to change
 -pnm fname  } = this value to 2000 pixels (say), do
                   setenv AFNI_1DPLOT_IMSIZE 2000
                 before running 1dplot.  Widths over 2000 may start
                 to look odd, and will run more slowly.
               * PNG files will be smaller than JPEG, and are
                 compressed without loss.
               * PNG output requires that the netpbm program
                 pnmtopng be installed somewhere in your PATH.
               * PNM output files are not compressed, and are manipulable
                 by the netpbm package: http://netpbm.sourceforge.net/

 -pngs SIZE fname } = a convenience function equivalent to
 -jpgs SIZE fname } = setenv AFNI_1DPLOT_IMSIZE SIZE and 
 -jpegs SIZE fname} = -png (or -jpg or -pnm) fname
 -pnms SIZE fname }

 -ytran 'expr'   = Transform the data along the y-axis by
                   applying the expression to each input value.
                   For example:
                     -ytran 'log10(z)'
                   will take log10 of each input time series value
                   before plotting it.
                 * The expression should have one variable (any letter
                   from a-z will do), which stands for the time series
                   data to be transformed.
                 * An expression such as 'sqrt(x*x+i)' will use 'x'
                   for the time series value and use 'i' for the time
                   index (starting at 0) -- in this way, you can use
                   time-dependent transformations, if needed.
                 * This transformation applies to all input time series
                   (at present, there is no way to transform different
                   time series in distinct ways inside 1dplot).
                 * '-ytran' is applied BEFORE the various '-norm' options.

 -xtran 'expr'    = Similar, but for the x-axis.
                  ** Applies to '-xmulti' , '-x' , or the default x-axis.

 -xaxis b:t:n:m  = Set the x-axis to run from value 'b' to
                   value 't', with 'n' major divisions and
                   'm' minor tic marks per major division.
                   For example:
                     -xaxis 0:100:5:20
                   Setting 'n' to 0 means no tic marks or labels.
                 * You can set 'b' to be greater than 't', to
                   have the x-coordinate decrease from left-to-right.
                 * This is the only way to have this effect in 1dplot.
                 * In particular, '-dx' with a negative value will not work!

 -yaxis b:t:n:m  = Similar to above, for the y-axis.  These
                   options override the normal autoscaling
                   of their respective axes.

 -ynames a b ... = Use the strings 'a', 'b', etc., as
                   labels to the right of the graphs,
                   corresponding to each input column.
                   These strings CANNOT start with the
                   '-' character.
             N.B.: Each separate string after '-ynames'
                   is taken to be a new label, until the
                   end of the command line or until some
                   string starts with a '-'.  In particular,
                   This means you CANNOT do something like
                     1dplot -ynames a b c file.1D
                   since the input filename 'file.1D' will
                   be used as a label string, not a filename.
                   Instead, you must put another option between
                   the end of the '-ynames' label list, OR you
                   can put a single '-' at the end of the label
                   list to signal its end:
                     1dplot -ynames a b c - file.1D
        TSV files: When plotting a TSV file, where the first row
                   is the set of column labels, you can use this
                   Unix trick to put the column labels here:
                     -ynames `head -1 file.tsv`
                   The 'head' command copies just the first line
                   of the file to stdout, and the backquotes `...`
                   capture stdout and put it onto the command line.
                 * You might need to put a single '-' after this
                   option to prevent the problem alluded to above.
                   In any case, it can't hurt to use '-' as an option
                   after '-ynames'.
                 * If any of the TSV labels start with the '-' character,
                   peculiar and unpleasant things might transpire.

 -volreg         = Makes the 'ynames' be the same as the
                   6 labels used in plug_volreg for
                   Roll, Pitch, Yaw, I-S, R-L, and A-P
                   movements, in that order.

 -thick          = Each time you give this, it makes the line
                   thickness used for plotting a little larger.
                   [An alternative to using '-DAFNI_1DPLOT_THIK=...']
 -THICK          = Twice the power of '-thick' at no extra cost!!

 -dashed codes   = Plot dashed lines between data points.  The 'codes'
                   are a colon-separated list of dash values, which
                   can be 1 (solid), 2 (longer dashes), or 3 (shorter dashes).
                ** Example: '-dashed 1:2:3' means to plot the first time
                   series with solid lines, the second with long dashes,
                   and the third with short dashes.

 -Dname=val      = Set environment variable 'name' to 'val'
                   for this run of the program only:
 1dplot -DAFNI_1DPLOT_THIK=0.01 -DAFNI_1DPLOT_COLOR_01=blue '1D:3 4 5 3 1 0'

You may also select a subset of columns to display using
a tsfile specification like 'fred.1D[0,3,5]', indicating
that columns #0, #3, and #5 will be the only ones plotted.
For more details on this selection scheme, see the output
of '3dcalc -help'.

Example: graphing a 'dfile' output by 3dvolreg, when TR=5:
   1dplot -volreg -dx 5 -xlabel Time 'dfile[1..6]'

You can also input more than one tsfile, in which case the files
will all be plotted.  However, if the files have different column
lengths, the shortest one will rule.

The colors for the line graphs cycle between black, red, green, and
blue.  You can alter these colors by setting Unix environment
variables of the form AFNI_1DPLOT_COLOR_xx -- cf. README.environment.
You can alter the thickness of the lines by setting the variable
AFNI_1DPLOT_THIK to a value between 0.00 and 0.05 -- the units are
fractions of the page size; of course, you can also use the options
'-thick' or '-THICK' if you prefer.

----------------
RENDERING METHOD
----------------
On 30 Apr 2012, a new method of rendering the 1dplot graph into an X11
window was introduced -- this method uses 'anti-aliasing' to produce
smoother-looking lines and characters.  If you want the old coarser-looking
rendering method, set environment variable AFNI_1DPLOT_RENDEROLD to YES.

The program always uses the new rendering method when drawing to a JPEG
or PNG or PNM file (which is not and never has been just a screen capture).
There is no way to disable the new rendering method for image-file saves.

------
LABELS
------
Besides normal alphabetic text, the various labels can include some
special characters, using TeX-like escapes starting with '\'.
Also, the '^' and '_' characters denote super- and sub-scripts,
respectively.  The following command shows many of the escapes:
 1deval -num 100 -expr 'J0(t/4)' | 1dplot -stdin -thick \
 -xlabel '\alpha\beta\gamma\delta\epsilon\zeta\eta^{\oplus\dagger}\times c' \
 -ylabel 'Bessel Function \green J_0(t/4)'     \
 -plabel '\Upsilon\Phi\Chi\Psi\Omega\red\leftrightarrow\blue\partial^{2}f/\partial x^2'

TIMESERIES (1D) INPUT
---------------------
A timeseries file is in the form of a 1D or 2D table of ASCII numbers;
for example:   3 5 7
               2 4 6
               0 3 3
               7 2 9
This example has 4 rows and 3 columns.  Each column is considered as
a timeseries in AFNI.  The convention is to store this type of data
in a filename ending in '.1D'.

** COLUMN SELECTION WITH [] **
When specifying a timeseries file to an command-line AFNI program, you
can select a subset of columns using the '[...]' notation:
  'fred.1D[5]'            ==> use only column #5
  'fred.1D[5,9,17]'       ==> use columns #5, #9, and #17
  'fred.1D[5..8]'         ==> use columns #5, #6, #7, and #8
  'fred.1D[5..13(2)]'     ==> use columns #5, #7, #9, #11, and #13
Column indices start at 0.  You can use the character '$'
to indicate the last column in a 1D file; for example, you
can select every third column in a 1D file by using the selection list
  'fred.1D[0..$(3)]'      ==> use columns #0, #3, #6, #9, ....

** ROW SELECTION WITH {} **
Similarly, you select a subset of the rows using the '{...}' notation:
  'fred.1D{0..$(2)}'      ==> use rows #0, #2, #4, ....
You can also use both notations together, as in
  'fred.1D[1,3]{1..$(2)}' ==> columns #1 and #3; rows #1, #3, #5, ....

** DIRECT INPUT OF DATA ON THE COMMAND LINE WITH 1D: **
You can also input a 1D time series 'dataset' directly on the command
line, without an external file. The 'filename' for such input has the
general format
  '1D:n_1@val_1,n_2@val_2,n_3@val_3,...'
where each 'n_i' is an integer and each 'val_i' is a float.  For
example
   -a '1D:5@0,10@1,5@0,10@1,5@0'
specifies that variable 'a' be assigned to a 1D time series of 35,
alternating in blocks between values 0 and value 1.
 * Spaces or commas can be used to separate values.
 * A '|' character can be used to start a new input "line":
   Try 1dplot '1D: 3 4 3 5 | 3 5 4 3'

** TRANSPOSITION WITH \' **
Finally, you can force most AFNI programs to transpose a 1D file on
input by appending a single ' character at the end of the filename.
N.B.: Since the ' character is also special to the shell, you'll
      probably have to put a \ character before it. Examples:
       1dplot '1D: 3 2 3 4 | 2 3 4 3'   and
       1dplot '1D: 3 2 3 4 | 2 3 4 3'\'
When you have reached this level of understanding, you are ready to
take the AFNI Jedi Master test.  I won't insult you by telling you
where to find this examination.

TAB SEPARATED VALUE (.tsv) FILES [Sep 2018]
-------------------------------------------
These files are used in BIDS http://bids.neuroimaging.io and AFNI
programs can read these in a few places.

The format of a .tsv file is a set of columns, where the values in
each row are separated by tab characters -- spaces are NOT separators.
Each element is string, some of which are numeric (e.g. 3.1416).
The first row of a .tsv file is a set of strings which are column
desciptors (separated by tabs, of course). For the most part, the
following data in each column are exclusively numeric or exclusively
strings. Strings can contain blanks/spaces since only tabs are used
to separate values.

A .tsv file can be read in most places where a .1D file is read.
However, columns (after the header row) that are not purely numeric
will be ignored, since the internal usage of .1D data in AFNI is numeric.
Thus, you can do something like
  1dplot -nopush -sepscl sub-10506_task-pamenc_events.tsv
and you will get a plot of all the numeric columns in this BIDS file.
Column selection '[]' can be done, using numbers to specify columns
or using the column labels in the .tsv file.

N.B.: The string 'N/A' or 'n/a' in a column that is otherwise numeric
      will be considered to be a number, and will be replaced on input
      with the mean of the "true" numbers in the column -- there is
      no concept of missing data in an AFNI .1D file.
    ++ If you don't like this, well ... too bad for you.

Program 1dcat has special knowledge of .tsv files, and will cat
(sideways - along rows) .tsv and .1D files together. It also has an
option to write the output in .tsv format.

For example, to get the 'onset', 'duration', and 'trial_type' columns
out of a BIDS task .tsv file, a command like this could be used:
  1dcat sub-10506_task-pamenc_events.tsv'[onset,duration,trial_type]'
Note that the column headers are lost in this output, but could be kept
if the 1dcat '-tsvout' option were used. In reverse, a numeric .1D file
can be converted to .tsv format by a command like:
  1dcat -tsvout Fred.1D
In this case, since a the data for .1D file doesn't have headers for its
columns, 1dcat will invent some column names.

At this time, other programs don't 'know' much about .tsv files, and will
ignore the header row and non-numeric columns when reading a .tsv file.
in place of a .1D file.

--------------
MARKING BLOCKS (e.g., censored time points)
--------------
The following options let you mark blocks along the x-axis, by drawing
colored vertical boxes over the standard white background.
 * The intended use is to mark blocks of time points that are censored
   out of an analysis, which is why the options are the same as those
   in 3dDeconvolve -- but you can mark blocks for any reason, of course.
 * These options don't do anything when the '-x' option is used to
   alter the x-axis spacings.
 * To see what the various color markings look like, try this silly example:

   1deval -num 100 -expr 'lran(2)' > zz.1D
   1dplot -thick -censor_RGB red    -CENSORTR 3-8   \
                 -censor_RGB green  -CENSORTR 11-16 \
                 -censor_RGB blue   -CENSORTR 22-27 \
                 -censor_RGB yellow -CENSORTR 34-39 \
                 -censor_RGB violet -CENSORTR 45-50 \
                 -censor_RGB pink   -CENSORTR 55-60 \
                 -censor_RGB gray   -CENSORTR 65-70 \
                 -censor_RGB #2cf   -CENSORTR 75-80 \
          -plabel 'red green blue yellow violet pink gray #2cf' zz.1D &

 -censor_RGB clr   = set the color used for the marking to 'clr', which
                     can be one of the strings below:
                       red green blue yellow violet pink gray (OR grey)
                   * OR 'clr' can be in the form '#xyz' or '#xxyyzz', where
                     'x', 'y', and 'z' are hexadecimal digits -- for example,
                     '#2cf' is sort of a cyan color.
                   * OR 'clr' can be in the form 'rgbi:rf/gf/bf' where
                     each color intensity (rf, gf, bf) is a number between
                     0.0 and 1.0 -- e.g., white is 'rgbi:1.0/1.0/1.0'.
                     Since the background is white, dark colors don't look
                     good here, and will obscure the graphs; for example,
                     pink is defined here as 'rgbi:1.0/0.5/0.5'.
                   * The default color is (a rather pale) yellow.
                   * You can use '-censor_RGB' more than once.  The color
                     most recently specified previous on the command line
                     is what will be used with the '-censor' and '-CENSORTR'
                     options.  This allows you to mark different blocks
                     with different colors (e.g., if they were censored
                     for different reasons).
                   * The feature of allowing multiple '-censor_RGB' options
                     means that you must put this option BEFORE the
                     relevant '-censor' and/or '-CENSORTR' options.
                     Otherwise, you'll get the default yellow color!

 -censor cname     = cname is the filename of censor .1D time series   
                   * This is a file of 1s and 0s, indicating which     
                     time points are to be un-marked (1) and which are 
                     to be marked (0).                                 
                   * Please note that only one '-censor' option can be 
                     used, for compatibility with 3dDeconvolve.        
                   * The option below may be simpler to use!           
                     (And can be used multiple times.)                 

 -CENSORTR clist   = clist is a list of strings that specify time indexes
                     to be marked in the graph(s).  Each string is of  
                     one of the following forms:                       
                           37 => mark global time index #37            
                         2:37 => mark time index #37 in run #2         
                       37..47 => mark global time indexes #37-47       
                       37-47  => same as above                         
                     *:0-2    => mark time indexes #0-2 in all runs    
                     2:37..47 => mark time indexes #37-47 in run #2    
                   * Time indexes within each run start at 0.          
                   * Run indexes start at 1 (just be to confusing).    
                   * Multiple -CENSORTR options may be used, or        
                     multiple -CENSORTR strings can be given at        
                     once, separated by spaces or commas.              
                   * Each argument on the command line after           
                     '-CENSORTR' is treated as a censoring string,     
                     until an argument starts with a '-' or an         
                     alphabetic character, or it contains the substring
                     '1D'.  This means that if you want to plot a file 
                     named '9zork.xyz', you may have to do this:       
                       1dplot -CENSORTR 3-7 18-22 - 9zork.xyz          
                     The stand-alone '-' will stop the processing      
                     of censor strings; otherwise, the '9zork.xyz'     
                     string, since it doesn't start with a letter,     
                     would be treated as a censoring string, which     
                     you would find confusing.                         
                  ** N.B.: 2:37,47 means index #37 in run #2 and       
                     global time index 47; it does NOT mean            
                     index #37 in run #2 AND index #47 in run #2.      

 -concat rname      = rname is the filename for list of concatenated runs
                      * 'rname' can be in the format                   
                          '1D: 0 100 200 300'                          
                        which indicates 4 runs, the first of which     
                        starts at time index=0, second at index=100,   
                        and so on.                                     
                      * The ONLY function of '-concat' is for use with 
                        '-CENSORTR', to be compatible with 3dDeconvolve
                          [e.g., for plotting motion parameters from]
                          [3dvolreg -1Dfile, where you've cat-enated]
                          [the 1D files from separate runs into one ]
                          [long file for plotting with this program.]

 -rbox x1 y1 x2 y2 color1 color2
                    = Draw a rectangular box with corners (x1,y1) to
                      (x2,y2), in color1, with an outline in color2.
                      Colors are names, such as 'green'.
                        [This option lets you make bar]
                        [charts, *if* you care enough.]

 -Rbox x1 y1 x2 y2 y3 color1 color2
                    = As above, with an extra horizontal line at y3.

 -line x1 y1 x2 y2 color dashcode
                    = Draw one line segment.

Another fun fun example:

  1dplot -censor_RGB #ffa -CENSORTR '0-99'           \
         `1deval -1D: -num 61 -dx 0.3 -expr 'J0(x)'`

which illustrates the use of 'censoring' to mark the entire graph
background in pale yellow '#ffa', and also illustrates the use
of the '-1D:' option in 1deval to produce output that can be
used directly on the command line, via the backquote `...` operator.


++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dplot.py
Traceback (most recent call last):
  File "/home/afniHQ/afni.build/pub.dist/bin/linux_ubuntu_16_64/1dplot.py", line 18, in <module>
    import lib_plot_1D as lpod
  File "/home/afniHQ/afni.build/pub.dist/bin/linux_ubuntu_16_64/lib_plot_1D.py", line 20, in <module>
    import matplotlib.pyplot  as plt
ImportError: No module named matplotlib.pyplot



AFNI program: 1dsound

Usage: 1dsound [options] tsfile

Program to create a sound file from a 1D file (column of numbers).

Is this program useful? Probably not, but it can be fun.

-------
OPTIONS
-------

 ===== output filename =====

 -prefix ppp  = Output filename will be ppp.au
                [Sun audio format https://en.wikipedia.org/wiki/Au_file_format]
                + If you don't use '-prefix', the output is file 'sound.au'.
                + If 'ppp' ends in '.au', this program won't add another '.au.

 ===== encoding details =====

 -16PCM       = Output in 16-bit linear PCM encoding (uncompressed)
                + Less quantization noise (audible hiss)            :)
                + Takes twice as much disk space for output as 8-bit output :(
              +++ This is the default method now!
                + https://en.wikipedia.org/wiki/Pulse-code_modulation

 -8PCM        = Output in 8-bit linear PCM encoding
                + There is no good reason to use this option.

 -8ulaw       = Output in 8-bit mu-law encoding.
                + Provides a little better quality than -8PCM,
                  but still has audible quantization noise hiss.
                +  https://en.wikipedia.org/wiki/M-law_algorithm

 -tper X      = X seconds of sound per time point in 'tsfile'.
 -TR X          Allowed range for 'X' is 0.01 to 1.0 (inclusive).
 -dt X          [default time step is 0.2 s]
                You can use '-tper', '-dt', or '-TR', as you like.

 ===== how the sound timeseries is produced from the data timeseries =====

 -FM          = Output sound is frequency modulated between 110 and 1760 Hz
                from min to max in the input 1D file.
                + Usually 'sounds terrible'.
                + The only reason this is here is that it was the first method
                  I implemented, and I kept it for the sake of nostalgia.

 -notes       = Output sound is a sequence of notes, low to high pitch
                based on min to max in the input 1D file.
              +++ This is the default method of operation.
                + A pentatonic scale is used, which usually 'sounds nice':
                  https://en.wikipedia.org/wiki/Pentatonic_scale

 -notewave W  = Selects the shape of the notes used. 'W' is one of these:
 -waveform W      sine     = pure sine wave (sounds simplistic)
                  sqsine   = square root of sine wave (a little harsh and loud)
                  square   = square wave              (a lot harsh and loud)
                  triangle = triangle wave            [the default waveform]

 -despike     = apply a simple despiking algorithm, to avoid the artifact
                of one very large or small value making all the other notes
                end up being the same.

 ===== Notes about notes =====

 ** At this time, the default production method is '-notes',      **
 **               using the triangle waveform (I like this best). **

 ** With '-notes', up to 6 columns of the input file will be used **
 ** to produce a polyphonic sound (in a single channel).          **
 ** (Any columns past the 6th in the input 'tsfile' are ignored.) **

 ===== hear the sound right away! =====

 -play        = Plays the sound file after it is written.
                On this computer: uses program /usr/bin/mplayer
            ===>> Playing sound on a remote computer is
                  annoying, pointless, and likely to get you punched.

--------
EXAMPLES
--------
The first 2 examples are purely synthetic, using 'data' files created
on the command line. The third example uses a data file that was written
out of an AFNI graph viewer using the 'w' keystroke.

 1dsound -prefix A1 '1D: 0 1 2 1 0 1 2 0 1 2'

 1deval -num 100 -expr 'sin(x+0.01*x*x)' | 1dsound -tper 0.1 -prefix A2 1D:stdin

 1dsound -prefix -tper 0.1 A3 028_044_003.1D

-----
NOTES
-----
* File can be played with the 'sox' audio package command
    play A1.au gain -5
  + Here 'gain -5' turns the volume down :)
  + sox is not provided with AFNI :(
  + To see if sox is on your system, type the command 'which sox'
  + If you have sox, you can add 'reverb 99' at the end of the
    'play' command line, and have some extra fun.
  + Many other effects are available with sox 'play',
    and they can also be used to produce edited sound files:
    http://sox.sourceforge.net/sox.html#EFFECTS
  + You can convert the .au file produced from here to other
    formats using sox; for example:
      sox Bob.au Cox.au BobCox.aiff
    combines the 2 .au input files to a 2-channel (stereo)
    Apple .aiff output file. See this for more information:
    http://sox.sourceforge.net/soxformat.html

* Creation of the file does not depend on sox, so if you have
  another way to play .au files, you can use that.
  * Mac OS X: Quicktime (GUI) or afplay (command line) programs.
              + sox can be installed by first installing 'brew'
                -- see https://brew.sh/ -- and then using command
                'brew install sox'.
  * Linux:    Getting sox is probably the simplest thing to do.
              + Or install the mplayer package (which also does videos).
              + Another possibility is the aplay program.

* The audio output file is sampled at 16K bytes per second.
  For example, a 30 second file will be 960K bytes in size,
  at 16 bits per sample.

* The auditory effect varies significantly with the '-tper'
  parameter X; '-tper 0.02' is very different than '-tper 0.4'.

--- Quick hack for experimentation and fun - RWCox - Aug 2018 ---




AFNI program: 1dsum
Usage: 1dsum [options] a.1D b.1D ...
where each file a.1D, b.1D, etc. is an ASCII file of numbers arranged
in rows and columns. The sum of each column is written to stdout.

Options:
  -ignore nn = skip the first nn rows of each file
  -use    mm = use only mm rows from each file
  -mean      = compute the average instead of the sum
  -nocomment = the # comments from the header of the first
               input file will be reproduced to the output;
               if you do NOT want this to happen, use the
               '-nocomment' option.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dsvd
Usage: 1dsvd [options] 1Dfile 1Dfile ...
- Computes SVD of the matrix formed by the 1D file(s).
- Output appears on stdout; to save it, use '>' redirection.

OPTIONS:
 -one    = Make 1st vector be all 1's.
 -vmean  = Remove mean from each vector (can't be used with -one).
 -vnorm  = Make L2-norm of each vector = 1 before SVD.
           * The above 2 options mirror those in 3dpc.
 -cond   = Only print condition number (ratio of extremes)
 -sing   = Only print singular values
           * To compare the singular values from 1dsvd with those from
             3dDeconvolve you must use the -vnorm option with 1dsvd.
             For example, try
               3dDeconvolve -nodata 200 1 -polort 5 -num_stimts 1 \
                            -stim_times 1 '1D: 30 130' 'BLOCK(50,1)' -singvals
               1dsvd -sing -vnorm nodata.xmat.1D
 -sort   = Sort singular values (descending) [the default]
 -nosort = Don't bother to sort the singular values
 -asort  = Sort singular values (ascending)
 -1Dleft = Only output left eigenvectors, in a .1D format
           This might be useful for reducing the number of
           columns in a design matrix.  The singular values
           are printed at the top of each vector column,
           as a '#...' comment line.
 -nev n  = If -1Dleft is used, '-nev' specifies to output only
           the first 'n' eigenvectors, rather than all of them.
           * If you are a tricky person, such as Souheil, you can
             put a '%' after the value, and then you are saying
             keep eigenvectors until at least n% of the sum of
             singular values is accounted for.  In this usage,
             'n' must be a number less than 100; for example, to
             reduce a matrix down to a smaller set of columns that
             capture most of its column space, try something like
               1dsvd -1Dleft -nev 99% Xorig.1D > X99.1D
EXAMPLE:
 1dsvd -vmean -vnorm -1Dleft fred.1D'[1..6]' | 1dplot -stdin
NOTES:
* Call the input n X m matrix [A] (n rows, m columns).  The SVD
  is the factorization [A] = [U] [S] [V]' ('=transpose), where
  - [U] is an n x m matrix (whose columns are the 'Left vectors')
  - [S] is a diagonal m x m matrix (the 'singular values')
  - [V] is an m x m matrix (whose columns are the 'Right vectors')
* The default output of the program is
  - An echo of the input [A]
  - The [U] matrix, each column headed by its singular value
  - The [V] matrix, each column headed by its singular value
    (please note that [V] is output, not [V]')
  - The pseudo-inverse of [A]
* This program was written simply for some testing purposes,
  but is distributed with AFNI because it might be useful-ish.
* Recall that you can transpose a .1D file on input by putting
  an escaped ' character after the filename.  For example,
    1dsvd fred.1D\'
  You can use this feature to get around the fact that there
  is no '-1Dright' option.  If you understand.
* For more information on the SVD, you can start at
  http://en.wikipedia.org/wiki/Singular_value_decomposition
* Author: Zhark the Algebraical (Linear).

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 1dtranspose
Usage: 1dtranspose infile outfile
where infile is an AFNI *.1D file (ASCII list of numbers arranged
in columns); outfile will be a similar file, but transposed.
You can use a column subvector selector list on infile, as in
  1dtranspose 'fred.1D[0,3,7]' ethel.1D

* This program may produce files with lines longer than a
   text editor can handle.
* If 'outfile' is '-' (or missing entirely), output goes to stdout.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 24swap
Usage: 24swap [options] file ...
Swaps bytes pairs and/or quadruples on the files listed.
Options:
 -q            Operate quietly
 -pattern pat  'pat' determines the pattern of 2 and 4
                 byte swaps.  Each element is of the form
                 2xN or 4xN, where N is the number of
                 bytes to swap as pairs (for 2x) or
                 as quadruples (for 4x).  For 2x, N must
                 be divisible by 2; for 4x, N must be
                 divisible by 4.  The whole pattern is
                 made up of elements separated by colons,
                 as in '-pattern 4x39984:2x0'.  If bytes
                 are left over after the pattern is used
                 up, the pattern starts over.  However,
                 if a byte count N is zero, as in the
                 example below, then it means to continue
                 until the end of file.

 N.B.: You can also use 1xN as a pattern, indicating to
         skip N bytes without any swapping.
 N.B.: A default pattern can be stored in the Unix
         environment variable AFNI_24SWAP_PATTERN.
         If no -pattern option is given, the default
         will be used.  If there is no default, then
         nothing will be done.
 N.B.: If there are bytes 'left over' at the end of the file,
         they are written out unswapped.  This will happen
         if the file is an odd number of bytes long.
 N.B.: If you just want to swap pairs, see program 2swap.
         For quadruples only, see program 4swap.
 N.B.: This program will overwrite the input file!
         You might want to test it first.

 Example: 24swap -pat 4x8:2x0 fred
          If fred contains 'abcdabcdabcdabcdabcd' on input,
          then fred has    'dcbadcbabadcbadcbadc' on output.



AFNI program: 2dImReg
++ 2dImReg: AFNI version=AFNI_18.3.16 (Dec 11 2018) [64-bit]
This program performs 2d image registration.  Image alignment is      
performed on a slice-by-slice basis for the input 3d+time dataset,    
relative to a user specified base image.                              

 ** Note that the script @2dwarper.Allin can do similar things, **
 ** with nonlinear (polynomial) warping on a slice-wise basis.  **
                                                                      
Usage:                                                                
2dImReg                                                               
-input fname           Filename of input 3d+time dataset to process   
-basefile fname        Filename of 3d+time dataset for base image     
                         (default = current input dataset)            
-base num              Time index for base image  (0 <= num)          
                         (default:  num = 3)                          
-nofine                Deactivate fine fit phase of image registration
                         (default:  fine fit is active)               
-fine blur dxy dphi    Set fine fit parameters                        
   where:                                                             
     blur = FWHM of blurring prior to registration (in pixels)        
               (default:  blur = 1.0)                                 
     dxy  = Convergence tolerance for translations (in pixels)        
               (default:  dxy  = 0.07)                                
     dphi = Convergence tolerance for rotations (in degrees)          
               (default:  dphi = 0.21)                                
                                                                      
-prefix pname     Prefix name for output 3d+time dataset              
                                                                      
-dprefix dname    Write files 'dname'.dx, 'dname'.dy, 'dname'.psi     
                    containing the registration parameters for each   
                    slice in chronological order.                     
                    File formats:                                     
                      'dname'.dx:    time(sec)   dx(pixels)           
                      'dname'.dy:    time(sec)   dy(pixels)           
                      'dname'.psi:   time(sec)   psi(degrees)         
-dmm              Change dx and dy output format from pixels to mm    
                                                                      
-rprefix rname    Write files 'rname'.oldrms and 'rname'.newrms       
                    containing the volume RMS error for the original  
                    and the registered datasets, respectively.        
                    File formats:                                     
                      'rname'.oldrms:   volume(number)   rms_error    
                      'rname'.newrms:   volume(number)   rms_error    
                                                                      
-debug            Lots of additional output to screen                 



AFNI program: 2perm
Usage: 2perm [-prefix PPP] [-comma] bot top [n1 n2]

This program creates 2 random non-overlapping subsets of the set of
integers from 'bot' to 'top' (inclusive).  The first subset is of
length 'n1' and the second of length 'n2'.  If those values are not
given, then equal size subsets of length (top-bot+1)/2 are used.

This program is intended for use in various simulation and/or
randomization scripts, or for amusement/hilarity.

OPTIONS:
========
 -prefix PPP == Two output files are created, with names PPP_A and PPP_B,
                where 'PPP' is the given prefix.  If no '-prefix' option
                is given, then the string 'AFNIroolz' will be used.
                ++ Each file is a single column of numbers.
                ++ Note that the filenames do NOT end in '.1D'.

 -comma      == Write each file as a single row of comma-separated numbers.

EXAMPLE:
========
This illustration shows the purpose of 2perm -- for use in permutation
and/or randomization tests of statistical significance and power.
Given a dataset with 100 sub-bricks (indexed 0..99), split it into two
random halves and do a 2-sample t-test between them.

  2perm -prefix Q50 0 99
  3dttest++ -setA dataset+orig"[1dcat Q50_A]" \
            -setB dataset+orig"[1dcat Q50_B]" \
            -no1sam -prefix Q50
  \rm -f Q50_?

Alternatively:

  2perm -prefix Q50 -comma 0 99
  3dttest++ -setA dataset+orig"[`cat Q50_A`]" \
            -setB dataset+orig"[`cat Q50_B`]" \
            -no1sam -prefix Q50
  \rm -f Q50_?

Note the combined use of the double quote " and backward quote `
shell operators in this second approach.

AUTHOR: (no one want to admit they wrote this trivial code).

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 2swap
Usage: 2swap [-q] file ...
-- Swaps byte pairs on the files listed.
   The -q option means to work quietly.



AFNI program: 3dABoverlap
Usage: 3dABoverlap [options] A B
Output (to screen) is a count of various things about how
the automasks of datasets A and B overlap or don't overlap.

* Dataset B will be resampled to match dataset A, if necessary,
   which will be slow if A is high resolution.  In such a case,
   you should only use one sub-brick from dataset B.
  ++ The resampling of B is done before the automask is generated.
* The values output are labeled thusly:
    #A         = number of voxels in the A mask
    #B         = number of voxels in the B mask
    #(A uni B) = number of voxels in the either or both masks (set union)
    #(A int B) = number of voxels present in BOTH masks (set intesection)
    #(A \ B)   = number of voxels in A mask that aren't in B mask
    #(B \ A)   = number of voxels in B mask that arent' in A mask
    %(A \ B)   = percentage of voxels from A mask that aren't in B mask
    %(B \ A)   = percentage of voxels from B mask that aren't in A mask
    Rx(B/A)    = radius of gyration of B mask / A mask, in x direction
    Ry(B/A)    = radius of gyration of B mask / A mask, in y direction
    Rz(B/A)    = radius of gyration of B mask / A mask, in z direction
* If B is an EPI dataset sub-brick, and A is a skull stripped anatomical
   dataset, then %(B \ A) might be useful for assessing if the EPI
   brick B is grossly misaligned with respect to the anatomical brick A.
* The radius of gyration ratios might be useful for determining if one
   dataset is grossly larger or smaller than the other.

OPTIONS
-------
 -no_automask = consider input datasets as masks
                (automask does not work on mask datasets)
 -quiet = be as quiet as possible (without being entirely mute)
 -verb  = print out some progress reports (to stderr)

NOTES
-----
 * If an input dataset is comprised of bytes and contains only one
   sub-brick, then this program assumes it is already an automask-
   generated dataset and the automask operation will be skipped.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAFNIto3D
*+ WARNING: This program (3dAFNIto3D) is old, not maintained, and probably useless!
Usage: 3dAFNIto3D [options] dataset
Reads in an AFNI dataset, and writes it out as a 3D file.

OPTIONS:
 -prefix ppp  = Write result into file ppp.3D;
                  default prefix is same as AFNI dataset's.
 -bin         = Write data in binary format, not text.
 -txt         = Write data in text format, not binary.

NOTES:
* At present, all bricks are written out in float format.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAFNItoANALYZE
*+ WARNING: This program (3dAFNItoANALYZE) is old, not maintained, and probably useless!
Usage: 3dAFNItoANALYZE [-4D] [-orient code] aname dset
Writes AFNI dataset 'dset' to 1 or more ANALYZE 7.5 format
.hdr/.img file pairs (one pair for each sub-brick in the
AFNI dataset).  The ANALYZE files will be named
  aname_0000.hdr aname_0000.img   for sub-brick #0
  aname_0001.hdr aname_0001.img   for sub-brick #1
and so forth.  Each file pair will contain a single 3D array.

* If the AFNI dataset does not include sub-brick scale
  factors, then the ANALYZE files will be written in the
  datum type of the AFNI dataset.
* If the AFNI dataset does have sub-brick scale factors,
  then each sub-brick will be scaled to floating format
  and the ANALYZE files will be written as floats.
* The .hdr and .img files are written in the native byte
  order of the computer on which this program is executed.

Options
-------
-4D [30 Sep 2002]:
 If you use this option, then all the data will be written to
 one big ANALYZE file pair named aname.hdr/aname.img, rather
 than a series of 3D files.  Even if you only have 1 sub-brick,
 you may prefer this option, since the filenames won't have
 the '_0000' appended to 'aname'.

-orient code [19 Mar 2003]:
 This option lets you flip the dataset to a different orientation
 when it is written to the ANALYZE files.  The orientation code is
 formed as follows:
   The code must be 3 letters, one each from the
   pairs {R,L} {A,P} {I,S}.  The first letter gives
   the orientation of the x-axis, the second the
   orientation of the y-axis, the third the z-axis:
      R = Right-to-Left          L = Left-to-Right
      A = Anterior-to-Posterior  P = Posterior-to-Anterior
      I = Inferior-to-Superior   S = Superior-to-Inferior
   For example, 'LPI' means
      -x = Left       +x = Right
      -y = Posterior  +y = Anterior
      -z = Inferior   +z = Superior
 * For display in SPM, 'LPI' or 'RPI' seem to work OK.
    Be careful with this: you don't want to confuse L and R
    in the SPM display!
 * If you DON'T use this option, the dataset will be written
    out in the orientation in which it is stored in AFNI
    (e.g., the output of '3dinfo dset' will tell you this.)
 * The dataset orientation is NOT stored in the .hdr file.
 * AFNI and ANALYZE data are stored in files with the x-axis
    varying most rapidly and the z-axis most slowly.
 * Note that if you read an ANALYZE dataset into AFNI for
    display, AFNI assumes the LPI orientation, unless you
    set environment variable AFNI_ANALYZE_ORIENT.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAFNItoMINC
*+ WARNING: This program (3dAFNItoMINC) is old, not maintained, and probably useless!
Usage: 3dAFNItoMINC [options] dataset
Reads in an AFNI dataset, and writes it out as a MINC file.

OPTIONS:
 -prefix ppp  = Write result into file ppp.mnc;
                  default prefix is same as AFNI dataset's.
 -floatize    = Write MINC file in float format.
 -swap        = Swap bytes when passing data to rawtominc

NOTES:
* Multi-brick datasets are written as 4D (x,y,z,t) MINC
   files.
* If the dataset has complex-valued sub-bricks, then this
   program won't write the MINC file.
* If any of the sub-bricks have floating point scale
   factors attached, then the output will be in float
   format (regardless of the presence of -floatize).
* This program uses the MNI program 'rawtominc' to create
   the MINC file; rawtominc must be in your path.  If you
   don't have rawtominc, you must install the MINC tools
   software package from MNI.  (But if you don't have the
   MINC tools already, why do you want to convert to MINC
   format anyway?)
* At this time, you can find the MINC tools at
     ftp://ftp.bic.mni.mcgill.ca/pub/minc/
   You need the latest version of minc-*.tar.gz and also
   of netcdf-*.tar.gz.

-- RWCox - April 2002

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAFNItoNIFTI
++ 3dAFNItoNIFTI: AFNI version=AFNI_18.3.16 (Dec 11 2018) [64-bit]
Usage: 3dAFNItoNIFTI [options] dataset
Reads an AFNI dataset, writes it out as a NIfTI-1.1 file.

NOTES:
* The nifti_tool program can be used to manipulate
   the contents of a NIfTI-1.1 file.
* The input dataset can actually be in any input format
   that AFNI can read directly (e.g., MINC-1).
* There is no 3dNIFTItoAFNI program, since AFNI programs
   can directly read .nii files.  If you wish to make such
   a conversion anyway, one way to do so is like so:
     3dcalc -a ppp.nii -prefix ppp -expr 'a'

OPTIONS:
  -prefix ppp = Write the NIfTI-1.1 file as 'ppp.nii'.
                  Default: the dataset's prefix is used.
                * You can use 'ppp.hdr' to output a 2-file
                  NIfTI-1.1 file pair 'ppp.hdr' & 'ppp.img'.
                * If you want a compressed file, try
                  using a prefix like 'ppp.nii.gz'.
                * Setting the Unix environment variable
                  AFNI_AUTOGZIP to YES will result in
                  all output .nii files being gzip-ed.
  -verb       = Be verbose = print progress messages.
                  Repeating this increases the verbosity
                  (maximum setting is 3 '-verb' options).
  -float      = Force the output dataset to be 32-bit
                  floats.  This option should be used when
                  the input AFNI dataset has different
                  float scale factors for different sub-bricks,
                  an option that NIfTI-1.1 does not support.

The following options affect the contents of the AFNI extension
field that is written by default into the NIfTI-1.1 header:

  -pure       = Do NOT write an AFNI extension field into
                  the output file.  Only use this option if
                  needed.  You can also use the 'nifti_tool'
                  program to strip extensions from a file.
  -denote     = When writing the AFNI extension field, remove
                  text notes that might contain subject
                  identifying information.
  -oldid      = Give the new dataset the input dataset's
                  AFNI ID code.
  -newid      = Give the new dataset a new AFNI ID code, to
                  distinguish it from the input dataset.
     **** N.B.:  -newid is now the default action.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAFNItoNIML
Usage: 3dAFNItoNIML [options] dset
 Dumps AFNI dataset header information to stdout in NIML format.
 Mostly for debugging and testing purposes!

 OPTIONS:
  -data          == Also put the data into the output (will be huge).
  -ascii         == Format in ASCII, not binary (even huger).
  -tcp:host:port == Instead of stdout, send the dataset to a socket.
                    (implies '-data' as well)

-- RWCox - Mar 2005

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAFNItoRaw
*+ WARNING: This program (3dAFNItoRaw) is old, not maintained, and probably useless!
Usage: 3dAFNItoRaw [options] dataset
Convert an AFNI brik file with multiple sub-briks to a raw file with
  each sub-brik voxel concatenated voxel-wise.
For example, a dataset with 3 sub-briks X,Y,Z with elements x1,x2,x3,...,xn,
  y1,y2,y3,...,yn and z1,z2,z3,...,zn will be converted to a raw dataset with
  elements x1,y1,z1, x2,y2,z2, x3,y3,z3, ..., xn,yn,zn 
The dataset is kept in the original data format (float/short/int)
Options:
  -output / -prefix = name of the output file (not an AFNI dataset prefix)
    the default output name will be rawxyz.dat

  -datum float = force floating point output. Floating point forced if any
    sub-brik scale factors not equal to 1.


INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dANALYZEtoAFNI
** DON'T USE THIS PROGRAM!  REALLY!
USE 3dcopy OR to3d INSTEAD.

IF YOU CHOOSE TO USE IT ANYWAY, PERHAPS
BECAUSE IT WORKS BETTER ON YOUR 12th
CENTURY PLANTAGENET ANALYZE FILES,
ADD THE OPTION -OK TO YOUR COMMAND
LINE.

Usage: 3dANALYZEtoAFNI [options] file1.hdr file2.hdr ...
This program constructs a 'volumes' stored AFNI dataset
from the ANALYZE-75 files file1.img file2.img ....
In this type of dataset, there is only a .HEAD file; the
.BRIK file is replaced by the collection of .img files.
- Other AFNI programs can read (but not write) this type
  of dataset.
- The advantage of using this type of dataset vs. one created
   with to3d is that you don't have to duplicate the image data
   into a .BRIK file, thus saving disk space.
- The disadvantage of using 'volumes' for a multi-brick dataset
   is that all the .img files must be kept with the .HEAD file
   if you move the dataset around.
- The .img files must be in the same directory as the .HEAD file.
- Note that you put the .hdr files on the command line, but it is
   the .img files that will be named in the .HEAD file.
- After this program is run, you must keep the .img files with
   the output .HEAD file.  AFNI doesn't need the .hdr files, but
   other programs (e.g., FSL, SPM) will want them as well.

Options:
 -prefix ppp   = Save the dataset with the prefix name 'ppp'.
                  [default='a2a']
 -view vvv     = Save the dataset in the 'vvv' view, where
                  'vvv' is one of 'orig', 'acpc', or 'tlrc'.
                  [default='orig']

 -TR ttt       = For multi-volume datasets, create it as a
                  3D+time dataset with TR set to 'ttt'.
 -fbuc         = For multi-volume datasets, create it as a
                  functional bucket dataset.
 -abuc         = For multi-volume datasets, create it as an
                  anatomical bucket dataset.
   ** If more than one ANALYZE file is input, and none of the
       above options is given, the default is as if '-TR 1s'
       was used.
   ** For single volume datasets (1 ANALYZE file input), the
       default is '-abuc'.

 -geomparent g = Use the .HEAD file from dataset 'g' to set
                  the geometry of this dataset.
   ** If you don't use -geomparent, then the following options
       can be used to specify the geometry of this dataset:
 -orient code  = Tells the orientation of the 3D volumes.  The code
                  must be 3 letters, one each from the pairs {R,L}
                  {A,P} {I,S}.  The first letter gives the orientation
                  of the x-axis, the second the orientation of the
                  y-axis, the third the z-axis:
                   R = right-to-left         L = left-to-right
                   A = anterior-to-posterior P = posterior-to-anterior
                   I = inferior-to-superior  S = superior-to-inferior
 -zorigin dz   = Puts the center of the 1st slice off at the
                  given distance ('dz' in mm).  This distance
                  is in the direction given by the corresponding
                  letter in the -orient code.  For example,
                    -orient RAI -zorigin 30
                  would set the center of the first slice at
                  30 mm Inferior.
   ** If the above options are NOT used to specify the geometry
       of the dataset, then the default is '-orient RAI', and the
       z origin is set to center the slices about z=0.

 It is likely that you will want to patch up the .HEAD file using
 program 3drefit.

 -- RWCox - June 2002.


** DON'T USE THIS PROGRAM!  REALLY!
USE 3dcopy OR to3d INSTEAD.

IF YOU CHOOSE TO USE IT ANYWAY, PERHAPS
BECAUSE IT WORKS BETTER ON YOUR 12th
CENTURY PLANTAGENET ANALYZE FILES,
ADD THE OPTION -OK TO YOUR COMMAND
LINE.-- KRH - April 2005.




AFNI program: 3dANOVA
++ 3dANOVA: AFNI version=AFNI_18.3.16 (Dec 11 2018) [64-bit]
++ Authored by: B. Douglas Ward
This program performs single factor Analysis of Variance (ANOVA)
on 3D datasets

---------------------------------------------------------------

Usage:
-----

3dANOVA
   -levels r                   : r = number of factor levels

   -dset 1 filename            : data set for factor level 1
         . . .. . .
   -dset 1 filename              data set for factor level 1
         . . .. . .
   -dset r filename              data set for factor level r
         . . .. . .
   -dset r filename              data set for factor level r

  [-voxel num]                 : screen output for voxel # num

  [-diskspace]                 : print out disk space required for
                                 program execution

  [-mask mset]                 : use sub-brick #0 of dataset 'mset'
                                 to define which voxels to process

  [-debug level]               : request extra output

The following commands generate individual AFNI 2-sub-brick datasets:
  (In each case, output is written to the file with the specified
   prefix file name.)

  [-ftr prefix]                : F-statistic for treatment effect

  [-mean i prefix]             : estimate of factor level i mean

  [-diff i j prefix]           : difference between factor levels

  [-contr c1...cr prefix]      : contrast in factor levels

Modified ANOVA computation options:    (December, 2005)

     ** For details, see https://afni.nimh.nih.gov/sscc/gangc/ANOVA_Mod.html

[-old_method]       request to perform ANOVA using the previous
                    functionality (requires -OK, also)

[-OK]               confirm you understand that contrasts that
                    do not sum to zero have inflated t-stats, and
                    contrasts that do sum to zero assume sphericity
                    (to be used with -old_method)

[-assume_sph]       assume sphericity (zero-sum contrasts, only)

                    This allows use of the old_method for
                    computing contrasts which sum to zero (this
                    includes diffs, for instance).  Any contrast
                    that does not sum to zero is invalid, and
                    cannot be used with this option (such as
                    ameans).

The following command generates one AFNI 'bucket' type dataset:

  [-bucket prefix]             : create one AFNI 'bucket' dataset whose
                                 sub-bricks are obtained by
                                 concatenating the above output files;
                                 the output 'bucket' is written to file
                                 with prefix file name

N.B.: For this program, the user must specify 1 and only 1 sub-brick
      with each -dset command. That is, if an input dataset contains
      more than 1 sub-brick, a sub-brick selector must be used,
      e.g., -dset 2 'fred+orig[3]'

Example of 3dANOVA:
------------------

 Example is based on a study with one factor (independent variable)
 called 'Pictures', with 3 levels:
        (1) Faces, (2) Houses, and (3) Donuts

 The ANOVA is being conducted on the data of subjects Fred and Ethel:

 3dANOVA -levels 3                     \
         -dset 1 fred_Faces+tlrc       \
         -dset 1 ethel_Faces+tlrc      \
                                       \
         -dset 2 fred_Houses+tlrc      \
         -dset 2 ethel_Houses+tlrc     \
                                       \
         -dset 3 fred_Donuts+tlrc      \
         -dset 3 ethel_Donuts+tlrc     \
                                       \
         -ftr Pictures                 \
         -mean 1 Faces                 \
         -mean 2 Houses                \
         -mean 3 Donuts                \
         -diff 1 2 FvsH                \
         -diff 2 3 HvsD                \
         -diff 1 3 FvsD                \
         -contr  1  1 -1 FHvsD         \
         -contr -1  1  1 FvsHD         \
         -contr  1 -1  1 FDvsH         \
         -bucket fred_n_ethel_ANOVA

INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.
---------------------------------------------------
Also see HowTo#5 - Group Analysis on the AFNI website:
https://afni.nimh.nih.gov/pub/dist/HOWTO/howto/ht05_group/html/index.shtml

-------------------------------------------------------------------------
STORAGE FORMAT:
---------------
The default output format is to store the results as scaled short
(16-bit) integers.  This truncantion might cause significant errors.
If you receive warnings that look like this:
  *+ WARNING: TvsF[0] scale to shorts misfit = 8.09% -- *** Beware
then you can force the results to be saved in float format by
defining the environment variable AFNI_FLOATIZE to be YES
before running the program.  For convenience, you can do this
on the command line, as in
  3dANOVA -DAFNI_FLOATIZE=YES ... other options ... 
Also see the following links:
 https://afni.nimh.nih.gov/pub/dist/doc/program_help/common_options.html
 https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.environment.html

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dANOVA2
++ 3dANOVA: AFNI version=AFNI_18.3.16 (Dec 11 2018) [64-bit]
++ Authored by: B. Douglas Ward
This program performs a two-factor Analysis of Variance (ANOVA)
on 3D datasets

-----------------------------------------------------------

Usage:

   3dANOVA2
      -type k              : type of ANOVA model to be used:
                              k=1  fixed effects model  (A and B fixed)    
                              k=2  random effects model (A and B random)   
                              k=3  mixed effects model  (A fixed, B random)

      -alevels a           : a = number of levels of factor A

      -blevels b           : b = number of levels of factor B

      -dset 1 1 filename   : data set for level 1 of factor A
                                      and level 1 of factor B
            . . .                           . . .
      -dset i j filename   : data set for level i of factor A
                                      and level j of factor B
            . . .                           . . .
      -dset a b filename   : data set for level a of factor A
                                      and level b of factor B

     [-voxel num]          : screen output for voxel # num

     [-diskspace]          : print out disk space required for
                             program execution

     [-mask mset]          : use sub-brick #0 of dataset 'mset'
                             to define which voxels to process


   The following commands generate individual AFNI 2-sub-brick datasets:
  (In each case, output is written to the file with the specified
   prefix file name.)

     [-ftr prefix]         : F-statistic for treatment effect

     [-fa prefix]          : F-statistic for factor A effect

     [-fb prefix]          : F-statistic for factor B effect

     [-fab prefix]         : F-statistic for interaction

     [-amean i prefix]     : estimate mean of factor A level i

     [-bmean j prefix]     : estimate mean of factor B level j

     [-xmean i j prefix]   : estimate mean of cell at level i of factor A,
                                                      level j of factor B

     [-adiff i j prefix]   : difference between levels i and j of factor A

     [-bdiff i j prefix]   : difference between levels i and j of factor B

     [-xdiff i j k l prefix]     : difference between cell mean at A=i,B=j
                                                  and cell mean at A=k,B=l

     [-acontr c1 ... ca prefix]  : contrast in factor A levels

     [-bcontr c1 ... cb prefix]  : contrast in factor B levels

     [-xcontr c11 ... c1b c21 ... c2b  ...  ca1 ... cab  prefix]
                                 : contrast in cell means


The following command generates one AFNI 'bucket' type dataset:

     [-bucket prefix]      : create one AFNI 'bucket' dataset whose
                             sub-bricks are obtained by concatenating
                             the above output files; the output 'bucket'
                             is written to file with prefix file name

Modified ANOVA computation options:    (December, 2005)

     ** These options apply to model type 3, only.
        For details, see https://afni.nimh.nih.gov/sscc/gangc/ANOVA_Mod.html

     [-old_method]        : request to perform ANOVA using the previous
                            functionality (requires -OK, also)

     [-OK]                : confirm you understand that contrasts that
                            do not sum to zero have inflated t-stats, and
                            contrasts that do sum to zero assume sphericity
                            (to be used with -old_method)

     [-assume_sph]        : assume sphericity (zero-sum contrasts, only)

                            This allows use of the old_method for
                            computing contrasts which sum to zero (this
                            includes diffs, for instance).  Any contrast
                            that does not sum to zero is invalid, and
                            cannot be used with this option (such as
                            ameans).

----------------------------------------------------------

 Example of 3dANOVA2:

      Example is based on a study with a 3 x 4 mixed factorial design:

              Factor 1 - DONUTS has 3 levels:
                         (1) chocolate, (2) glazed, (3) sugar

              Factor 2 - SUBJECTS, of which there are 4 in this analysis:
                         (1) fred, (2) ethel, (3) lucy, (4) ricky

 3dANOVA2 -type 3 -alevels 3 -blevels 4   \
          -dset 1 1 fred_choc+tlrc        \
          -dset 2 1 fred_glaz+tlrc        \
          -dset 3 1 fred_sugr+tlrc        \
          -dset 1 2 ethel_choc+tlrc       \
          -dset 2 2 ethel_glaz+tlrc       \
          -dset 3 2 ethel_sugr+tlrc       \
          -dset 1 3 lucy_choc+tlrc        \
          -dset 2 3 lucy_glaz+tlrc        \
          -dset 3 3 lucy_sugr+tlrc        \
          -dset 1 3 ricky_choc+tlrc       \
          -dset 2 3 ricky_glaz+tlrc       \
          -dset 3 3 ricky_sugr+tlrc       \
          -amean 1 Chocolate              \
          -amean 2 Glazed                 \
          -amean 3 Sugar                  \
          -adiff 1 2 CvsG                 \
          -adiff 2 3 GvsS                 \
          -adiff 1 3 CvsS                 \
          -acontr 1 1 -2 CGvsS            \
          -acontr -2 1 1 CvsGS            \
          -acontr 1 -2 1 CSvsG            \
          -fa Donuts                      \
          -bucket ANOVA_results

 The -bucket option will place all of the 3dANOVA2 results (i.e., main
 effect of DONUTS, means for each of the 3 levels of DONUTS, and
 contrasts between the 3 levels of DONUTS) into one big dataset with
 multiple sub-bricks called ANOVA_results+tlrc.

-----------------------------------------------------------


N.B.: For this program, the user must specify 1 and only 1 sub-brick
      with each -dset command. That is, if an input dataset contains
      more than 1 sub-brick, a sub-brick selector must be used, e.g.:
      -dset 2 4 'fred+orig[3]'

INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.

Also see HowTo #5: Group Analysis on the AFNI website:
 https://afni.nimh.nih.gov/pub/dist/HOWTO/howto/ht05_group/html/index.shtml

-------------------------------------------------------------------------
STORAGE FORMAT:
---------------
The default output format is to store the results as scaled short
(16-bit) integers.  This truncantion might cause significant errors.
If you receive warnings that look like this:
  *+ WARNING: TvsF[0] scale to shorts misfit = 8.09% -- *** Beware
then you can force the results to be saved in float format by
defining the environment variable AFNI_FLOATIZE to be YES
before running the program.  For convenience, you can do this
on the command line, as in
  3dANOVA -DAFNI_FLOATIZE=YES ... other options ... 
Also see the following links:
 https://afni.nimh.nih.gov/pub/dist/doc/program_help/common_options.html
 https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.environment.html

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dANOVA3
This program performs three-factor ANOVA on 3D data sets.           

Usage: 
3dANOVA3 
-type  k          type of ANOVA model to be used:
                         k = 1   A,B,C fixed;          AxBxC
                         k = 2   A,B,C random;         AxBxC
                         k = 3   A fixed; B,C random;  AxBxC
                         k = 4   A,B fixed; C random;  AxBxC
                         k = 5   A,B fixed; C random;  AxB,BxC,C(A)

-alevels a                     a = number of levels of factor A
-blevels b                     b = number of levels of factor B
-clevels c                     c = number of levels of factor C
-dset 1 1 1 filename           data set for level 1 of factor A
                                        and level 1 of factor B
                                        and level 1 of factor C
 . . .                           . . .

-dset i j k filename           data set for level i of factor A
                                        and level j of factor B
                                        and level k of factor C
 . . .                           . . .

-dset a b c filename           data set for level a of factor A
                                        and level b of factor B
                                        and level c of factor C

[-voxel num]                   screen output for voxel # num
[-diskspace]                   print out disk space required for
                                  program execution

[-mask mset]                   use sub-brick #0 of dataset 'mset'
                               to define which voxels to process


The following commands generate individual AFNI 2 sub-brick datasets:
  (In each case, output is written to the file with the specified
   prefix file name.)

[-fa prefix]                F-statistic for factor A effect
[-fb prefix]                F-statistic for factor B effect
[-fc prefix]                F-statistic for factor C effect
[-fab prefix]               F-statistic for A*B interaction
[-fac prefix]               F-statistic for A*C interaction
[-fbc prefix]               F-statistic for B*C interaction
[-fabc prefix]              F-statistic for A*B*C interaction

[-amean i prefix]           estimate of factor A level i mean
[-bmean i prefix]           estimate of factor B level i mean
[-cmean i prefix]           estimate of factor C level i mean
[-xmean i j k prefix]       estimate mean of cell at factor A level i,
                               factor B level j, factor C level k

[-adiff i j prefix]         difference between factor A levels i and j
                               (with factors B and C collapsed)
[-bdiff i j prefix]         difference between factor B levels i and j
                               (with factors A and C collapsed)
[-cdiff i j prefix]         difference between factor C levels i and j
                               (with factors A and B collapsed)
[-xdiff i j k l m n prefix] difference between cell mean at A=i,B=j,
                               C=k, and cell mean at A=l,B=m,C=n

[-acontr c1...ca prefix]    contrast in factor A levels
                               (with factors B and C collapsed)
[-bcontr c1...cb prefix]    contrast in factor B levels
                               (with factors A and C collapsed)
[-ccontr c1...cc prefix]    contrast in factor C levels
                               (with factors A and B collapsed)

[-aBcontr c1 ... ca : j prefix]   2nd order contrast in A, at fixed
                                     B level j (collapsed across C)
[-Abcontr i : c1 ... cb prefix]   2nd order contrast in B, at fixed
                                     A level i (collapsed across C)

[-aBdiff i_1 i_2 : j prefix] difference between levels i_1 and i_2 of
                               factor A, with factor B fixed at level j

[-Abdiff i : j_1 j_2 prefix] difference between levels j_1 and j_2 of
                               factor B, with factor A fixed at level i

[-abmean i j prefix]         mean effect at factor A level i and
                               factor B level j

The following command generates one AFNI 'bucket' type dataset:

[-bucket prefix]         create one AFNI 'bucket' dataset whose
                           sub-bricks are obtained by concatenating
                           the above output files; the output 'bucket'
                           is written to file with prefix file name

Modified ANOVA computation options:    (December, 2005)

     ** These options apply to model types 4 and 5, only.
        For details, see https://afni.nimh.nih.gov/sscc/gangc/ANOVA_Mod.html

[-old_method]       request to perform ANOVA using the previous
                    functionality (requires -OK, also)

[-OK]               confirm you understand that contrasts that
                    do not sum to zero have inflated t-stats, and
                    contrasts that do sum to zero assume sphericity
                    (to be used with -old_method)

[-assume_sph]       assume sphericity (zero-sum contrasts, only)

                    This allows use of the old_method for
                    computing contrasts which sum to zero (this
                    includes diffs, for instance).  Any contrast
                    that does not sum to zero is invalid, and
                    cannot be used with this option (such as
                    ameans).

-----------------------------------------------------------------
example: "classic" houses/faces/donuts for 4 subjects (2 genders)
         (level sets are gender (M/W), image (H/F/D), and subject)

    Note: factor C is really subject within gender (since it is
          nested).  There are 4 subjects in this example, and 2
          subjects per gender.  So clevels is 2.

    3dANOVA3 -type 5                            \
        -alevels 2                              \
        -blevels 3                              \
        -clevels 2                              \
        -dset 1 1 1 man1_houses+tlrc            \
        -dset 1 2 1 man1_faces+tlrc             \
        -dset 1 3 1 man1_donuts+tlrc            \
        -dset 1 1 2 man2_houses+tlrc            \
        -dset 1 2 2 man2_faces+tlrc             \
        -dset 1 3 2 man2_donuts+tlrc            \
        -dset 2 1 1 woman1_houses+tlrc          \
        -dset 2 2 1 woman1_faces+tlrc           \
        -dset 2 3 1 woman1_donuts+tlrc          \
        -dset 2 1 2 woman2_houses+tlrc          \
        -dset 2 2 2 woman2_faces+tlrc           \
        -dset 2 3 2 woman2_donuts+tlrc          \
        -adiff   1 2           MvsW             \
        -bdiff   2 3           FvsD             \
        -bcontr -0.5 1 -0.5    FvsHD            \
        -aBcontr 1 -1 : 1      MHvsWH           \
        -aBdiff  1  2 : 1      same_as_MHvsWH   \
        -Abcontr 2 : 0 1 -1    WFvsWD           \
        -Abdiff  2 : 2 3       same_as_WFvsWD   \
        -Abcontr 2 : 1 7 -4.2  goofy_example    \
        -bucket donut_anova


N.B.: For this program, the user must specify 1 and only 1 sub-brick
      with each -dset command. That is, if an input dataset contains
      more than 1 sub-brick, a sub-brick selector must be used, e.g.:
      -dset 2 4 5 'fred+orig[3]'

INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.
-------------------------------------------------------------------------
STORAGE FORMAT:
---------------
The default output format is to store the results as scaled short
(16-bit) integers.  This truncantion might cause significant errors.
If you receive warnings that look like this:
  *+ WARNING: TvsF[0] scale to shorts misfit = 8.09% -- *** Beware
then you can force the results to be saved in float format by
defining the environment variable AFNI_FLOATIZE to be YES
before running the program.  For convenience, you can do this
on the command line, as in
  3dANOVA -DAFNI_FLOATIZE=YES ... other options ... 
Also see the following links:
 https://afni.nimh.nih.gov/pub/dist/doc/program_help/common_options.html
 https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.environment.html

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAllineate
Usage: 3dAllineate [options] sourcedataset

Program to align one dataset (the 'source') to a base dataset.
Options are available to control:
 ++ How the matching between the source and the base is computed
    (i.e., the 'cost functional' measuring image mismatch).
 ++ How the resliced source is interpolated to the base space.
 ++ The complexity of the spatial transformation ('warp') used.
 ++ And many many technical options to control the process in detail,
    if you know what you are doing (or just like to fool around).

=====----------------------------------------------------------------------
NOTES: For most 3D image registration purposes, we now recommend that you
=====  use Daniel Glen's script align_epi_anat.py (which, despite its name,
       can do many more registration problems than EPI-to-T1-weighted).
  -->> In particular, using 3dAllineate with the 'lpc' cost functional
       (to align EPI and T1-weighted volumes) requires using a '-weight'
       volume to get good results, and the align_epi_anat.py script will
       automagically generate such a weight dataset that works well for
       EPI-to-structural alignment.
  -->> This script can also be used for other alignment purposes, such
       as T1-weighted alignment between field strengths using the
       '-lpa' cost functional.  Investigate align_epi_anat.py to
       see if it will do what you need -- you might make your life
       a little easier and nicer and happier and more tranquil.
  -->> Also, if/when you ask for registration help on the AFNI
       message board, we'll probably start by recommending that you
       try align_epi_anat.py if you haven't already done so.
  -->> For aligning EPI and T1-weighted volumes, we have found that
       using a flip angle of 50-60 degrees for the EPI works better than
       a flip angle of 90 degrees.  The reason is that there is more
       internal contrast in the EPI data when the flip angle is smaller,
       so the registration has some image structure to work with.  With
       the 90 degree flip angle, there is so little internal contrast in
       the EPI dataset that the alignment process ends up being just
       trying to match brain outlines -- which doesn't always give accurate
       results: see http://dx.doi.org/10.1016/j.neuroimage.2008.09.037
  -->> Although the total MRI signal is reduced at a smaller flip angle,
       there is little or no loss in FMRI/BOLD information, since the bulk
       of the time series 'noise' is from physiological fluctuation signals,
       which are also reduced by the lower flip angle -- for more details,
       see http://dx.doi.org/10.1016/j.neuroimage.2010.11.020
---------------------------------------------------------------------------
  **** New (Summer 2013) program 3dQwarp is available to do nonlinear  ****
  ***  alignment between a base and source dataset, including the use   ***
  **   of 3dAllineate for the preliminary affine alignment.  If you are  **
  *    interested, see the output of '3dQwarp -help' for the details.     *
---------------------------------------------------------------------------

COMMAND LINE OPTIONS:
====================
 -base bbb   = Set the base dataset to be the #0 sub-brick of 'bbb'.
               If no -base option is given, then the base volume is
               taken to be the #0 sub-brick of the source dataset.
               (Base must be stored as floats, shorts, or bytes.)

 -source ttt = Read the source dataset from 'ttt'.  If no -source
   *OR*        (or -input) option is given, then the source dataset
 -input ttt    is the last argument on the command line.
               (Source must be stored as floats, shorts, or bytes.)
            ** 3dAllineate can register 2D datasets (single slice),
               but both the base and source must be 2D -- you cannot
               use this program to register a 2D slice into a 3D volume!
            ** See the script @2dwarper.Allin for an example of using
               3dAllineate to do slice-by-slice nonlinear warping to
               align 3D volumes distorted by time-dependent magnetic
               field inhomogeneities.

 ** NOTA BENE: The base and source dataset do NOT have to be defined **
 ** [that's]   on the same 3D grids; the alignment process uses the  **
 ** [Latin ]   coordinate systems defined in the dataset headers to  **
 ** [  for ]   make the match between spatial locations, rather than **
 ** [ NOTE ]   matching the 2 datasets on a voxel-by-voxel basis     **
 ** [ WELL ]   (as 3dvolreg and 3dWarpDrive do).                     **
 **       -->> However, this coordinate-based matching requires that **
 **            image volumes be defined on roughly the same patch of **
 **            of (x,y,z) space, in order to find a decent starting  **
 **            point for the transformation.  You might need to use  **
 **            the script @Align_Centers to do this, if the 3D       **
 **            spaces occupied by the images do not overlap much.    **
 **       -->> Or the '-cmass' option to this program might be       **
 **            sufficient to solve this problem, maybe, with luck.   **
 **            (Another reason why you should use align_epi_anat.py) **
 **       -->> If the coordinate system in the dataset headers is    **
 **            WRONG, then 3dAllineate will probably not work well!  **

 -prefix ppp = Output the resulting dataset to file 'ppp'.  If this
   *OR*        option is NOT given, no dataset will be output!  The
 -out ppp      transformation matrix to align the source to the base will
               be estimated, but not applied.  You can save the matrix
               for later use using the '-1Dmatrix_save' option.
        *N.B.: By default, the new dataset is computed on the grid of the
                base dataset; see the '-master' and/or the '-mast_dxyz'
                options to change this grid.
        *N.B.: If 'ppp' is 'NULL', then no output dataset will be produced.
                This option is for compatibility with 3dvolreg.

 -floatize   = Write result dataset as floats.  Internal calculations
 -float        are all done on float copies of the input datasets.
               [Default=convert output dataset to data format of  ]
               [        source dataset; if the source dataset was ]
               [        shorts with a scale factor, then the new  ]
               [        dataset will get a scale factor as well;  ]
               [        if the source dataset was shorts with no  ]
               [        scale factor, the result will be unscaled.]

 -1Dparam_save ff   = Save the warp parameters in ASCII (.1D) format into
                      file 'ff' (1 row per sub-brick in source).
                    * A historical synonym for this option is '-1Dfile'.
                    * At the top of the saved 1D file is a #comment line
                      listing the names of the parameters; those parameters
                      that are fixed (e.g., via '-parfix') will be marked
                      by having their symbolic names end in the '$' character.
                      You can use '1dcat -nonfixed' to remove these columns
                      from the 1D file if you just want to further process the
                      varying parameters somehow (e.g., 1dsvd).
                    * However, the '-1Dparam_apply' option requires the
                      full list of parameters, including those that were
                      fixed, in order to work properly!

 -1Dparam_apply aa  = Read warp parameters from file 'aa', apply them to 
                      the source dataset, and produce a new dataset.
                      (Must also use the '-prefix' option for this to work!  )
                      (In this mode of operation, there is no optimization of)
                      (the cost functional by changing the warp parameters;  )
                      (previously computed parameters are applied directly.  )
               *N.B.: A historical synonym for this is '-1Dapply'.
               *N.B.: If you use -1Dparam_apply, you may also want to use
                       -master to control the grid on which the new
                       dataset is written -- the base dataset from the
                       original 3dAllineate run would be a good possibility.
                       Otherwise, the new dataset will be written out on the
                       3D grid coverage of the source dataset, and this
                       might result in clipping off part of the image.
               *N.B.: Each row in the 'aa' file contains the parameters for
                       transforming one sub-brick in the source dataset.
                       If there are more sub-bricks in the source dataset
                       than there are rows in the 'aa' file, then the last
                       row is used repeatedly.
               *N.B.: A trick to use 3dAllineate to resample a dataset to
                       a finer grid spacing:
                         3dAllineate -input dataset+orig         \
                                     -master template+orig       \
                                     -prefix newdataset          \
                                     -final wsinc5               \
                                     -1Dparam_apply '1D: 12@0'\'  
                       Here, the identity transformation is specified
                       by giving all 12 affine parameters as 0 (note
                       the extra \' at the end of the '1D: 12@0' input!).
                     ** You can also use the word 'IDENTITY' in place of
                        '1D: 12@0'\' (to indicate the identity transformation).
              **N.B.: Some expert options for modifying how the wsinc5
                       method works are described far below, if you use
                       '-HELP' instead of '-help'.
            ****N.B.: The interpolation method used to produce a dataset
                       is always given via the '-final' option, NOT via
                       '-interp'.  If you forget this and use '-interp'
                       along with one of the 'apply' options, this program
                       will chastise you (gently) and change '-final'
                       to match what the '-interp' input.

 -1Dmatrix_save ff  = Save the transformation matrix for each sub-brick into
                      file 'ff' (1 row per sub-brick in the source dataset).
                      If 'ff' does NOT end in '.1D', then the program will
                      append '.aff12.1D' to 'ff' to make the output filename.
               *N.B.: This matrix is the coordinate transformation from base
                       to source DICOM coordinates. In other terms:
                          Xin = Xsource = M Xout = M Xbase
                                   or
                          Xout = Xbase = inv(M) Xin = inv(M) Xsource
                       where Xin or Xsource is the 4x1 coordinates of a
                       location in the input volume. Xout is the 
                       coordinate of that same location in the output volume.
                       Xbase is the coordinate of the corresponding location
                       in the base dataset. M is ff augmented by a 4th row of
                       [0 0 0 1], X. is an augmented column vector [x,y,z,1]'
                       To get the inverse matrix inv(M)
                       (source to base), use the cat_matvec program, as in
                         cat_matvec fred.aff12.1D -I

 -1Dmatrix_apply aa = Use the matrices in file 'aa' to define the spatial
                      transformations to be applied.  Also see program
                      cat_matvec for ways to manipulate these matrix files.
               *N.B.: You probably want to use either -base or -master
                      with either *_apply option, so that the coordinate
                      system that the matrix refers to is correctly loaded.
                     ** You can also use the word 'IDENTITY' in place of a
                        filename to indicate the identity transformation --
                        presumably for the purpose of resampling the source
                        dataset to a new grid.

  * The -1Dmatrix_* options can be used to save and re-use the transformation *
  * matrices.  In combination with the program cat_matvec, which can multiply *
  * saved transformation matrices, you can also adjust these matrices to      *
  * other alignments.                                                         *

  * The script 'align_epi_anat.py' uses 3dAllineate and 3dvolreg to align EPI *
  * datasets to T1-weighted anatomical datasets, using saved matrices between *
  * the two programs.  This script is our currently recommended method for    *
  * doing such intra-subject alignments.                                      *

 -cost ccc   = Defines the 'cost' function that defines the matching
               between the source and the base; 'ccc' is one of
                ls   *OR*  leastsq         = Least Squares [Pearson Correlation]
                mi   *OR*  mutualinfo      = Mutual Information [H(b)+H(s)-H(b,s)]
                crM  *OR*  corratio_mul    = Correlation Ratio (Symmetrized*)
                nmi  *OR*  norm_mutualinfo = Normalized MI [H(b,s)/(H(b)+H(s))]
                hel  *OR*  hellinger       = Hellinger metric
                crA  *OR*  corratio_add    = Correlation Ratio (Symmetrized+)
                crU  *OR*  corratio_uns    = Correlation Ratio (Unsym)
                lpc  *OR*  localPcorSigned = Local Pearson Correlation Signed
                lpa  *OR*  localPcorAbs    = Local Pearson Correlation Abs
                lpc+ *OR*  localPcor+Others= Local Pearson Signed + Others
                lpa+ *OR*  localPcorAbs+Others= Local Pearson Abs + Others
               You can also specify the cost functional using an option
               of the form '-mi' rather than '-cost mi', if you like
               to keep things terse and cryptic (as I do).
               [Default == '-hel' (for no good reason, but it sounds nice).]
               **NB** See more below about lpa and lpc, which are typically
                      what we would recommend as first-choice cost functions
                      now:
                        lpa if you have similar contrast vols to align;
                        lpc if you have *non*similar contrast vols to align!

 -interp iii = Defines interpolation method to use during matching
               process, where 'iii' is one of
                 NN      *OR* nearestneighbour *OR nearestneighbor
                 linear  *OR* trilinear
                 cubic   *OR* tricubic
                 quintic *OR* triquintic
               Using '-NN' instead of '-interp NN' is allowed (e.g.).
               Note that using cubic or quintic interpolation during
               the matching process will slow the program down a lot.
               Use '-final' to affect the interpolation method used
               to produce the output dataset, once the final registration
               parameters are determined.  [Default method == 'linear'.]
            ** N.B.: Linear interpolation is used during the coarse
                     alignment pass; the selection here only affects
                     the interpolation method used during the second
                     (fine) alignment pass.
            ** N.B.: '-interp' does NOT define the final method used
                     to produce the output dataset as warped from the
                     input dataset.  If you want to do that, use '-final'.

 -final iii  = Defines the interpolation mode used to create the
               output dataset.  [Default == 'cubic']
            ** N.B.: For '-final' ONLY, you can use 'wsinc5' to specify
                       that the final interpolation be done using a
                       weighted sinc interpolation method.  This method
                       is so SLOW that you aren't allowed to use it for
                       the registration itself.
                  ++ wsinc5 interpolation is highly accurate and should
                       reduce the smoothing artifacts from lower
                       order interpolation methods (which are most
                       visible if you interpolate an EPI time series
                       to high resolution and then make an image of
                       the voxel-wise variance).
                  ++ On my Intel-based Mac, it takes about 2.5 s to do
                       wsinc5 interpolation, per 1 million voxels output.
                       For comparison, quintic interpolation takes about
                       0.3 s per 1 million voxels: 8 times faster than wsinc5.
                  ++ The '5' refers to the width of the sinc interpolation
                       weights: plus/minus 5 grid points in each direction;
                       this is a tensor product interpolation, for speed.

TECHNICAL OPTIONS (used for fine control of the program):
=================
 -nmatch nnn = Use at most 'nnn' scattered points to match the
               datasets.  The smaller nnn is, the faster the matching
               algorithm will run; however, accuracy may be bad if
               nnn is too small.  If you end the 'nnn' value with the
               '%' character, then that percentage of the base's
               voxels will be used.
               [Default == 47% of voxels in the weight mask]

 -nopad      = Do not use zero-padding on the base image.
               [Default == zero-pad, if needed; -verb shows how much]

 -zclip      = Replace negative values in the input datasets (source & base)
               with zero.  The intent is to clip off a small set of negative
               values that may arise when using 3dresample (say) with
               cubic interpolation.

 -conv mmm   = Convergence test is set to 'mmm' millimeters.
               This doesn't mean that the results will be accurate
               to 'mmm' millimeters!  It just means that the program
               stops trying to improve the alignment when the optimizer
               (NEWUOA) reports it has narrowed the search radius
               down to this level.  [Default == 0.05 mm]

 -verb       = Print out verbose progress reports.
               [Using '-VERB' will give even more prolix reports.]
 -quiet      = Don't print out verbose stuff.

 -usetemp    = Write intermediate stuff to disk, to economize on RAM.
               Using this will slow the program down, but may make it
               possible to register datasets that need lots of space.
       **N.B.: Temporary files are written to the directory given
               in environment variable TMPDIR, or in /tmp, or in ./
               (preference in that order).  If the program crashes,
               these files are named TIM_somethingrandom, and you
               may have to delete them manually. (TIM=Temporary IMage)
       **N.B.: If the program fails with a 'malloc failure' type of
               message, then try '-usetemp' (malloc=memory allocator).
       **N.B.: If you use '-verb', then memory usage is printed out
               at various points along the way.

 -nousetemp  = Don't use temporary workspace on disk [the default].

 -check hhh  = After cost functional optimization is done, start at the
               final parameters and RE-optimize using the new cost
               function 'hhh'.  If the results are too different, a
               warning message will be printed.  However, the final
               parameters from the original optimization will be
               used to create the output dataset. Using '-check'
               increases the CPU time, but can help you feel sure
               that the alignment process did not go wild and crazy.
               [Default == no check == don't worry, be happy!]
       **N.B.: You can put more than one function after '-check', as in
                 -nmi -check mi hel crU crM
               to register with Normalized Mutual Information, and
               then check the results against 4 other cost functionals.
       **N.B.: On the other hand, some cost functionals give better
               results than others for specific problems, and so
               a warning that 'mi' was significantly different than
               'hel' might not actually mean anything useful (e.g.).

 ** PARAMETERS THAT AFFECT THE COST OPTIMIZATION STRATEGY **

 -onepass    = Use only the refining pass -- do not try a coarse
               resolution pass first.  Useful if you know that only
               small amounts of image alignment are needed.
               [The default is to use both passes.]

 -twopass    = Use a two pass alignment strategy, first searching for
               a large rotation+shift and then refining the alignment.
               [Two passes are used by default for the first sub-brick]
               [in the source dataset, and then one pass for the others.]
               ['-twopass' will do two passes for ALL source sub-bricks.]
            *** The first (coarse) pass is relatively slow, as it tries
                 to search a large volume of parameter (rotations+shifts)
                 space for initial guesses at the alignment transformation.
              * A lot of these initial guesses are kept and checked to
                 see which ones lead to good starting points for the
                 further refinement.
              * The winners of this competition are then passed to the
                 '-twobest' (infra) successive optimization passes.
              * The ultimate winner of THAT stage is what starts
                 the second (fine) pass alignment. Usually, this starting
                 point is so good that the fine pass optimization does
                 not provide a lot of improvement.
              * All of these stages are intended to help the program avoid
                 stopping at a 'false' minimum in the cost functional.
                 They were added to the software as we gathered experience
                 with difficult 3D alignment problems. The combination of
                 multiple stages of partial optimization of multiple
                 parameter candidates makes the coarse pass slow, but also
                 makes it (usually) work well.

 -twoblur rr = Set the blurring radius for the first pass to 'rr'
               millimeters.  [Default == 11 mm]
       **N.B.: You may want to change this from the default if
               your voxels are unusually small or unusually large
               (e.g., outside the range 1-4 mm along each axis).

 -twofirst   = Use -twopass on the first image to be registered, and
               then on all subsequent images from the source dataset,
               use results from the first image's coarse pass to start
               the fine pass.
               (Useful when there may be large motions between the   )
               (source and the base, but only small motions within   )
               (the source dataset itself; since the coarse pass can )
               (be slow, doing it only once makes sense in this case.)
       **N.B.: [-twofirst is on by default; '-twopass' turns it off.]

 -twobest bb = In the coarse pass, use the best 'bb' set of initial
               points to search for the starting point for the fine
               pass.  If bb==0, then no search is made for the best
               starting point, and the identity transformation is
               used as the starting point.  [Default=5; min=0 max=22]
       **N.B.: Setting bb=0 will make things run faster, but less reliably.

 -fineblur x = Set the blurring radius to use in the fine resolution
               pass to 'x' mm.  A small amount (1-2 mm?) of blurring at
               the fine step may help with convergence, if there is
               some problem, especially if the base volume is very noisy.
               [Default == 0 mm = no blurring at the final alignment pass]

   **NOTES ON
   **STRATEGY: * If you expect only small-ish (< 2 voxels?) image movement,
                 then using '-onepass' or '-twobest 0' makes sense.
               * If you expect large-ish image movements, then do not
                 use '-onepass' or '-twobest 0'; the purpose of the
                 '-twobest' parameter is to search for large initial
                 rotations/shifts with which to start the coarse
                 optimization round.
               * If you have multiple sub-bricks in the source dataset,
                 then the default '-twofirst' makes sense if you don't expect
                 large movements WITHIN the source, but expect large motions
                 between the source and base.
               * '-twopass' re-starts the alignment process for each sub-brick
                 in the source dataset -- this option can be time consuming,
                 and is really intended to be used when you might expect large
                 movements between sub-bricks; for example, when the different
                 volumes are gathered on different days.  For most purposes,
                 '-twofirst' (the default process) will be adequate and faster,
                 when operating on multi-volume source datasets.

 -cmass        = Use the center-of-mass calculation to bracket the shifts.
                   [This option is OFF by default]
                 If given in the form '-cmass+xy' (for example), means to
                 do the CoM calculation in the x- and y-directions, but
                 not the z-direction.

 -nocmass      = Don't use the center-of-mass calculation. [The default]
                  (You would not want to use the C-o-M calculation if the  )
                  (source sub-bricks have very different spatial locations,)
                  (since the source C-o-M is calculated from all sub-bricks)

 **EXAMPLE: You have a limited coverage set of axial EPI slices you want to
            register into a larger head volume (after 3dSkullStrip, of course).
            In this case, '-cmass+xy' makes sense, allowing CoM adjustment
            along the x = R-L and y = A-P directions, but not along the
            z = I-S direction, since the EPI doesn't cover the whole brain
            along that axis.

 -autoweight = Compute a weight function using the 3dAutomask
               algorithm plus some blurring of the base image.
       **N.B.: '-autoweight+100' means to zero out all voxels
                 with values below 100 before computing the weight.
               '-autoweight**1.5' means to compute the autoweight
                 and then raise it to the 1.5-th power (e.g., to
                 increase the weight of high-intensity regions).
               These two processing steps can be combined, as in
                 '-autoweight+100**1.5'
               ** Note that '**' must be enclosed in quotes;
                  otherwise, the shell will treat it as a wildcard
                  and you will get an error message before 3dAllineate
                  even starts!!
       **N.B.: Some cost functionals do not allow -autoweight, and
               will use -automask instead.  A warning message
               will be printed if you run into this situation.
               If a clip level '+xxx' is appended to '-autoweight',
               then the conversion into '-automask' will NOT happen.
               Thus, using a small positive '+xxx' can be used trick
               -autoweight into working on any cost functional.

 -automask   = Compute a mask function, which is like -autoweight,
               but the weight for a voxel is set to either 0 or 1.
       **N.B.: '-automask+3' means to compute the mask function, and
               then dilate it outwards by 3 voxels (e.g.).
               ** Note that '+' means something very different
                  for '-automask' and '-autoweight'!!

 -autobox    = Expand the -automask function to enclose a rectangular
               box that holds the irregular mask.
       **N.B.: This is the default mode of operation!
               For intra-modality registration, '-autoweight' may be better!
             * If the cost functional is 'ls', then '-autoweight' will be
               the default, instead of '-autobox'.

 -nomask     = Don't compute the autoweight/mask; if -weight is not
               also used, then every voxel will be counted equally.

 -weight www = Set the weighting for each voxel in the base dataset;
               larger weights mean that voxel counts more in the cost
               function.
       **N.B.: The weight dataset must be defined on the same grid as
               the base dataset.
       **N.B.: Even if a method does not allow -autoweight, you CAN
               use a weight dataset that is not 0/1 valued.  The
               risk is yours, of course (!*! as always in AFNI !*!).

 -wtprefix p = Write the weight volume to disk as a dataset with
               prefix name 'p'.  Used with '-autoweight/mask', this option
               lets you see what voxels were important in the algorithm.

 -emask ee   = This option lets you specify a mask of voxels to EXCLUDE from
               the analysis. The voxels where the dataset 'ee' is nonzero
               will not be included (i.e., their weights will be set to zero).
             * Like all the weight options, it applies in the base image
               coordinate system.
             * Like all the weight options, it means nothing if you are using
               one of the 'apply' options.

    Method  Allows -autoweight
    ------  ------------------
     ls     YES
     mi     NO
     crM    YES
     nmi    NO
     hel    NO
     crA    YES
     crU    YES
     lpc    YES
     lpa    YES
     lpc+   YES
     lpa+   YES

 -source_mask sss = Mask the source (input) dataset, using 'sss'.
 -source_automask = Automatically mask the source dataset.
                      [By default, all voxels in the source]
                      [dataset are used in the matching.   ]
            **N.B.: You can also use '-source_automask+3' to dilate
                    the default source automask outward by 3 voxels.

 -warp xxx   = Set the warp type to 'xxx', which is one of
                 shift_only         *OR* sho =  3 parameters
                 shift_rotate       *OR* shr =  6 parameters
                 shift_rotate_scale *OR* srs =  9 parameters
                 affine_general     *OR* aff = 12 parameters
               [Default = affine_general, which includes image]
               [      shifts, rotations, scaling, and shearing]

 -warpfreeze = Freeze the non-rigid body parameters (those past #6)
               after doing the first sub-brick.  Subsequent volumes
               will have the same spatial distortions as sub-brick #0,
               plus rigid body motions only.

 -replacebase   = If the source has more than one sub-brick, and this
                  option is turned on, then after the #0 sub-brick is
                  aligned to the base, the aligned #0 sub-brick is used
                  as the base image for subsequent source sub-bricks.

 -replacemeth m = After sub-brick #0 is aligned, switch to method 'm'
                  for later sub-bricks.  For use with '-replacebase'.

 -EPI        = Treat the source dataset as being composed of warped
               EPI slices, and the base as comprising anatomically
               'true' images.  Only phase-encoding direction image
               shearing and scaling will be allowed with this option.
       **N.B.: For most people, the base dataset will be a 3dSkullStrip-ed
               T1-weighted anatomy (MPRAGE or SPGR).  If you don't remove
               the skull first, the EPI images (which have little skull
               visible due to fat-suppression) might expand to fit EPI
               brain over T1-weighted skull.
       **N.B.: Usually, EPI datasets don't have as complete slice coverage
               of the brain as do T1-weighted datasets.  If you don't use
               some option (like '-EPI') to suppress scaling in the slice-
               direction, the EPI dataset is likely to stretch the slice
               thicknesss to better 'match' the T1-weighted brain coverage.
       **N.B.: '-EPI' turns on '-warpfreeze -replacebase'.
               You can use '-nowarpfreeze' and/or '-noreplacebase' AFTER the
               '-EPI' on the command line if you do not want these options used.

 -parfix n v   = Fix parameter #n to be exactly at value 'v'.

 -parang n b t = Allow parameter #n to range only between 'b' and 't'.
                 If not given, default ranges are used.

 -parini n v   = Initialize parameter #n to value 'v', but then
                 allow the algorithm to adjust it.
         **N.B.: Multiple '-par...' options can be used, to constrain
                 multiple parameters.
         **N.B.: -parini has no effect if -twopass is used, since
                 the -twopass algorithm carries out its own search
                 for initial parameters.

 -maxrot dd    = Allow maximum rotation of 'dd' degrees.  Equivalent
                 to '-parang 4 -dd dd -parang 5 -dd dd -parang 6 -dd dd'
                 [Default=30 degrees]

 -maxshf dd    = Allow maximum shift of 'dd' millimeters.  Equivalent
                 to '-parang 1 -dd dd -parang 2 -dd dd -parang 3 -dd dd'
                 [Default=32% of the size of the base image]
         **N.B.: This max shift setting is relative to the center-of-mass
                 shift, if the '-cmass' option is used.

 -maxscl dd    = Allow maximum scaling factor to be 'dd'.  Equivalent
                 to '-parang 7 1/dd dd -parang 8 1/dd dd -paran2 9 1/dd dd'
                 [Default=1.2=image can go up or down 20% in size]

 -maxshr dd    = Allow maximum shearing factor to be 'dd'. Equivalent
                 to '-parang 10 -dd dd -parang 11 -dd dd -parang 12 -dd dd'
                 [Default=0.1111 for no good reason]

 NOTE: If the datasets being registered have only 1 slice, 3dAllineate
       will automatically fix the 6 out-of-plane motion parameters to
       their 'do nothing' values, so you don't have to specify '-parfix'.

 -master mmm = Write the output dataset on the same grid as dataset
               'mmm'.  If this option is NOT given, the base dataset
               is the master.
       **N.B.: 3dAllineate transforms the source dataset to be 'similar'
               to the base image.  Therefore, the coordinate system
               of the master dataset is interpreted as being in the
               reference system of the base image.  It is thus vital
               that these finite 3D volumes overlap, or you will lose data!
       **N.B.: If 'mmm' is the string 'SOURCE', then the source dataset
               is used as the master for the output dataset grid.
               You can also use 'BASE', which is of course the default.

 -mast_dxyz del = Write the output dataset using grid spacings of
  *OR*            'del' mm.  If this option is NOT given, then the
 -newgrid del     grid spacings in the master dataset will be used.
                  This option is useful when registering low resolution
                  data (e.g., EPI time series) to high resolution
                  datasets (e.g., MPRAGE) where you don't want to
                  consume vast amounts of disk space interpolating
                  the low resolution data to some artificially fine
                  (and meaningless) spatial grid.

----------------------------------------------
DEFINITION OF AFFINE TRANSFORMATION PARAMETERS
----------------------------------------------
The 3x3 spatial transformation matrix is calculated as [S][D][U],
where [S] is the shear matrix,
      [D] is the scaling matrix, and
      [U] is the rotation (proper orthogonal) matrix.
Thes matrices are specified in DICOM-ordered (x=-R+L,y=-A+P,z=-I+S)
coordinates as:

  [U] = [Rotate_y(param#6)] [Rotate_x(param#5)] [Rotate_z(param #4)]
        (angles are in degrees)

  [D] = diag( param#7 , param#8 , param#9 )

        [    1        0     0 ]        [ 1 param#10 param#11 ]
  [S] = [ param#10    1     0 ]   OR   [ 0    1     param#12 ]
        [ param#11 param#12 1 ]        [ 0    0        1     ]

The shift vector comprises parameters #1, #2, and #3.

The goal of the program is to find the warp parameters such that
   I([x]_warped) 'is similar to' J([x]_in)
as closely as possible in some sense of 'similar', where J(x) is the
base image, and I(x) is the source image.

Using '-parfix', you can specify that some of these parameters
are fixed.  For example, '-shift_rotate_scale' is equivalent
'-affine_general -parfix 10 0 -parfix 11 0 -parfix 12 0'.
Don't even think of using the '-parfix' option unless you grok
this example!

----------- Special Note for the '-EPI' Option's Coordinates -----------
In this case, the parameters above are with reference to coordinates
  x = frequency encoding direction (by default, first axis of dataset)
  y = phase encoding direction     (by default, second axis of dataset)
  z = slice encoding direction     (by default, third axis of dataset)
This option lets you freeze some of the warping parameters in ways that
make physical sense, considering how echo-planar images are acquired.
The x- and z-scaling parameters are disabled, and shears will only affect
the y-axis.  Thus, there will be only 9 free parameters when '-EPI' is
used.  If desired, you can use a '-parang' option to allow the scaling
fixed parameters to vary (put these after the '-EPI' option):
  -parang 7 0.833 1.20     to allow x-scaling
  -parang 9 0.833 1.20     to allow z-scaling
You could also fix some of the other parameters, if that makes sense
in your situation; for example, to disable out-of-slice rotations:
  -parfix 5 0  -parfix 6 0
and to disable out of slice translation:
  -parfix 3 0
NOTE WELL: If you use '-EPI', then the output warp parameters (e.g., in
           '-1Dparam_save') apply to the (freq,phase,slice) xyz coordinates,
           NOT to the DICOM xyz coordinates, so equivalent transformations
           will be expressed with different sets of parameters entirely
           than if you don't use '-EPI'!  This comment does NOT apply
           to the output of '-1Dmatrix_save', since that matrix is
           defined relative to the RAI (DICOM) spatial coordinates.

*********** CHANGING THE ORDER OF MATRIX APPLICATION ***********
   {{{ There is no good reason to ever use these options! }}}

  -SDU or -SUD }= Set the order of the matrix multiplication
  -DSU or -DUS }= for the affine transformations:
  -USD or -UDS }=   S = triangular shear (params #10-12)
                    D = diagonal scaling matrix (params #7-9)
                    U = rotation matrix (params #4-6)
                  Default order is '-SDU', which means that
                  the U matrix is applied first, then the
                  D matrix, then the S matrix.

  -Supper      }= Set the S matrix to be upper or lower
  -Slower      }= triangular [Default=lower triangular]

  -ashift OR   }= Apply the shift parameters (#1-3) after OR
  -bshift      }= before the matrix transformation. [Default=after]

            ==================================================
        ===== RWCox - September 2006 - Live Long and Prosper =====
            ==================================================

         ********************************************************
        *** From Webster's Dictionary: Allineate == 'to align' ***
         ********************************************************

===========================================================================
                       FORMERLY SECRET HIDDEN OPTIONS
---------------------------------------------------------------------------
        ** N.B.: Most of these are experimental! [permanent beta] **
===========================================================================

 -num_rtb n  = At the beginning of the fine pass, the best set of results
               from the coarse pass are 'refined' a little by further
               optimization, before the single best one is chosen for
               for the final fine optimization.
              * This option sets the maximum number of cost functional
                evaluations to be used (for each set of parameters)
                in this step.
              * The default is 99; a larger value will take more CPU
                time but may give more robust results.
              * If you want to skip this step entirely, use '-num_rtb 0'.
                then, the best of the coarse pass results is taken
                straight to the final optimization passes.
       **N.B.: If you use '-VERB', you will see that one extra case
               is involved in this initial fine refinement step; that
               case is starting with the identity transformation, which
               helps insure against the chance that the coarse pass
               optimizations ran totally amok.

 -nocast     = By default, parameter vectors that are too close to the
               best one are cast out at the end of the coarse pass
               refinement process. Use this option if you want to keep
               them all for the fine resolution pass.

 -norefinal  = Do NOT re-start the fine iteration step after it
               has converged.  The default is to re-start it, which
               usually results in a small improvement to the result
               (at the cost of CPU time).  This re-start step is an
               an attempt to avoid a local minimum trap.  It is usually
               not necessary, but sometimes helps.

 -realaxes   = Use the 'real' axes stored in the dataset headers, if they
               conflict with the default axes.  [For Jedi AFNI Masters only!]

 -savehist sss = Save start and final 2D histograms as PGM
                 files, with prefix 'sss' (cost: cr mi nmi hel).
                * if filename contains 'FF', floats is written
                * these are the weighted histograms!
                * -savehist will also save histogram files when
                  the -allcost evaluations takes place
                * this option is mostly useless unless '-histbin' is
                  also used
 -median       = Smooth with median filter instead of Gaussian blur.
                 (Somewhat slower, and not obviously useful.)

 -powell m a   = Set the Powell NEWUOA dimensional parameters to
                 'm' and 'a' (cf. source code in powell_int.c).
                 The number of points used for approximating the
                 cost functional is m*N+a, where N is the number
                 of parameters being optimized.  The default values
                 are m=2 and a=3.  Larger values will probably slow
                 the program down for no good reason.  The smallest
                 allowed values are 1.

 -target ttt   = Same as '-source ttt'.  In the earliest versions,
                 what I now call the 'source' dataset was called the
                 'target' dataset:
                    Try to remember the kind of September (2006)
                    When life was slow and oh so mellow
                    Try to remember the kind of September
                    When grass was green and source was target.
 -Xwarp       =} Change the warp/matrix setup so that only the x-, y-, or z-
 -Ywarp       =} axis is stretched & sheared.  Useful for EPI, where 'X',
 -Zwarp       =} 'Y', or 'Z' corresponds to the phase encoding direction.
 -FPS fps      = Generalizes -EPI to arbitrary permutation of directions.

 -histpow pp   = By default, the number of bins in the histogram used
                 for calculating the Hellinger, Mutual Information, and
                 Correlation Ratio statistics is n^(1/3), where n is
                 the number of data points.  You can change that exponent
                 to 'pp' with this option.
 -histbin nn   = Or you can just set the number of bins directly to 'nn'.
 -eqbin   nn   = Use equalized marginal histograms with 'nn' bins.
 -clbin   nn   = Use 'nn' equal-spaced bins except for the bot and top,
                 which will be clipped (thus the 'cl').  If nn is 0, the
                 program will pick the number of bins for you.
                 **N.B.: '-clbin 0' is now the default [25 Jul 2007];
                         if you want the old all-equal-spaced bins, use
                         '-histbin 0'.
                 **N.B.: '-clbin' only works when the datasets are
                         non-negative; any negative voxels in either
                         the input or source volumes will force a switch
                         to all equal-spaced bins.

 -wtmrad  mm   = Set autoweight/mask median filter radius to 'mm' voxels.
 -wtgrad  gg   = Set autoweight/mask Gaussian filter radius to 'gg' voxels.
 -nmsetup nn   = Use 'nn' points for the setup matching [default=98756]
 -ignout       = Ignore voxels outside the warped source dataset.

 -blok bbb     = Blok definition for the 'lp?' (Local Pearson) cost
                 functions: 'bbb' is one of
                   'BALL(r)' or 'CUBE(r)' or 'RHDD(r)' or 'TOHD(r)'
                 corresponding to
                   spheres or cubes or rhombic dodecahedra or
                   truncated octahedra
                 where 'r' is the size parameter in mm.
                 [Default is 'RHDD(6.54321)' (rhombic dodecahedron)]

 -allcost        = Compute ALL available cost functionals and print them
                   at various points.
 -allcostX       = Compute and print ALL available cost functionals for the
                   un-warped inputs, and then quit.
 -allcostX1D p q = Compute ALL available cost functionals for the set of
                   parameters given in the 1D file 'p' (12 values per row),
                   write them to the 1D file 'q', then exit. (For you, Zman)
                  * N.B.: If -fineblur is used, that amount of smoothing
                          will be applied prior to the -allcostX evaluations.
                          The parameters are the rotation, shift, scale,
                          and shear values, not the affine transformation
                          matrix. An identity matrix could be provided as
                          "0 0 0  0 0 0  1 1 1  0 0 0" for instance or by
                          using the word "IDENTITY"

===========================================================================

Modifying '-final wsinc5'
-------------------------
 * The windowed (tapered) sinc function interpolation can be modified
     by several environment variables.  This is expert-level stuff, and
     you should understand what you are doing if you use these options.
     The simplest way to use these would be on the command line, as in
       -DAFNI_WSINC5_RADIUS=9 -DAFNI_WSINC5_TAPERFUN=Hamming

 * AFNI_WSINC5_TAPERFUN lets you choose the taper function.
     The default taper function is the minimum sidelobe 3-term cosine:
       0.4243801 + 0.4973406*cos(PI*x) + 0.0782793*cos(2*PI*x)
     If you set this environment variable to 'Hamming', then the
     minimum sidelobe 2-term cosine will be used instead:
       0.53836 + 0.46164*cos(PI*x)
     Here, 'x' is between 0 and 1, where x=0 is the center of the
     interpolation mask and x=1 is the outer edge.
 ++  Unfortunately, the 3-term cosine doesn't have a catchy name; you can
       find it (and many other) taper functions described in the paper
         AH Nuttall, Some Windows with Very Good Sidelobe Behavior.
         IEEE Trans. ASSP, 29:84-91 (1981).
       In particular, see Fig.14 and Eq.36 in this paper.

 * AFNI_WSINC5_TAPERCUT lets you choose the start 'x' point for tapering:
     This value should be between 0 and 0.8; for example, 0 means to taper
     all the way from x=0 to x=1 (maximum tapering).  The default value
     is 0.  Setting TAPERCUT to 0.5 (say) means only to taper from x=0.5
     to x=1; thus, a larger value means that fewer points are tapered
     inside the interpolation mask.

 * AFNI_WSINC5_RADIUS lets you choose the radius of the tapering window
     (i.e., the interpolation mask region).  This value is an integer
     between 3 and 21.  The default value is 5 (which used to be the
     ONLY value, thus 'wsinc5').  RADIUS is measured in voxels, not mm.

 * AFNI_WSINC5_SPHERICAL lets you choose the shape of the mask region.
     If you set this value to 'Yes', then the interpolation mask will be
     spherical; otherwise, it defaults to cubical.

 * The Hamming taper function is a little faster than the 3-term function,
     but will have a little more Gibbs phenomenon.
 * A larger TAPERCUT will give a little more Gibbs phenomenon; compute
     speed won't change much with this parameter.
 * Compute time goes up with (at least) the 3rd power of the RADIUS; setting
     RADIUS to 21 will be VERY slow.
 * Visually, RADIUS=3 is similar to quintic interpolation.  Increasing
     RADIUS makes the interpolated images look sharper and more well-
     defined.  However, values of RADIUS greater than or equal to 7 appear
     (to Zhark's eagle eye) to be almost identical.  If you really care,
     you'll have to experiment with this parameter yourself.
 * A spherical mask is also VERY slow, since the cubical mask allows
     evaluation as a tensor product.  There is really no good reason
     to use a spherical mask; I only put it in for experimental purposes.
** For most users, there is NO reason to ever use these environment variables
     to modify wsinc5.  You should only do this kind of thing if you have a
     good and articulable reason!  (Or if you really like to screw around.)
** The wsinc5 interpolation function is parallelized using OpenMP, which
     makes its usage moderately tolerable.

===========================================================================

Hidden experimental cost functionals:
-------------------------------------
   sp   *OR*  spearman        = Spearman [rank] Correlation
   je   *OR*  jointentropy    = Joint Entropy [H(b,s)]
   lss  *OR*  signedPcor      = Signed Pearson Correlation

Notes for the new [Feb 2010] lpc+ cost functional:
--------------------------------------------------
 * The cost functional named 'lpc+' is a combination of several others:
     lpc + hel*0.4 + crA*0.4 + nmi*0.2 + mi*0.2 + ov*0.4
   ++ 'hel', 'crA', 'nmi', and 'mi' are the histogram-based cost
      functionals also available as standalone options.
   ++ 'ov' is a measure of the overlap of the automasks of the base and
      source volumes; ov is not available as a standalone option.

 * The purpose of lpc+ is to avoid situations where the pure lpc cost
   goes wild; this especially happens if '-source_automask' isn't used.
   ++ Even with lpc+, you should use '-source_automask+2' (say) to be safe.

 * You can alter the weighting of the extra functionals by giving the
   option in the form (for example)
     '-lpc+hel*0.5+nmi*0+mi*0+crA*1.0+ov*0.5'

 * The quotes are needed to prevent the shell from wild-card expanding
   the '*' character.
   --> You can now use ':' in place of '*' to avoid this wildcard problem:
         -lpc+hel:0.5+nmi:0+mi:0+crA:1+ov:0.5+ZZ

 * Notice the weight factors FOLLOW the name of the extra functionals.
   ++ If you want a weight to be 0 or 1, you have to provide for that
      explicitly -- if you leave a weight off, then it will get its
      default value!
   ++ The order of the weight factor names is unimportant here:
        '-lpc+hel*0.5+nmi*0.8' == '-lpc+nmi*0.8+hel*0.5'

 * Only the 5 functionals listed (hel,crA,nmi,mi,ov) can be used in '-lpc+'.

 * In addition, if you want the initial alignments to be with '-lpc+' and
   then finish the Final alignment with pure '-lpc', you can indicate this
   by putting 'ZZ' somewhere in the option string, as in '-lpc+ZZ'.

 * [28 Nov 2018]
   All of the above now applies to the 'lpa+' cost functional,
   which can be used as a robust method for like-to-like alignment.

Cost functional descriptions (for use with -allcost output):
------------------------------------------------------------
   ls  :: 1 - abs(Pearson correlation coefficient)
   sp  :: 1 - abs(Spearman correlation coefficient)
   mi  :: - Mutual Information = H(base,source)-H(base)-H(source)
   crM :: 1 - abs[ CR(base,source) * CR(source,base) ]
   nmi :: 1/Normalized MI = H(base,source)/[H(base)+H(source)]
   je  :: H(base,source) = joint entropy of image pair
   hel :: - Hellinger distance(base,source)
   crA :: 1 - abs[ CR(base,source) + CR(source,base) ]
   crU :: CR(source,base) = Var(source|base) / Var(source)
   lss :: Pearson correlation coefficient between image pair
   lpc :: nonlinear average of Pearson cc over local neighborhoods
   lpa :: 1 - abs(lpc)
   lpc+:: lpc + hel + mi + nmi + crA + overlap
   lpa+:: lpa + hel + mi + nmi + crA + overlap

 * N.B.: Some cost functional values (as printed out above)
   are negated from their theoretical descriptions (e.g., 'hel')
   so that the best image alignment will be found when the cost
   is minimized.  See the descriptions above and the references
   below for more details for each functional.

 * For more information about the 'lpc' functional, see
     ZS Saad, DR Glen, G Chen, MS Beauchamp, R Desai, RW Cox.
       A new method for improving functional-to-structural
       MRI alignment using local Pearson correlation.
       NeuroImage 44: 839-848, 2009.
     http://dx.doi.org/10.1016/j.neuroimage.2008.09.037
     https://afni.nimh.nih.gov/sscc/rwcox/papers/LocalPearson2009.pdf
   The '-blok' option can be used to control the regions
   (size and shape) used to compute the local correlations.
 *** Using the 'lpc' functional wisely requires the use of
     a proper weight volume.  We HIGHLY recommend you use
     the align_epi_anat.py script if you want to use this
     cost functional!  Otherwise, you are likely to get
     less than optimal results (and then swear at us unjustly).

 * For more information about the 'cr' functionals, see
     http://en.wikipedia.org/wiki/Correlation_ratio
   Note that CR(x,y) is not the same as CR(y,x), which
   is why there are symmetrized versions of it available.

 * For more information about the 'mi', 'nmi', and 'je'
   cost functionals, see
     http://en.wikipedia.org/wiki/Mutual_information
     http://en.wikipedia.org/wiki/Joint_entropy
     http://www.cs.jhu.edu/~cis/cista/746/papers/mutual_info_survey.pdf

 * For more information about the 'hel' functional, see
     http://en.wikipedia.org/wiki/Hellinger_distance

 * Some cost functionals (e.g., 'mi', 'cr', 'hel') are
   computed by creating a 2D joint histogram of the
   base and source image pair.  Various options above
   (e.g., '-histbin', etc.) can be used to control the
   number of bins used in the histogram on each axis.
   (If you care to control the program in such detail!)

 * Minimization of the chosen cost functional is done via
   the NEWUOA software, described in detail in
     MJD Powell. 'The NEWUOA software for unconstrained
       optimization without derivatives.' In: GD Pillo,
       M Roma (Eds), Large-Scale Nonlinear Optimization.
       Springer, 2006.
     http://www.damtp.cam.ac.uk/user/na/NA_papers/NA2004_08.pdf

===========================================================================

 -nwarp type = Experimental nonlinear warping:

              ***** Note that these '-nwarp' options are superseded  *****
              ***** by the AFNI program 3dQwarp,  which does a more  *****
              ***** accurate and better and job of nonlinear warping *****
              ***** ------ Zhark the Warper ------ July 2013 ------- *****

              * At present, the only 'type' is 'bilinear',
                as in 3dWarpDrive, with 39 parameters.
              * I plan to implement more complicated nonlinear
                warps in the future, someday ....
              * -nwarp can only be applied to a source dataset
                that has a single sub-brick!
              * -1Dparam_save and -1Dparam_apply work with
                bilinear warps; see the Notes for more information.
        ==>>*** Nov 2010: I have now added the following polynomial
                warps: 'cubic', 'quintic', 'heptic', 'nonic' (using
                3rd, 5th, 7th, and 9th order Legendre polynomials); e.g.,
                   -nwarp heptic
              * These are the nonlinear warps that I now am supporting.
              * Or you can call them 'poly3', 'poly5', 'poly7', and 'poly9',
                  for simplicity and non-Hellenistic clarity.
              * These names are not case sensitive: 'nonic' == 'Nonic', etc.
              * Higher and higher order polynomials will take longer and longer
                to run!
              * If you wish to apply a nonlinear warp, you have to supply
                a parameter file with -1Dparam_apply and also specify the
                warp type with -nwarp.  The number of parameters in the
                file (per line) must match the warp type:
                   bilinear =  43   [for all nonlinear warps, the final]
                   cubic    =  64   [4 'parameters' are fixed values to]
                   quintic  = 172   [normalize the coordinates to -1..1]
                   heptic   = 364   [for the nonlinear warp functions. ]
                   nonic    = 664
                In all these cases, the first 12 parameters are the
                affine parameters (shifts, rotations, etc.), and the
                remaining parameters define the nonlinear part of the warp
                (polynomial coefficients); thus, the number of nonlinear
                parameters over which the optimization takes place is
                the number in the table above minus 16.
               * The actual polynomial functions used are products of
                 Legendre polynomials, but the symbolic names used in
                 the header line in the '-1Dparam_save' output just
                 express the polynomial degree involved; for example,
                      quint:x^2*z^3:z
                 is the name given to the polynomial warp basis function
                 whose highest power of x is 2, is independent of y, and
                 whose highest power of z is 3; the 'quint' indicates that
                 this was used in '-nwarp quintic'; the final ':z' signifies
                 that this function was for deformations in the (DICOM)
                 z-direction (+z == Superior).
        ==>>*** You can further control the form of the polynomial warps
                (but not the bilinear warp!) by restricting their degrees
                of freedom in 2 different ways.
                ++ You can remove the freedom to have the nonlinear
                   deformation move along the DICOM x, y, and/or z axes.
                ++ You can remove the dependence of the nonlinear
                   deformation on the DICOM x, y, and/or z coordinates.
                ++ To illustrate with the six second order polynomials:
                      p2_xx(x,y,z) = x*x  p2_xy(x,y,z) = x*y
                      p2_xz(x,y,z) = x*z  p2_yy(x,y,z) = y*y
                      p2_yz(x,y,z) = y*z  p2_zz(x,y,z) = z*z
                   Unrestricted, there are 18 parameters associated with
                   these polynomials, one for each direction of motion (x,y,z)
                   * If you remove the freedom of the nonlinear warp to move
                     data in the z-direction (say), then there would be 12
                     parameters left.
                   * If you instead remove the freedom of the nonlinear warp
                     to depend on the z-coordinate, you would be left with
                     3 basis functions (p2_xz, p2_yz, and p2_zz would be
                     eliminated), each of which would have x-motion, y-motion,
                     and z-motion parameters, so there would be 9 parameters.
                ++ To fix motion along the x-direction, use the option
                   '-nwarp_fixmotX' (and '-nwarp_fixmotY' and '-nwarp_fixmotZ).
                ++ To fix dependence of the polynomial warp on the x-coordinate,
                   use the option '-nwarp_fixdepX' (et cetera).
                ++ These coordinate labels in the options (X Y Z) refer to the
                   DICOM directions (X=R-L, Y=A-P, Z=I-S).  If you would rather
                   fix things along the dataset storage axes, you can use
                   the symbols I J K to indicate the fastest to slowest varying
                   array dimensions (e.g., '-nwarp_fixdepK').
                   * Mixing up the X Y Z and I J K forms of parameter freezing
                     (e.g., '-nwarp_fixmotX -nwarp_fixmotJ') may cause trouble!
                ++ If you input a 2D dataset (a single slice) to be registered
                   with '-nwarp', the program automatically assumes '-nwarp_fixmotK'
                   and '-nwarp_fixdepK' so there are no out-of-plane parameters
                   or dependence.  The number of nonlinear parameters is then:
                     2D: cubic = 14 ; quintic =  36 ; heptic =  66 ; nonic = 104.
                     3D: cubic = 48 ; quintic = 156 ; heptic = 348 ; nonic = 648.
                     [ n-th order: 2D = (n+4)*(n-1) ; 3D = (n*n+7*n+18)*(n-1)/2 ]
                ++ Note that these '-nwarp_fix' options have no effect on the
                   affine part of the warp -- if you want to constrain that as
                   well, you'll have to use the '-parfix' option.
                   * However, for 2D images, the affine part will automatically
                     be restricted to in-plane (6 parameter) 'motions'.
                ++ If you save the warp parameters (with '-1Dparam_save') when
                   doing 2D registration, all the parameters will be saved, even
                   the large number of them that are fixed to zero. You can use
                   '1dcat -nonfixed' to remove these columns from the 1D file if
                   you want to further process the varying parameters (e.g., 1dsvd).
              **++ The mapping from I J K to X Y Z (DICOM coordinates), where the
                   '-nwarp_fix' constraints are actually applied, is very simple:
                   given the command to fix K (say), the coordinate X, or Y, or Z
                   whose direction most closely aligns with the dataset K grid
                   direction is chosen.  Thus, for coronal images, K is in the A-P
                   direction, so '-nwarp_fixmotK' is translated to '-nwarp_fixmotY'.
                   * This simplicity means that using the '-nwarp_fix' commands on
                     oblique datasets is problematic.  Perhaps it would work in
                     combination with the '-EPI' option, but that has not been tested.

-nwarp NOTES:
-------------
* -nwarp is slow - reeeaaallll slow - use it with OpenMP!
* Check the results to make sure the optimizer didn't run amok!
   (You should ALWAYS do this with any registration software.)
* For the nonlinear warps, the largest coefficient allowed is
   set to 0.10 by default.  If you wish to change this, use an
   option like '-nwarp_parmax 0.05' (to make the allowable amount
   of nonlinear deformation half the default).
  ++ N.B.: Increasing the maximum past 0.10 may give very bad results!!
* If you use -1Dparam_save, then you can apply the nonlinear
   warp to another dataset using -1Dparam_apply in a later
   3dAllineate run. To do so, use '-nwarp xxx' in both runs
   , so that the program knows what the extra parameters in
   the file are to be used for.
  ++ Bilinear: 43 values are saved in 1 row of the param file.
  ++ The first 12 are the affine parameters
  ++ The next 27 are the D1,D2,D3 matrix parameters (cf. infra).
  ++ The final 'extra' 4 values are used to specify
      the center of coordinates (vector Xc below), and a
      pre-computed scaling factor applied to parameters #13..39.
  ++ For polynomial warps, a similar format is used (mutatis mutandis).
* The option '-nwarp_save sss' lets you save a 3D dataset of the
  the displacement field used to create the output dataset.  This
  dataset can be used in program 3dNwarpApply to warp other datasets.
  ++ If the warp is symbolized by x -> w(x) [here, x is a DICOM 3-vector],
     then the '-nwarp_save' dataset contains w(x)-x; that is, it contains
     the warp displacement of each grid point from its grid location.
  ++ Also see program 3dNwarpCalc for other things you can do with this file:
       warp inversion, catenation, square root, ...

* Bilinear warp formula:
   Xout = inv[ I + {D1 (Xin-Xc) | D2 (Xin-Xc) | D3 (Xin-Xc)} ] [ A Xin ]
  where Xin  = input vector  (base dataset coordinates)
        Xout = output vector (source dataset coordinates)
        Xc   = center of coordinates used for nonlinearity
               (will be the center of the base dataset volume)
        A    = matrix representing affine transformation (12 params)
        I    = 3x3 identity matrix
    D1,D2,D3 = three 3x3 matrices (the 27 'new' parameters)
               * when all 27 parameters == 0, warp is purely affine
     {P|Q|R} = 3x3 matrix formed by adjoining the 3-vectors P,Q,R
    inv[...] = inverse 3x3 matrix of stuff inside '[...]'
* The inverse of a bilinear transformation is another bilinear
   transformation.  Someday, I may write a program that will let
   you compute that inverse transformation, so you can use it for
   some cunning and devious purpose.
* If you expand the inv[...] part of the above formula in a 1st
   order Taylor series, you'll see that a bilinear warp is basically
   a quadratic warp, with the additional feature that its inverse
   is directly computable (unlike a pure quadratic warp).
* 'bilinearD' means the matrices D1, D2, and D3 with be constrained
  to be diagonal (a total of 9 nonzero values), rather than full
  (a total of 27 nonzero values).  This option is much faster.
* Is '-nwarp bilinear' useful?  Try it and tell me!
* Unlike a bilinear warp, the polynomial warps cannot be exactly
  inverted.  At some point, I'll write a program to compute an
  approximate inverse, if there is enough clamor for such a toy.

===========================================================================

 =========================================================================
* This binary version of 3dAllineate is compiled using OpenMP, a semi-
   automatic parallelizer software toolkit, which splits the work across
   multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
   by a network (e.g., OpenMP doesn't work with 'cluster' setups).
* For implementation and compilation details, please see
   https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
   your system. You can control this value by setting environment variable
   OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
   using all CPUs available.
   ++ However, on some systems, it seems to be necessary to set variable
      OMP_NUM_THREADS explicitly, or you only get one CPU.
   ++ On other systems with many CPUS, you probably want to limit the CPU
      count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
   since OpenMP queries this variable BEFORE the program actually starts.
   ++ You can't usefully set this variable in your ~/.afnirc file or on the
      command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
   it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 2.
* The maximum number of CPUs that will be used is now set to .... 2.
* OpenMP may or may not speed up the program significantly.  Limited
   tests show that it provides some benefit, particularly when using
   the more complicated interpolation methods (e.g., '-cubic' and/or
   '-final wsinc5'), for up to 3-4 CPU threads.
* But the speedup is definitely not linear in the number of threads, alas.
   Probably because my parallelization efforts were pretty limited.
 =========================================================================

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAmpToRSFC

  This program is for converting spectral amplitudes into standard RSFC
  parameters.  This function is made to work directly with the outputs of
  3dLombScargle, but you could use other inputs that have similar 
  formatting. (3dLombScargle's main algorithm is special because it
  calculates spectra from time series with nonconstant sampling, such as if
  some time points have been censored during processing-- check it out!.)

  At present, 6 RSFC parameters get returned in separate volumes:
     ALFF, mALFF, fALFF, RSFA, mRSFA and fRSFA.
  For more information about each RSFC parameter, see, e.g.:   
     ALFF/mALFF -- Zang et al. (2007),
     fALFF --      Zou et al. (2008),
     RSFA --       Kannurpatti & Biswal (2008).
  You can also see the help of 3dRSFC, as well as the Appendix of 
  Taylor, Gohel, Di, Walter and Biswal (2012) for a mathematical
  description and set of relations.

  NB: *if* you want to input an unbandpassed time series and do some
  filtering/other processing at the same time as estimating RSFC parameters,
  then you would want to use 3dRSFC, instead.

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + COMMAND: 
        3dAmpToRSFC { -in_amp AMPS | -in_pow POWS } -prefix PREFIX \
            -band FBOT FTOP  { -mask MASK } { -nifti }

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + RUNNING:

   -in_amp AMPS   :input file of one-sided spectral amplitudes, such as
                    output by 3dLombScargle.  It is also assumed that the
                    the frequencies are uniformly spaced with a single DF
                    ('delta f'), and that the zeroth brick is at 1*DF (i.e.
                    that the zeroth/baseline frequency is not present in the
         or         spectrum.
   -in_pow POWS    :input file of a one-sided power spectrum, such as
                    output by 3dLombScargle.  Similar freq assumptions
                    as in '-in_amp ...'.

   -band FBOT FTOP :lower and upper boundaries, respectively, of the low
                    frequency fluctuations (LFFs), which will be in the
                    inclusive interval [FBOT, FTOP], within the provided
                    input file's frequency range.
   -prefix PREFIX  :output file prefix; file names will be: PREFIX_ALFF*,
                    PREFIX_FALFF*, etc.

   -mask MASK      :volume mask of voxels to include for calculations; if
                    no mask is included, values are calculated for voxels
                    whose values are not identically zero across time.
   -nifti          :output files as *.nii.gz (default is BRIK/HEAD).

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  + OUTPUT: 
       Currently, 6 volumes of common RSFC parameters, briefly:
          PREFIX_ALFF+orig    :amplitude of low freq fluctuations
                               (L1 sum).
          PREFIX_MALFF+orig   :ALFF divided by the mean value within
                               the input/estimated whole brain mask
                               (a.k.a. 'mean-scaled ALFF').
          PREFIX_FALFF+orig   :ALFF divided by sum of full amplitude
                               spectrum (-> 'fractional ALFF').
          PREFIX_RSFA+orig    :square-root of summed square of low freq
                               fluctuations (L2 sum).
          PREFIX_MRSFA+orig   :RSFA divided by the mean value within
                               the input/estimated whole brain mask
                               (a.k.a. 'mean-scaled RSFA').
          PREFIX_FRSFA+orig   :ALFF divided by sum of full amplitude
                               spectrum (a.k.a. 'fractional RSFA').

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + EXAMPLE:
        3dAmpToRSFC                         \
            -in_amp SUBJ_01_amp.nii.gz     \
            -prefix  SUBJ_01                \
            -mask    mask_WB.nii.gz         \
            -band    0.01  0.1              \
            -nifti 

___________________________________________________________________________



AFNI program: 3dAnatNudge
*+ WARNING: This program (3dAnatNudge) is old, obsolete, and not maintained!
Usage: 3dAnatNudge [options]
Moves the anat dataset around to best overlap the epi dataset.

OPTIONS:
 -anat aaa   = aaa is an 'scalped' (3dIntracranial) high-resolution
                anatomical dataset [a mandatory option]
 -epi eee    = eee is an EPI dataset [a mandatory option]
                The first [0] sub-brick from each dataset is used,
                unless otherwise specified on the command line.
 -prefix ppp = ppp is the prefix of the output dataset;
                this dataset will differ from the input only
                in its name and its xyz-axes origin
                [default=don't write new dataset]
 -step sss   = set the step size to be sss times the voxel size
                in the anat dataset [default=1.0]
 -x nx       = search plus and minus nx steps along the EPI
 -y ny          dataset's x-axis; similarly for ny and the
 -z nz          y-axis, and for nz and the z-axis
                [default: nx=1 ny=5 nz=0]
 -verb       = print progress reports (this is a slow program)

NOTES
*Systematically moves the anat dataset around and find the shift
  that maximizes overlap between the anat dataset and the EPI
  dataset.  No rotations are done.
*Note that if you use -prefix, a new dataset will be created that
  is a copy of the anat, except that it's origin will be shifted
  and it will have a different ID code than the anat.  If you want
  to use this new dataset as the anatomy parent for the EPI
  datasets, you'll have to use
    3drefit -apar ppp+orig eee1+orig eee2+orig ...
*If no new dataset is written (no -prefix option), then you
  can use the 3drefit command emitted at the end to modify
  the origin of the anat dataset.  (Assuming you trust the
  results - visual inspection is recommended!)
*The reason the default search grid is mostly along the EPI y-axis
  is that axis is usually the phase-encoding direction, which is
  most subject to displacement due to off-resonance effects.
*Note that the time this program takes will be proportional to
  (2*nx+1)*(2*ny+1)*(2*nz+1), so using a very large search grid
  will result in a very large usage of CPU time.
*Recommended usage:
 + Make a 1-brick function volume from a typical EPI dataset:
     3dbucket -fbuc -prefix epi_fb epi+orig
 + Use 3dIntracranial to scalp a T1-weighted volume:
     3dIntracranial -anat spgr+orig -prefix spgr_st
 + Use 3dAnatNudge to produce a shifted anat dataset
     3dAnatNudge -anat spgr_st+orig -epi epi_fb+orig -prefix spgr_nudge
 + Start AFNI and look at epi_fb overlaid in color on the
    anat datasets spgr_st+orig and spgr_nudge+orig, to see if the
    nudged dataset seems like a better fit.
 + Delete the nudged dataset spgr_nudge.
 + If the nudged dataset DOES look better, then apply the
    3drefit command output by 3dAnatNudge to spgr+orig.
*Note that the x-, y-, and z-axes for the epi and anat datasets
  may point in different directions (e.g., axial SPGR and
  coronal EPI).  The 3drefit command applies to the anat
  dataset, NOT to the EPI dataset.
*If the program runs successfully, the only thing set to stdout
  will be the 3drefit command string; all other messages go to
  stderr.  This can be useful if you want to capture the command
  to a shell variable and then execute it, as in the following
  csh fragment:
     set cvar = `3dAnatNudge ...`
     if( $cvar[1] == "3drefit" ) $cvar
  The test on the first sub-string in cvar allows for the
  possibility that the program fails, or that the optimal
  nudge is zero.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAnhist
Usage: 3dAnhist [options] dataset
Input dataset is a T1-weighted high-res of the brain (shorts only).
Output is a list of peaks in the histogram, to stdout, in the form
  ( datasetname #peaks peak1 peak2 ... )
In the C-shell, for example, you could do
  set anhist = `3dAnhist -q -w1 dset+orig`
Then the number of peaks found is in the shell variable $anhist[2].

Options:
  -q  = be quiet (don't print progress reports)
  -h  = dump histogram data to Anhist.1D and plot to Anhist.ps
  -F  = DON'T fit histogram with stupid curves.
  -w  = apply a Winsorizing filter prior to histogram scan
         (or -w7 to Winsorize 7 times, etc.)
  -2  = Analyze top 2 peaks only, for overlap etc.

  -label xxx = Use 'xxx' for a label on the Anhist.ps plot file
                instead of the input dataset filename.
  -fname fff = Use 'fff' for the filename instead of 'Anhist'.

If the '-2' option is used, AND if 2 peaks are detected, AND if
the -h option is also given, then stdout will be of the form
  ( datasetname 2 peak1 peak2 thresh CER CJV count1 count2 count1/count2)
where 2      = number of peaks
      thresh = threshold between peak1 and peak2 for decision-making
      CER    = classification error rate of thresh
      CJV    = coefficient of joint variation
      count1 = area under fitted PDF for peak1
      count2 = area under fitted PDF for peak2
      count1/count2 = ratio of the above quantities
NOTA BENE
---------
* If the input is a T1-weighted MRI dataset (the usual case), then
   peak 1 should be the gray matter (GM) peak and peak 2 the white
   matter (WM) peak.
* For the definitions of CER and CJV, see the paper
   Method for Bias Field Correction of Brain T1-Weighted Magnetic
   Resonance Images Minimizing Segmentation Error
   JD Gispert, S Reig, J Pascau, JJ Vaquero, P Garcia-Barreno,
   and M Desco, Human Brain Mapping 22:133-144 (2004).
* Roughly speaking, CER is the ratio of the overlapping area of the
   2 peak fitted PDFs to the total area of the fitted PDFS.  CJV is
   (sigma_GM+sigma_WM)/(mean_WM-mean_GM), and is a different, ad hoc,
   measurement of how much the two PDF overlap.
* The fitted PDFs are NOT Gaussians.  They are of the form
   f(x) = b((x-p)/w,a), where p=location of peak, w=width, 'a' is
   a skewness parameter between -1 and 1; the basic distribution
   is defined by b(x)=(1-x^2)^2*(1+a*x*abs(x)) for -1 < x < 1.

-- RWCox - November 2004

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAttribute
Usage: 3dAttribute [options] aname dset
Prints (to stdout) the value of the attribute 'aname' from
the header of dataset 'dset'.  If the attribute doesn't exist,
prints nothing and sets the exit status to 1.

Options:
  -name = Include attribute name in printout
  -all  = Print all attributes [don't put aname on command line]
          Also implies '-name'.  Attributes print in whatever order
          they are in the .HEAD file, one per line.  You may want
          to do '3dAttribute -all elvis+orig | sort' to get them
          in alphabetical order.
  -center = Center of volume in RAI coordinates.
            Note that center is not itself an attribute in the 
           .HEAD file. It is calculated from other attributes.
  Special options for string attributes:
    -ssep SSEP    Use string SSEP as a separator between strings for
                  multiple sub-bricks. The default is '~', which is what
                  is used internally in AFNI's .HEAD file. For tcsh,
                  I recommend ' ' which makes parsing easy, assuming each
                  individual string contains no spaces to begin with.
                  Try -ssep 'NUM'
    -sprep SPREP  Use string SPREP to replace blank space in string 
                  attributes.
    -quote        Use single quote around each string.
    Examples:
       3dAttribute -quote -ssep ' '  BRICK_LABS SomeStatDset+tlrc.BRIK
       3dAttribute -quote -ssep 'NUM' -sprep '+' BRICK_LABS SomeStatDset+tlrc.BRIK

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAutoTcorrelate
Usage: 3dAutoTcorrelate [options] dset
Computes the correlation coefficient between the time series of each
pair of voxels in the input dataset, and stores the output into a
new anatomical bucket dataset [scaled to shorts to save memory space].

*** Also see program 3dTcorrMap ***

Options:
  -pearson  = Correlation is the normal Pearson (product moment)
               correlation coefficient [default].
  -eta2     = Output is eta^2 measure from Cohen et al., NeuroImage, 2008:
               http://www.ncbi.nlm.nih.gov/pmc/articles/PMC2705206/
               http://dx.doi.org/10.1016/j.neuroimage.2008.01.066
             ** '-eta2' is intended to be used to measure the similarity
                 between 2 correlation maps; therefore, this option is
                 to be used in a second stage analysis, where the input
                 dataset is the output of running 3dAutoTcorrelate with
                 the '-pearson' option -- the voxel 'time series' from
                 that first stage run is the correlation map of that
                 voxel with all other voxels.
             ** '-polort -1' is recommended with this option!
             ** Odds are you do not want use this option if the dataset
                on which eta^2 is to be computed was generated with
                options -mask_only_targets or -mask_source.
                In this program, the eta^2 is computed between pseudo-
                timeseries (the 4th dimension of the dataset).
                If you want to compute eta^2 between sub-bricks then use
                3ddot -eta2 instead.
  -spearman AND -quadrant are disabled at this time :-(

  -polort m = Remove polynomial trend of order 'm', for m=-1..3.
               [default is m=1; removal is by least squares].
               Using m=-1 means no detrending; this is only useful
               for data/information that has been pre-processed.

  -autoclip = Clip off low-intensity regions in the dataset,
  -automask =  so that the correlation is only computed between
               high-intensity (presumably brain) voxels.  The
               mask is determined the same way that 3dAutomask works.

  -mask mmm = Mask of both 'source' and 'target' voxels.
              ** Restricts computations to those in the mask.  Output
                  volumes are restricted to masked voxels.  Also, only
                  masked voxels will have non-zero output.
              ** A dataset with 1000 voxels would lead to output of
                  1000 sub-bricks.  With a '-mask' of 50 voxels, the
                  output dataset have 50 sub-bricks, where the 950
                  unmasked voxels would be all zero in all 50 sub-bricks
                  (unless option '-mask_only_targets' is also used).
              ** The mask is encoded in the output dataset header in the
                  attribute named 'AFNI_AUTOTCORR_MASK' (cf. 3dMaskToASCII).

  -mask_only_targets = Provide output for all voxels.
              ** Used with '-mask': every voxel is correlated with each
                  of the mask voxels.  In the example above, there would
                  be 50 output sub-bricks; the n-th output sub-brick
                  would contain the correlations of the n-th voxel in
                  the mask with ALL 1000 voxels in the dataset (rather
                  than with just the 50 voxels in the mask).

  -mask_source sss = Provide ouput for voxels only in mask sss
               ** For each seed in mask mm, compute correlations only with 
                   non-zero voxels in sss. If you have 250 non-zero voxels 
                   in sss, then the output will still have 50 sub-bricks, but
                   each n-th sub-brick will have non-zero values at the 250
                   non-zero voxels in sss
                   Do not use this option along with -mask_only_targets

  -prefix p = Save output into dataset with prefix 'p'
               [default prefix is 'ATcorr'].
  -out1D FILE.1D = Save output in a text file formatted thusly:
                   Row 1 contains the 1D indices of non zero voxels in the 
                         mask from option -mask.
                   Column 1 contains the 1D indices of non zero voxels in the
                         mask from option -mask_source
                   The rest of the matrix contains the correlation/eta2 
                   values. Each column k corresponds to sub-brick k in 
                   the output volume p.
                   To see 1D indices in AFNI, right click on the top left
                   corner of the AFNI controller - where coordinates are
                   shown - and chose voxel indices.
                   A 1D index (ijk) is computed from the 3D (i,j,k) indices:
                       ijk = i + j*Ni + k*Ni*Nj , with Ni and Nj being the
                   number of voxels in the slice orientation and given by:
                       3dinfo -ni -nj YOUR_VOLUME_HERE
                   This option can only be used in conjunction with 
                   options -mask and -mask_source. Otherwise it makes little
                   sense to write a potentially enormous text file.

  -time     = Mark output as a 3D+time dataset instead of an anat bucket.

  -mmap     = Write .BRIK results to disk directly using Unix mmap().
               This trick can speed the program up  when the amount
               of memory required to hold the output is very large.
              ** In many case, the amount of time needed to write
                 the results to disk is longer than the CPU time.
                 This option can shorten the disk write time.
              ** If the program crashes, you'll have to manually
                 remove the .BRIK file, which will have been created
                 before the loop over voxels and written into during
                 that loop, rather than being written all at once
                 at the end of the analysis, as is usually the case.
              ** If the amount of memory needed is bigger than the
                 RAM on your system, this program will be very slow
                 with or without '-mmap'.
              ** This option won't work with NIfTI-1 (.nii) output!

Example: correlate every voxel in mask_in+tlrc with only those voxels in
         mask_out+tlrc (the rest of each volume is zero, for speed).
         Assume detrending was already done along with other pre-processing.
         The output will have one volume per masked voxel in mask_in+tlrc.
         Volumes will be labeled by the ijk index triples of mask_in+tlrc.

   3dAutoTcorrelate -mask_source mask_out+tlrc -mask mask_in+tlrc \
                    -polort -1 -prefix test_corr clean_epi+tlrc

Notes:
 * The output dataset is anatomical bucket type of shorts
    (unless '-time' is used).
 * Values are scaled so that a correlation (or eta-squared)
    of 1 corresponds to a value of 10000.
 * The output file might be gigantic and you might run out
    of memory running this program.  Use at your own risk!
   ++ If you get an error message like
        *** malloc error for dataset sub-brick
      this means that the program ran out of memory when making
      the output dataset.
   ++ If this happens, you can try to use the '-mmap' option,
      and if you are lucky, the program may actually run.
 * The program prints out an estimate of its memory usage
    when it starts.  It also prints out a progress 'meter'
    to keep you pacified.
 * This is a quick hack for Peter Bandettini. Now pay up.
 * OpenMP-ized for Hang Joon Jo.  Where's my baem-sul?

-- RWCox - 31 Jan 2002 and 16 Jul 2010

 =========================================================================
* This binary version of 3dAutoTcorrelate is compiled using OpenMP, a semi-
   automatic parallelizer software toolkit, which splits the work across
   multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
   by a network (e.g., OpenMP doesn't work with 'cluster' setups).
* For implementation and compilation details, please see
   https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
   your system. You can control this value by setting environment variable
   OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
   using all CPUs available.
   ++ However, on some systems, it seems to be necessary to set variable
      OMP_NUM_THREADS explicitly, or you only get one CPU.
   ++ On other systems with many CPUS, you probably want to limit the CPU
      count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
   since OpenMP queries this variable BEFORE the program actually starts.
   ++ You can't usefully set this variable in your ~/.afnirc file or on the
      command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
   it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 2.
* The maximum number of CPUs that will be used is now set to .... 2.
 =========================================================================

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAutobox
++ 3dAutobox: AFNI version=AFNI_18.3.16 (Dec 11 2018) [64-bit]
Usage: 3dAutobox [options] DATASET
Computes size of a box that fits around the volume.
Also can be used to crop the volume to that box.

OPTIONS:
--------
-prefix PREFIX = Crop the input dataset to the size of the box, and
                 write an output dataset with PREFIX for the name.
               * If -prefix is not used, no new volume is written out,
                 just the (x,y,z) extents of the voxels to be kept.

-input DATASET = An alternate way to specify the input dataset.
                 The default method is to pass DATASET as
                 the last parameter on the command line.

-noclust       = Don't do any clustering to find box. Any non-zero
                 voxel will be preserved in the cropped volume.
                 The default method uses some clustering to find the
                 cropping box, and will clip off small isolated blobs.

-extent: Write to standard out the spatial extent of the box

-extent_ijk    = Write out the 6 auto bbox ijk slice numbers to
                 screen:
                     imin imax jmin jmax kmin kmax
                 Note that resampling would affect the ijk vals (but
                 not necessarily the xyz ones).
                 Also note that this value is calculated before
                 any '-npad ...' option, so it would ignore that.

-extent_ijk_to_file FF = Write out the 6 auto bbox ijk slice numbers to
                 a simple-formatted text file FF (single row file):
                     imin imax jmin jmax kmin kmax
                 (same notes as above apply).

-extent_ijk_midslice = Write out the 3 ijk midslices of the autobox to
                 the screen:
                     imid jmid kmid
                 These are obtained via: (imin + imax)/2, etc.

-extent_xyz_midslice = Write out the 3 xyz midslices of the autobox to
                 the screen:
                     xmid ymid zmid
                 These are obtained via: (xmin + xmax)/2, etc.
                 These follow the same meaning as '-extent'.

-npad NNN      = Number of extra voxels to pad on each side of box,
                 since some troublesome people (that's you, LRF) want
                 this feature for no apparent reason.
               * With this option, it is possible to get a dataset that
                 is actually bigger than the input.
               * You can input a negative value for NNN, which will
                 crop the dataset even more than the automatic method.


++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dAutomask
Usage: 3dAutomask [options] dataset
Input dataset is EPI 3D+time, or a skull-stripped anatomical.
Output dataset is a brain-only mask dataset.

This program by itself does NOT do 'skull-stripping'.  Use
program 3dSkullStrip for that purpose!

Method:
 + Uses 3dClipLevel algorithm to find clipping level.
 + Keeps only the largest connected component of the
   supra-threshold voxels, after an erosion/dilation step.
 + Writes result as a 'fim' type of functional dataset,
   which will be 1 inside the mask and 0 outside the mask.

Options:
--------
  -prefix ppp = Write mask into dataset with prefix 'ppp'.
                 [Default == 'automask']

  -apply_prefix ppp = Apply mask to input dataset and save
                masked dataset. If an apply_prefix is given
                and not the usual prefix, the only output
                will be the applied dataset

  -clfrac cc  = Set the 'clip level fraction' to 'cc', which
                 must be a number between 0.1 and 0.9.
                 A small 'cc' means to make the initial threshold
                 for clipping (a la 3dClipLevel) smaller, which
                 will tend to make the mask larger.  [default=0.5]

  -nograd     = The program uses a 'gradual' clip level by default.
                 To use a fixed clip level, use '-nograd'.
                 [Change to gradual clip level made 24 Oct 2006.]

  -peels pp   = Peel the mask 'pp' times, then unpeel.  Designed
                 to clip off protuberances less than 2*pp voxels
                 thick. [Default == 1]

  -nbhrs nn   = Define the number of neighbors needed for a voxel
                 NOT to be peeled.  The 18 nearest neighbors in
                 the 3D lattice are used, so 'nn' should be between
                 9 and 18.  [Default == 17]

  -q          = Don't write progress messages (i.e., be quiet).

  -eclip      = After creating the mask, remove exterior
                 voxels below the clip threshold.

  -dilate nd  = Dilate the mask outwards 'nd' times.

  -erode ne   = Erode the mask inwards 'ne' times.

  -SI hh      = After creating the mask, find the most superior
                 voxel, then zero out everything more than 'hh'
                 millimeters inferior to that.  hh=130 seems to
                 be decent (i.e., for Homo Sapiens brains).

  -depth DEP  = Produce a dataset (DEP) that shows how many peel 
                operations it takes to get to a voxel in the mask.
                The higher the number, the deeper a voxel is located 
                in the mask. 
          None of -peels, -dilate, or -erode affect this option.
--------------------------------------------------------------------
How to make an edge-of-brain mask from an anatomical volume:
3dSkullStrip to create a brain-only dataset; say, Astrip+orig
* 3dAutomask -prefix Amask Astrip+orig
* Create a mask of edge-only voxels via
   3dcalc -a Amask+orig -b a+i -c a-i -d a+j -e a-j -f a+k -g a-k \
          -expr 'ispositive(a)*amongst(0,b,c,d,e,f,g)' -prefix Aedge
  which will be 1 at all voxels in the brain mask that have a
  nearest neighbor that is NOT in the brain mask.
* cf. '3dcalc -help' DIFFERENTIAL SUBSCRIPTS for information
  on the 'a+i' et cetera inputs used above.
* In regions where the brain mask is 'stair-stepping', then the
  voxels buried inside the corner of the steps probably won't
  show up in this edge mask:
     ...00000000...
     ...aaa00000...
     ...bbbaa000...
     ...bbbbbaa0...
  Only the 'a' voxels are in this edge mask, and the 'b' voxels
  down in the corners won't show up, because they only touch a
  0 voxel on a corner, not face-on.  Depending on your use for
  the edge mask, this effect may or may not be a problem.
--------------------------------------------------------------------

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dBRAIN_VOYAGERtoAFNI

Usage: 3dBRAIN_VOYAGERtoAFNI <-input BV_VOLUME.vmr> 
                             [-bs] [-qx] [-tlrc|-acpc|-orig] [<-prefix PREFIX>]
 
 Converts a BrainVoyager vmr dataset to AFNI's BRIK format
 The conversion is based on information from BrainVoyager's
 website: www.brainvoyager.com. 
 Sample data and information provided by 
  Adam Greenberg and Nikolaus Kriegeskorte.

  If you get error messages about the number of
 voxels and file size, try the options below.
 I hope to automate these options once I have
 a better description of the BrainVoyager QX format.

  Optional Parameters:
  -bs: Force byte swapping.
  -qx: .vmr file is from BrainVoyager QX
  -tlrc: dset in tlrc space
  -acpc: dset in acpc-aligned space
  -orig: dset in orig space
  If unspecified, the program attempts to guess the view from
  the name of the input.
   [-novolreg]: Ignore any Rotate, Volreg, Tagalign, 
                or WarpDrive transformations present in 
                the Surface Volume.
   [-noxform]: Same as -novolreg
   [-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname
                to be ENVvalue. Quotes are necessary.
             Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'"
                See also options -update_env, -environment, etc
                in the output of 'suma -help'
  Common Debugging Options:
   [-trace]: Turns on In/Out debug and Memory tracing.
             For speeding up the tracing log, I recommend 
             you redirect stdout to a file when using this option.
             For example, if you were running suma you would use:
             suma -spec lh.spec -sv ... > TraceFile
             This option replaces the old -iodbg and -memdbg.
   [-TRACE]: Turns on extreme tracing.
   [-nomall]: Turn off memory tracing.
   [-yesmall]: Turn on memory tracing (default).
  NOTE: For programs that output results to stdout
    (that is to your shell/screen), the debugging info
    might get mixed up with your results.


Global Options (available to all AFNI/SUMA programs)
  -h: Mini help, at time, same as -help in many cases.
  -help: The entire help output
  -HELP: Extreme help, same as -help in majority of cases.
  -h_view: Open help in text editor. AFNI will try to find a GUI editor
  -hview : on your machine. You can control which it should use by
           setting environment variable AFNI_GUI_EDITOR.
  -h_web: Open help in web browser. AFNI will try to find a browser.
  -hweb : on your machine. You can control which it should use by
          setting environment variable AFNI_GUI_EDITOR. 
  -h_find WORD: Look for lines in this programs's -help output that match
                (approximately) WORD.
  -h_raw: Help string unedited
  -h_spx: Help string in sphinx loveliness, but do not try to autoformat
  -h_aspx: Help string in sphinx with autoformatting of options, etc.
  -all_opts: Try to identify all options for the program from the
             output of its -help option. Some options might be missed
             and others misidentified. Use this output for hints only.
  


Compile Date:
   Dec 11 2018

       Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov     



AFNI program: 3dBandpass

--------------------------------------------------------------------------
** NOTA BENE:  For the purpose of preparing resting-state FMRI datasets **
** for analysis (e.g., with 3dGroupInCorr),  this program is now mostly **
** superseded by the afni_proc.py script.  See the 'afni_proc.py -help' **
** section 'Resting state analysis (modern)' to get our current rs-FMRI **
** pre-processing recommended sequence of steps. -- RW Cox, et alii.    **
--------------------------------------------------------------------------
** If you insist on doing your own bandpassing, I now recommend using   **
** program 3dTproject instead of this program.  3dTproject also can do  **
** censoring and other nuisance regression at the same time -- RW Cox.  **
--------------------------------------------------------------------------

Usage: 3dBandpass [options] fbot ftop dataset

* One function of this program is to prepare datasets for input
   to 3dSetupGroupInCorr.  Other uses are left to your imagination.

* 'dataset' is a 3D+time sequence of volumes
   ++ This must be a single imaging run -- that is, no discontinuities
       in time from 3dTcat-ing multiple datasets together.

* fbot = lowest frequency in the passband, in Hz
   ++ fbot can be 0 if you want to do a lowpass filter only;
       HOWEVER, the mean and Nyquist freq are always removed.

* ftop = highest frequency in the passband (must be > fbot)
   ++ if ftop > Nyquist freq, then it's a highpass filter only.

* Set fbot=0 and ftop=99999 to do an 'allpass' filter.
  ++ Except for removal of the 0 and Nyquist frequencies, that is.

* You cannot construct a 'notch' filter with this program!
  ++ You could use 3dBandpass followed by 3dcalc to get the same effect.
  ++ If you are understand what you are doing, that is.
  ++ Of course, that is the AFNI way -- if you don't want to
     understand what you are doing, use Some other PrograM, and
     you can still get Fine StatisticaL maps.

* 3dBandpass will fail if fbot and ftop are too close for comfort.
  ++ Which means closer than one frequency grid step df,
     where df = 1 / (nfft * dt) [of course]

* The actual FFT length used will be printed, and may be larger
   than the input time series length for the sake of efficiency.
  ++ The program will use a power-of-2, possibly multiplied by
     a power of 3 and/or 5 (up to and including the 3rd power of
     each of these: 3, 9, 27, and 5, 25, 125).

* Note that the results of combining 3dDetrend and 3dBandpass will
   depend on the order in which you run these programs.  That's why
   3dBandpass has the '-ort' and '-dsort' options, so that the
   time series filtering can be done properly, in one place.

* The output dataset is stored in float format.

* The order of processing steps is the following (most are optional):
 (0) Check time series for initial transients [does not alter data]
 (1) Despiking of each time series
 (2) Removal of a constant+linear+quadratic trend in each time series
 (3) Bandpass of data time series
 (4) Bandpass of -ort time series, then detrending of data
      with respect to the -ort time series
 (5) Bandpass and de-orting of the -dsort dataset,
      then detrending of the data with respect to -dsort
 (6) Blurring inside the mask [might be slow]
 (7) Local PV calculation     [WILL be slow!]
 (8) L2 normalization         [will be fast.]

--------
OPTIONS:
--------
 -despike        = Despike each time series before other processing.
                   ++ Hopefully, you don't actually need to do this,
                      which is why it is optional.
 -ort f.1D       = Also orthogonalize input to columns in f.1D
                   ++ Multiple '-ort' options are allowed.
 -dsort fset     = Orthogonalize each voxel to the corresponding
                    voxel time series in dataset 'fset', which must
                    have the same spatial and temporal grid structure
                    as the main input dataset.
                   ++ At present, only one '-dsort' option is allowed.
 -nodetrend      = Skip the quadratic detrending of the input that
                    occurs before the FFT-based bandpassing.
                   ++ You would only want to do this if the dataset
                      had been detrended already in some other program.
 -dt dd          = set time step to 'dd' sec [default=from dataset header]
 -nfft N         = set the FFT length to 'N' [must be a legal value]
 -norm           = Make all output time series have L2 norm = 1
                   ++ i.e., sum of squares = 1
 -mask mset      = Mask dataset
 -automask       = Create a mask from the input dataset
 -blur fff       = Blur (inside the mask only) with a filter
                    width (FWHM) of 'fff' millimeters.
 -localPV rrr    = Replace each vector by the local Principal Vector
                    (AKA first singular vector) from a neighborhood
                    of radius 'rrr' millimiters.
                   ++ Note that the PV time series is L2 normalized.
                   ++ This option is mostly for Bob Cox to have fun with.

 -input dataset  = Alternative way to specify input dataset.
 -band fbot ftop = Alternative way to specify passband frequencies.

 -prefix ppp     = Set prefix name of output dataset.
 -quiet          = Turn off the fun and informative messages. (Why?)

 -notrans        = Don't check for initial positive transients in the data:
  *OR*             ++ The test is a little slow, so skipping it is OK,
 -nosat               if you KNOW the data time series are transient-free.
                   ++ Or set AFNI_SKIP_SATCHECK to YES.
                   ++ Initial transients won't be handled well by the
                      bandpassing algorithm, and in addition may seriously
                      contaminate any further processing, such as inter-voxel
                      correlations via InstaCorr.
                   ++ No other tests are made [yet] for non-stationary behavior
                      in the time series data.

 =========================================================================
* This binary version of 3dBandpass is compiled using OpenMP, a semi-
   automatic parallelizer software toolkit, which splits the work across
   multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
   by a network (e.g., OpenMP doesn't work with 'cluster' setups).
* For implementation and compilation details, please see
   https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
   your system. You can control this value by setting environment variable
   OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
   using all CPUs available.
   ++ However, on some systems, it seems to be necessary to set variable
      OMP_NUM_THREADS explicitly, or you only get one CPU.
   ++ On other systems with many CPUS, you probably want to limit the CPU
      count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
   since OpenMP queries this variable BEFORE the program actually starts.
   ++ You can't usefully set this variable in your ~/.afnirc file or on the
      command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
   it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 2.
* The maximum number of CPUs that will be used is now set to .... 2.
* At present, the only part of 3dBandpass that is parallelized is the
  '-blur' option, which processes each sub-brick independently.
 =========================================================================

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dBlurInMask
Usage: ~1~
3dBlurInMask [options]
Blurs a dataset spatially inside a mask. That's all. Experimental.

OPTIONS ~1~
-------
 -input  ddd = This required 'option' specifies the dataset
               that will be smoothed and output.
 -FWHM   f   = Add 'f' amount of smoothness to the dataset (in mm).
              **N.B.: This is also a required 'option'.
 -FWHMdset d = Read in dataset 'd' and add the amount of smoothness
               given at each voxel -- spatially variable blurring.
              ** EXPERIMENTAL EXPERIMENTAL EXPERIMENTAL **
 -mask   mmm = Mask dataset, if desired.  Blurring will
               occur only within the mask.  Voxels NOT in
               the mask will be set to zero in the output.
 -Mmask  mmm = Multi-mask dataset -- each distinct nonzero
               value in dataset 'mmm' will be treated as
               a separate mask for blurring purposes.
              **N.B.: 'mmm' must be byte- or short-valued!
 -automask   = Create an automask from the input dataset.
              **N.B.: only 1 masking option can be used!
 -preserve   = Normally, voxels not in the mask will be
               set to zero in the output.  If you want the
               original values in the dataset to be preserved
               in the output, use this option.
 -prefix ppp = Prefix for output dataset will be 'ppp'.
              **N.B.: Output dataset is always in float format.
 -quiet      = Don't be verbose with the progress reports.
 -float      = Save dataset as floats, no matter what the
               input data type is.
              **N.B.: If the input dataset is unscaled shorts, then
                      the default is to save the output in short
                      format as well.  In EVERY other case, the
                      program saves the output as floats. Thus,
                      the ONLY purpose of the '-float' option is to
                      force an all-shorts input dataset to be saved
                      as all-floats after blurring.

NOTES ~1~
-----
 * If you don't provide a mask, then all voxels will be included
     in the blurring.  (But then why are you using this program?)
 * Note that voxels inside the mask that are not contiguous with
     any other voxels inside the mask will not be modified at all!
 * Works iteratively, similarly to 3dBlurToFWHM, but without
     the extensive overhead of monitoring the smoothness.
 * But this program will be faster than 3dBlurToFWHM, and probably
     slower than 3dmerge.
 * Since the blurring is done iteratively, rather than all-at-once as
     in 3dmerge, the results will be slightly different than 3dmerge's,
     even if no mask is used here (3dmerge, of course, doesn't take a mask).
 * If the original FWHM of the dataset was 'S' and you input a value
     'F' with the '-FWHM' option, then the output dataset's smoothness
     will be about sqrt(S*S+F*F).  The number of iterations will be
     about (F*F/d*d) where d=grid spacing; this means that a large value
     of F might take a lot of CPU time!
 * The spatial smoothness of a 3D+time dataset can be estimated with a
     command similar to the following:
          3dFWHMx -detrend -mask mmm+orig -input ddd+orig
 * The minimum number of voxels in the mask is 9
 * Isolated voxels will be removed from the mask!

 =========================================================================
* This binary version of 3dBlurInMask is compiled using OpenMP, a semi-
   automatic parallelizer software toolkit, which splits the work across
   multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
   by a network (e.g., OpenMP doesn't work with 'cluster' setups).
* For implementation and compilation details, please see
   https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
   your system. You can control this value by setting environment variable
   OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
   using all CPUs available.
   ++ However, on some systems, it seems to be necessary to set variable
      OMP_NUM_THREADS explicitly, or you only get one CPU.
   ++ On other systems with many CPUS, you probably want to limit the CPU
      count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
   since OpenMP queries this variable BEFORE the program actually starts.
   ++ You can't usefully set this variable in your ~/.afnirc file or on the
      command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
   it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 2.
* The maximum number of CPUs that will be used is now set to .... 2.
 =========================================================================

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dBlurToFWHM
Usage: 3dBlurToFWHM [options]

Blurs a 'master' dataset until it reaches a specified FWHM
smoothness (approximately).  The same blurring schedule is
applied to the input dataset to produce the output.  The goal
is to make the output dataset have the given smoothness, no
matter what smoothness it had on input (however, the program
cannot 'unsmooth' a dataset!).  See below for the METHOD used.

OPTIONS
-------
 -input      ddd = This required 'option' specifies the dataset
                   that will be smoothed and output.
 -blurmaster bbb = This option specifies the dataset whose
                   whose smoothness controls the process.
                  **N.B.: If not given, the input dataset is used.
                  **N.B.: This should be one continuous run.
                          Do not input catenated runs!
 -prefix     ppp = Prefix for output dataset will be 'ppp'.
                  **N.B.: Output dataset is always in float format.
 -mask       mmm = Mask dataset, if desired.  Blurring will
                   occur only within the mask.  Voxels NOT in
                   the mask will be set to zero in the output.
 -automask       = Create an automask from the input dataset.
                  **N.B.: Not useful if the input dataset has been
                          detrended or otherwise regressed before input!
 -FWHM       f   = Blur until the 3D FWHM is 'f'.
 -FWHMxy     f   = Blur until the 2D (x,y)-plane FWHM is 'f'.
                   No blurring is done along the z-axis.
                  **N.B.: Note that you can't REDUCE the smoothness
                          of a dataset.
                  **N.B.: Here, 'x', 'y', and 'z' refer to the
                          grid/slice order as stored in the dataset,
                          not DICOM ordered coordinates!
                  **N.B.: With -FWHMxy, smoothing is done only in the
                          dataset xy-plane.  With -FWHM, smoothing
                          is done in 3D.
                  **N.B.: The actual goal is reached when
                            -FWHM  :  cbrt(FWHMx*FWHMy*FWHMz) >= f
                            -FWHMxy:  sqrt(FWHMx*FWHMy)       >= f
                          That is, when the area or volume of a
                          'resolution element' goes past a threshold.
 -quiet            Shut up the verbose progress reports.
                  **N.B.: This should be the first option, to stifle
                          any verbosity from the option processing code.

FILE RECOMMENDATIONS for -blurmaster:
For FMRI statistical purposes, you DO NOT want the FWHM to reflect
  the spatial structure of the underlying anatomy.  Rather, you want
  the FWHM to reflect the spatial structure of the noise.  This means
  that the -blurmaster dataset should not have anatomical structure.  One
  good form of input is the output of '3dDeconvolve -errts', which is
  the residuals left over after the GLM fitted signal model is subtracted
  out from each voxel's time series.  You can also use the output of
  '3dREMLfit -Rerrts' or '3dREMLfit -Rwherr' for this purpose.
You CAN give a multi-brick EPI dataset as the -blurmaster dataset; the
  dataset will be detrended in time (like the -detrend option in 3dFWHMx)
  which will tend to remove the spatial structure.  This makes it
  practicable to make the input and blurmaster datasets be the same,
  without having to create a detrended or residual dataset beforehand.
  Considering the accuracy of blurring estimates, this is probably good
  enough for government work [that is an insider's joke :-]. 
  N.B.: Do not use catenated runs as blurmasters. There should
  be no discontinuities in the time axis of blurmaster, which would
  make the simple regression detrending do peculiar things.

ALSO SEE:
 * 3dFWHMx, which estimates smoothness globally
 * 3dLocalstat -stat FWHM, which estimates smoothness locally
 * This paper, which discusses the need for a fixed level of smoothness
   when combining FMRI datasets from different scanner platforms:
     Friedman L, Glover GH, Krenz D, Magnotta V; The FIRST BIRN. 
     Reducing inter-scanner variability of activation in a multicenter
     fMRI study: role of smoothness equalization.
     Neuroimage. 2006 Oct 1;32(4):1656-68.

METHOD:
The blurring is done by a conservative finite difference approximation
to the diffusion equation:
  du/dt = d/dx[ D_x(x,y,z) du/dx ] + d/dy[ D_y(x,y,z) du/dy ]
                                   + d/dz[ D_z(x,y,z) du/dz ]
        = div[ D(x,y,z) grad[u(x,y,z)] ]
where diffusion tensor D() is diagonal, Euler time-stepping is used, and
with Neumann (reflecting) boundary conditions at the edges of the mask
(which ensures that voxel data inside and outside the mask don't mix).
* At each pseudo-time step, the FWHM is estimated globally (like '3dFWHMx')
  and locally (like '3dLocalstat -stat FWHM'). Voxels where the local FWHM
  goes past the goal will not be smoothed any more (D gets set to zero).
* When the global smoothness estimate gets close to the goal, the blurring
  rate (pseudo-time step) will be reduced, to avoid over-smoothing.
* When an individual direction's smoothness (e.g., FWHMz) goes past the goal,
  all smoothing in that direction stops, but the other directions continue
  to be smoothed until the overall resolution element goal is achieved.
* When the global FWHM estimate reaches the goal, the program is done.
  It will also stop if progress stalls for some reason, or if the maximum
  iteration count is reached (infinite loops being unpopular).
* The output dataset will NOT have exactly the smoothness you ask for, but
  it will be close (fondly we do hope).  In our Imperial experiments, the
  results (measured via 3dFWHMx) are within 10% of the goal (usually better).
* 2D blurring via -FWHMxy may increase the smoothness in the z-direction
  reported by 3dFWHMx, even though there is no inter-slice processing.
  At this moment, I'm not sure why.  It may be an estimation artifact due
  to increased correlation in the xy-plane that biases the variance estimates
  used to calculate FWHMz.

ADVANCED OPTIONS:
 -maxite  ccc = Set maximum number of iterations to 'ccc' [Default=variable].
 -rate    rrr = The value of 'rrr' should be a number between
                0.05 and 3.5, inclusive.  It is a factor to change
                the overall blurring rate (slower for rrr < 1) and thus
                require more or less blurring steps.  This option should only
                be needed to slow down the program if the it over-smooths
                significantly (e.g., it overshoots the desired FWHM in
                Iteration #1 or #2).  You can increase the speed by using
                rrr > 1, but be careful and examine the output.
 -nbhd    nnn = As in 3dLocalstat, specifies the neighborhood
                used to compute local smoothness.
                [Default = 'SPHERE(-4)' in 3D, 'SPHERE(-6)' in 2D]
               ** N.B.: For the 2D -FWHMxy, a 'SPHERE()' nbhd
                        is really a circle in the xy-plane.
               ** N.B.: If you do NOT want to estimate local
                        smoothness, use '-nbhd NULL'.
 -ACF or -acf = Use the 'ACF' method (from 3dFWHMx) to estimate
                the global smoothness, rather than the 'classic'
                Forman 1995 method. This option will be somewhat
                slower.  It will also set '-nbhd NULL', since there
                is no local ACF estimation method implemented.
 -bsave   bbb = Save the local smoothness estimates at each iteration
                with dataset prefix 'bbb' [for debugging purposes].
 -bmall       = Use all blurmaster sub-bricks.
                [Default: a subset will be chosen, for speed]
 -unif        = Uniformize the voxel-wise MAD in the blurmaster AND
                input datasets prior to blurring.  Will be restored
                in the output dataset.
 -detrend     = Detrend blurmaster dataset to order NT/30 before starting.
 -nodetrend   = Turn off detrending of blurmaster.
               ** N.B.: '-detrend' is the new default [05 Jun 2007]!
 -detin       = Also detrend input before blurring it, then retrend
                it afterwards. [Off by default]
 -temper      = Try harder to make the smoothness spatially uniform.

-- Author: The Dreaded Emperor Zhark - Nov 2006

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dBrainSync

Usage:  3dBrainSync [options]

This program 'synchronizes' the -inset2 dataset to match the -inset1
dataset, as much as possible (average voxel-wise correlation), using the
same transformation on each input time series from -inset2:

 ++ With the -Qprefix option, the transformation is an orthogonal matrix,
    computed as described in Joshi's original OHBM 2017 presentations.

 ++ With the -Pprefix option, the transformation is simply a
    permutation of the time order of -inset2 (a special case
    of an orthogonal matrix).

 ++ The algorithms and a little discussion of the different features of
    these two techniques are discussed in the METHODS section, infra.

 ++ At least one of '-Qprefix' or '-Pprefix' must be given, or
    this program does not do anything! You can use both methods,
    if you want to compare them.

 ++ 'Harmonize' might be a better name for what this program does,
    but calling it 3dBrainHarm would probably not be good marketing
    (except for Traumatic Brain Injury researchers?).

One possible application of this program is to correlate resting state
FMRI datasets between subjects, voxel-by-voxel, as is sometimes done
with naturalistic stimuli (e.g., movie viewing).

--------
OPTIONS:
--------
 -inset1 dataset1 = Reference dataset

 -inset2 dataset2 = Dataset to be matched to the reference dataset,
                    as much as possible.
                    ++ These 2 datasets must be on the same spatial grid,
                       and must have the same number of time points!
                    ++ There must be at least twice as many voxels being
                       processed as there are time points (see '-mask', below).
                    ++ These are both MANDATORY 'options'.
                    ++ As usual in AFNI, since the computations herein are
                       voxel-wise, it is possible to input plain text .1D
                       files as datasets. When doing so, remember that
                       a ROW in the .1D file is interpreted as a time series
                       (single voxel's data). If your .1D files are oriented
                       so that time runs in down the COLUMNS, you will have to
                       transpose the inputs, which can be done on the command
                       line with the \' operator, or externally using the
                       1dtranspose program.
                -->>++ These input datasets should be pre-processed first
                       to remove undesirable components (motions, baseline,
                       spikes, breathing, etc). Otherwise, you will be trying
                       to match artifacts between the datasets, which is not
                       likely to be interesting or useful. 3dTproject would be
                       one way to do this. Even better: afni_proc.py!
                    ++ In particular, the mean of each time series should have
                       been removed! Otherwise, the calculations are fairly
                       meaningless.

 -Qprefix qqq     = Specifies the output dataset to be used for
                    the orthogonal matrix transformation.
                    ++ This will be the -inset2 dataset transformed
                       to be as correlated as possible (in time)
                       with the -inset1 dataset, given the constraint
                       that the transformation applied to each time
                       series is an orthogonal matrix.

 -Pprefix ppp     = Specifies the output dataset to be used for
                    the permutation transformation.
                    ++ The output dataset is the -inset2 dataset
                       re-ordered in time, again to make the result
                       as correlated as possible with the -inset1
                       dataset.

 -normalize       = Normalize the output dataset(s) so that each
                    time series has sum-of-squares = 1.
                    ++ This option is not usually needed in AFNI
                       (e.g., 3dTcorrelate does not care).

 -mask mset       = Only operate on nonzero voxels in the mset dataset.
                    ++ Voxels outside the mask will not be used in computing
                       the transformation, but WILL be transformed for
                       your application and/or edification later.
                    ++ For FMRI purposes, a gray matter mask would make
                       sense here, or at least a brain mask.
                    ++ If no masking option is given, then all voxels
                       will be processed in computing the transformation.
                       This set will include all non-brain voxels (if any).
                    ++ Any voxel which is all constant in time
                       (in either input) will be removed from the mask.
                    ++ This mask dataset must be on the same spatial grid
                       as the other input datasets!

 -verb             = Print some progress reports and auxiliary information.
                     ++ Use this option twice to get LOTS of progress
                        reports; mostly useful for debugging.

------
NOTES:
------
* Is this program useful? Not even The Shadow knows!
  (But do NOT call it BS.)

* The output dataset is in floating point format.

* Although the goal of 3dBrainSync is to make the transformed
  -inset2 as correlated (voxel-by-voxel) as possible with -inset1,
  it does not actually compute that correlation dataset. You can do
  that computation with program 3dTcorrelate, as in
    3dTcorrelate -polort -1 -prefix AB.pcor.nii \
                 dataset1 transformed-dataset2

* Besides the transformed dataset(s), if the '-verb' option is used,
  some other (text formatted) files are written out:
   {Qprefix}.sval.1D = singular values from the BC' decomposition
   {Qprefix}.qmat.1D = Q matrix
   {Pprefix}.perm.1D = permutation indexes p(i)
  You probably do not have any use for these files; they are mostly
  present to diagnose any problems.

--------
METHODS:
--------
* Notation used in the explanations below:
    M = Number of time points
    N = Number of voxels > M (N = size of mask)
    B = MxN matrix of time series from -inset1
    C = MxN matrix of time series from -inset2
        Both matrices will have each column normalized to
        have sum-of-squares = 1 (L2 normalized) --
        the program does this operation internally; you do not have
        to ensure that the input datasets are so normalized)
    Q = Desired orthgonal MxM matrix to transform C such that B-QC
        is as small as possible (sum-of-squares = Frobenius norm)
        normF(A) = sum_{ij} A_{ij}^2 = trace(AA') = trace(A'A).
        NOTE: This norm is different from the matrix L2 norm.
        NOTE: A' denotes the transpose of A.

* The expansion below shows why the matrix BC' is crucial to the analysis:
    normF(B-QC) = trace( [B-QC][B'-C'Q'] )
                = trace(BB') + trace(QCC'Q') - trace(BC'Q') - trace(QCB')
                = trace(BB') + trace(C'C) - 2 trace(BC'Q')
  The second term collapses because trace(AA') = trace(A'A), so
  trace([QC][QC]') = trace([QC]'[QC]) = trace(C'Q'QC) = trace(C'C)
  because Q is orthogonal. So the first 2 terms in the expansion of
  normF(B-QC) do not depend on Q at all. Thus, to minimize normF(B-QC),
  we have to maximize trace(BC'Q') = trace([B][QC]') = trace([QC][B]').

  Since the columns of B and C are the (normalized) time series,
  each row represents the image at a particular time. So the (i,j)
  element of BC' is the (spatial) dot product of the i-th TR image from
  -inset1 with the j-th TR image from -inset2. Furthermore,
  trace(BC') = trace(C'B) = sum of dot products (correlations)
  of all time series. So maximizing trace(BC'Q') will maximize the
  summed correlations of B (time series from -inset1) and QC
  (transformed time series from -inset2).

  Note again that the sum of correlations (dot products) of all the time
  series is equal to the sum of dot products of all the spatial images.
  So the algorithm to find the transformation Q is to maximize the sum of
  dot products of spatial images from B with Q-transformed spatial images
  from C -- since there are fewer time points than voxels, this is more
  efficient and elegant than trying to maximize the sum over voxels of dot
  products of time series.

  If you use the '-verb' option, these summed correlations ('scores')
  are printed to stderr during the analysis.

* Joshi method [-Qprefix]:
    (a) compute MxM matrix B C'
    (b) compute SVD of B C' = U S V' (U, S, V are MxM matrices)
    (c) Q = U V'
        [note: if B=C, then U=V, so Q=I, as it should]
    (d) transform each time series from -inset2 using Q
  This matrix Q is the solution to the restricted least squares
  problem (i.e., restricted to have Q be an orthogonal matrix).
  NOTE: The sum of the singular values in S is equal to the sum
        of the time series dot products (correlations) in B and QC,
        when Q is calculated as above.

  A pre-print of this method is available as:
    AA Joshi, M Chong, RM Leahy.
    BrainSync: An Orthogonal Transformation for Synchronization of fMRI
    Data Across Subjects, Proc. MICCAI 2017
  https://www.dropbox.com/s/tu4kuqqlg6r02kt/brainsync_miccai2017.pdf
  https://www.google.com/search?q=joshi+brainsync
  http://neuroimage.usc.edu/neuro/Resources/BrainSync

* Permutation method [-Pprefix]:
    (a) Compute B C' (as above)
    (b) Find a permutation p(i) of the integers {0..M-1} such
        that sum_i { (BC')[i,p(i)] } is as large as possible
        (i.e., p() is used as a permutation of the COLUMNS of BC').
        This permutation is equivalent to post-multiplying BC'
        by an orthogonal matrix P representing the permutation;
        such a P is full of 0s except for a single 1 in each row
        and each column.
    (c) Permute the ROWS (time direction) of the time series matrix
        from -inset2 using p().
  Only an approximate (greedy) algorithm is used to find this
  permutation; that is, the best permutation is not guaranteed to be found
  (just a 'good' permutation -- it is the best thing I could code quickly :).

  Algorithm currently implemented (let D=BC' for notational simplicity):
    1) Find the largest element D(i,j) in the matrix.
       Then the permutation at row i is p(i)=j.
       Strike row i and column j out of the matrix D.
    2) Repeat, finding the largest element left, say at D(f,g).
       Then p(f) = g. Strike row f and column g from the matrix.
       Repeat until done.
  (Choosing the largest possible element at each step is what makes this
  method 'greedy'.) This permutation is not optimal but is pretty good,
  and another step is used to improve it:
    3) For all pairs (i,j), p(i) and p(j) are swapped and that permutation
       is tested to see if the trace gets bigger.
    4) This pair-wise swapping is repeated until it does not improve things
       any more (typically, it improves the trace about 1-2% -- not much).
  The purpose of the pair swapping is to deal with situations where D looks
  something like this: [  1 70 ]
                       [ 70 99 ]
  Step 1 would pick out 99, and Step 2 would pick out 1; that is,
  p(2)=2 and then p(1)=1, for a total trace/score of 100. But swapping
  1 and 2 would give a total trace/score of 140. In practice, extreme versions
  of this situation do not seem common with real FMRI data, probably because
  the subject's brain isn't actively conspiring against this algorithm :)

  [Something called the 'Hungarian algorithm' can solve for the optimal]
  [permutation exactly, but I've not had the inclination to program it.]

  This whole permutation optimization procedure is very fast: about 1 second.
  In the RS-FMRI data I've tried this on, the average time series correlation
  resulting from this optimization is 50-65% of that which comes from
  optimizing over ALL orthogonal matrices (Joshi method). If you use '-verb',
  the stderr output line that looks like this
   + corr scores: original=-722.5 Q matrix=22366.0 permutation=12918.7 57.8%
  shows trace(BC') before any transforms, with the Q matrix transform,
  and with the permutation transform. As explained above, trace(BC') is
  the summed correlations of the time series (since the columns of B and C
  are normalized prior to the optimizations); in this example, the ratio of
  the average time series correlation between the permutation method and the
  Joshi method is about 58% (in a gray matter mask with 72221 voxels).

* Results from the permutation method MUST be less correlated (on average)
  with -inset1 than the Joshi method's results: the permutation can be
  thought of as an orthogonal matrix containing only 1s and 0s, and the BEST
  possible orthogonal matrix, from Joshi's method, has more general entries.
  ++ However, the permutation method has an obvious interpretation
     (re-ordering time points), while the general method linearly combines
     different time points (perhaps far apart); the interpretation of this
     combination in terms of synchronizing brain activity is harder to intuit
     (at least for me).
  ++ Another feature of a permutation-only transformation is that it cannot
     change the sign of data, unlike a general orthgonal matrix; e.g.,
       [ 0 -1]
       [-1  0], which swaps 2 time points AND negates them, is a valid
     orthogonal matrix. For rs-FMRI datasets, this consideration might not
     be important, since correlations are generally positive, so don't often
     need sign-flipping to make them so.

* This program is NOT multi-threaded. Typically, I/O is a big part of
  the run time (at least, for the cases I've tested). The '-verb' option
  will give progress reports with elapsed-time stamps, making it easy to
  see which parts of the program take the most time.

* Author: RWCox, servant of the ChronoSynclastic Infundibulum - July 2017

* Thanks go to Anand Joshi for his clear exposition of BrainSync at OHBM 2017,
  and his encouragement about the development of this program.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dBrickStat
Usage: 3dBrickStat [options] dataset
Compute maximum and/or minimum voxel values of an input dataset

The output is a number to the console.  The input dataset
may use a sub-brick selection list, as in program 3dcalc.

Note that this program computes ONE number as the output; e.g.,
the mean over all voxels and time points.  If you want (say) the
mean over all voxels but for each time point individually, see
program 3dmaskave.

Note: If you don't specify one sub-brick, the parameter you get
----- back is computed from all the sub-bricks in dataset.
Options :
  -quick = get the information from the header only (default)
  -slow = read the whole dataset to find the min and max values
         all other options except min and max imply slow
  -min = print the minimum value in dataset
  -max = print the maximum value in dataset (default)
  -mean = print the mean value in dataset 
  -sum = print the sum of values in the dataset
  -var = print the variance in the dataset 
  -stdev = print the standard deviation in the dataset 
           -stdev and -var are mutually exclusive
  -count = print the number of voxels included
  -volume = print the volume of voxels included in microliters
  -positive = include only positive voxel values 
  -negative = include only negative voxel values 
  -zero = include only zero voxel values 
  -non-positive = include only voxel values 0 or negative 
  -non-negative = include only voxel values 0 or greater 
  -non-zero = include only voxel values not equal to 0 
  -absolute = use absolute value of voxel values for all calculations
              can be combined with restrictive non-positive, non-negative,
              etc. even if not practical. Ignored for percentile and
              median computations.
  -nan = include only voxel values that are finite numbers, 
         not NaN, or inf. -nan forces -slow mode.
  -nonan =exclude voxel values that are not numbers
  -mask dset = use dset as mask to include/exclude voxels
  -mrange MIN MAX = Only accept values between MIN and MAX (inclusive)
                    from the mask. Default it to accept all non-zero
                    voxels.
  -mvalue VAL = Only accept values equal to VAL from the mask.
  -automask = automatically compute mask for dataset
    Can not be combined with -mask
  -percentile p0 ps p1 write the percentile values starting
              at p0% and ending at p1% at a step of ps%
              Output is of the form p% value   p% value ...
              Percentile values are output first. 
              Only one sub-brick is accepted as input with this option.
              Write the author if you REALLY need this option
              to work with multiple sub-bricks.
  -median a shortcut for -percentile 50 1 50
  -ver = print author and version info
  -help = print this help screen

INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dCM
Usage: 3dCM [options] dset
Output = center of mass of dataset, to stdout.
    Note: by default, the output is (x,y,z) values in DICOM
          coordinates.  But as of Dec, 2016, there are now
          command line switches for other options (see -local*
          below).

  -mask mset   Means to use the dataset 'mset' as a mask:
                 Only voxels with nonzero values in 'mset'
                 will be averaged from 'dataset'.  Note
                 that the mask dataset and the input dataset
                 must have the same number of voxels.
  -automask    Generate the mask automatically.
  -set x y z   After computing the CM of the dataset, set the
                 origin fields in the header so that the CM
                 will be at (x,y,z) in DICOM coords.
  -local_ijk   Output values as (i,j,k) in local orienation.
  -roi_vals v0 v1 v2 ... : Compute center of mass for each blob
                           with voxel value of v0, v1, v2, etc.
                           This option is handy for getting ROI 
                           centers of mass.
  -all_rois     Don't bother listing the values of ROIs you want
                the program will find all of them and produce a 
                full list.
  NOTE: Masking options are ignored with -roi_vals and -all_rois

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dCRUISEtoAFNI

Usage: 3dCRUISEtoAFNI -input CRUISE_HEADER.dx
 Converts a CRUISE dataset defined by a heder in OpenDX format
 The conversion is based on sample data and information
 provided by Aaron Carass from JHU's IACL iacl.ece.jhu.edu
   [-novolreg]: Ignore any Rotate, Volreg, Tagalign, 
                or WarpDrive transformations present in 
                the Surface Volume.
   [-noxform]: Same as -novolreg
   [-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname
                to be ENVvalue. Quotes are necessary.
             Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'"
                See also options -update_env, -environment, etc
                in the output of 'suma -help'
  Common Debugging Options:
   [-trace]: Turns on In/Out debug and Memory tracing.
             For speeding up the tracing log, I recommend 
             you redirect stdout to a file when using this option.
             For example, if you were running suma you would use:
             suma -spec lh.spec -sv ... > TraceFile
             This option replaces the old -iodbg and -memdbg.
   [-TRACE]: Turns on extreme tracing.
   [-nomall]: Turn off memory tracing.
   [-yesmall]: Turn on memory tracing (default).
  NOTE: For programs that output results to stdout
    (that is to your shell/screen), the debugging info
    might get mixed up with your results.


Global Options (available to all AFNI/SUMA programs)
  -h: Mini help, at time, same as -help in many cases.
  -help: The entire help output
  -HELP: Extreme help, same as -help in majority of cases.
  -h_view: Open help in text editor. AFNI will try to find a GUI editor
  -hview : on your machine. You can control which it should use by
           setting environment variable AFNI_GUI_EDITOR.
  -h_web: Open help in web browser. AFNI will try to find a browser.
  -hweb : on your machine. You can control which it should use by
          setting environment variable AFNI_GUI_EDITOR. 
  -h_find WORD: Look for lines in this programs's -help output that match
                (approximately) WORD.
  -h_raw: Help string unedited
  -h_spx: Help string in sphinx loveliness, but do not try to autoformat
  -h_aspx: Help string in sphinx with autoformatting of options, etc.
  -all_opts: Try to identify all options for the program from the
             output of its -help option. Some options might be missed
             and others misidentified. Use this output for hints only.
  


Compile Date:
   Dec 11 2018

       Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov     



AFNI program: 3dClipLevel
Usage: 3dClipLevel [options] dataset
Estimates the value at which to clip the anatomical dataset so
  that background regions are set to zero.

The program's output is a single number sent to stdout.  This
  value can be 'captured' to a shell variable using the backward
  single quote operator; a trivial csh/tcsh example is

    set ccc = `3dClipLevel -mfrac 0.333 Elvis+orig`
    3dcalc -a Elvis+orig -expr "step(a-$ccc)" -prefix Presley

Algorithm:
  (a) Set some initial clip value using wizardry (AKA 'variance').
  (b) Find the median of all positive values >= clip value.
  (c) Set the clip value to 0.50 of this median.
  (d) Loop back to (b) until the clip value doesn't change.
This method was made up out of nothing, based on histogram gazing.

Options:
--------
  -mfrac ff = Use the number ff instead of 0.50 in the algorithm.
  -doall    = Apply the algorithm to each sub-brick separately.
              [Cannot be combined with '-grad'!]

  -grad ppp = In addition to using the 'one size fits all routine',
              also compute a 'gradual' clip level as a function
              of voxel position, and output that to a dataset with
              prefix 'ppp'.
             [This is the same 'gradual' clip level that is now the
              default in 3dAutomask - as of 24 Oct 2006.
              You can use this option to see how 3dAutomask clips
              the dataset as its first step.  The algorithm above is
              is used in each octant of the dataset, and then these
              8 values are interpolated to cover the whole volume.]
Notes:
------
* Use at your own risk!  You might want to use the AFNI Histogram
    plugin to see if the results are reasonable.  This program is
    likely to produce bad results on images gathered with local
    RF coils, or with pulse sequences with unusual contrasts.

* For brain images, most brain voxels seem to be in the range from
    the clip level (mfrac=0.5) to about 3-3.5 times the clip level.
    - In T1-weighted images, voxels above that level are usually
      blood vessels (e.g., inflow artifact brightens them).

* If the input dataset has more than 1 sub-brick, the data is
    analyzed on the median volume -- at each voxel, the median
    of all sub-bricks at that voxel is computed, and then this
    median volume is used in the histogram algorithm.

* If the input dataset is short- or byte-valued, the output will
    be an integer; otherwise, the output is a float value.

* Example -- Scaling a sequence of sub-bricks from a collection of
             anatomicals from different sites to have about the
             same numerical range (from 0 to 255):
       3dTcat -prefix input anat_*+tlrc.HEAD
       3dClipLevel -doall input+tlrc > clip.1D
       3dcalc -datum byte -nscale -a input+tlrc -b clip.1D \
              -expr '255*max(0,min(1,a/(3.2*b)))' -verb -prefix scaled
----------------------------------------------------------------------
* Author: Emperor Zhark -- Sadistic Galactic Domination since 1994!


++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dClustCount
Usage: 3dClustCount [options] dataset1 ... 

This program takes as input 1 or more datasets, thresholds them at various
levels, and counts up the number of clusters of various sizes.  It is
adapted from 3dClustSim, but only does the cluster counting functions --
where the datasets come from is the user's business.  It is intended for
use in a simulation script.

-------
OPTIONS
-------
 -prefix sss = Use string 'sss' as the prefix of the filename into which
               results will be summed.  The actual filename will be
               'sss.clustcount.niml'.  If this file already exists, then
               the results from the current run will be summed into the
               existing results, and the file then re-written.

 -final      = If this option is given, then the results will be output
               in a format like that used from 3dClustSim -- as 1D and
               NIML formatted files with probabilities of various
               cluster sizes.
               ++ You can use '-final' without any input datasets if
                  you want to create the final output files from the
                  saved '.clustcount.niml' output file from earlier runs.

 -quiet      = Don't print out the progress reports, etc.
               ++ Put this option first to quiet most informational messages.

--------
EXAMPLE:
-------
The steps here are
  (a) Create a set of 250 3dGroupInCorr results from a set of 190 subjects,
      using 250 randomly located seed locations.  Note the use of '-sendall'
      to get the individual subject results -- these are used in the next
      step, and are in sub-bricks 2..191 -- the collective 3dGroupInCorr
      results (in sub-bricks 0..1) are not actually used here.
  (b) For each of these 250 output datasets, create 80 random splittings
      into 2 groups of 95 subjects each, and carry out a 2-sample t-test
      between these groups.
      ++ Note the use of program 2perm to create the random splittings into
         files QQ_A and QQ_B, drawn from sub-bricks 2..191 of the ${fred}
         datasets.
      ++ Note the use of the '[1dcat filename]' construction to specify
         which sub-bricks of the ${fred} dataset are used for input to
         the '-setX' options of 3dttest++.
  (c) Count clusters from the '[1]' sub-brick of the 80 t-test outputs --
      the t-statistic sub-brick.
      ++  Note the use of a wildcard filename with a sub-brick selector:
          'QQ*.HEAD[1]' -- 3dClustCount will do the wildcard expansion
          internally, then add the sub-brick selector '[1]' to each expanded
          dataset filename.
  (d) Produce the final report files for empirical cluster-size thresholds
      for 3dGroupInCorr analyses -- rather than rely on 3dClustSim's assumption
      of Gaussian-shaped spatial correlation structure.
The syntax is C-shell (tcsh), naturally.

    \rm -f ABscat*
    3dGroupInCorr -setA A.errts.grpincorr.niml                 \
                  -setB B.errts.grpincorr.niml                  \
                  -labelA A -labelB B -seedrad 5 -nosix -sendall \
                  -batchRAND 250 ABscat
    foreach fred ( ABscat*.HEAD )
      foreach nnn ( `count -dig 2 0 79` )
        2perm -prefix QQ 2 191
        3dttest++ -setA ${fred}'[1dcat QQ_A]' \
                  -setB ${fred}'[1dcat QQ_B]' \
                  -no1sam -prefix QQ${nnn}
      end
      3dClustCount -prefix ABcount 'QQ*.HEAD[1]'
      \rm -f QQ*
    end
    3dClustCount -final -prefix ABcount
    \rm -f ABscat*

--------------------------------
---- RW Cox -- August 2012 -----
--------------------------------

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dClustSim
Usage: 3dClustSim [options]

Program to estimate the probability of false positive (noise-only) clusters.
An adaptation of Doug Ward's AlphaSim, streamlined for various purposes.

-----------------------------------------------------------------------------
This program has several different modes of operation, each one involving
simulating noise-only random volumes, thresholding and clustering them,
and counting statistics of how often data 'survives' these processes at
various threshold combinations (per-voxel and cluster-size).

OLDEST method = simulate noise volume assuming the spatial auto-correlation
                function (ACF) is given by a Gaussian-shaped function, where
                this shape is specified using the FWHM parameter. The FWHM
                parameter can be estimated by program 3dFWHMx.
          ** THIS METHOD IS NO LONGER RECOMMENDED **

NEWER method  = simulate noise volume assuming the ACF is given by a mixed-model
                of the form a*exp(-r*r/(2*b*b))+(1-a)*exp(-r/c), where a,b,c
                are 3 parameters giving the shape, and can also be estimated
                by program 3dFWHMx.
          ** THIS METHOD IS ACCEPTABLE **

NEWEST method = program 3dttest++ simulates the noise volumes by randomizing
                and permuting input datasets, and sending those volumes into
                3dClustSim directly. There is no built-in math model for the
                spatial ACF.
          ** THIS METHOD IS MOST ACCURATE AT CONTROLLING FALSE POSITIVE RATE **
          ** You invoke this method with the '-Clustsim' option in 3dttest++ **

3dClustSim computes a cluster-size threshold for a given voxel-wise p-value
threshold, such that the probability of anything surviving the dual thresholds
is at some given level (specified by the '-athr' option).

Note that this cluster-size threshold is the same for all brain regions.
There is an implicit assumption that the noise spatial statistics are
the same everywhere.

Program 3dXClustSim introduces the idea of spatially variable cluster-size
thresholds, which may be more useful in some cases. 3dXClustSim's method is
invoked by using the '-ETAC' option in 3dttest++.
-----------------------------------------------------------------------------

**** NOTICE ****
You should use the -acf method, NOT the -fwhm method, when determining
cluster-size thresholds for FMRI data. The -acf method will give more
accurate false positive rate (FPR) control.
****************

In particular, this program lets you run with multiple p-value thresholds
(the '-pthr' option) and only outputs the cluster size threshold at chosen
values of the alpha significance level (the '-athr' option).

In addition, the program allows the output to be formatted for inclusion
into an AFNI dataset's header, whence it can be used in the AFNI Clusterize
interface to show approximate alpha values for the displayed clusters, where
the per-voxel p-value is taken from the interactive threshold slider in the
AFNI 'Define Overlay' control panel, and then the per-cluster alpha value
is interpolated in this table from 3dClustSim.  As you change the threshold
slider, the per-voxel p-value (shown below the slider) changes, and then
the interpolated alpha values are updated.

************* IMPORTANT NOTE [Dec 2015] ***************************************
A completely new method for estimating and using noise smoothness values is
now available in 3dFWHMx and 3dClustSim. This method is implemented in the
'-acf' options to both programs.  'ACF' stands for (spatial) AutoCorrelation
Function, and it is estimated by calculating moments of differences out to
a larger radius than before.

Notably, real FMRI data does not actually have a Gaussian-shaped ACF, so the
estimated ACF is then fit (in 3dFWHMx) to a mixed model (Gaussian plus
mono-exponential) of the form
  ACF(r) = a * exp(-r*r/(2*b*b)) + (1-a)*exp(-r/c)
where 'r' is the radius, and 'a', 'b', 'c' are the fitted parameters.
The apparent FWHM from this model is usually somewhat larger in real data
than the FWHM estimated from just the nearest-neighbor differences used
in the 'classic' analysis.

The longer tails provided by the mono-exponential are also significant.
3dClustSim has also been modified to use the ACF model given above to generate
noise random fields.

**----------------------------------------------------------------------------**
** The take-away (TL;DR or summary) message is that the 'classic' 3dFWHMx and **
** 3dClustSim analysis, using a pure Gaussian ACF, is not very correct for    **
** FMRI data -- I cannot speak for PET or MEG data.                           **
**----------------------------------------------------------------------------**

** ---------------------------------------------------------------------------**
** IMPORTANT CHANGES -- February 2015 ******************************************
** ---------------------------------------------------------------------------**
** In the past, 3dClustSim did '1-sided' testing; that is, the random dataset
** of Gaussian noise-only values is generated, and then it is thresholded on
** the positive side so that the N(0,1) upper tail probability is pthr.
**
** NOW, 3dClustSim does 3 different types of thresholding:
**   1-sided: as above
**   2-sided: where positive and negative values above the threshold
**            are included, and then clustered together
**            (in this case, the threshold on the Gaussian values is)
**            (fixed so that the 1-sided tail probability is pthr/2.)
**  bi-sided: where positive values and negative values above the
**            threshold are clustered SEPARATELY (with the 2-sided threshold)
** For high levels of smoothness, the results from bi-sided and 2-sided are
** very similar -- since for smooth data, it is unlikely that large clusters of
** positive and negative values will be next to each other. With high smoothness,
** it is also true that the 2-sided results for 2*pthr will be similar to the
** 1-sided results for pthr, for the same reason. Since 3dClustSim is meant to be
** useful when the noise is NOT very smooth, we provide tables for all 3 cases.
**
** In particular, note that when the AFNI GUI threshold is set to a t-statistic,
** 2-sided testing is what is usually appropriate -- in that case, the cluster
** size thresholds tend to be smaller than the 1-sided case, which means that
** more clusters tend to be significant than in the past.
**
** In addition, the 3 different NN approaches (NN=1, NN=2, NN=3) are ALL
** always computed now.  That is, 9 different tables are produced, each
** of which has its proper place when combined with the AFNI Clusterize GUI.
** The 3 different NN methods are:
**  1 = Use first-nearest neighbor clustering
**      * above threshold voxels cluster together if faces touch
**  2 = Use second-nearest neighbor clustering
**      * voxels cluster together if faces OR edges touch
**  3 = Use third-nearest neighbor clustering
**      * voxels cluster together if faces OR edges OR corners touch
** The clustering method only makes a difference at higher (less significant)
** values of pthr.   At small values of pthr (more significant),  all three
** clustering methods will give very similar results.
**
**** PLEASE NOTE that the NIML outputs from this new version are not named the
**** same as those from the older version. Thus, any script that takes the NIML
**** format tables and inserts them into an AFNI dataset header must be modified
**** to match the new names. The 3drefit command fragment output at the end of
**** this program (and echoed into file '3dClustSim.cmd') shows the new form
**** of the names involved.
**** -------------------------------------------------------------------------**
**** SMOOTHING CHANGE -- May 2015 **********************************************
** ---------------------------------------------------------------------------**
** It was pointed out to me (by Anders Eklund and Tom Nichols) that smoothing
** the simulated data over a finite volume introduces 2 artifacts, which might
** be called 'edge effects'.  To minimize these problems, this program now makes
** extra-large (padded) simulated volumes before blurring, and then trims those
** back down to the desired size, before continuing with the thresholding and
** cluster-counting steps.  To run 3dClustSim without this padding added, use
** the new '-nopad' option.
**** -------------------------------------------------------------------------**

-------
OPTIONS  [at least 1 option is required, or you'll get this help message!]
-------
 ******* Specify the volume over which the simulation will occur *******

  -----** (a) Directly give the spatial domain that will be used **-----

-nxyz n1 n2 n3 = Size of 3D grid to use for simulation
                  [default values = 64 64 32]
-dxyz d1 d2 d3 = give all 3 voxel sizes at once
                  [default values = 3.5 3.5 3.5]
-BALL          = inside the 3D grid, mask off points outside a ball
                  at the center of the grid and touching the edges;
                  this will keep about 1/2 the points in the 3D grid.
                  [default = use all voxels in the 3D grid]

  -----** OR: (b) Specify the spatial domain using a dataset mask **-----

-mask mset     = Use the 0 sub-brick of dataset 'mset' as a mask
                  to indicate which voxels to analyze (a sub-brick
                  selector '[]' is allowed) 

-OKsmallmask   = Allow small masks. Normally, a mask volume must have
                  128 or more nonzero voxels.  However, IF you know what
                  you are doing, and IF you are willing to live life on
                  the edge of statistical catastrophe, then you can use
                  this option to allow smaller masks -- in a sense, this
                  is the 'consent form' for such strange shenanigans.
                 * If you use this option, it must come BEFORE '-mask'.
                 * Also read the 'CAUTION and CAVEAT' section, far below.
            -->>** This option is really only recommended for users who
                   understand what they are doing. Misuse of this option
                   could easily be construed as 'p-hacking'; for example,
                   finding results, but your favorite cluster is too small
                   to survive thresholding, so you post-hoc put a small mask
                   down in that region. DON'T DO THIS!

    ** '-mask' means that '-nxyz' & '-dxyz' & '-BALL' will be ignored. **

  -----** OR: (c) Specify the spatial domain by directly giving simulated volumes **-----

-inset iset [iset ...] = Read the 'iset' dataset(s) and use THESE volumes
                          as the simulations to threshold and clusterize,
 [Feb 2016]               rather than create the simulations internally.
                         * For example, these datasets could come from
                           3dttest++ -toz -randomsign 1000 -setA ...
                         * This can be combined with '-mask'.
                         * Using '-inset' means that '-fwhm', '-acf', '-nopad',
                           '-niter', and '-ssave' are ignored as meaningless.

  ---** the remaining options control how the simulation is done **---

-fwhm s         = Gaussian filter width (all 3 dimensions) in mm (non-negative)
                   [default = 0.0 = no smoothing]
                  * If you wish to set different smoothing amounts for each
                    axis, you can instead use option
                      -fwhmxyz sx sy sz
                    to specify the three values separately.
       **** This option is no longer recommended, since FMRI data    ****
       **** does not have a Gaussian-shaped spatial autocorrelation. ****
       **** Consider using '-acf' or '3dttest++ -Clustsim' instead.  ****

-acf a b c      = Alternative to Gaussian filtering: use the spherical
                  autocorrelation function parameters output by 3dFWHMx
                  to do non-Gaussian (long-tailed) filtering.
                  * Using '-acf' will make '-fwhm' pointless!
                  * The 'a' parameter must be between 0 and 1.
                  * The 'b' and 'c' parameters (scale radii) must be positive.
                  * The spatial autocorrelation function is given by
                      ACF(r) = a * exp(-r*r/(2*b*b)) + (1-a)*exp(-r/c)
  >>---------->>*** Combined with 3dFWHMx, the '-acf' method is now a
                    recommended way to generate clustering statistics in AFNI!
                *** Alternative methods we also recommend:
                    3dttest++ with the -Clustsim and/or -ETAC options.

-nopad          = The program now [12 May 2015] adds 'padding' slices along
                   each face to allow for edge effects of the smoothing process.
                   If you want to turn this feature off, use the '-nopad' option.
                  * For example, if you want to compare the 'old' (un-padded)
                    results with the 'new' (padded) results.
                  * '-nopad' has no effect when '-acf' is used, since that option
                    automatically pads the volume when creating it (via FFTs) and
                    then truncates it back to the desired size for clustering.

-pthr p1 .. pn = list of uncorrected (per voxel) p-values at which to
                  threshold the simulated images prior to clustering.
                  [default = 0.05 0.02 0.01 0.005 0.002 0.001 0.0005 0.0002 0.0001]

-athr a1 .. an = list of corrected (whole volume) alpha-values at which
                  the simulation will print out the cluster size
                  thresholds.  For each 'p' and 'a', the smallest cluster
                  size C(p,a) for which the probability of the 'p'-thresholded
                  image having a noise-only cluster of size C is less than 'a'
                  is the output (cf. the sample output, below)
                  [default = 0.10 0.05 0.02 0.01]

         ** It is possible to use only ONE value in each of '-pthr' and     **
         ** '-athr', and then you will get exactly one line of output       **
         ** for each sided-ness and NN case. For example:                   **
         **   -pthr 0.001 -athr 0.05                                        **

         ** Both lists '-pthr' and '-athr' (of values between 0 and 0.2)    **
         ** should be given in DESCENDING order.  They will be sorted to be **
         ** that way in any case, and such is how the output will be given. **

         ** The list of values following '-pthr' or '-athr' can be replaced **
         ** with the single word 'LOTS', which will tell the program to use **
         ** a longer list of values for these probabilities [try it & see!] **
         ** (i.e., '-pthr LOTS' and/or '-athr LOTS' are legal options)      **

-LOTS          = the same as using '-pthr LOTS -athr LOTS'
-MEGA          = adds even MORE values to the '-pthr' and '-athr' grids.

-iter n        = number of Monte Carlo simulations [default = 10000]

-nodec         = normally, the program prints the cluster size threshold to
                  1 decimal place (e.g., 27.2).  Of course, clusters only come
                  with an integer number of voxels -- this fractional value
                  is interpolated to give the desired alpha level.  If you
                  want no decimal places (so that 27.2 becomes 28), use '-nodec'.

-seed S        = random number seed [default seed = 123456789]
                  * if seed=0, then program will quasi-randomize it

-niml          = Output the table in an XML/NIML format, rather than a .1D format.
                  * This option is for use with other software programs;
                    see the NOTES section below for details.
                  * '-niml' also implicitly means '-LOTS'.

-both          = Output the table in XML/NIML format AND in .1D format.
                  * You probably want to use '-prefix' with this option!
                    Otherwise, everything is mixed together on stdout.
                  * '-both' implies 'niml' which implies '-LOTS'.
                    So '-pthr' (if desired) should follow '-both'/'-niml'

-prefix ppp    = Write output for NN method #k to file 'ppp.NNk_Xsided.1D',
                  for k=1, 2, 3, and for X=1sided, 2sided, bisided.
                  * If '-prefix is not used, all results go to standard output.
                    You will probably find this confusing.
                  * If '-niml' is used, the filename is 'ppp.NNk_Xsided.niml'.
                    To be clear, the 9 files that will be named
                      ppp.NN1_1sided.niml ppp.NN1_2sided.niml ppp.NN1_bisided.niml
                      ppp.NN2_1sided.niml ppp.NN2_2sided.niml ppp.NN2_bisided.niml
                      ppp.NN3_1sided.niml ppp.NN3_2sided.niml ppp.NN3_bisided.niml
                  * If '-niml' AND '-mask' are both used, then a compressed ASCII
                    encoding of the mask volume is stored into file 'ppp.mask'.
                    This string can be stored into a dataset header as an attribute
                    with name AFNI_CLUSTSIM_MASK, and will be used in the AFNI
                    Clusterize GUI, if present, to mask out above-threshold voxels
                    before the clusterizing is done (which is how the mask is used
                    here in 3dClustSim).
                  * If the ASCII mask string is NOT stored into the statistics dataset
                    header, then the Clusterize GUI will try to find the original
                    mask dataset and use that instead.  If that fails, then masking
                    won't be done in the Clusterize process.

 -cmd ccc      = Write command for putting results into a file's header to a file
                 named 'ccc' instead of '3dClustSim.cmd'.  This option is mostly
                 to help with scripting, as in
                   3dClustSim -cmd XXX.cmd -prefix XXX.nii ...
                   `cat XXX.cmd` XXX.nii

 -quiet        = Don't print out the progress reports, etc.
                 * Put this option first to silence most informational messages.

 -ssave:TYPE ssprefix = Save the un-thresholded generated random volumes into
                        datasets ('-iter' of them). Here, 'TYPE' is one of these:
                          * blurred == save the blurred 3D volume before masking
                          * masked  == save the blurred volume after masking
                        The output datasets will actually get prefixes generated
                        with the string 'ssprefix' being appended by a 6 digit
                        integer (the iteration index), starting at 000000.
                        (You can use SOMETHING.nii as a prefix; it will work OK.)
                        N.B.: This option will slow the program down a lot,
                              and was intended to help just one specific user.

------
NOTES:
------
* This program is like running AlphaSim once for each '-pthr' value and then
  extracting the relevant information from its 'Alpha' output column.
 ++ One reason for 3dClustSim to be used in place of AlphaSim is that it will
    be much faster than running AlphaSim multiple times.
 ++ Another reason is that the resulting table can be stored in an AFNI
    dataset's header, and used in the AFNI Clusterize GUI to see estimated
    cluster significance (alpha) levels.

* To be clear, the C(p,alpha) thresholds that are calculated are for
  alpha = probability of a noise-only smooth random field, after masking
  and then thresholding at the given per-voxel p value, producing a cluster
  of voxels at least this big.
 ++ So if your cluster is larger than the C(p,0.01) threshold in size (say),
    then it is very unlikely that noise BY ITSELF produced this result.
 ++ This statement does not mean that ALL the voxels in the cluster are
    'truly' active -- it means that at least SOME of them are (very probably)
    active.  The statement of low probability (0.01 in this example) of a
    false positive result applies to the cluster as a whole, not to each
    voxel within the cluster.

* To add the cluster simulation C(p,alpha) table to the header of an AFNI
  dataset, something like the following can be done [tcsh syntax]:
     set fx = ( `3dFWHMx -detrend time_series_dataset+orig` )
     3dClustSim -mask mask+orig -acf $fx[5] $fx[6] $fx[7] -niml -prefix CStemp
     3drefit -atrstring AFNI_CLUSTSIM_NN1_1sided file:CStemp.NN1_1sided.niml \
             -atrstring AFNI_CLUSTSIM_MASK file:CStemp.mask    \
             statistics_dataset+orig
     rm -f CStemp.*
  AFNI's Clusterize GUI makes use of these attributes, if stored in a
  statistics dataset (e.g., something from 3dDeconvolve3dREMLfit, etc.).

   ** Nota Bene: afni_proc.py will automatically run 3dClustSim,  and **
  *** put the results  into the statistical results  dataset for you. ***
 **** Another reason to use afni_proc.py for single-subject analyses! ****

* 3dClustSim will print (to stderr) a 3drefit command fragment, similar
  to the one above, that you can use to add cluster tables to any
  relevant statistical datasets you have lolling about.

* The C(p,alpha) table will be used in Clusterize to provide the cluster
  level alpha value when the AFNI GUI is set so that the Overlay threshold
  sub-brick is a statistical parameter (e.g., a t- or F-statistic), from which
  a per-voxel p-value can be calculated, so that Clusterize can interpolate
  in the C(p,alpha) table.
 ++ To be clear, the per-voxel p-value is taken from the AFNI GUI threshold
    slider (the p-value is shown beneath the slider), and then the C(p,alpha)
    table is inverse-interpolated to find the per-cluster alpha value for
    each different cluster size.
 ++ As you move the AFNI threshold slider, the per-voxel (uncorrected for
    multiple comparisons) p-value changes, the cluster sizes change (as fewer
    or more voxels are included), and so the reported per-cluster alpha
    values change for both reasons -- different p and different cluster size.
 ++ The alpha values reported are 'per-cluster', and are not themselves
    corrected for multiple comparisons ACROSS clusters.  These alpha values
    are corrected for multiple comparisons WITHIN a cluster.

* AFNI will use the NN1, NN2, NN3 tables as needed in its Clusterize
  interface if they are all stored in the statistics dataset header,
  depending on the NN level chosen in the Clusterize controller.

* The blur estimates (provided to 3dClustSim via -acf) comes from using
  program 3dFWHMx.

-------------------
CAUTION and CAVEAT: [January 2011]
-------------------
* If you use a small ROI mask and also have a large blur, then it might happen
  that it is impossible to find a cluster size threshold C that works for a
  given (p,alpha) combination.

* Generally speaking, C(p,alpha) gets smaller as p gets smaller and C(p,alpha)
  gets smaller as alpha gets larger.  As a result, in a small mask with small p
  and large alpha, C(p,alpha) might shrink below 1.  But clusters of size C
  less than 1 don't make any sense!

* For example, suppose that for p=0.0005 that only 6% of the simulations
  have ANY above-threshold voxels inside the ROI mask.  In that case,
  C(p=0.0005,alpha=0.06) = 1.  There is no smaller value of C where 10%
  of the simulations have a cluster of size C or larger.  Thus, it is
  impossible to find the cluster size threshold for the combination of
  p=0.0005 and alpha=0.10 in this case.

* 3dClustSim will report a cluster size threshold of C=1 for such cases.
  It will also print (to stderr) a warning message for all the (p,alpha)
  combinations that had this problem.

-----------------------------
---- RW Cox -- July 2010 ----

-------------
SAMPLE OUTPUT from the command '3dClustSim -fwhm 7' [only the NN=1 1-sided results]
-------------
# 3dClustSim -fwhm 7
# 1-sided thresholding
# Grid: 64x64x32 3.50x3.50x3.50 mm^3 (131072 voxels)
#
# CLUSTER SIZE THRESHOLD(pthr,alpha) in Voxels
# -NN 1  | alpha = Prob(Cluster >= given size)
#  pthr  |  0.100  0.050  0.020  0.010
# ------ | ------ ------ ------ ------
 0.050000   162.5  182.2  207.8  225.7
 0.020000    64.3   71.0   80.5   88.5
 0.010000    40.3   44.7   50.7   55.1
 0.005000    28.0   31.2   34.9   38.1
 0.002000    19.0   21.2   24.2   26.1
 0.001000    14.6   16.3   18.9   20.5
 0.000500    11.5   13.0   15.1   16.7
 0.000200     8.7   10.0   11.6   12.8
 0.000100     7.1    8.3    9.7   10.9

e.g., for this sample volume, if the per-voxel p-value threshold is set
at 0.005, then to keep the probability of getting a single noise-only
cluster at 0.05 or less, the cluster size threshold should be 32 voxels
(the next integer above 31.2).

If you ran the same simulation with the '-nodec' option, then the last
line above would be
 0.000100       8      9     10     11
If you set the per voxel p-value to 0.0001 (1e-4), and want the chance
of a noise-only false-positive cluster to be 5% or less, then the cluster
size threshold would be 9 -- that is, you would keep all NN clusters with
9 or more voxels.

The header lines start with the '#' (commenting) character so that the result
is a correctly formatted AFNI .1D file -- it can be used in 1dplot, etc.

 =========================================================================
* This binary version of 3dClustSim is compiled using OpenMP, a semi-
   automatic parallelizer software toolkit, which splits the work across
   multiple CPUs/cores on the same shared memory computer.
* OpenMP is NOT like MPI -- it does not work with CPUs connected only
   by a network (e.g., OpenMP doesn't work with 'cluster' setups).
* For implementation and compilation details, please see
   https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html
* The number of CPU threads used will default to the maximum number on
   your system. You can control this value by setting environment variable
   OMP_NUM_THREADS to some smaller value (including 1).
* Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of
   using all CPUs available.
   ++ However, on some systems, it seems to be necessary to set variable
      OMP_NUM_THREADS explicitly, or you only get one CPU.
   ++ On other systems with many CPUS, you probably want to limit the CPU
      count, since using more than (say) 16 threads is probably useless.
* You must set OMP_NUM_THREADS in the shell BEFORE running the program,
   since OpenMP queries this variable BEFORE the program actually starts.
   ++ You can't usefully set this variable in your ~/.afnirc file or on the
      command line with the '-D' option.
* How many threads are useful? That varies with the program, and how well
   it was coded. You'll have to experiment on your own systems!
* The number of CPUs on this particular computer system is ...... 2.
* The maximum number of CPUs that will be used is now set to .... 2.
 =========================================================================

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dClusterize
 PURPOSE ~1~
 
 This program is for performing clusterizing: one can perform voxelwise
 thresholding on a dataset (such as a statistic), and then make a map
 of remaining clusters of voxels larger than a certain volume.  The
 main output of this program is a single volume dataset showing a map
 of the cluster ROIs.
 
 This program is specifically meant to reproduce behavior of the muuuch
 older 3dclust, but this new program:
   + uses simpler syntax (hopefully);
   + includes additional clustering behavior such as the '-bisided ...'
     variety (essentially, two-sided testing where all voxels in a
     given cluster come from either the left- or right- tail, but not
     mixed);
   + a mask (such as the whole brain) can be entered in;
   + voxelwise thresholds can be input as statistic values or p-values.
 
 This program was also written to have simpler/more direct syntax of
 usage than 3dclust.  Some minor options have been carried over for
 similar behavior, but many of the major option names have been
 altered.  Please read the helps for those below carefully.
 
 This program was cobbled together by PA Taylor (NIMH, NIH), but it
 predominantly uses code written by many legends: RW Cox, BD Ward, MS
 Beauchamp, ZS Saad, and more.
 
 
 USAGE ~1~
 
   Input: ~2~
 
     + A dataset of one or more bricks
     + Specify an index of the volume to threshold
     + Declare a voxelwise threshold, and optionally a cluster-volume
       threshold
     + Optionally specify the index an additional 'data' brick
     + Optionally specify a mask
 
   Output: ~2~
 
     + A report about the clusters (center of mass, extent, volume,
       etc.) that can be dumped into a text file.

     + Optional: A dataset volume containing a map of cluster ROIs 
       (sorted by size) after thresholding (and clusterizing, if
       specified).
       That is, a data set where the voxels in the largest cluster all
       have a value 1, those in the next largest are all 2, etc.
     + Optional: a cluster-masked version of an input data set. That is,
       the values of a selected data set (e.g., effect estimate) that fall
       within a cluster are output unchanged, and those outside a cluster
       are zeroed.
     + Optional: a mask.
 
   Explanation of 3dClusterize text report: ~2~
 
     Nvoxel       : Number of voxels in the cluster
 
     CM RL        : Center of mass (CM) for the cluster in the Right-Left
                    direction (i.e., the coordinates for the CM)
 
     CM AP        : Center of mass for the cluster in the
                    Anterior-Posterior direction
 
     CM IS        : Center of mass for the cluster in the
                    Inferior-Superior direction
 
     minRL, maxRL : Bounding box for the cluster, min and max
                    coordinates in the Right-Left direction
 
     minAP, maxAP : Min and max coordinates in the Anterior-Posterior
                    direction of the volume cluster
 
     minIS, maxIS : Min and max coordinates in the Inferior-Superior
                    direction of the volume cluster
 
     Mean         : Mean value for the volume cluster
 
     SEM          : Standard Error of the Mean for the volume cluster
 
     Max Int      : Maximum Intensity value for the volume cluster
 
     MI RL        : Coordinate of the Maximum Intensity value in the
                    Right-Left direction of the volume cluster
 
     MI AP        : Coordinate of the Maximum Intensity value in the
                    Anterior-Posterior direction of the volume cluster
 
     MI IS        : Coordinate of the Maximum Intensity value in the
                    Inferior-Superior direction of the volume cluster
 
     * CM values use the absolute value of the voxel values as weights.
 
     * The program does not work on complex- or rgb-valued datasets!
 
     * SEM values are not realistic for interpolated data sets!  A
       ROUGH correction is to multiply the SEM of the interpolated data
       set by the square root of the number of interpolated voxels per
       original voxel.
 
     * Some summary or 'global' values are placed at the bottoms of
       report columns, by default.  These include the 'global' volume,
       CM of the combined cluster ROIs, and the mean+SEM of that
       Pangaea.
 
 
 COMMAND OPTIONS ~1~
 
 -inset  III    :Load in a dataset III of one or more bricks for
                 thresholding and clusterizing; one can choose to use
                 either just a single sub-brick within it for all
                 operations (e.g., a 'statistics' brick), or to specify
                 an additional sub-brick within it for the actual
                 clusterizing+reporting (after the mask from the
                 thresholding dataset has been applied to it).
 
 -mask MMM      :Load in a dataset MMM to use as a mask, within which
                 to look for clusters.
 
 -mask_from_hdr :If 3dClustSim put an internal attribute into the
                 input dataset that describes a mask, 3dClusterize will
                 use this mask to eliminate voxels before clustering,
                 if you give this option (this is how the AFNI
                 Clusterize GUI works by default).  If there is no
                 internal mask in the dataset header, then this
                 doesn't do anything.
 
 -out_mask OM   :specify that you wanted the utilized mask dumped out
                 as a single volume dataset OM.  This is probably only
                 really useful if you are using '-mask_from_hdr'.  If
                 not mask option is specified, there will be no output.
 
 -ithr   j      :(required) Uses sub-brick [j] as the threshold source;
                 'j' can be either an integer *or* a brick_label string.
 
 -idat   k      :Uses sub-brick [k] as the data source (optional);
                 'k' can be either an integer *or* a brick_label string.
                 If this option is used, thresholding is still done by
                 the 'threshold' dataset, but that threshold map is
                 applied to this 'data' set, which is in turn used for
                 clusterizing and the 'data' set values are used to
                 make the report.  If a 'data' dataset is NOT input
                 with '-idat ..', then thresholding, clustering and
                 reporting are all done using the 'threshold' dataset.
 
 -1sided SSS TT :Perform one-sided testing. Two arguments are required:
                   SSS -> either 'RIGHT_TAIL' (or 'RIGHT') or 'LEFT_TAIL'
                          (or 'LEFT') to specify which side of the 
                          distribution to test.
                   TT  -> the threshold value itself.
                 See 'NOTES' below to use a p-value as threshold.
 
 -2sided  LL RR :Perform two-sided testing. Two arguments are required:
                   LL  -> the upper bound of the left tail.
                   RR  -> lower bound of the right tail.
                 *NOTE* that in this case, potentially a cluster could
                 be made of both left- and right-tail survivors (e.g.,
                 both positive and negative values). For this reason,
                 probably '-bisided ...' is a preferable choice.
                 See 'NOTES' below to use a p-value as threshold.
 
 -bisided LL RR :Same as '-2sided ...', except that the tails are tested
                 independently, so a cluster cannot be made of both.
                 See 'NOTES' below to use a p-value as threshold.
 
 -within_range AA BB
                :Perform a kind of clustering where a different kind of
                 thresholding is first performed, compared to the above
                 cases;  here, one keeps values within the range [AA, BB],
                 INSTEAD of keeping values on the tails. Is this useful?
                 Who knows, but it exists.
                 See 'NOTES' below to use a p-value as threshold.
 
 -NN {1|2|3}    :Necessary option to specify how many neighbors a voxel
                 has; one MUST put one of 1, 2 or 3 after it:
                   1 -> 6 facewise neighbors
                   2 -> 18 face+edgewise neighbors
                   3 -> 26 face+edge+cornerwise neighbors
                 If using 3dClustSim (or any other method), make sure
                 that this NN value matches what was used there. (In
                 many AFNI programs, NN=1 is a default choice, but BE
                 SURE YOURSELF!)
 
 -clust_nvox M  :specify the minimum cluster size in terms of number
                 of voxels M (such as output by 3dClustSim).
 
 -clust_vol   V :specify the minimum cluster size in terms of volume V,
                 in microliters (requires knowing the voxel
                 size). Probably '-clust_nvox ...' is more useful.
 
 -pref_map PPP  :The prefix/filename of the output map of cluster ROIs.
                 The 'map' shows each cluster as a set of voxels with the
                 same integer.  The clusters are ordered by size, so the
                 largest cluster is made up of 1s, the next largest of 2s,
                 etc.
                 (def:  no map of clusters output).
 
 -pref_dat DDD  :Including this option instructs the program to output
                 a cluster-masked version of the 'data' volume
                 specified by the '-idat ..' index.  That is, only data
                 values within the cluster ROIs are included in the
                 output volume.  Requires specifying '-idat ..'.
                 (def:  no cluster-masked dataset output).
 
 -1Dformat      :Write output in 1D format (now default). You can
                 redirect the output to a .1D file and use the file
                 as input to whereami for obtaining Atlas-based
                 information on cluster locations.
                 See whereami -help for more info.
 
 -no_1Dformat   :Do not write output in 1D format.
 
 -summarize     :Write out only the total nonzero voxel count and
                 volume for each dataset
 
 -nosum         :Suppress printout of the totals
 
 -quiet         :Suppress all non-essential output
 
 -outvol_if_no_clust: flag to still output an (empty) vol if no 
                 clusters are found.  Even in this case, no report is
                 is produced if no clusters are found.  This option is
                 likely used for some scripting scenarios; also, the
                 user would still need to specify '-pref_* ...' options
                 as above in order to output any volumes with this opt.
                 (def: no volumes output if no clusters found).

 -orient OOO    :change the coordinate output order to 'OOO' (def:
                 is DICOM, RAI); alternatively, one could set the
                 environment variable AFNI_ORIENT (see the file
                 README.environment).
 
 -noabs         :Use the signed voxel intensities (not the absolute
                 value) for calculation of the mean and Standard
                 Error of the Mean (SEM)
 
 -binary        :This turns the output map of cluster ROIs into a binary
                 (0 or 1) mask, rather than a cluster-index mask.
                 If no clusters are found, the mask is not written!
                 (def: each cluster has separate values)
 
 
 NOTES ~1~
 
   Saving the text report ~2~
 
     To save the text file report, use the redirect '>' after the
     3dClusterize command and dump the text into a separate file of
     your own naming.
 
   Using p-values as thresholds ~2~
 
     By default, numbers entered as voxelwise thresholds are assumed to
     be appropriate statistic values that you have calculated for your
     desired significance (e.g., using p2dsetstat).  HOWEVER, if you
     just want to enter p-values and have the program do the conversion
     work for you, then do as follows: prepend 'p=' to your threshold
     number.
 
     - For one-sided tests, the *_TAIL specification is still used, so
       in either case the p-value just represents the area in the
       statistical distribution's tail (i.e., you don't have to worry
       about doing '1-p').  Examples:
         -1sided RIGHT_TAIL p=0.005
         -1sided LEFT_TAIL  p=0.001
 
     - For the two-sided/bi-sided tests, the a single p-value is
       entered to represent the total area under both tails in the
       statistical distribution, which are assumed to be symmetric.
       Examples:
         -bisided p=0.001
         -2sided  p=0.005
 
       If you want asymmetric tails, you will have to enter both
       threshold values as statistic values (NB: you could use
       p2dsetstat to convert each desired p-value to a statistic, and
       then put in those stat values to this program).
 
     You will probably NEED to have negative signs for the cases of
     '-1sided LEFT_TAIL ..', and for the first entries of '-bisided ..'
     or '-2sided ..'.
 
     You cannot mix p-values and statistic values (for two-sided
     things, enter either the single p-value or both stats).
 
   Performing appropriate testing ~2~
 
     Don't use a pair of one-sided tests when you *should* be using a
     two-sided test!
 
 
 EXAMPLES ~1~
 
   1. Take an output of FMRI testing (e.g., from afni_proc.py), whose
   [1] brick contains the effect estimate from a statistical model and
   whose [2] brick contains the associated statistic; use the results
   of 3dClustSim run with NN=1 (here, a cluster threshold volume of 157
   voxels) and perform one-sided testing with a threshold at an
   appropriate value (here, 3.313).
 
     3dClusterize                  \
        -inset stats.FT+tlrc.      \
        -ithr 2                    \
        -idat 1                    \
        -mask mask_group+tlrc.     \
        -NN 1                      \
        -1sided RIGHT_TAIL 3.313   \
        -clust_nvox 157            \
        -pref_map ClusterMap
 
   2. The same as Ex. 1, but using bisided testing (two sided testing
   where the results of each tail can't be joined into the same
   cluster). Note, the tail thresholds do NOT have to be symmetric (but
   often they are).  Also, here we output the cluster-masked 'data'
   volume.
 
     3dClusterize                  \
        -inset stats.FT+tlrc.      \
        -ithr 2                    \
        -idat 1                    \
        -mask mask_group+tlrc.     \
        -NN 1                      \
        -bisided -3.313 3.313      \
        -clust_nvox 157            \
        -pref_map ClusterMap       \
        -pref_dat ClusterEffEst
 
   3. The same as Ex. 2, but specifying a p-value to set the voxelwise
   thresholds (in this case, tails DO have to be symmetric).
 
     3dClusterize                  \
        -inset stats.FT+tlrc.      \
        -ithr 2                    \
        -idat 1                    \
        -mask mask_group+tlrc.     \
        -NN 1                      \
        -bisided p=0.001           \
        -clust_nvox 157            \
        -pref_map ClusterMap       \
        -pref_dat ClusterEffEst
 
 # ------------------------------------------------------------------------



AFNI program: 3dConformist
** Program 3dConformist reads in a collection of datasets and
   zero pads them to the same size.
** The output volume size is the smallest region that includes
   all datasets (i.e., the minimal covering box).
** If the datasets cannot be processed (e.g., different grid
   spacings), then nothing will happen except for error messages.
** The purpose of this program is to be used in scripts that
   process lots of datasets and needs to make them all conform
   to the same size for collective voxel-wise analyses.
** The input datasets ARE ALTERED (embiggened)! <<<<<<------******
   Therefore, don't use this program casually.



AFNI program: 3dConvolve
** ERROR: 
** :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( **
**                                                          **
** This program, 3dConvolve, is no longer supported in AFNI **
**                                                          **
** :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( **
** Program compile date = Dec 11 2018



AFNI program: 3dCountSpikes
Usage: 3dCountSpikes dataset

Does this program do something useful?
If it does, that circumstance is completely accidental.



AFNI program: 3dDFT
++ Authored by: Kevin Murphy & Zhark the Transformer
Usage: 3dDFT [options] dataset
       where 'dataset' is complex- or float-valued.
 * Carries out the DFT along the time axis.
 * To do the DFT along the spatial axes, use program 3dFFT.
 * The input dataset can be complex-valued or float-valued.
   If it is any other data type, it will be converted to floats
   before processing.
 * [June 2018] The FFT length used is NOT rounded up to a convenient
   FFT radix; instead, the FFT size is actual value supplied in option
   '-nfft' or the number of time points (if '-nfft' isn't used).
 * However, if the FFT length has large prime factors (say > 97), the
   Fast Fourier Transform algorithm will be relatively slow. This slowdown
   is probably only noticeable for very long files, since reading and
   writing datasets seems to take most of the elapsed time in 'normal' cases.

OPTIONS:
--------

 -prefix PP  == use 'PP' as the prefix of the output file

 -abs     == output float dataset = abs(DFT)
            * Otherwise, the output file is complex-valued.
              You can then use 3dcalc to extract the real part, the
              imaginary part, the phase, etc.; see its '-cx2r' option:
                3dcalc  -cx2r REAL -a cxset+orig-expr a -prefix rset+orig
            * Please note that if you view a complex dataset in AFNI,
              the default operation is that you are looking at the
              absolute value of the dataset.
             ++ You can control the way a complex IMAGE appears via
                the 'Disp' control panel (ABS, PHASE, REAL, IMAGE).
             ++ You can control the way a complex TIME SERIES graph appears
                via environment variable AFNI_GRAPH_CX2R (in 'EditEnv').

 -nfft N  == use 'N' for DFT length (must be >= #time points)

 -detrend == least-squares remove linear drift before DFT
              [for more intricate detrending, use 3dDetrend first]

 -taper f == taper 'f' fraction of data at ends (0 <= f <= 1).
              [Hamming 'raised cosine' taper of f/2 of the ]
              [data length at each end; default is no taper]
              [cf. 3dPeriodogam -help for tapering details!]

 -inverse == Do the inverse DFT:
               SUM{ data[j] * exp(+2*PI*i*j/nfft) } * 1/nfft
             instead of the forward transform
               SUM{ data[j] * exp(-2*PI*i*j/nfft) }

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dDTeig
Usage: 3dDTeig [options] dataset
Computes eigenvalues and eigenvectors for an input dataset of
 6 sub-bricks Dxx,Dxy,Dyy,Dxz,Dyz,Dzz (lower diagonal order).
 The results are stored in a 14-subbrick bucket dataset.
 The resulting 14-subbricks are
  lambda_1,lambda_2,lambda_3,
  eigvec_1[1-3],eigvec_2[1-3],eigvec_3[1-3],
  FA,MD.

The output is a bucket dataset.  The input dataset
may use a sub-brick selection list, as in program 3dcalc.
 Options:
  -prefix pname = Use 'pname' for the output dataset prefix name.
    [default='eig']

  -datum type = Coerce the output data to be stored as the given type
    which may be byte, short or float. [default=float]

  -sep_dsets = save eigenvalues,vectors,FA,MD in separate datasets

  -uddata = tensor data is stored as upper diagonal 
            instead of lower diagonal

 Mean diffusivity (MD) calculated as simple average of eigenvalues.
 Fractional Anisotropy (FA) calculated according to Pierpaoli C, Basser PJ.
 Microstructural and physiological features of tissues elucidated by
 quantitative-diffusion tensor MRI, J Magn Reson B 1996; 111:209-19

INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.

++ Compile date = Dec 11 2018 {AFNI_18.3.16:linux_ubuntu_16_64}




AFNI program: 3dDTtoDWI
Usage: 3dDTtoDWI [options] gradient-file I0-dataset DT-dataset

Computes multiple gradient images from 6 principle direction tensors and
    corresponding gradient vector coordinates applied to the I0-dataset.
 The program takes three parameters as input :  
    a 1D file of the gradient vectors with lines of ASCII floats Gxi,Gyi,Gzi.
    Only the non-zero gradient vectors are included in this file (no G0 line).
 The I0 dataset is a volume without any gradient applied.
 The DT dataset is the 6-sub-brick dataset containing the diffusion tensor data,
    Dxx, Dxy, Dyy, Dxz, Dyz, Dzz (lower triangular row-wise order)

 Options:
   -prefix pname    = Use 'pname' for the output dataset prefix name.
                      [default='DWI']
   -automask        = mask dataset so that the gradient images
                      are computed only for high-intensity (presumably
                      brain) voxels.  The intensity level is determined
                      the same way that 3dClipLevel works.

   -datum type      = output dataset type [float/short/byte] 
                      (default is float).
   -help            = show this help screen.
   -scale_out_1000  = matches with 3dDWItoDT's '-scale_out_1000'
                      functionality.  If the option was used
                      there, then use it here, too.

 Example:

    3dDTtoDWI -prefix DWI -automask tensor25.1D 'DT+orig[26]' DT+orig.


 The output is a n sub-brick bucket dataset containing computed DWI images.
    where n is the number of vectors in the gradient file + 1


INPUT DATASET NAMES
-------------------
This program accepts datasets that are modified on input according to the
following schemes:
  'r1+orig[3..5]'                                    {sub-brick selector}
  'r1+orig<100..200>'                                {sub-range selector}
  'r1+orig[3..5]<100..200>'                          {both selectors}
  '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )'  {calculation}
For the gruesome details, see the output of 'afni -help'.



AFNI program: 3dDTtoNoisyDWI

  Take an AFNI-style DT file as input, such as might be output by 3dDWItoDT
  (which means that the DT elements are ordered: Dxx,Dxy,Dyy,Dxz,Dyz,Dzz),
  as well as a set of gradients, and then generate a synthetic set of DWI
  measures with a given SNR. Might be useful for simulations/testing.

  Part of FATCAT (Taylor & Saad, 2013) in AFNI.
  It is similar in premise to 3dDTtoDWI, however this allows for the modeled
  inclusion of Rician noise (such as appears in MRI magnitude images).

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + COMMAND: 3dDTtoNoisyDWI -dt_in DTFILE -grads GRADFILE -noise_frac0 FF \
           {-bval BB} {-S0 SS} {-mask MASK } -prefix PREFIX 

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

  + OUTPUT:
     1) If N gradients are input, then the output is a file with N+1 bricks
     that mimics a set of B0+DWI data (0th brick is the B0 reference).

  + RUNNING:
    -dt_in DTFILE    :diffusi