AFNI program: 3dDeconvolve

Output of -help


++ 3dDeconvolve: AFNI version=AFNI_24.3.08 (Dec  6 2024) [64-bit]
++ Authored by: B. Douglas Ward, et al.

------------------------------------------------------------------------
-----                 DESCRIPTION and PROLEGOMENON                 -----
------------------------------------------------------------------------
Program to calculate the deconvolution of a measurement 3D+time dataset 
with a specified input stimulus time series.  This program can also     
perform multiple linear regression using multiple input stimulus time   
series. Output consists of an AFNI 'bucket' type dataset containing     
(for each voxel)                                                        
 * the least squares estimates of the linear regression coefficients    
 * t-statistics for significance of the coefficients                    
 * partial F-statistics for significance of individual input stimuli    
 * the F-statistic for significance of the overall regression model     
The program can optionally output extra datasets containing             
 * the estimated impulse response function                              
 * the fitted model and error (residual) time series                    
------------------------------------------------------------------------
* Program 3dDeconvolve does Ordinary Least Squares (OLSQ) regression.   
* Program 3dREMLfit can be used to do Generalized Least Squares (GLSQ)  
  regression (AKA 'pre-whitened' least squares) combined with REML      
  estimation of an ARMA(1,1) temporal correlation structure:            
   https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dREMLfit.html   
* The input to 3dREMLfit is the .xmat.1D matrix file output by          
  3dDeconvolve, which also writes a 3dREMLfit command line to a file    
  to make it relatively easy to use the latter program.                 
* 3dREMLfit also allows for voxel-specific regressors, unlike           
  3dDeconvolve. This feature is used with the '-fanaticor' option       
  to afni_proc.py, for example.                                         
* Nonlinear time series model fitting can be done with program 3dNLfim
   https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dNLfim.html     
* Preprocessing of the time series input can be done with various AFNI  
  programs, or with the 'uber-script' afni_proc.py:                     
   https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html
------------------------------------------------------------------------
------------------------------------------------------------------------
****  The recommended way to use 3dDeconvolve is via afni_proc.py,  ****
****  which will pre-process the data, and also provide some useful ****
****  diagnostic tools/outputs for assessing the data's quality.    ****
****  It can also run 3dREMLfit for you 'at no extra charge'.       ****
****  [However, it will not wax your car or wash your windows.]     ****
------------------------------------------------------------------------
------------------------------------------------------------------------
Consider the time series model  Z(t) = K(t)*S(t) + baseline + noise,    
where Z(t) = data                                                       
      K(t) = kernel (e.g., hemodynamic response function or HRF)        
      S(t) = stimulus time series                                       
  baseline = constant, drift, etc. [regressors of no interest]          
     and * = convolution                                                
Then 3dDeconvolve solves for K(t) given S(t).  If you want to process   
the reverse problem and solve for S(t) given the kernel K(t), use the   
program 3dTfitter with the '-FALTUNG' option.  The difference between   
the two cases is that K(t) is presumed to be causal and have limited    
support, whereas S(t) is a full-length time series.  Note that program  
3dTfitter does not have all the capabilities of 3dDeconvolve for        
calculating output statistics; on the other hand, 3dTfitter can solve   
a deconvolution problem (in either direction) with L1 or L2 regression, 
and with sign constraints on the computed values (e.g., requiring that  
the output S(t) or K(t) be non-negative):                               
 https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dTfitter.html     
------------------------------------------------------------------------
The 'baseline model' in 3dDeconvolve (and 3dREMLfit) does not mean just 
a constant (mean) level of the signal, or even just the slow drifts that
happen in FMRI time series.  'Baseline' here also means the model that  
forms the null hypothesis.  The Full_Fstat result is the F-statistic    
of the full model (all regressors) vs. the baseline model.  Thus, it    
it common to include irregular time series, such as estimated motion    
parameters, in the baseline model via the -stim_file/-stim_base options,
or by using the -ortvec option (to include multiple regressors at once).
Thus, the 'baseline model' is really the 'null hypothesis model'.       
------------------------------------------------------------------------
It is VERY important to realize that statistics (F, t, R^2) computed in 
3dDeconvolve are MARGINAL (or partial) statistics.  For example, the    
t-statistic for a single beta coefficient measures the significance of  
that beta value against the regression model where ONLY that one column 
of the matrix is removed; that is, the null hypothesis for that         
t-statistic is the full regression model minus just that single         
regressor.  Similarly, the F-statistic for a set of regressors measures 
the significance of that set of regressors (eg, a set of TENT functions)
against the full model with just that set of regressors removed.  If    
this explanation or its consequences are unclear, you need to consult   
with a statistician, or with the AFNI message board guru entities       
(when they can be lured down from the peak of Mt Taniquetil or Kailash).
------------------------------------------------------------------------
Regression Programs in the AFNI Package:                                
* At its core, 3dDeconvolve solves a linear regression problem z = X b  
  for the parameter vector b, given the data vector z in each voxel, and
  given the SAME matrix X in each voxel.  The solution is calculated in 
  the Ordinary Least Squares (OLSQ) sense.                              
* Program 3dREMLfit does something similar, but allows for ARMA(1,1)    
  serial correlation in the data, so the solution method is called      
  Generalized Least Squares (GLSQ).                                     
* If you want to solve a problem where some of the matrix columns in X  
  (the regressors) are different in different voxels (spatially variable),
  then use program 3dTfitter, which uses OLSQ, or used 3dREMLfit.       
* 3dTfitter can also use L1 and LASSO regression, instead of OLSQ; if you
  want to use such 'robust' fitting methods, this program is your friend.
  It can also impose sign constraints (positivity or negativity) on the 
  parameters b, and can (as mentioned above) do deconvolution.          
3dBandpass and 3dTproject can do a sequence of 'time series cleanup'  
  operations, including 'regressing out' (via OLSQ) a set of nuisance   
  vectors (columns).                                                    
* 3dLSS can be used to solve -stim_times_IM systems using an alternative
  linear technique that gives biased results, but with smaller variance.
------------------------------------------------------------------------

Usage Details:                                                         
3dDeconvolve command-line-arguments ...
                                                                       
**** Input data and control options ****                               

-input fname         fname = filename of 3D+time input dataset         
                       [more than  one filename  can  be  given]       
                       [here,   and  these  datasets  will   be]       
                       [auto-catenated in time; if you do this,]       
                       ['-concat' is not needed and is ignored.]       
                **** You can input a 1D time series file here,         
                     but the time axis should run along the            
                     ROW direction, not the COLUMN direction as        
                     in the -input1D option.  You can automatically    
                     transpose a 1D file on input using the \'        
                     operator at the end of the filename, as in        
                       -input fred.1D\'                               
                  ** This is the only way to use 3dDeconvolve          
                     with a multi-column 1D time series file.          
                   * The output datasets by default will then          
                     be in 1D format themselves.  To have them         
                     formatted as AFNI datasets instead, use           
                       -DAFNI_WRITE_1D_AS_PREFIX=YES                   
                     on the command line.                              
                   * You should use '-force_TR' to set the TR of       
                     the 1D 'dataset' if you use '-input' rather       
                     than '-input1D' [the default is 1.0 sec].         

-sat OR -trans     * 3dDeconvolve can check the dataset time series    
                     for initial saturation transients, which should   
                     normally have been excised before data analysis.  
                     (Or should be censored out: see '-censor' below.) 
                     If you want to have it do this somewhat time      
                     consuming check, use the option '-sat'.           
                   * Or set environment variable AFNI_SKIP_SATCHECK to NO.
                   * Program 3dSatCheck does this check, also.         

