AFNI program: 3dMEPFM

Output of -help


  Usage: 3dMEPFM [options]
  ------

  Brief summary:
  ==============
  * 3dMEPFM is the equivalent program to 3dPFM for Multiecho fMRI data. This program 
    performs the voxelwise deconvolution of ME-fMRI data to yield time-varying estimates 
    of the changes in the transverse relaxation (DR2*) and, optionally, the net magnetization
    (DS0) assuming a mono-exponential decay model of the signal, i.e. linear dependence of
    the BOLD signal on the echo time (TE).

  * It is also recommended to read the help of 3dPFM to understand its functionality.
  
  * The ideas behind 3dMEPFM are described in the following papers:
      
   - For a comprehensive description of the algorithm, based on a model that
     only considers fluctuations in R2* (DR2*) and thus only estimates DR2*
     (i.e. this model is selected with option -R2only), see:

        C Caballero-Gaudes, S Moia, P. Panwar, PA Bandettini, J Gonzalez-Castillo
        A deconvolution algorithm for multiecho functional MRI: Multiecho Sparse Paradigm Free Mapping
        (submitted to Neuroimage)

   - For a model that considers both fluctuations in the net magnetization (DS0) and R2*,
     but only imposes a regularization term on DR2* (setting -rho 0 and without -R2only), 
     see

        C Caballero-Gaudes, PA Bandettini, J Gonzalez-Castillo
        A temporal deconvolution algorithm for multiecho functional MRI
        2018 IEEE 15th International Symposium on Biomedical Imaging (ISBI 2018)
        https://ieeexplore.ieee.org/document/8363649
     
   - For a model that considers both fluctuations in the net magnetization (DS0) and R2*,
     and imposes regularization terms on DR2* and DS0 (i.e. setting rho > 0, and without -R2only),
     see

     The results of this paper were obtained with rho = 0.5
        
        C Caballero-Gaudes, S. Moia, PA Bandettini, J Gonzalez-Castillo
        Quantitative deconvolution of fMRI data with Multi-echo Sparse Paradigm Free Mapping
        Medical Image Computing and Computer Assisted Intervention (MICCAI 2018)
        Lecture Notes in Computer Science, vol. 11072. Springer
        https://doi.org/10.1007/978-3-030-00931-1_36
    
  * IMPORTANT. This program is written in R. Please follow the guidelines in

        http://afni.nimh.nih.gov/sscc/gangc/Rinstall.html

    to install R and make AFNI compatible with R. Particularly, the "snow" library 
    must be installed for parallelization across CPU nodes. 

       install.packages("snow",dependencies=TRUE)

    In addition, you need to install the following libraries with dependencies:

       install.packages("abind",dependencies=TRUE)
       install.packages("lars",dependencies=TRUE)
       install.packages("wavethresh",dependencies=TRUE)

    Also, if you want to run the program with the options "rho > 0", you must install
    the R package of the generalized lasso (https://projecteuclid.org/euclid.aos/1304514656)  
    This package was removed from CRAN repository, but the source code is available in:

       https://github.com/glmgen/genlasso
  

  Example usage with a dataset with 3 echoes:
  -----------------------------------------------------------------------------
  3dMEPFM  -input data_TE1.nii 0.015      
           -input data_TE2.nii 0.030      
           -input data_TE3.nii 0.045      
           -mask mask.nii                 
           -criteria bic                  
           -hrf SPMG1                     
           -jobs 1                        

  

Options:
--------

   -input DSET TE                       
      DSET: Dataset to analyze with Multiecho Paradigm Free Mapping.      
      and the corresponding TE. DSET can be any of the formats available  
      in AFNI, e.g: -input Data+orig                                      
      TE: echo time of dataset in seconds                                 
      Also .1D files where each column is a voxel timecourse.             
      If an .1D file is input, you MUST specify the TR with option -TR.   

   -dbgArgs: This option will enable R to save the parameters in a
         file called .3dMEPFM.dbg.AFNI.args in the current directory
          so that debugging can be performed.

   -mask MASK: Process voxels inside this mask only. Default is no masking. 

   -penalty PEN:  Regularization term (a.k.a. penalty) for DR2 & DS0        
      * Available options for PEN are:                                    
          lasso:            LASSO (i.e. L1-norm)                          
      * If you are interested in other penalties (e.g. ridge regression,  
        fused lasso, elastic net), contact c.caballero@bcbl.eu            

   -criteria CRIT:  Model selection of the regularization parameter.        
      * Available options are:                                            
          bic:  Bayesian Information Criterion (default)                  
          aic:  Akaike Information Criterion                              
          mad:  Regularization parameter is selected as the iteration     
                that makes the standard deviation of the residuals to be  
                larger than factor_MAD * sigma_MAD, where sigma_MAD is    
                 the MAD estimate of the noise standard deviation         
                 (after wavelet decomposition of the echo signals)        
          mad2: Regularization parameter is selected so that              
                 the standard deviation of the residuals is the closest   
                 to factor_MAD*sigma_MAD.                                 
      * If you want other options, contact c.caballero@bcbl.eu            

   -maxiterfactor MaxIterFactor (between 0 and 1):                          
      * Maximum number of iterations for the computation of the           
        regularization path will be 2*MaxIerFactor*nscans                 
      * Default value is MaxIterFactor = 1                                

   -TR tr:  Repetition time or sampling period of the input data            
      * It is required for the generation of the deconvolution HRF model. 
      * If input datasets are .1D file, TR must be specified in seconds.  
        If TR is not given, the program will STOP.                        
      * If input datasets are 3D+time volumes and TR is NOT given,        
        the value of TR is taken from the dataset header.                 
      * If TR is specified and it is different from the TR in the header  
        of the input datasets, the program will STOP.                     

   -hrf fhrf:   haemodynamic response function used for deconvolution       
      *  fhrf can be any of the HRF models available in 3dDeconvolve.     
      http://afni.nimh.nih.gov/pub/dist/doc/program_help/3dDeconvolve.html
      i.e. 3dMEPFM calls 3dDeconvolve with options -x1D_stop & -nodata    
      to create the HRF with onset at 0 (i.e. -stim_time 1 '1D:0' fhrf )  
      *  [Default] fhrf == 'GAM', the 1 parameter gamma variate  
                      (t/(p*q))^p * exp(p-t/q)                            
                     with 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.3*sqrt(p)*q.      
      *  Another option is fhrf == 'SPMG1', the SPM canonical HRF.        
      *  If fhrf is a .1D, the program will use it as the HRF model.      
             ** It should be generated with the same TR as the input data 
                to get sensible results (i.e. know what you are doing).   
             ** fhrf must be column or row vector, i.e. only 1 hrf allowed.
      * The HRF is normalized to maximum absolute amplitude equal to 1.   

   -R2only:                                                                 
      * If this option is given, the model will only consider R2* changes 
        and do not estimate S0 changes.                                   

   -rho:    0 <= rho <= 1 (default 0):                                      
      * Parameter that balances the penalization of the DS0 (rho) and     
        DR2star (1-rho) coefficients.                                     
      * Default is rho = 0, i.e. no penalization of DS0 coefficients.     
      * It becomes irrelevant with -R2only option.                        

   -factor_min_lambda  value >= 0      (default factor_min_lambda = 0.1):   
      * Stop the computation of the regularization path when              
        lambda <= factor_min_lambda*sigma_MAD, where sigma_MAD is the     
         estimate of the standard deviation of the noise (computed after  
         wavelet decomposition). It must be equal to or larger than 0.    

   -factor_MAD        (default factor_MAD = 1):                             
      *  For criteria 'mad', select lambda so that the standard deviation 
         of residuals is approximately equal to factor_MAD*sigma_MAD      

   -debias_TEopt: 0 <= debias_TEopt <= number of input datasets             
      * For debiasing, only consider the 'debias_TEopt' input dataset,    
        i.e. if debias_TEopt=2, the dataset corresponding to the second   
        TE will be used for debiasing. This option is available in case   
        you really know that one of the echoes is the 'optimal' TE  ...   
        As if this information was easy to know and match :)              
      * Default is debias_TEopt = 0, i.e. all echoes will be considered.  
      * This option is not recommended unless you understand it,          
        (i.e. use at your own risk)                                       

   -do_prior_debias:                                                        
      * If this option is given, the algorithm will perform debiasing     
        before the selection of the regularization parameter.             
      * This option is not recommended unless you understand it,          
        (i.e. use at your own risk)                                       

   -n_selection_Nscans:                                                     
      * The equation for model selection for selection of regularization  
        parameter with the 'bic' and 'aic' criteria depends on the number 
        of observations (i.e. number of scans * number of echoes)         
      * If -n_selection_Nscans is given, the formula will assume that     
        the number of observations is the number of scans. This is        
        mathematically wrong, but who cares if it gives better results!!  
      * This option is not recommended unless you understand it,          
        (i.e. use at your own risk)                                       

   -prefix                                                                  
      * The names of the output volumes will be generated automatically   
        as outputname_prefix_input, e.g. if -input = TheEmperor+orig,     
        and prefix is Zhark, the names of the DR2 output volumes is       
              DR2_Zhark_TheEmperor+orig for  volume                       
        whereas if prefix is not given, the output will be                
              DR2_TheEmperor+orig.                                        
      * The program will automatically save the following volumes:        
        -DR2      Changes in R2* parameter, which is assumed to           
                  represent neuronal-related signal changes.              
        -DR2fit   Convolution of DR2 with HRF, i.e. neuronal-related      
                  haemodynamic signal. One volume per echo is created.    
        -DS0      Changes in net magnetization (S0) (if estimated)        
        -lambda   Regularization parameter                                
        -sigmas_MAD  Estimate of the noise standard deviation after       
                    wavelet decomposition for each input dataset          
        -costs      Cost function to select the regularization parameter  
                    (lambda) according to selection criterion             
      * If you don't want to delete or rename anyone, you can always      
        delete them later or rename them with 3dcopy.                     

   -jobs NJOBS: On a multi-processor machine, parallel computing will       
              speed up the program significantly.                         
              Choose 1 for a single-processor computer (DEFAULT).         

   -nSeg XX: Divide into nSeg segments of voxels to report progress,        
           e.g. nSeg 5 will report every 20% of processed voxels.         
           Default = 10                                                   

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

   -help: this help message

   -show_allowed_options: list of allowed options
This page auto-generated on Thu Apr 18 14:45:45 EDT 2024