3dMEPFM


  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 proccesed 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