[-noblock]           Normally, if you input multiple datasets with     
                     '-input', then the separate datasets are taken to 
                     be separate image runs that get separate baseline 
                     models.  If you want to have the program consider 
                     these to be all one big run, use -noblock.        
                   * If any of the input datasets has only 1 sub-brick,
                     then this option is automatically invoked!        
                   * If the auto-catenation feature isn't used, then   
                     this option has no effect, no how, no way.        

[-force_TR TR]       Use this value of TR instead of the one in        
                     the -input dataset.                               
                     (It's better to fix the input using 3drefit.)     

[-input1D dname]     dname = filename of single (fMRI) .1D time series 
                             where time run downs the column.          
                    * If you want to analyze multiple columns from a   
                      .1D file, see the '-input' option above for      
                      the technique.                                   

[-TR_1D tr1d]        tr1d = TR for .1D time series [default 1.0 sec].  
                     This option has no effect without -input1D        

[-nodata [NT [TR]]   Evaluate experimental design only (no input data) 
                   * Optional, but highly recommended: follow the      
                     '-nodata' with two numbers, NT=number of time     
                     points, and TR=time spacing between points (sec)  

[-mask mname]        mname = filename of 3D mask dataset               
                      Only data time series from within the mask       
                      will be analyzed; results for voxels outside     
                      the mask will be set to zero.                    

[-automask]          Build a mask automatically from input data        
                      (will be slow for long time series datasets)     
                  ** If you don't specify ANY mask, the program will   
                      build one automatically (from each voxel's RMS)  
                      and use this mask solely for the purpose of      
                      reporting truncation-to-short errors (if '-short'
                      is used) AND for computing the FDR curves in the 
                      bucket dataset's header (unless '-noFDR' is used,
                      of course).                                      
                   * If you don't want the FDR curves to be computed   
                      inside this automatically generated mask, then   
                      use '-noFDR' and later run '3drefit -addFDR' on  
                      the bucket dataset.                              
                   * To be precise, the above default masking only     
                      happens when you use '-input' to run the program 
                      with a 3D+time dataset; not with '-input1D'.     

[-STATmask sname]    Build a mask from file 'sname', and use this      
                       mask for the purpose of reporting truncation-to 
                       float issues AND for computing the FDR curves.  
                       The actual results ARE not masked with this     
                       option (only with '-mask' or '-automask' options)
                       * If you don't use '-STATmask', then the mask   
                         from '-mask' or '-automask' is used for these 
                         purposes.  If neither of those is given, then 
                         the automatically generated mask described    
                         just above is used for these purposes.        

[-censor cname]      cname = filename of censor .1D time series        
                   * This is a file of 1s and 0s, indicating which     
                     time points are to be included (1) and which are  
                     to be excluded (0).                               
                   * Option '-censor' can only be used once!           
                   * The option below may be simpler to use!           

[-CENSORTR clist]    clist = list of strings that specify time indexes 
                       to be removed from the analysis.  Each string is
                       of one of the following forms:                  
                           37 => remove global time index #37          
                         2:37 => remove time index #37 in run #2       
                       37..47 => remove global time indexes #37-47     
                       37-47  => same as above                         
                     2:37..47 => remove time indexes #37-47 in run #2  
                     *:0-2    => remove time indexes #0-2 in all runs  
                      +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.           
                      +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 = 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.                                     

[-nfirst fnum]       fnum = number of first dataset image to use in the
                       deconvolution procedure. [default = max maxlag] 

[-nlast  lnum]       lnum = number of last dataset image to use in the 
                       deconvolution procedure. [default = last point] 

[-polort pnum]       pnum = degree of polynomial corresponding to the  
                       null hypothesis  [default: pnum = 1]            
                    ** For pnum > 2, this type of baseline detrending  
                       is roughly equivalent to a highpass filter      
                       with a cutoff of (p-2)/D Hz, where 'D' is the   
                       duration of the imaging run: D = N*TR           
                    ** If you use 'A' for pnum, the program will       
                       automatically choose a value based on the       
                       time duration D of the longest run:             
                         pnum = 1 + int(D/150)                         
                ==>>** 3dDeconvolve is the ONLY AFNI program with the  
                       -polort option that allows the use of 'A' to    
                       set the polynomial order automatically!!!       
                    ** Use '-1' for pnum to specifically NOT include   
                       any polynomials in the baseline model.  Only    
                       do this if you know what this means!            

[-legendre]          use Legendre polynomials for null hypothesis      
                       (baseline model)                                

[-nolegendre]        use power polynomials for null hypotheses         
                       [default is -legendre]                          
                    ** Don't do this unless you are crazy!             

[-nodmbase]          don't de-mean baseline time series                
                       (i.e., polort>0 and -stim_base inputs)          
[-dmbase]            de-mean baseline time series [default if polort>=0]

[-svd]               Use SVD instead of Gaussian elimination [default] 
[-nosvd]             Use Gaussian elimination instead of SVD           
                       (only use for testing + backwards compatibility)

[-rmsmin r]          r = minimum rms error to reject reduced model     
                       (default = 0; don't use this option normally!)  

[-nocond]            DON'T calculate matrix condition number           
                      ** This value is NOT the same as Matlab!         

[-singvals]          Print out the matrix singular values              
                      (useful for some testing/debugging purposes)     
                      Also see program 1dsvd.                          

[-GOFORIT [g]]       Use this to proceed even if the matrix has        
                     bad problems (e.g., duplicate columns, large      
                     condition number, etc.).                          
               *N.B.: Warnings that you should particularly heed have  
                      the string '!!' somewhere in their text.         
               *N.B.: Error and Warning messages go to stderr and      
                      also to file 3dDeconvolve.err.               
                      ++ You can disable the creation of this .err     
                         file by setting environment variable          
                         AFNI_USE_ERROR_FILE to NO before running      
                         this program.                                 
               *N.B.: The optional number 'g' that appears is the      
                      number of warnings that can be ignored.          
                      That is, if you use -GOFORIT 7 and 9 '!!'        
                      matrix warnings appear, then the program will    
                      not run.  If 'g' is not present, 1 is used.      

[-allzero_OK]        Don't consider all zero matrix columns to be      
                      the type of error that -GOFORIT is needed to     
                      ignore.                                          
                     * Please know what you are doing when you use     
                       this option!                                    

[-Dname=val]       = Set environment variable 'name' to 'val' for this 
                     run of the program only.                          
                                                                       
******* Input stimulus options *******                                 
                                                                       
-num_stimts num      num = number of input stimulus time series        
                       (0 <= num)   [default: num = 0]                 
               *N.B.: '-num_stimts' must come before any of the        
                      following '-stim' options!                       
               *N.B.: Most '-stim' options have as their first argument
                      an integer 'k', ranging from 1..num, indicating  
                      which stimulus class the argument is defining.   
               *N.B.: The purpose of requiring this option is to make  
                      sure your model is complete -- that is, you say  
                      you are giving 5 '-stim' options, and then the   
                      program makes sure that all of them are given    
                      -- that is, that you don't forget something.     
                                                                       
-stim_file k sname   sname = filename of kth time series input stimulus
               *N.B.: This option directly inserts a column into the   
                      regression matrix; unless you are using the 'old'
                      method of deconvolution (cf below), you would    
                      normally only use '-stim_file' to insert baseline
                      model components such as motion parameters.      
                                                                       
[-stim_label k slabel] slabel = label for kth input stimulus           
               *N.B.: This option is highly recommended, so that       
                      output sub-bricks will be labeled for ease of    
                      recognition when you view them in the AFNI GUI.  
                                                                       
[-stim_base k]       kth input stimulus is part of the baseline model  
               *N.B.: 'Baseline model' == Null Hypothesis model        
               *N.B.: The most common baseline components to add are   
                      the 6 estimated motion parameters from 3dvolreg

-ortvec fff lll      This option lets you input a rectangular array    
                     of 1 or more baseline vectors from file 'fff',    
                     which will get the label 'lll'.  Functionally,    
                     it is the same as using '-stim_file' on each      
                     column of 'fff' separately (plus '-stim_base').   
                     This method is just a faster and simpler way to   
                     include a lot of baseline regressors in one step. 
          -->>**N.B.: This file is NOT included in the '-num_stimts'   
                      count that you provide.                          
               *N.B.: These regression matrix columns appear LAST      
                      in the matrix, after everything else.            
               *N.B.: You can use column '[..]' and/or row '{..}'      
                      selectors on the filename 'fff' to pick out      
                      a subset of the numbers in that file.            
               *N.B.: The q-th column of 'fff' will get a label        
                      like 'lll[q]' in the 3dDeconvolve results.       
               *N.B.: This option is known as the 'Inati Option'.      
               *N.B.: Unlike the original 'Inati' (who is unique), it  
                      is allowed to have more than one '-ortvec' option.
               *N.B.: Program 1dBport is one place to generate a file  
                      for use with '-ortvec'; 1deval might be another. 

**N.B.: You must have -num_stimts > 0  AND/OR                          
        You must use  -ortvec          AND/OR                          
        You must have -polort >= 0                                     
        Otherwise, there is no regression model!                       
        An example using -polort only:                                 
 3dDeconvolve -x1D_stop -polort A -nodata 300 2 -x1D stdout: | 1dplot -one -stdin

**N.B.: The following 3 options are for the 'old' style of explicit    
        deconvolution.  For most purposes, their usage is no longer    
        recommended.  Instead, you should use the '-stim_times' options
        to directly input the stimulus times, rather than code the     
        stimuli as a sequence of 0s and 1s in this 'old' method!       

[-stim_minlag k m]   m = minimum time lag for kth input stimulus       
                       [default: m = 0]                                
[-stim_maxlag k n]   n = maximum time lag for kth input stimulus       
                       [default: n = 0]                                
[-stim_nptr k p]     p = number of stimulus function points per TR     
                       Note: This option requires 0 slice offset times 
                       [default: p = 1]                                
                                                                       
**N.B.: The '-stim_times' options below are the recommended way of     
        analyzing FMRI time series data now.  The options directly     
        above are only maintained for the sake of backwards            
        compatibility!  For most FMRI users, the 'BLOCK' and 'TENT'    
        (or 'CSPLIN') response models will serve their needs.  The     
        other models are for users with specific needs who understand  
        clearly what they are doing.                                   
                                                                       
[-stim_times k tname Rmodel]                                           
   Generate the k-th response model from a set of stimulus times       
   given in file 'tname'.                                              
    *** The format of file 'tname' is one line per imaging run         
        (cf. '-concat' above), and each line contains the list of START
        times (in seconds) for the stimuli in class 'k' for its        
        corresponding run of data; times are relative to the start of  
        the run (i.e., sub-brick #0 occurring at time=0).              
    *** The DURATION of the stimulus is encoded in the 'Rmodel'        
        argument, described below. Units are in seconds, not TRs!      
        -- If different stimuli in the same class 'k' have different   
           durations, you'll have to use the dmBLOCK response model    
           and '-stim_times_AM1' or '-stim_times_AM2', described below.
    *** Different lines in the 'tname' file can contain different      
        numbers of start times.  Each line must contain at least 1 time.
    *** If there is no stimulus in class 'k' in a particular imaging   
        run, there are two ways to indicate that:                      
          (a) put a single '*' on the line, or                         
          (b) put a very large number or a negative number             
              (e.g., 99999, or -1) on the line                         
              -- times outside the range of the imaging run will cause 
                 a warning message, but the program will soldier on.   
    *** In the case where the stimulus doesn't actually exist in the   
        data model (e.g., every line in 'tname' is a '*'), you will    
        also have to use the '-allzero_OK' option to force 3dDeconvolve
        to run with regressor matrix columns that are filled with zeros.
                                                                       
   The response model is specified by the third argument after         
   '-stim_times' ('Rmodel'), and can be one of the following:          
    *** In the descriptions below, a '1 parameter' model has a fixed   
        shape, and only the estimated amplitude ('Coef') varies:       
          BLOCK GAM TWOGAM SPMG1 WAV MION                              
    *** Models with more than 1 parameter have multiple basis          
        functions, and the estimated parameters ('Coef') are their     
        amplitudes. The estimated shape of the response to a stimulus  
        will be different in different voxels:                         
          TENT CSPLIN SPMG2 SPMG3 POLY SIN EXPR                        
    *** Many models require the input of the start and stop times for  
        the response, 'b' and 'c'.  Normally, 'b' would be zero, but   
        in some cases, 'b' could be negative -- for example, if you    
        are concerned about anticipatory effects.  The stop time 'c'   
        should be based on how long you realistically expect the       
        hemodynamic response to last after the onset of the stimulus;  
        e.g., the duration of the stimulus plus 14 seconds for BOLD.   
    *** If you use '-tout', each parameter will get a separate         
        t-statistic.  As mentioned far above, this is a marginal       
        statistic, measuring the impact of that model component on the 
        regression fit, relative to the fit with that one component    
        (matrix column) removed.                                       
    *** If you use '-fout', each stimulus will also get an F-statistic,
        which is the collective impact of all the model components     
        it contains, relative to the regression fit with the entire    
        stimulus removed. (If there is only 1 parameter, then F = t*t.)
    *** Some models below are described in terms of a simple response  
        function that is then convolved with a square wave whose       
        duration is a parameter you give (duration is NOT a parameter  
        that will be estimated).  Read the descriptions below carefully:
        not all functions are (or can be) convolved in this way:       
         * ALWAYS convolved:      BLOCK  dmBLOCK  MION  MIONN          
         * OPTIONALLY convolved:  GAM    TWOGAM   SPMGx WAV            
         * NEVER convolved:       TENT   CSPLIN   POLY  SIN   EXPR     
        Convolution is specified by providing the duration parameter   
        as described below for each particular model function.         

     'BLOCK(d,p)'  = 1 parameter block stimulus of duration 'd'        
                    ** There are 2 variants of BLOCK:                  
                         BLOCK4 [the default] and BLOCK5               
                       which have slightly different delays:           
                         HRF(t) = int( g(t-s) , s=0..min(t,d) )        
                       where g(t) = t^q * exp(-t) /(q^q*exp(-q))       
                       and q = 4 or 5.  The case q=5 is delayed by     
                       about 1 second from the case q=4.               
                ==> ** Despite the name, you can use 'BLOCK' for event-
                       related analyses just by setting the duration to
                       a small value; e.g., 'BLOCK5(1,1)'              
                    ** The 'p' parameter is the amplitude of the       
                       basis function, and should usually be set to 1. 
                       If 'p' is omitted, the amplitude will depend on 
                       the duration 'd', which is useful only in       
                       special circumstances!!                         
                    ** For bad historical reasons, the peak amplitude  
                       'BLOCK' without the 'p' parameter does not go to
                       1 as the duration 'd' gets large.  Correcting   
                       this oversight would break some people's lives, 
                       so that's just the way it is.                   
                    ** The 'UBLOCK' function (U for Unit) is the same  
                       as the 'BLOCK' function except that when the    
                       'p' parameter is missing (or 0), the peak       
                       amplitude goes to 1 as the duration gets large. 
                       If p > 0, 'UBLOCK(d,p)' and 'BLOCK(d,p)' are    
                       identical.                                      

     'TENT(b,c,n)' = n parameter tent function expansion from times    
                       b..c after stimulus time [piecewise linear]     
                       [n must be at least 2; time step is (c-b)/(n-1)]
    'CSPLIN(b,c,n)'= n parameter cubic spline function expansion       
                       from times b..c after stimulus time             
                       [n must be at least 4]                          
                     ** CSPLIN is a drop-in upgrade of TENT to a       
                        differentiable set of functions.               
                     ** TENT and CSPLIN are 'cardinal' interpolation   
                        functions: their parameters are the values     
                        of the HRF model at the n 'knot' points        
                          b , b+dt , b+2*dt , ... [dt = (c-b)/(n-1)]   
                        In contrast, in a model such as POLY or SIN,   
                        the parameters output are not directly the     
                        hemodynamic response function values at any    
                        particular point.                              
                 ==> ** You can also use 'TENTzero' and 'CSPLINzero',  
                        which means to eliminate the first and last    
                        basis functions from each set.  The effect     
                        of these omissions is to force the deconvolved 
                        HRF to be zero at t=b and t=c (to start and    
                        and end at zero response).  With these 'zero'  
                        response models, there are n-2 parameters      
                        (thus for 'TENTzero', n must be at least 3).   
                     ** These 'zero' functions will force the HRF to   
                        be continuous, since they will now be unable   
                        to suddenly rise up from 0 at t=b and/or drop  
                        down to 0 at t=c.                              

     'GAM(p,q)'    = 1 parameter gamma variate                         
                         (t/(p*q))^p * exp(p-t/q)                      
                       Defaults: p=8.6 q=0.547 if only 'GAM' is used   
                     ** The peak of 'GAM(p,q)' is at time p*q after    
                        the stimulus.  The FWHM is about 2.35*sqrt(p)*q;
                        this approximation is accurate for p > 0.3*q.  
                     ** To check this approximation, try the command   
               1deval -num 100 -del 0.02 -xzero 0.02   \
                      -expr 'sqrt(gamp(x,1))/2.35/x' | \
               1dplot -stdin -del 0.02 -xzero 0.02 -yaxis 1:1.4:4:10   
                        If the two functions gamp(x,1) and 2.35*x      
                        were equal, the plot would be constant y=1.    
                 ==> ** If you add a third argument 'd', then the GAM  
                        function is convolved with a square wave of    
                        duration 'd' seconds; for example:             
                          'GAM(8.6,.547,17)'                           
                        for a 17 second stimulus.  [09 Aug 2010]       
     'GAMpw(K,W)'  = Same as 'GAM(p,q)' but where the shape parameters 
                       are specified at time to peak 'K' and full      
                       width at half max (FWHM) 'W'. You can also      
                       add a third argument as the duration. The (K,W) 
                       parameters are converted to (p,q) values for    
                       the actual computations; the (p,q) parameters   
                       are printed to the text (stderr) output.        
                     ** Note that if you give weird values for K and W,
                        weird things will happen: (tcsh syntax)        
                         set pp = `ccalc 'gamp(2,8)'`                  
                         set qq = `ccalc 'gamq(2,8)'`                  
                         1deval -p=$pp -q=$qq -num 200 -del 0.1  \
                                -expr '(t/p/q)^p*exp(p-t/q)'   | \
                                1dplot -stdin -del 0.1                 
                        Here, K is significantly smaller than W,       
                        so a gamma variate that fits peak=2 width=8    
                        must be weirdly shaped. [Also note use of the  
                        'calc' functions gamp(K,W) and gamq(K,W) to    
                        calculate p and q from K and W in the script.] 

     'TWOGAM(p1,q1,r,p2,q2)'                                           
                   = 1 parameter (amplitude) model:                    
                   = A combination of two 'GAM' functions:             
                         GAM(p1,q1) - r*GAM(p2,q2)                     
                       This model is intended to let you use a HRF     
                       similar to BrainVoyager (e.g.). You can         
                       add a sixth argument as the duration.           
                     ** Note that a positive 'r' parameter means to    
                        subtract the second GAM function (undershoot). 
     'TWOGAMpw(K1,W1,r,K2,W2)'                                         
                   = Same as above, but where the peaks and widths     
                       of the 2 component gamma variates are given     
                       instead of the less intuitive p and q.          
                       For FMRI work, K2 > K1 is usual, as the         
                       second (subtracted) function is intended        
                       to model the 'undershoot' after the main        
                       positive part of the model. You can also        
                       add a sixth argument as the duration.           
                     ** Example (no duration given):                   
        3dDeconvolve -num_stimts 1 -polort -1 -nodata 81 0.5         \
                     -stim_times 1 '1D: 0' 'TWOGAMpw(3,6,0.2,10,12)' \
                     -x1D stdout: | 1dplot -stdin -THICK -del 0.5      

     'SPMG1'       = 1 parameter SPM gamma variate basis function      
                         exp(-t)*(A1*t^P1-A2*t^P2) where               
                       A1 = 0.0083333333  P1 = 5  (main positive lobe) 
                       A2 = 1.274527e-13  P2 = 15 (undershoot part)    
                       This function is NOT normalized to have peak=1! 
     'SPMG2'       = 2 parameter SPM: gamma variate + d/dt derivative  
                       [For backward compatibility: 'SPMG' == 'SPMG2'] 
     'SPMG3'       = 3 parameter SPM basis function set                
                 ==> ** The SPMGx functions now can take an optional   
                        (duration) argument, specifying that the primal
                        SPM basis functions should be convolved with   
                        a square wave 'duration' seconds long and then 
                        be normalized to have peak absolute value = 1; 
                        e.g., 'SPMG3(20)' for a 20 second duration with
                        three basis function.  [28 Apr 2009]           
                     ** Note that 'SPMG1(0)' will produce the usual    
                        'SPMG1' wavefunction shape, but normalized to  
                        have peak value = 1 (for example).             

     'POLY(b,c,n)' = n parameter Legendre polynomial expansion         
                       from times b..c after stimulus time             
                       [n can range from 1 (constant) to 20]           

     'SIN(b,c,n)'  = n parameter sine series expansion                 
                       from times b..c after stimulus time             
                       [n must be at least 1]                          

     'WAV(d)'      = 1 parameter block stimulus of duration 'd'.       
                      * This is the '-WAV' function from program waver!
                      * If you wish to set the shape parameters of the 
                        WAV function, you can do that by adding extra  
                        arguments, in the order                        
                         delay time , rise time , fall time ,          
                         undershoot fraction, undershoot restore time  
                      * The default values are 'WAV(d,2,4,6,0.2,2)'    
                      * Omitted parameters get the default values.     
                      * 'WAV(d,,,,0)' (setting undershoot=0) is        
                        very similar to 'BLOCK5(d,1)', for d > 0.      
                      * Setting duration d to 0 (or just using 'WAV')  
                        gives the pure '-WAV' impulse response function
                        from waver.                                    
                      * If d > 0, the WAV(0) function is convolved with
                        a square wave of duration d to make the HRF,   
                        and the amplitude is scaled back down to 1.    

     'EXPR(b,c) exp1 ... expn'                                         
                   = n parameter; arbitrary expressions from times     
                     b..c after stimulus time                          
                      * Expressions are separated by spaces, so        
                        each expression must be a contiguous block     
                        of non-whitespace characters                   
                      * The entire model, from 'EXPR' to the final     
                        expression must be enclosed in one set of      
                        quotes. The individual component expressions   
                        are separated by blanks. Example:              
                          '-EXPR(0,20) sin(PI*t/20)^2'                 
                      * Expressions use the same format as 3dcalc      
                      * Symbols that can be used in an expression:     
                         t = time in sec since stimulus time           
                         x = time scaled to be x= 0..1 for t=bot..top  
                         z = time scaled to be z=-1..1 for t=bot..top  
                      * Spatially dependent regressors are not allowed!
                      * Other symbols are set to 0 (silently).         
                 ==> ** There is no convolution of the 'EXPR' functions
                        with a square wave implied.  The expressions   
                        you input are what you get, evaluated over     
                        times b..c after each stimulus time.  To be    
                        sure of what your response model is, you should
                        plot the relevant columns from the matrix      
                        .xmat.1D output file.                          

     'MION(d)'     = 1 parameter block stimulus of duration 'd',       
                     intended to model the response of MION.           
                     The zero-duration impulse response 'MION(0)' is   
                       h(t) = 16.4486 * ( -0.184/ 1.5 * exp(-t/ 1.5)   
                                          +0.330/ 4.5 * exp(-t/ 4.5)   
                                          +0.670/13.5 * exp(-t/13.5) ) 
                     which is adapted from the paper                   
                      FP Leite, et al. NeuroImage 16:283-294 (2002)    
                      http://dx.doi.org/10.1006/nimg.2002.1110         
                  ** Note that this is a positive function, but MION   
                     produces a negative response to activation, so the
                     beta and t-statistic for MION are usually negative.
               ***** If you want a negative MION function (so you get  
                     a positive beta), use the name 'MIONN' instead.   
                  ** After convolution with a square wave 'd' seconds  
                     long, the resulting single-trial waveform is      
                     scaled to have magnitude 1.  For example, try     
                     this fun command to compare BLOCK and MION:       
               3dDeconvolve -nodata 300 1 -polort -1 -num_stimts 2   \
                            -stim_times 1 '1D: 10 150' 'MION(70)'    \
                            -stim_times 2 '1D: 10 150' 'BLOCK(70,1)' \
                            -x1D stdout: | 1dplot -stdin -one -thick   
                     You will see that the MION curve rises and falls  
                     much more slowly than the BLOCK curve.            
              ==> ** Note that 'MION(d)' is already convolved with a   
                     square wave of duration 'd' seconds.  Do not      
                     convolve it again by putting in multiple closely  
                     spaced stimulus times (this mistake has been made)!
                  ** Scaling the single-trial waveform to have magnitude
                     1 means that trials with different durations 'd'  
                     will have the same magnitude for their regression 
                     models.                                           
                                                                       
 * 3dDeconvolve does LINEAR regression, so the model parameters are    
   amplitudes of the basis functions; 1 parameter models are 'simple'  
   regression, where the shape of the impulse response function is     
   fixed and only the magnitude/amplitude varies.  Models with more    
   free parameters have 'variable' shape impulse response functions.   

 * LINEAR regression means that each data time series (thought of as   
   a single column of numbers = a vector) is fitted to a sum of the    
   matrix columns, each one multiplied by an amplitude parameter to    
   be calculated ('Coef'). The purpose of the various options          
     '-stim_times', '-polort', '-ortvec', and/or '-stim_file'          
   is to build the columns of the regression matrix.                   
                                                                       
 * If you want NONLINEAR regression, see program 3dNLfim.              
                                                                       
 * If you want LINEAR regression with allowance for non-white noise,   
   use program 3dREMLfit, after using 3dDeconvolve to set up the       
   regression model (in the form of a matrix file).                    
                                                                       
** When in any doubt about the shape of the response model you are   **
*  asking for, you should plot the relevant columns from the X matrix *
*  to help develop some understanding of the analysis.  The 'MION'    *
*  example above can be used as a starting point for how to easily    *
*  setup a quick command pipeline to graph response models.  In that  *
*  example, '-polort -1' is used to suppress the usual baseline model *
*  since graphing that part of the matrix would just be confusing.    *
*  Another example, for example, comparing the similar models         *
** 'WAV(10)', 'BLOCK4(10,1)', and 'SPMG1(10)':                       **
                                                                       
     3dDeconvolve -nodata 100 1.0 -num_stimts 3 -polort -1   \
                  -local_times -x1D stdout:                  \
                  -stim_times 1 '1D: 10 60' 'WAV(10)'        \
                  -stim_times 2 '1D: 10 60' 'BLOCK4(10,1)'   \
                  -stim_times 3 '1D: 10 60' 'SPMG1(10)'      \
      | 1dplot -thick -one -stdin -xlabel Time -ynames WAV BLOCK4 SPMG1
                                                                       
 * For the format of the 'tname' file, see the last part of            
 https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/DeconSummer2004.html 
   and also see the other documents stored in the directory below:     
 https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/                     
   and also read the presentation below:                               
 https://afni.nimh.nih.gov/pub/dist/edu/latest/afni_handouts/afni05_regression.pdf
  ** Note Well:                                                        
   * The contents of the 'tname' file are NOT just 0s and 1s,          
     but are the actual times of the stimulus events IN SECONDS.       
   * You can give the times on the command line by using a string      
     of the form '1D: 3.2 7.9 | 8.2 16.2 23.7' in place of 'tname',    
     where the '|' character indicates the start of a new line         
     (so this example is for a case with 2 catenated runs).            
=> * You CANNOT USE the '1D:' form of input for any of the more        
     complicated '-stim_times_*' options below!!                       
   * The '1D:' form of input is mostly useful for quick tests, as      
     in the examples above, rather than for production analyses with   
     lots of different stimulus times and multiple imaging runs.       
                                                                       
[-stim_times_AM1 k tname Rmodel]                                       
   Similar, but generates an amplitude modulated response model.       
   The 'tname' file should consist of 'time*amplitude' pairs.          
   As in '-stim_times', the '*' character can be used as a placeholder 
   when an imaging run doesn't have any stimulus of a given class.     
   *N.B.: What I call 'amplitude' modulation is called 'parametric'    
          modulation in Some other PrograM.                            
 ***N.B.: If NO run at all has a stimulus of a given class, then you   
          must have at least 1 time that is not '*' for -stim_times_*  
          to work (so that the proper number of regressors can be set  
          up).  You can use a negative time for this purpose, which    
          will produce a warning message but otherwise will be         
          ignored, as in:                                              
             -1*37                                                     
             *                                                         
          for a 2 run 'tname' file to be used with -stim_times_*.      
       ** In such a case, you will also need the -allzero_OK option,   
          and probably -GOFORIT as well.                               
    ** It is possible to combine '-stim_times_AM1' with the Rmodel     
       being TENT. If you have an amplitude parameter at each TR,      
       and you want to try to deconvolve its impact on the data,       
       you can try the following:                                      
         a) create a 1D column file with the amplitude parameter,      
            one value per TR, matching the length of the data;         
            say this file is called Akk.1D                             
         b) create a 1D column file with the actual TR time in         
            each row; for example, if you have 150 time points         
            and TR=2 s, then                                           
              1deval -num 150 -expr '2*i' > Att.1D                     
         c) glue these files together for use with -stim_times_AM1:    
              echo `1dMarry Att.1D Akk.1D` > Atk.1D                    
         d) Use option                                                 
              -stim_times 1 Atk.1D 'TENT(0,20,11)' -stim_label 1 TENT  
            which gives a TENT response lasting 20s with 11 parameters 
            -- one every TR.                                           
         e) Use all the other clever options you need in 3dDeconvolve, 
            such as censoring, baseline, motion parameters, ....       
       Variations on the options chosen here can be made to            
       constrain the deconvolution; e.g., use CSPLIN vs. TENT, or      
       CSPLINzero; use fewer parameters in the TENT/CSPLIN to force    
       a smoother deconvolution, etc.                                  
       Graphing the regression matrix is useful in this type of        
       analysis, to be sure you are getting the analysis you want;     
       for example:                                                    
         1dplot -sep_scl prefix.xmat.1D                                

