AFNI program: 3dNLfim

Program:          3dNLfim 
Author:           B. Douglas Ward 
Initial Release:  19 June 1997 
Latest Revision:  07 May 2003 

This program calculates a nonlinear regression for each voxel of the  
input AFNI 3d+time data set.  The nonlinear regression is calculated  
by means of a least squares fit to the signal plus noise models which 
are specified by the user.                                            
                                                                      
Usage:                                                                
3dNLfim                                                               
-input fname       fname = filename of 3d + time data file for input  
[-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)  [default = use all voxels] 
[-ignore num]      num   = skip this number of initial images in the  
                     time series for regresion analysis; default = 3  
[-inTR]            set delt = TR of the input 3d+time dataset         
                     [The default is to compute with delt = 1.0 ]     
                     [The model functions are calculated using a      
                      time grid of: 0, delt, 2*delt, 3*delt, ... ]    
[-time fname]      fname = ASCII file containing each time point      
                     in the time series. Defaults to even spacing     
                     given by TR (this option overrides -inTR).       
-signal slabel     slabel = name of (non-linear) signal model         
-noise  nlabel     nlabel = name of (linear) noise model              
-sconstr k c d     constraints for kth signal parameter:              
                      c <= gs[k] <= d                                 
-nconstr k c d     constraints for kth noise parameter:               
                      c+b[k] <= gn[k] <= d+b[k]                       
[-nabs]            use absolute constraints for noise parameters:     
                      c <= gn[k] <= d                                 
[-nrand n]         n = number of random test points                   
[-nbest b]         b = find opt. soln. for b best test points         
[-rmsmin r]        r = minimum rms error to reject reduced model      
[-fdisp fval]      display (to screen) results for those voxels       
                     whose f-statistic is > fval                      
                                                                      
                                                                      
The following commands generate individual AFNI 2 sub-brick datasets: 
                                                                      
[-freg fname]      perform f-test for significance of the regression; 
                     output 'fift' is written to prefix filename fname
[-frsqr fname]     calculate R^2 (coef. of multiple determination);   
                     store along with f-test for regression;          
                     output 'fift' is written to prefix filename fname
[-fsmax fname]     estimate signed maximum of signal; store along     
                     with f-test for regression; output 'fift' is     
                     written to prefix filename fname                 
[-ftmax fname]     estimate time of signed maximum; store along       
                     with f-test for regression; output 'fift' is     
                     written to prefix filename fname                 
[-fpsmax fname]    calculate (signed) maximum percentage change of    
                     signal from baseline; output 'fift' is           
                     written to prefix filename fname                 
[-farea fname]     calculate area between signal and baseline; store  
                     with f-test for regression; output 'fift' is     
                     written to prefix filename fname                 
[-fparea fname]    percentage area of signal relative to baseline;    
                     store with f-test for regression; output 'fift'  
                     is written to prefix filename fname              
[-fscoef k fname]  estimate kth signal parameter gs[k]; store along   
                     with f-test for regression; output 'fift' is     
                     written to prefix filename fname                 
[-fncoef k fname]  estimate kth noise parameter gn[k]; store along    
                     with f-test for regression; output 'fift' is     
                     written to prefix filename fname                 
[-tscoef k fname]  perform t-test for significance of the kth signal  
                     parameter gs[k]; output 'fitt' is written        
                     to prefix filename fname                         
[-tncoef k fname]  perform t-test for significance of the kth noise   
                     parameter gn[k]; output 'fitt' is written        
                     to prefix filename fname                         
                                                                      
                                                                      
The following commands generate one AFNI 'bucket' type dataset:       
                                                                      
[-bucket n prefixname]   create one AFNI 'bucket' dataset containing  
                           n sub-bricks; n=0 creates default output;  
                           output 'bucket' is written to prefixname   
The mth sub-brick will contain:                                       
[-brick m scoef k label]   kth signal parameter regression coefficient
[-brick m ncoef k label]   kth noise parameter regression coefficient 
[-brick m tmax label]      time at max. abs. value of signal          
[-brick m smax label]      signed max. value of signal                
[-brick m psmax label]     signed max. value of signal as percent     
                             above baseline level                     
[-brick m area label]      area between signal and baseline           
[-brick m parea label]     signed area between signal and baseline    
                             as percent of baseline area              
[-brick m tscoef k label]  t-stat for kth signal parameter coefficient
[-brick m tncoef k label]  t-stat for kth noise parameter coefficient 
[-brick m resid label]     std. dev. of the full model fit residuals  
[-brick m rsqr  label]     R^2 (coefficient of multiple determination)
[-brick m fstat label]     F-stat for significance of the regression  
                                                                      
                                                                      
The following commands write the time series fit for each voxel       
to an AFNI 3d+time dataset:                                           
[-sfit fname]      fname = prefix for output 3d+time signal model fit 
[-snfit fname]     fname = prefix for output 3d+time signal+noise fit 
                                                                      

 -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 is silly.
             J should be a number from 1 up to the
             number of CPU sharing memory on the system.
             J=1 is normal (single process) operation.
             The maximum allowed value of J is 32.
         * For more information on parallelizing, see
             http://afni.nimh.nih.gov/afni/doc/misc/parallize.html
         * Use -mask to get more speed; cf. 3dAutomask.