# 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 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
```