[-stim_times_AM2 k tname Rmodel]                                       
   Similar, but generates 2 response models: one with the mean         
   amplitude and one with the differences from the mean.               
  *** Please note that 'AM2' is the option you should probably use!    
  *** 'AM1' is for special cases, and normally should not be used      
      for FMRI task activation analyses!!                              
  *** 'AM2' will give you the ability to detect voxels that activate   
      but do not change proportional to the amplitude factor, as well  
      as provide a direct measure of the proportionality of the        
      activation to changes in the input amplitude factors.  'AM1'     
      will do neither of these things.                                 
  *** Normally, 3dDeconvolve removes the mean of the auxiliary         
      parameter(s) from the modulated regressor(s).  However, if you   
      set environment variable AFNI_3dDeconvolve_rawAM2 to YES, then   
      the mean will NOT be removed from the auxiliary parameter(s).    
      This ability is provided for users who want to center their      
      parameters using their own method.                               
  *** [12 Jul 2012] You can now specify the value to subtract from     
      each modulation parameter -- this value will replace the         
      subtraction of the average parameter value that usually happens. 
      To do this, add an extra parameter after the option, as in       
        -stim_times_AM2 1 timesAM.1D 'BLOCK(2,1)' :5.2:x:2.0           
      The extra argument must start with the colon ':' character, and  
      there should be as many different values (separated by ':') as   
      there are parameters in the timing file (timesAM.1D above).      
  ==> In the example above, ':5.2:x:2.0' means                         
        subtract 5.2 from each value of the first parameter in timesAM.1D
        subtract the MEAN from each value of the second parameter      
          (since 'x' doesn't translate to a number)                    
        subtract 2.0 from each value of the third parameter            
  ==> What is this option for, anyway?  The purpose is to facilitate   
      GROUP analysis the results from a collection of subjects, where  
      you want to treat each subject's analysis exactly the same       
      way -- and thus, the subtraction value for a parameter (e.g.,    
      reaction time) should then be the mean over all the reaction     
      times from all trials in all subjects.                           
                                                                       
** NOTE [04 Dec 2008] **                                               
 -stim_times_AM1 and -stim_times_AM2 now take files with more          
   than 1 amplitude attached to each time; for example,                
     33.7*9,-2,3                                                       
   indicates a stimulus at time 33.7 seconds with 3 amplitudes         
   attached (9 and -2 and 3).  In this example, -stim_times_AM2 would  
   generate 4 response models: 1 for the constant response case        
   and 1 scaled by each of the amplitude sets.                         
   ** Please don't carried away and use too many parameters!! **       
 For more information on modulated regression, see                     
   https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/AMregression.pdf   
                                                                       
** NOTE [08 Dec 2008] **                                               
 -stim_times_AM1 and -stim_times_AM2 now have 1 extra response model   
 function available:                                                   
   dmBLOCK (or dmBLOCK4 or dmBLOCK5)                                   
 where 'dm' means 'duration modulated'.  If you use this response      
 model, then the LAST married parameter in the timing file will        
 be used to modulate the duration of the block stimulus.  Any          
 earlier parameters will be used to modulate the amplitude,            
 and should be separated from the duration parameter by a ':'          
 character, as in '30*5,3:12' which means (for dmBLOCK):               
   a block starting at 30 s,                                           
   with amplitude modulation parameters 5 and 3,                       
   and with duration 12 s.                                             
 The unmodulated peak response of dmBLOCK depends on the duration      
 of the stimulus, as the BOLD response accumulates.                    
 If you want the peak response to be a set to a fixed value, use       
   dmBLOCK(p)                                                          
 where p = the desired peak value (e.g., 1).                           
 *** Understand what you doing when you use dmBLOCK, and look at  ***  
 *** the regression matrix!  Otherwise, you will end up confused. ***  
 *N.B.: The maximum allowed dmBLOCK duration is 999 s.                 
 *N.B.: You cannot use '-iresp' or '-sresp' with dmBLOCK!              
 *N.B.: If you are NOT doing amplitude modulation at the same time     
        (and so you only have 1 'married' parameter per time), use     
        '-stim_times_AM1' with dmBLOCK.  If you also want to do        
        amplitude modulation at the same time as duration modulation   
        (and so you have 2 or more parameters with each time), use     
        '-stim_times_AM2' instead.  If you use '-stim_times_AM2' and   
        there is only 1 'married' parameter, the program will print    
        a warning message, then convert to '-stim_times_AM1', and      
        continue -- so nothing bad will happen to your analysis!       
        (But you will be embarrassed in front of your friends.)         
 *N.B.: If you are using AM2 (amplitude modulation) with dmBLOCK, you  
        might want to use 'dmBLOCK(1)' to make each block have native  
        amplitude 1 before it is scaled by the amplitude parameter.    
        Or maybe not -- this is a matter for fine judgment.            
 *N.B.: You can also use dmBLOCK with -stim_times_IM, in which case    
        each time in the 'tname' file should have just ONE extra       
        parameter -- the duration -- married to it, as in '30:15',     
        meaning a block of duration 15 seconds starting at t=30 s.     
 *N.B.: For bad historical reasons, the peak amplitude dmBLOCK without 
        the 'p' parameter does not go to 1 as the duration gets large. 
        Correcting this oversight would break some people's lives, so  
        that's just the way it is.                                     
 *N.B.: The 'dmUBLOCK' function (U for Unit) is the same as the        
        'dmBLOCK' function except that when the 'p' parameter is       
        missing (or 0), the peak amplitude goes to 1 as the duration   
        gets large.  If p > 0, 'dmUBLOCK(p)' and 'dmBLOCK(p)' are      
        identical                                                      
 For some graphs of what dmBLOCK regressors look like, see             
   https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/AMregression.pdf   
 and/or try the following command:                                     
    3dDeconvolve -nodata 350 1 -polort -1 -num_stimts 1 \
                 -stim_times_AM1 1 q.1D 'dmBLOCK'       \
                 -x1D stdout: | 1dplot -stdin -thick -thick            
 where file q.1D contains the single line                              
   10:1 40:2 70:3 100:4 130:5 160:6 190:7 220:8 250:9 280:30           
 Change 'dmBLOCK' to 'dmBLOCK(1)' and see how the matrix plot changes. 
                                                                       
 **************** Further notes on dmBLOCK [Nov 2013] **************** 
                                                                       
 Basically (IMHO), there are 2 rational choices to use:                
                                                                       
   (a) 'dmUBLOCK' = allow the amplitude of the response model to       
                    vary with the duration of the stimulus; getting    
                    larger with larger durations; for durations longer 
                    than about 15s, the amplitude will become 1.       
               -->> This choice is equivalent to 'dmUBLOCK(0)', but    
                    is NOT equivalent to 'dmBLOCK(0)' due to the       
                    historical scaling issue alluded to above.         
                                                                       
   (b) 'dmUBLOCK(1)' = all response models will get amplitude 1,       
                       no matter what the duration of the stimulus.    
                  -->> This choice is equivalent to 'dmBLOCK(1)'.      
                                                                       
 Some users have expressed the desire to allow the amplitude to        
 vary with duration, as in case (a), BUT to specify the duration       
 at which the amplitude goes to 1.  This desideratum has now been      
 implemented, and provides the case below:                             
                                                                       
   (a1) 'dmUBLOCK(-X)' = set the amplitude to be 1 for a duration      
                         of 'X' seconds; e.g., 'dmBLOCK(-5)' means     
                         that a stimulus with duration 5 gets          
                         amplitude 1, shorter durations get amplitudes 
                         smaller than 1, and longer durations get      
                         amplitudes larger than 1.                     
                    -->> Please note that 'dmBLOCK(-X)' is NOT the     
                         same as this case (a1), and in fact it        
                         has no meaning.                               
                                                                       
 I hope this clarifies things and makes your life simpler, happier,    
 and more carefree. (If not, please blame Gang Chen, not me.)          
                                                                       
 An example to clarify the difference between these cases:             
    3dDeconvolve -nodata 350 1 -polort -1 -num_stimts 3 \
                 -stim_times_AM1 1 q.1D 'dmUBLOCK'      \
                 -stim_times_AM1 2 q.1D 'dmUBLOCK(1)'   \
                 -stim_times_AM1 3 q.1D 'dmUBLOCK(-4)'  \
                 -x1D stdout: |                         \
     1dplot -stdin -thick                               \
            -ynames 'dmUBLOCK' 'dmUB(1)' 'dmUB(-4)'                    
 where file q.1D contains the single line                              
   10:1 60:2 110:4 160:10 210:20 260:30                                
 Note how the 'dmUBLOCK(-4)' curve (green) peaks at 1 for the 3rd      
 stimulus, and peaks at larger values for the later (longer) blocks.   
 Whereas the 'dmUBLOCK' curve (black) peaks at 1 at only the longest   
 blocks, and the 'dmUBLOCK(1)' curve (red) peaks at 1 for ALL blocks.  
 ********************************************************************* 
                                                                       
[-stim_times_FSL k tname Rmodel]                                       
   This option allows you to input FSL-style 3-column timing files,    
   where each line corresponds to one stimulus event/block; the        
   line '40 20 1' means 'stimulus starts at 40 seconds, lasts for      
   20 seconds, and is given amplitude 1'.  Since in this format,       
   each stimulus can have a different duration and get a different     
   response amplitude, the 'Rmodel' must be one of the 'dm'            
   duration-modulated options above ['dmUBLOCK(1)' is probably the     
   most useful].  The amplitude modulation is taken to be like         
   '-stim_times_AM1', where the given amplitude in the 'tname' file    
   multiplies the basic response shape.                                
 *** We DO NOT advocate the use of this '_FSL' option, but it's here   
     to make some scripting easier for some (unfortunate) people.      
 *** The results of 3dDeconvolve (or 3dREMLfit) cannot be expected     
     to be exactly the same as FSL FEAT, since the response model      
     shapes are different, among myriad other details.                 
 *** You can also use '-stim_times_FS1' to indicate that the           
     amplitude factor in the 'tname' file should be ignored and        
     replaced with '1' in all cases.                                   
 *** FSL FEAT only analyzes contiguous time series -- nothing like     
     '-concat' allowing for multiple EPI runs is possible in FSL       
     (AFAIK).  So the FSL stimulus time format doesn't allow for       
     this possibility.  In 3dDeconvolve, you can get around this       
     problem by using a line consisting of '* * *' to indicate the     
     break between runs, as in the example below:                      
         1 2 3                                                         
         4 5 6                                                         
         * * *                                                         
         7 8 9                                                         
     that indicates 2 runs, the first of which has 2 stimuli and       
     the second of which has just 1 stimulus.  If there is a run       
     that has NO copies of this type of stimulus, then you would       
     use two '* * *' lines in succession.                              
     Of course, a file using the '* * *' construction will NOT be      
     compatible with FSL!                                              
                                                                       
[-stim_times_IM k tname Rmodel]                                        
   Similar, but each separate time in 'tname' will get a separate      
   regressor; 'IM' means 'Individually Modulated' -- that is, each     
   event will get its own amplitude estimated.  Presumably you will    
   collect these many amplitudes afterwards and do some sort of        
   statistics or analysis on them.                                     
 *N.B.: Each time in the 'tname' file will get a separate regressor.   
        If some time is outside the duration of the imaging run(s),    
        or if the response model for that time happens to hit only     
        censored-out data values, then the corresponding regressor     
        will be all zeros.  Normally, 3dDeconvolve will not run        
        if the matrix has any all zero columns.  To carry out the      
        analysis, use the '-allzero_OK' option.  Amplitude estimates   
        for all zero columns will be zero, and should be excluded      
        from any subsequent analysis.  (Probably you should fix the    
        times in the 'tname' file instead of using '-allzero_OK'.)     
                                                                       
[-global_times]                                                        
[-local_times]                                                         
   By default, 3dDeconvolve guesses whether the times in the 'tname'   
   files for the various '-stim_times' options are global times        
   (relative to the start of run #1) or local times (relative to       
   the start of each run).  With one of these options, you can force   
   the times to be considered as global or local for '-stim_times'     
   options that are AFTER the '-local_times' or '-global_times'.       
 ** Using one of these options (most commonly, '-local_times') is      
    VERY highly recommended.                                           
                                                                       
[-stim_times_millisec]                                                 
 This option scales all the times in any '-stim_times_*' option by     
 0.001; the purpose is to allow you to input the times in ms instead   
 of in s.  This factor will be applied to ALL '-stim_times' inputs,    
 before or after this option on the command line.  This factor will    
 be applied before -stim_times_subtract, so the subtraction value      
 (if present) must be given in seconds, NOT milliseconds!              
                                                                       
[-stim_times_subtract SS]                                              
 This option means to subtract 'SS' seconds from each time encountered 
 in any '-stim_times*' option.  The purpose of this option is to make  
 it simple to adjust timing files for the removal of images from the   
 start of each imaging run.  Note that this option will be useful      
 only if both of the following are true:                               
  (a) each imaging run has exactly the same number of images removed   
  (b) the times in the 'tname' files were not already adjusted for     
      these image removal (i.e., the times refer to the image runs     
      as acquired, not as input to 3dDeconvolve).                      
 In other words, use this option with understanding and care!          
 ** Note that the subtraction of 'SS' applies to ALL '-stim_times'     
    inputs, before or after this option on the command line!           
 ** And it applies to global times and local times alike!              
 ** Any time (thus subtracted) below 0 will be ignored, as falling     
    before the start of the imaging run.                               
 ** This option, and the previous one, are simply for convenience, to  
    help you in setting up your '-stim_times*' timing files from       
    whatever source you get them.                                      
                                                                       
[-basis_normall a]                                                     
   Normalize all basis functions for '-stim_times' to have             
   amplitude 'a' (must have a > 0).  The peak absolute value           
   of each basis function will be scaled to be 'a'.                    
   NOTES:                                                              
    * -basis_normall only affect -stim_times options that              
        appear LATER on the command line                               
    * The main use for this option is for use with the                 
        'EXPR' basis functions.                                        
                                                                       
******* General linear test (GLT) options *******                      
                                                                       
-num_glt num         num = number of general linear tests (GLTs)       
                       (0 <= num)   [default: num = 0]                 
                  **N.B.: You only need this option if you have        
                          more than 10 GLTs specified; the program     
                          has built-in space for 10 GLTs, and          
                          this option is used to expand that space.    
                          If you use this option, you should place     
                          it on the command line BEFORE any of the     
                          other GLT options.                           
[-glt s gltname]     Perform s simultaneous linear tests, as specified 
                       by the matrix contained in file 'gltname'       
[-glt_label k glabel]  glabel = label for kth general linear test      
[-gltsym gltname]    Read the GLT with symbolic names from the file    
                       'gltname'; see the document below for details:  
  https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/DeconSummer2004.html
                                                                       
******* Options to create 3D+time datasets *******                     
                                                                       
[-iresp k iprefix]   iprefix = prefix of 3D+time output dataset which  
                       will contain the kth estimated impulse response 
[-tshift]            Use cubic spline interpolation to time shift the  
                       estimated impulse response function, in order to
                       correct for differences in slice acquisition    
                       times. Note that this effects only the 3D+time  
                       output dataset generated by the -iresp option.  
             **N.B.: This option only applies to the 'old' style of    
                     deconvolution analysis.  Do not use this with     
                     -stim_times analyses!                             
[-sresp k sprefix]   sprefix = prefix of 3D+time output dataset which  
                       will contain the standard deviations of the     
                       kth impulse response function parameters        
[-fitts  fprefix]    fprefix = prefix of 3D+time output dataset which  
                       will contain the (full model) time series fit   
                       to the input data                               
[-errts  eprefix]    eprefix = prefix of 3D+time output dataset which  
                       will contain the residual error time series     
                       from the full model fit to the input data       
[-TR_times dt]                                                         
   Use 'dt' as the stepsize for output of -iresp and -sresp file       
   for response models generated by '-stim_times' options.             
   Default is same as time spacing in the '-input' 3D+time dataset.    
   The units here are in seconds!                                      
                                                                       
**** Options to control the contents of the output bucket dataset **** 
                                                                       
[-fout]            Flag to output the F-statistics for each stimulus   
                    ** F tests the null hypothesis that each and every 
                       beta coefficient in the stimulus set is zero    
                    ** If there is only 1 stimulus class, then its     
                       '-fout' value is redundant with the Full_Fstat  
                       computed for all stimulus coefficients together.
[-rout]            Flag to output the R^2 statistics                   
[-tout]            Flag to output the t-statistics                     
                    ** t tests a single beta coefficient against zero  
                    ** If a stimulus class has only one regressor, then
                       F = t^2 and the F statistic is redundant with t.
[-vout]            Flag to output the sample variance (MSE) map        
[-nobout]          Flag to suppress output of baseline coefficients    
                     (and associated statistics) [** DEFAULT **]       
[-bout]            Flag to turn on output of baseline coefs and stats. 
                    ** Will make the output dataset larger.            
[-nocout]          Flag to suppress output of regression coefficients  
                     (and associated statistics)                       
                    ** Useful if you just want GLT results.            
[-full_first]      Flag to specify that the full model statistics will 
                     be first in the bucket dataset [** DEFAULT **]    
[-nofull_first]    Flag to specify that full model statistics go last  
[-nofullf_atall]   Flag to turn off the full model F statistic         
                     ** DEFAULT: the full F is always computed, even if
                     sub-model partial F's are not ordered with -fout. 
[-bucket bprefix]  Create one AFNI 'bucket' dataset containing various 
                     parameters of interest, such as the estimated IRF 
                     coefficients, and full model fit statistics.      
                     Output 'bucket' dataset is written to bprefix.    
[-nobucket]        Don't output a bucket dataset.  By default, the     
                     program uses '-bucket Decon' if you don't give    
                     either -bucket or -nobucket on the command line.  
[-noFDR]           Don't compute the statistic-vs-FDR curves for the   
                     bucket dataset.                                   
                     [same as 'setenv AFNI_AUTOMATIC_FDR NO']          
                                                                       
[-xsave]           Flag to save X matrix into file bprefix.xsave       
                     (only works if -bucket option is also given)      
[-noxsave]         Don't save X matrix [this is the default]           
[-cbucket cprefix] Save the regression coefficients (no statistics)    
                     into a dataset named 'cprefix'.  This dataset     
                     will be used in a -xrestore run instead of the    
                     bucket dataset, if possible.                      
                ** Also, the -cbucket and -x1D output can be combined  
                     in 3dSynthesize to produce 3D+time datasets that  
                     are derived from subsets of the regression model  
                     [generalizing the -fitts option, which produces]  
                     [a 3D+time dataset derived from the full model].  
                                                                       
[-xrestore f.xsave] Restore the X matrix, etc. from a previous run     
                     that was saved into file 'f.xsave'.  You can      
                     then carry out new -glt tests.  When -xrestore    
                     is used, most other command line options are      
                     ignored.                                          
                                                                       
[-float]            Write output datasets in float format, instead of  
                    as scaled shorts [** now the default **]           
[-short]            Write output as scaled shorts [no longer default]  
                                                                       
***** The following options control miscellaneous outputs *****         
                                                                       
[-quiet]             Flag to suppress most screen output               
[-xout]              Flag to write X and inv(X'X) matrices to screen   
[-xjpeg filename]    Write a JPEG file graphing the X matrix           
                     * If filename ends in '.png', a PNG file is output
[-x1D filename]      Save X matrix to a .xmat.1D (ASCII) file [default]
                    ** If 'filename' is 'stdout:', the file is written 
                       to standard output, and could be piped into     
                       1dplot (some examples are given earlier).       
                     * This can be used for quick checks to see if your
                       inputs are setting up a 'reasonable' matrix.    
[-nox1D]             Don't save X matrix [a very bad idea]             
[-x1D_uncensored ff] Save X matrix to a .xmat.1D file, but WITHOUT     
                     ANY CENSORING.  Might be useful in 3dSynthesize.  
[-x1D_regcensored f] Save X matrix to a .xmat.1D file with the         
                     censoring imposed by adding 0-1 columns instead   
                     excising the censored rows.                       
[-x1D_stop]          Stop running after writing .xmat.1D files.        
                     * Useful for testing, or if you are going to      
                       run 3dREMLfit instead -- that is, you are just  
                       using 3dDeconvolve to set up the matrix file.   
[-progress n]        Write statistical results for every nth voxel     
                     * To let you know that something is happening!    
[-fdisp fval]        Write statistical results to the screen, for those
                       voxels whose full model F-statistic is > fval   
[-help]              Oh go ahead, try it!                              

**** Multiple CPU option (local CPUs only, no networking) ****

 -jobs J   Run the program with 'J' jobs (sub-processes).
             On a multi-CPU machine, this can speed the
             program up considerably.  On a single CPU
             machine, using this option would be silly.
         * J should be a number from 1 up to the
             number of CPUs sharing memory on the system.
         * J=1 is normal (single process) operation.
         * The maximum allowed value of J is 32.
         * Unlike other parallelized AFNI programs, this one
             does not use OpenMP; it directly uses fork()
             and shared memory to run multiple processes.
         * For more information on parallelizing, see
           https://afni.nimh.nih.gov/afni/doc/misc/afni_parallelize
         * Also use -mask or -automask to get more speed; cf. 3dAutomask.

-virtvec   To save memory, write the input dataset to a temporary file
           and then read data vectors from it only as needed.  This option
           is for Javier and will probably not be useful for anyone else.
           And it only takes effect if -jobs is greater than 1.

** NOTE **
This version of the program has been compiled to use
double precision arithmetic for most internal calculations.

++ Compile date = Dec  6 2024 {AFNI_24.3.08:linux_ubuntu_24_64}


This page auto-generated on Fri Dec 6 08:37:58 PM EST 2024