AFNI program: 3dDeconvolve
Output of -help
++ 3dDeconvolve: AFNI version=AFNI_2008_07_18_1710 (Jan 29 2009) [32-bit]
++ Authored by: B. Douglas Ward, et al.
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.
The program can optionally output extra datasets containing
* the estimated impulse response function
* the fitted model and error (residual) time series
------------------------------------------------------------------------
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),
S(t) = stimulus
baseline = constant, drift, etc.
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. 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 the deconvolution
problem (in either direction) with L1 or L2 regression, with sign
constraints on the computed values.
------------------------------------------------------------------------
Usage:
3dDeconvolve
**** 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)
(catenated in time; if you do this, )
('-concat' is not needed and is ignored)
[-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
[-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)
[-mask mname] mname = filename of 3d mask dataset
[-automask] build a mask automatically from input data
(will be slow for long time series datasets)
[-censor cname] cname = filename of censor .1D time series
[-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
[-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)
If you use 'A' for pnum, the program will
automatically choose a value.
[-legendre] use Legendre polynomials for null hypothesis
[-nolegendre] use power polynomials for null hypotheses
(default is -legendre)
[-nodmbase] don't de-mean baseline time series
(i.e., polort>1 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
[-rmsmin r] r = minimum rms error to reject reduced model
[-nocond] DON'T calculate matrix condition number
** This is NOT the same as Matlab!
[-singvals] Print out the matrix singular values
[-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.
*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.
[-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)
-stim_file k sname sname = filename of kth time series input stimulus
[-stim_label k slabel] slabel = label for kth input stimulus
[-stim_base k] kth input stimulus is part of the baseline model
[-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)
[-stim_times k tname Rmodel]
Generate the k-th response model from a set of stimulus times
given in file 'tname'. The response model is specified by the
'Rmodel' argument, which can be one of
'GAM(p,q)' = 1 parameter gamma variate
= (t/(p*q))^p * exp(p-t/q)
'SPMG' = 2 parameter SPM gamma variate + derivative
'SPMG3' = 3 parameter SPM basis function set
'POLY(b,c,n)' = n parameter Legendre polynomial expansion
from times b..c after stimulus time
[Max value of n is 20]
'SIN(b,c,n)' = n parameter sine series expansion
from times b..c after stimulus time
'TENT(b,c,n)' = n parameter tent function expansion
from times b..c after stimulus time
'CSPLIN(b,c,n)'= n parameter cubic spline function expansion
from times b..c after stimulus time
'BLOCK(d,p)' = 1 parameter block stimulus of duration 'd'
(can also be called 'IGFUN' which stands)
(for 'incomplete gamma function' )
** 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.
'EXPR(b,c) exp1 ... expn' = n parameter; arbitrary expressions
from times b..c after stimulus time
For the format of the 'tname' file, see the last part of
http://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/DeconSummer2004.html
and also see the other documents stored in the directory below:
http://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/
and also read the presentation below:
http://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.
* 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!
[-stim_times_AM1 k tname Rmodel]
Similar, but generates an amplitude modulated response model.
The 'tname' file should consist of 'time*amplitude' pairs.
[-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.
** 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.
For more information, see
http://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 parameters 5 and 3,
and with duration 12 s.
The unmodulated peak response of dmBLOCK is set to 1.
*N.B.: the maximum allowed dmBLOCK duration is 999 s.
*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.
For some graphs of what dmBLOCK regressors look like, see
http://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/AMregression.pdf
[-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(s). Presumably you will collect
these many amplitudes afterwards and do some sort of statistics
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'.
[-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'.
NOTE: -basis_normall only affect -stim_times options that
appear LATER on the command line
**** 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
[-TR_irc dt]
Use 'dt' as the stepsize for computation of integrals in -IRC_times
options. Default is to use value given in '-TR_times'.
**** Options for output 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.
[-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
[-rout] Flag to output the R^2 statistics
[-tout] Flag to output the t-statistics
[-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.
[-nocout] Flag to suppress output of regression coefficients
(and associated statistics)
[-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.
[-short] Write output as scaled shorts [default, for now]
**** The following options control the screen output only:
[-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]
[-nox1D] Don't save X matrix
[-x1D_uncensored ff Save X matrix to a .xmat.1D file, but WITHOUT
ANY CENSORING. Might be useful in 3dSynthesize.
[-x1D_stop] Stop running after writing .xmat.1D files.
[-progress n] Write statistical results for every nth voxel
[-fdisp fval] Write statistical results for those voxels
whose full model F-statistic is > fval
-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 CPUs 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/afni_parallelize
* Use -mask to get more speed; cf. 3dAutomask.
** NOTE **
This version of the program has been compiled to use
double precision arithmetic for most internal calculations.
++ Compile date = Jan 29 2009
This page auto-generated on
Fri Jan 30 20:02:20 EST 2009