------------------------------------------------------------------------
----- DESCRIPTION and PROLEGOMENON -----
------------------------------------------------------------------------
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 model
The program can optionally output extra datasets containing
* the estimated impulse response function
* the fitted model and error (residual) time series
------------------------------------------------------------------------
* Program 3dDeconvolve does Ordinary Least Squares (OLSQ) regression.
* Program 3dREMLfit can be used to do Generalized Least Squares (GLSQ)
regression (AKA 'pre-whitened' least squares) combined with REML
estimation of an ARMA(1,1) temporal correlation structure:
https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dREMLfit.html
* The input to 3dREMLfit is the .xmat.1D matrix file output by
3dDeconvolve, which also writes a 3dREMLfit command line to a file
to make it relatively easy to use the latter program.
* 3dREMLfit also allows for voxel-specific regressors, unlike
3dDeconvolve. This feature is used with the '-fanaticor' option
to afni_proc.py, for example.
* Nonlinear time series model fitting can be done with program 3dNLfim:
https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dNLfim.html
* Preprocessing of the time series input can be done with various AFNI
programs, or with the 'uber-script' afni_proc.py:
https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html
------------------------------------------------------------------------
------------------------------------------------------------------------
**** The recommended way to use 3dDeconvolve is via afni_proc.py, ****
**** which will pre-process the data, and also provide some useful ****
**** diagnostic tools/outputs for assessing the data's quality. ****
**** It can also run 3dREMLfit for you 'at no extra charge'. ****
**** [However, it will not wax your car or wash your windows.] ****
------------------------------------------------------------------------
------------------------------------------------------------------------
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 or HRF)
S(t) = stimulus time series
baseline = constant, drift, etc. [regressors of no interest]
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 with the '-FALTUNG' option. 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
a deconvolution problem (in either direction) with L1 or L2 regression,
and with sign constraints on the computed values (e.g., requiring that
the output S(t) or K(t) be non-negative):
https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dTfitter.html
------------------------------------------------------------------------
The 'baseline model' in 3dDeconvolve (and 3dREMLfit) does not mean just
a constant (mean) level of the signal, or even just the slow drifts that
happen in FMRI time series. 'Baseline' here also means the model that
forms the null hypothesis. The Full_Fstat result is the F-statistic
of the full model (all regressors) vs. the baseline model. Thus, it
it common to include irregular time series, such as estimated motion
parameters, in the baseline model via the -stim_file/-stim_base options,
or by using the -ortvec option (to include multiple regressors at once).
Thus, the 'baseline model' is really the 'null hypothesis model'.
------------------------------------------------------------------------
It is VERY important to realize that statistics (F, t, R^2) computed in
3dDeconvolve are MARGINAL (or partial) statistics. For example, the
t-statistic for a single beta coefficient measures the significance of
that beta value against the regression model where ONLY that one column
of the matrix is removed; that is, the null hypothesis for that
t-statistic is the full regression model minus just that single
regressor. Similarly, the F-statistic for a set of regressors measures
the significance of that set of regressors (eg, a set of TENT functions)
against the full model with just that set of regressors removed. If
this explanation or its consequences are unclear, you need to consult
with a statistician, or with the AFNI message board guru entities
(when they can be lured down from the peak of Mt Taniquetil or Kailash).
------------------------------------------------------------------------
Regression Programs in the AFNI Package:
* At its core, 3dDeconvolve solves a linear regression problem z = X b
for the parameter vector b, given the data vector z in each voxel, and
given the SAME matrix X in each voxel. The solution is calculated in
the Ordinary Least Squares (OLSQ) sense.
* Program 3dREMLfit does something similar, but allows for ARMA(1,1)
serial correlation in the data, so the solution method is called
Generalized Least Squares (GLSQ).
* If you want to solve a problem where some of the matrix columns in X
(the regressors) are different in different voxels (spatially variable),
then use program 3dTfitter, which uses OLSQ, or used 3dREMLfit.
* 3dTfitter can also use L1 and LASSO regression, instead of OLSQ; if you
want to use such 'robust' fitting methods, this program is your friend.
It can also impose sign constraints (positivity or negativity) on the
parameters b, and can (as mentioned above) do deconvolution.
* 3dBandpass and 3dTproject can do a sequence of 'time series cleanup'
operations, including 'regressing out' (via OLSQ) a set of nuisance
vectors (columns).
* 3dLSS can be used to solve -stim_times_IM systems using an alternative
linear technique that gives biased results, but with smaller variance.
------------------------------------------------------------------------
Usage Details:
3dDeconvolve command-line-arguments ...
**** 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]
[auto-catenated in time; if you do this,]
['-concat' is not needed and is ignored.]
**** You can input a 1D time series file here,
but the time axis should run along the
ROW direction, not the COLUMN direction as
in the -input1D option. You can automatically
transpose a 1D file on input using the \'
operator at the end of the filename, as in
-input fred.1D\'
** This is the only way to use 3dDeconvolve
with a multi-column 1D time series file.
* The output datasets by default will then
be in 1D format themselves. To have them
formatted as AFNI datasets instead, use
-DAFNI_WRITE_1D_AS_PREFIX=YES
on the command line.
* You should use '-force_TR' to set the TR of
the 1D 'dataset' if you use '-input' rather
than '-input1D' [the default is 1.0 sec].
-sat OR -trans * 3dDeconvolve can check the dataset time series
for initial saturation transients, which should
normally have been excised before data analysis.
(Or should be censored out: see '-censor' below.)
If you want to have it do this somewhat time
consuming check, use the option '-sat'.
* Or set environment variable AFNI_SKIP_SATCHECK to NO.
* Program 3dSatCheck does this check, also.
[-noblock] Normally, if you input multiple datasets with
'-input', then the separate datasets are taken to
be separate image runs that get separate baseline
models. If you want to have the program consider
these to be all one big run, use -noblock.
* If any of the input datasets has only 1 sub-brick,
then this option is automatically invoked!
* If the auto-catenation feature isn't used, then
this option has no effect, no how, no way.
[-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
where time run downs the column.
* If you want to analyze multiple columns from a
.1D file, see the '-input' option above for
the technique.
[-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)
* Optional, but highly recommended: follow the
'-nodata' with two numbers, NT=number of time
points, and TR=time spacing between points (sec)
[-mask mname] mname = filename of 3D mask dataset
Only data time series from within the mask
will be analyzed; results for voxels outside
the mask will be set to zero.
[-automask] Build a mask automatically from input data
(will be slow for long time series datasets)
** If you don't specify ANY mask, the program will
build one automatically (from each voxel's RMS)
and use this mask solely for the purpose of
reporting truncation-to-short errors (if '-short'
is used) AND for computing the FDR curves in the
bucket dataset's header (unless '-noFDR' is used,
of course).
* If you don't want the FDR curves to be computed
inside this automatically generated mask, then
use '-noFDR' and later run '3drefit -addFDR' on
the bucket dataset.
* To be precise, the above default masking only
happens when you use '-input' to run the program
with a 3D+time dataset; not with '-input1D'.
[-STATmask sname] Build a mask from file 'sname', and use this
mask for the purpose of reporting truncation-to
float issues AND for computing the FDR curves.
The actual results ARE not masked with this
option (only with '-mask' or '-automask' options)
* If you don't use '-STATmask', then the mask
from '-mask' or '-automask' is used for these
purposes. If neither of those is given, then
the automatically generated mask described
just above is used for these purposes.
[-censor cname] cname = filename of censor .1D time series
* This is a file of 1s and 0s, indicating which
time points are to be included (1) and which are
to be excluded (0).
* Option '-censor' can only be used once!
* The option below may be simpler to use!
[-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
* 'rname' can be in the format
'1D: 0 100 200 300'
which indicates 4 runs, the first of which
starts at time index=0, second at index=100,
and so on.
[-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]
** For pnum > 2, this type of baseline detrending
is roughly equivalent to a highpass filter
with a cutoff of (p-2)/D Hz, where 'D' is the
duration of the imaging run: D = N*TR
** If you use 'A' for pnum, the program will
automatically choose a value based on the
time duration D of the longest run:
pnum = 1 + int(D/150)
==>>** 3dDeconvolve is the ONLY AFNI program with the
-polort option that allows the use of 'A' to
set the polynomial order automatically!!!
** Use '-1' for pnum to specifically NOT include
any polynomials in the baseline model. Only
do this if you know what this means!
[-legendre] use Legendre polynomials for null hypothesis
(baseline model)
[-nolegendre] use power polynomials for null hypotheses
[default is -legendre]
** Don't do this unless you are crazy!
[-nodmbase] don't de-mean baseline time series
(i.e., polort>0 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
(only use for testing + backwards compatibility)
[-rmsmin r] r = minimum rms error to reject reduced model
(default = 0; don't use this option normally!)
[-nocond] DON'T calculate matrix condition number
** This value is NOT the same as Matlab!
[-singvals] Print out the matrix singular values
(useful for some testing/debugging purposes)
Also see program 1dsvd.
[-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.
++ You can disable the creation of this .err
file by setting environment variable
AFNI_USE_ERROR_FILE to NO before running
this program.
*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.
* Please know what you are doing when you use
this option!
[-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]
*N.B.: '-num_stimts' must come before any of the
following '-stim' options!
*N.B.: Most '-stim' options have as their first argument
an integer 'k', ranging from 1..num, indicating
which stimulus class the argument is defining.
*N.B.: The purpose of requiring this option is to make
sure your model is complete -- that is, you say
you are giving 5 '-stim' options, and then the
program makes sure that all of them are given
-- that is, that you don't forget something.
-stim_file k sname sname = filename of kth time series input stimulus
*N.B.: This option directly inserts a column into the
regression matrix; unless you are using the 'old'
method of deconvolution (cf below), you would
normally only use '-stim_file' to insert baseline
model components such as motion parameters.
[-stim_label k slabel] slabel = label for kth input stimulus
*N.B.: This option is highly recommended, so that
output sub-bricks will be labeled for ease of
recognition when you view them in the AFNI GUI.
[-stim_base k] kth input stimulus is part of the baseline model
*N.B.: 'Baseline model' == Null Hypothesis model
*N.B.: The most common baseline components to add are
the 6 estimated motion parameters from 3dvolreg.
-ortvec fff lll This option lets you input a rectangular array
of 1 or more baseline vectors from file 'fff',
which will get the label 'lll'. Functionally,
it is the same as using '-stim_file' on each
column of 'fff' separately (plus '-stim_base').
This method is just a faster and simpler way to
include a lot of baseline regressors in one step.
-->>**N.B.: This file is NOT included in the '-num_stimts'
count that you provide.
*N.B.: These regression matrix columns appear LAST
in the matrix, after everything else.
*N.B.: You can use column '[..]' and/or row '{..}'
selectors on the filename 'fff' to pick out
a subset of the numbers in that file.
*N.B.: The q-th column of 'fff' will get a label
like 'lll[q]' in the 3dDeconvolve results.
*N.B.: This option is known as the 'Inati Option'.
*N.B.: Unlike the original 'Inati' (who is unique), it
is allowed to have more than one '-ortvec' option.
*N.B.: Program 1dBport is one place to generate a file
for use with '-ortvec'; 1deval might be another.
**N.B.: You must have -num_stimts > 0 AND/OR
You must use -ortvec AND/OR
You must have -polort >= 0
Otherwise, there is no regression model!
An example using -polort only:
3dDeconvolve -x1D_stop -polort A -nodata 300 2 -x1D stdout: | 1dplot -one -stdin
**N.B.: The following 3 options are for the 'old' style of explicit
deconvolution. For most purposes, their usage is no longer
recommended. Instead, you should use the '-stim_times' options
to directly input the stimulus times, rather than code the
stimuli as a sequence of 0s and 1s in this 'old' method!
[-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]
**N.B.: The '-stim_times' options below are the recommended way of
analyzing FMRI time series data now. The options directly
above are only maintained for the sake of backwards
compatibility! For most FMRI users, the 'BLOCK' and 'TENT'
(or 'CSPLIN') response models will serve their needs. The
other models are for users with specific needs who understand
clearly what they are doing.
[-stim_times k tname Rmodel]
Generate the k-th response model from a set of stimulus times
given in file 'tname'.
*** The format of file 'tname' is one line per imaging run
(cf. '-concat' above), and each line contains the list of START
times (in seconds) for the stimuli in class 'k' for its
corresponding run of data; times are relative to the start of
the run (i.e., sub-brick #0 occurring at time=0).
*** The DURATION of the stimulus is encoded in the 'Rmodel'
argument, described below. Units are in seconds, not TRs!
-- If different stimuli in the same class 'k' have different
durations, you'll have to use the dmBLOCK response model
and '-stim_times_AM1' or '-stim_times_AM2', described below.
*** Different lines in the 'tname' file can contain different
numbers of start times. Each line must contain at least 1 time.
*** If there is no stimulus in class 'k' in a particular imaging
run, there are two ways to indicate that:
(a) put a single '*' on the line, or
(b) put a very large number or a negative number
(e.g., 99999, or -1) on the line
-- times outside the range of the imaging run will cause
a warning message, but the program will soldier on.
*** In the case where the stimulus doesn't actually exist in the
data model (e.g., every line in 'tname' is a '*'), you will
also have to use the '-allzero_OK' option to force 3dDeconvolve
to run with regressor matrix columns that are filled with zeros.
The response model is specified by the third argument after
'-stim_times' ('Rmodel'), and can be one of the following:
*** In the descriptions below, a '1 parameter' model has a fixed
shape, and only the estimated amplitude ('Coef') varies:
BLOCK GAM TWOGAM SPMG1 WAV MION
*** Models with more than 1 parameter have multiple basis
functions, and the estimated parameters ('Coef') are their
amplitudes. The estimated shape of the response to a stimulus
will be different in different voxels:
TENT CSPLIN SPMG2 SPMG3 POLY SIN EXPR
*** Many models require the input of the start and stop times for
the response, 'b' and 'c'. Normally, 'b' would be zero, but
in some cases, 'b' could be negative -- for example, if you
are concerned about anticipatory effects. The stop time 'c'
should be based on how long you realistically expect the
hemodynamic response to last after the onset of the stimulus;
e.g., the duration of the stimulus plus 14 seconds for BOLD.
*** If you use '-tout', each parameter will get a separate
t-statistic. As mentioned far above, this is a marginal
statistic, measuring the impact of that model component on the
regression fit, relative to the fit with that one component
(matrix column) removed.
*** If you use '-fout', each stimulus will also get an F-statistic,
which is the collective impact of all the model components
it contains, relative to the regression fit with the entire
stimulus removed. (If there is only 1 parameter, then F = t*t.)
*** Some models below are described in terms of a simple response
function that is then convolved with a square wave whose
duration is a parameter you give (duration is NOT a parameter
that will be estimated). Read the descriptions below carefully:
not all functions are (or can be) convolved in this way:
* ALWAYS convolved: BLOCK dmBLOCK MION MIONN
* OPTIONALLY convolved: GAM TWOGAM SPMGx WAV
* NEVER convolved: TENT CSPLIN POLY SIN EXPR
Convolution is specified by providing the duration parameter
as described below for each particular model function.
'BLOCK(d,p)' = 1 parameter block stimulus of duration 'd'
** 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.
==> ** Despite the name, you can use 'BLOCK' for event-
related analyses just by setting the duration to
a small value; e.g., 'BLOCK5(1,1)'
** The 'p' parameter is the amplitude of the
basis function, and should usually be set to 1.
If 'p' is omitted, the amplitude will depend on
the duration 'd', which is useful only in
special circumstances!!
** For bad historical reasons, the peak amplitude
'BLOCK' without the 'p' parameter does not go to
1 as the duration 'd' gets large. Correcting
this oversight would break some people's lives,
so that's just the way it is.
** The 'UBLOCK' function (U for Unit) is the same
as the 'BLOCK' function except that when the
'p' parameter is missing (or 0), the peak
amplitude goes to 1 as the duration gets large.
If p > 0, 'UBLOCK(d,p)' and 'BLOCK(d,p)' are
identical.
'TENT(b,c,n)' = n parameter tent function expansion from times
b..c after stimulus time [piecewise linear]
[n must be at least 2; time step is (c-b)/(n-1)]
'CSPLIN(b,c,n)'= n parameter cubic spline function expansion
from times b..c after stimulus time
[n must be at least 4]
** CSPLIN is a drop-in upgrade of TENT to a
differentiable set of functions.
** TENT and CSPLIN are 'cardinal' interpolation
functions: their parameters are the values
of the HRF model at the n 'knot' points
b , b+dt , b+2*dt , ... [dt = (c-b)/(n-1)]
In contrast, in a model such as POLY or SIN,
the parameters output are not directly the
hemodynamic response function values at any
particular point.
==> ** You can also use 'TENTzero' and 'CSPLINzero',
which means to eliminate the first and last
basis functions from each set. The effect
of these omissions is to force the deconvolved
HRF to be zero at t=b and t=c (to start and
and end at zero response). With these 'zero'
response models, there are n-2 parameters
(thus for 'TENTzero', n must be at least 3).
** These 'zero' functions will force the HRF to
be continuous, since they will now be unable
to suddenly rise up from 0 at t=b and/or drop
down to 0 at t=c.
'GAM(p,q)' = 1 parameter gamma variate
(t/(p*q))^p * exp(p-t/q)
Defaults: 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.35*sqrt(p)*q;
this approximation is accurate for p > 0.3*q.
** To check this approximation, try the command
1deval -num 100 -del 0.02 -xzero 0.02 \
-expr 'sqrt(gamp(x,1))/2.35/x' | \
1dplot -stdin -del 0.02 -xzero 0.02 -yaxis 1:1.4:4:10
If the two functions gamp(x,1) and 2.35*x
were equal, the plot would be constant y=1.
==> ** If you add a third argument 'd', then the GAM
function is convolved with a square wave of
duration 'd' seconds; for example:
'GAM(8.6,.547,17)'
for a 17 second stimulus. [09 Aug 2010]
'GAMpw(K,W)' = Same as 'GAM(p,q)' but where the shape parameters
are specified at time to peak 'K' and full
width at half max (FWHM) 'W'. You can also
add a third argument as the duration. The (K,W)
parameters are converted to (p,q) values for
the actual computations; the (p,q) parameters
are printed to the text (stderr) output.
** Note that if you give weird values for K and W,
weird things will happen: (tcsh syntax)
set pp = `ccalc 'gamp(2,8)'`
set qq = `ccalc 'gamq(2,8)'`
1deval -p=$pp -q=$qq -num 200 -del 0.1 \
-expr '(t/p/q)^p*exp(p-t/q)' | \
1dplot -stdin -del 0.1
Here, K is significantly smaller than W,
so a gamma variate that fits peak=2 width=8
must be weirdly shaped. [Also note use of the
'calc' functions gamp(K,W) and gamq(K,W) to
calculate p and q from K and W in the script.]
'TWOGAM(p1,q1,r,p2,q2)'
= 1 parameter (amplitude) model:
= A combination of two 'GAM' functions:
GAM(p1,q1) - r*GAM(p2,q2)
This model is intended to let you use a HRF
similar to BrainVoyager (e.g.). You can
add a sixth argument as the duration.
** Note that a positive 'r' parameter means to
subtract the second GAM function (undershoot).
'TWOGAMpw(K1,W1,r,K2,W2)'
= Same as above, but where the peaks and widths
of the 2 component gamma variates are given
instead of the less intuitive p and q.
For FMRI work, K2 > K1 is usual, as the
second (subtracted) function is intended
to model the 'undershoot' after the main
positive part of the model. You can also
add a sixth argument as the duration.
** Example (no duration given):
3dDeconvolve -num_stimts 1 -polort -1 -nodata 81 0.5 \
-stim_times 1 '1D: 0' 'TWOGAMpw(3,6,0.2,10,12)' \
-x1D stdout: | 1dplot -stdin -THICK -del 0.5
'SPMG1' = 1 parameter SPM gamma variate basis function
exp(-t)*(A1*t^P1-A2*t^P2) where
A1 = 0.0083333333 P1 = 5 (main positive lobe)
A2 = 1.274527e-13 P2 = 15 (undershoot part)
This function is NOT normalized to have peak=1!
'SPMG2' = 2 parameter SPM: gamma variate + d/dt derivative
[For backward compatibility: 'SPMG' == 'SPMG2']
'SPMG3' = 3 parameter SPM basis function set
==> ** The SPMGx functions now can take an optional
(duration) argument, specifying that the primal
SPM basis functions should be convolved with
a square wave 'duration' seconds long and then
be normalized to have peak absolute value = 1;
e.g., 'SPMG3(20)' for a 20 second duration with
three basis function. [28 Apr 2009]
** Note that 'SPMG1(0)' will produce the usual
'SPMG1' wavefunction shape, but normalized to
have peak value = 1 (for example).
'POLY(b,c,n)' = n parameter Legendre polynomial expansion
from times b..c after stimulus time
[n can range from 1 (constant) to 20]
'SIN(b,c,n)' = n parameter sine series expansion
from times b..c after stimulus time
[n must be at least 1]
'WAV(d)' = 1 parameter block stimulus of duration 'd'.
* This is the '-WAV' function from program waver!
* If you wish to set the shape parameters of the
WAV function, you can do that by adding extra
arguments, in the order
delay time , rise time , fall time ,
undershoot fraction, undershoot restore time
* The default values are 'WAV(d,2,4,6,0.2,2)'
* Omitted parameters get the default values.
* 'WAV(d,,,,0)' (setting undershoot=0) is
very similar to 'BLOCK5(d,1)', for d > 0.
* Setting duration d to 0 (or just using 'WAV')
gives the pure '-WAV' impulse response function
from waver.
* If d > 0, the WAV(0) function is convolved with
a square wave of duration d to make the HRF,
and the amplitude is scaled back down to 1.
'EXPR(b,c) exp1 ... expn'
= n parameter; arbitrary expressions from times
b..c after stimulus time
* Expressions are separated by spaces, so
each expression must be a contiguous block
of non-whitespace characters
* The entire model, from 'EXPR' to the final
expression must be enclosed in one set of
quotes. The individual component expressions
are separated by blanks. Example:
'-EXPR(0,20) sin(PI*t/20)^2'
* Expressions use the same format as 3dcalc
* Symbols that can be used in an expression:
t = time in sec since stimulus time
x = time scaled to be x= 0..1 for t=bot..top
z = time scaled to be z=-1..1 for t=bot..top
* Spatially dependent regressors are not allowed!
* Other symbols are set to 0 (silently).
==> ** There is no convolution of the 'EXPR' functions
with a square wave implied. The expressions
you input are what you get, evaluated over
times b..c after each stimulus time. To be
sure of what your response model is, you should
plot the relevant columns from the matrix
.xmat.1D output file.
'MION(d)' = 1 parameter block stimulus of duration 'd',
intended to model the response of MION.
The zero-duration impulse response 'MION(0)' is
h(t) = 16.4486 * ( -0.184/ 1.5 * exp(-t/ 1.5)
+0.330/ 4.5 * exp(-t/ 4.5)
+0.670/13.5 * exp(-t/13.5) )
which is adapted from the paper
FP Leite, et al. NeuroImage 16:283-294 (2002)
http://dx.doi.org/10.1006/nimg.2002.1110
** Note that this is a positive function, but MION
produces a negative response to activation, so the
beta and t-statistic for MION are usually negative.
***** If you want a negative MION function (so you get
a positive beta), use the name 'MIONN' instead.
** After convolution with a square wave 'd' seconds
long, the resulting single-trial waveform is
scaled to have magnitude 1. For example, try
this fun command to compare BLOCK and MION:
3dDeconvolve -nodata 300 1 -polort -1 -num_stimts 2 \
-stim_times 1 '1D: 10 150' 'MION(70)' \
-stim_times 2 '1D: 10 150' 'BLOCK(70,1)' \
-x1D stdout: | 1dplot -stdin -one -thick
You will see that the MION curve rises and falls
much more slowly than the BLOCK curve.
==> ** Note that 'MION(d)' is already convolved with a
square wave of duration 'd' seconds. Do not
convolve it again by putting in multiple closely
spaced stimulus times (this mistake has been made)!
** Scaling the single-trial waveform to have magnitude
1 means that trials with different durations 'd'
will have the same magnitude for their regression
models.
* 3dDeconvolve does LINEAR regression, so the model parameters are
amplitudes of the basis functions; 1 parameter models are 'simple'
regression, where the shape of the impulse response function is
fixed and only the magnitude/amplitude varies. Models with more
free parameters have 'variable' shape impulse response functions.
* LINEAR regression means that each data time series (thought of as
a single column of numbers = a vector) is fitted to a sum of the
matrix columns, each one multiplied by an amplitude parameter to
be calculated ('Coef'). The purpose of the various options
'-stim_times', '-polort', '-ortvec', and/or '-stim_file'
is to build the columns of the regression matrix.
* If you want NONLINEAR regression, see program 3dNLfim.
* If you want LINEAR regression with allowance for non-white noise,
use program 3dREMLfit, after using 3dDeconvolve to set up the
regression model (in the form of a matrix file).
** When in any doubt about the shape of the response model you are **
* asking for, you should plot the relevant columns from the X matrix *
* to help develop some understanding of the analysis. The 'MION' *
* example above can be used as a starting point for how to easily *
* setup a quick command pipeline to graph response models. In that *
* example, '-polort -1' is used to suppress the usual baseline model *
* since graphing that part of the matrix would just be confusing. *
* Another example, for example, comparing the similar models *
** 'WAV(10)', 'BLOCK4(10,1)', and 'SPMG1(10)': **
3dDeconvolve -nodata 100 1.0 -num_stimts 3 -polort -1 \
-local_times -x1D stdout: \
-stim_times 1 '1D: 10 60' 'WAV(10)' \
-stim_times 2 '1D: 10 60' 'BLOCK4(10,1)' \
-stim_times 3 '1D: 10 60' 'SPMG1(10)' \
| 1dplot -thick -one -stdin -xlabel Time -ynames WAV BLOCK4 SPMG1
* For the format of the 'tname' file, see the last part of
https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/DeconSummer2004.html
and also see the other documents stored in the directory below:
https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/
and also read the presentation below:
https://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 IN SECONDS.
* 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!!
* The '1D:' form of input is mostly useful for quick tests, as
in the examples above, rather than for production analyses with
lots of different stimulus times and multiple imaging runs.
[-stim_times_AM1 k tname Rmodel]
Similar, but generates an amplitude modulated response model.
The 'tname' file should consist of 'time*amplitude' pairs.
As in '-stim_times', the '*' character can be used as a placeholder
when an imaging run doesn't have any stimulus of a given class.
*N.B.: What I call 'amplitude' modulation is called 'parametric'
modulation in Some other PrograM.
***N.B.: If NO run at all has a stimulus of a given class, then you
must have at least 1 time that is not '*' for -stim_times_*
to work (so that the proper number of regressors can be set
up). You can use a negative time for this purpose, which
will produce a warning message but otherwise will be
ignored, as in:
-1*37
*
for a 2 run 'tname' file to be used with -stim_times_*.
** In such a case, you will also need the -allzero_OK option,
and probably -GOFORIT as well.
** It is possible to combine '-stim_times_AM1' with the Rmodel
being TENT. If you have an amplitude parameter at each TR,
and you want to try to deconvolve its impact on the data,
you can try the following:
a) create a 1D column file with the amplitude parameter,
one value per TR, matching the length of the data;
say this file is called Akk.1D
b) create a 1D column file with the actual TR time in
each row; for example, if you have 150 time points
and TR=2 s, then
1deval -num 150 -expr '2*i' > Att.1D
c) glue these files together for use with -stim_times_AM1:
echo `1dMarry Att.1D Akk.1D` > Atk.1D
d) Use option
-stim_times 1 Atk.1D 'TENT(0,20,11)' -stim_label 1 TENT
which gives a TENT response lasting 20s with 11 parameters
-- one every TR.
e) Use all the other clever options you need in 3dDeconvolve,
such as censoring, baseline, motion parameters, ....
Variations on the options chosen here can be made to
constrain the deconvolution; e.g., use CSPLIN vs. TENT, or
CSPLINzero; use fewer parameters in the TENT/CSPLIN to force
a smoother deconvolution, etc.
Graphing the regression matrix is useful in this type of
analysis, to be sure you are getting the analysis you want;
for example:
1dplot -sep_scl prefix.xmat.1D
[-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.
*** Please note that 'AM2' is the option you should probably use!
*** 'AM1' is for special cases, and normally should not be used
for FMRI task activation analyses!!
*** 'AM2' will give you the ability to detect voxels that activate
but do not change proportional to the amplitude factor, as well
as provide a direct measure of the proportionality of the
activation to changes in the input amplitude factors. 'AM1'
will do neither of these things.
*** Normally, 3dDeconvolve removes the mean of the auxiliary
parameter(s) from the modulated regressor(s). However, if you
set environment variable AFNI_3dDeconvolve_rawAM2 to YES, then
the mean will NOT be removed from the auxiliary parameter(s).
This ability is provided for users who want to center their
parameters using their own method.
*** [12 Jul 2012] You can now specify the value to subtract from
each modulation parameter -- this value will replace the
subtraction of the average parameter value that usually happens.
To do this, add an extra parameter after the option, as in
-stim_times_AM2 1 timesAM.1D 'BLOCK(2,1)' :5.2:x:2.0
The extra argument must start with the colon ':' character, and
there should be as many different values (separated by ':') as
there are parameters in the timing file (timesAM.1D above).
==> In the example above, ':5.2:x:2.0' means
subtract 5.2 from each value of the first parameter in timesAM.1D
subtract the MEAN from each value of the second parameter
(since 'x' doesn't translate to a number)
subtract 2.0 from each value of the third parameter
==> What is this option for, anyway? The purpose is to facilitate
GROUP analysis the results from a collection of subjects, where
you want to treat each subject's analysis exactly the same
way -- and thus, the subtraction value for a parameter (e.g.,
reaction time) should then be the mean over all the reaction
times from all trials in all subjects.
** 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.
** Please don't carried away and use too many parameters!! **
For more information on modulated regression, see
https://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 modulation parameters 5 and 3,
and with duration 12 s.
The unmodulated peak response of dmBLOCK depends on the duration
of the stimulus, as the BOLD response accumulates.
If you want the peak response to be a set to a fixed value, use
dmBLOCK(p)
where p = the desired peak value (e.g., 1).
*** Understand what you doing when you use dmBLOCK, and look at ***
*** the regression matrix! Otherwise, you will end up confused. ***
*N.B.: The maximum allowed dmBLOCK duration is 999 s.
*N.B.: You cannot use '-iresp' or '-sresp' with dmBLOCK!
*N.B.: If you are NOT doing amplitude modulation at the same time
(and so you only have 1 'married' parameter per time), use
'-stim_times_AM1' with dmBLOCK. If you also want to do
amplitude modulation at the same time as duration modulation
(and so you have 2 or more parameters with each time), use
'-stim_times_AM2' instead. If you use '-stim_times_AM2' and
there is only 1 'married' parameter, the program will print
a warning message, then convert to '-stim_times_AM1', and
continue -- so nothing bad will happen to your analysis!
(But you will be embarrassed in front of your friends.)
*N.B.: If you are using AM2 (amplitude modulation) with dmBLOCK, you
might want to use 'dmBLOCK(1)' to make each block have native
amplitude 1 before it is scaled by the amplitude parameter.
Or maybe not -- this is a matter for fine judgment.
*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.
*N.B.: For bad historical reasons, the peak amplitude dmBLOCK without
the 'p' parameter does not go to 1 as the duration gets large.
Correcting this oversight would break some people's lives, so
that's just the way it is.
*N.B.: The 'dmUBLOCK' function (U for Unit) is the same as the
'dmBLOCK' function except that when the 'p' parameter is
missing (or 0), the peak amplitude goes to 1 as the duration
gets large. If p > 0, 'dmUBLOCK(p)' and 'dmBLOCK(p)' are
identical
For some graphs of what dmBLOCK regressors look like, see
https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/AMregression.pdf
and/or try the following command:
3dDeconvolve -nodata 350 1 -polort -1 -num_stimts 1 \
-stim_times_AM1 1 q.1D 'dmBLOCK' \
-x1D stdout: | 1dplot -stdin -thick -thick
where file q.1D contains the single line
10:1 40:2 70:3 100:4 130:5 160:6 190:7 220:8 250:9 280:30
Change 'dmBLOCK' to 'dmBLOCK(1)' and see how the matrix plot changes.
**************** Further notes on dmBLOCK [Nov 2013] ****************
Basically (IMHO), there are 2 rational choices to use:
(a) 'dmUBLOCK' = allow the amplitude of the response model to
vary with the duration of the stimulus; getting
larger with larger durations; for durations longer
than about 15s, the amplitude will become 1.
-->> This choice is equivalent to 'dmUBLOCK(0)', but
is NOT equivalent to 'dmBLOCK(0)' due to the
historical scaling issue alluded to above.
(b) 'dmUBLOCK(1)' = all response models will get amplitude 1,
no matter what the duration of the stimulus.
-->> This choice is equivalent to 'dmBLOCK(1)'.
Some users have expressed the desire to allow the amplitude to
vary with duration, as in case (a), BUT to specify the duration
at which the amplitude goes to 1. This desideratum has now been
implemented, and provides the case below:
(a1) 'dmUBLOCK(-X)' = set the amplitude to be 1 for a duration
of 'X' seconds; e.g., 'dmBLOCK(-5)' means
that a stimulus with duration 5 gets
amplitude 1, shorter durations get amplitudes
smaller than 1, and longer durations get
amplitudes larger than 1.
-->> Please note that 'dmBLOCK(-X)' is NOT the
same as this case (a1), and in fact it
has no meaning.
I hope this clarifies things and makes your life simpler, happier,
and more carefree. (If not, please blame Gang Chen, not me.)
An example to clarify the difference between these cases:
3dDeconvolve -nodata 350 1 -polort -1 -num_stimts 3 \
-stim_times_AM1 1 q.1D 'dmUBLOCK' \
-stim_times_AM1 2 q.1D 'dmUBLOCK(1)' \
-stim_times_AM1 3 q.1D 'dmUBLOCK(-4)' \
-x1D stdout: | \
1dplot -stdin -thick \
-ynames 'dmUBLOCK' 'dmUB(1)' 'dmUB(-4)'
where file q.1D contains the single line
10:1 60:2 110:4 160:10 210:20 260:30
Note how the 'dmUBLOCK(-4)' curve (green) peaks at 1 for the 3rd
stimulus, and peaks at larger values for the later (longer) blocks.
Whereas the 'dmUBLOCK' curve (black) peaks at 1 at only the longest
blocks, and the 'dmUBLOCK(1)' curve (red) peaks at 1 for ALL blocks.
*********************************************************************
[-stim_times_FSL k tname Rmodel]
This option allows you to input FSL-style 3-column timing files,
where each line corresponds to one stimulus event/block; the
line '40 20 1' means 'stimulus starts at 40 seconds, lasts for
20 seconds, and is given amplitude 1'. Since in this format,
each stimulus can have a different duration and get a different
response amplitude, the 'Rmodel' must be one of the 'dm'
duration-modulated options above ['dmUBLOCK(1)' is probably the
most useful]. The amplitude modulation is taken to be like
'-stim_times_AM1', where the given amplitude in the 'tname' file
multiplies the basic response shape.
*** We DO NOT advocate the use of this '_FSL' option, but it's here
to make some scripting easier for some (unfortunate) people.
*** The results of 3dDeconvolve (or 3dREMLfit) cannot be expected
to be exactly the same as FSL FEAT, since the response model
shapes are different, among myriad other details.
*** You can also use '-stim_times_FS1' to indicate that the
amplitude factor in the 'tname' file should be ignored and
replaced with '1' in all cases.
*** FSL FEAT only analyzes contiguous time series -- nothing like
'-concat' allowing for multiple EPI runs is possible in FSL
(AFAIK). So the FSL stimulus time format doesn't allow for
this possibility. In 3dDeconvolve, you can get around this
problem by using a line consisting of '* * *' to indicate the
break between runs, as in the example below:
1 2 3
4 5 6
* * *
7 8 9
that indicates 2 runs, the first of which has 2 stimuli and
the second of which has just 1 stimulus. If there is a run
that has NO copies of this type of stimulus, then you would
use two '* * *' lines in succession.
Of course, a file using the '* * *' construction will NOT be
compatible with FSL!
[-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 estimated. Presumably you will
collect these many amplitudes afterwards and do some sort of
statistics or analysis 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'.
** Using one of these options (most commonly, '-local_times') is
VERY highly recommended.
[-stim_times_millisec]
This option scales all the times in any '-stim_times_*' option by
0.001; the purpose is to allow you to input the times in ms instead
of in s. This factor will be applied to ALL '-stim_times' inputs,
before or after this option on the command line. This factor will
be applied before -stim_times_subtract, so the subtraction value
(if present) must be given in seconds, NOT milliseconds!
[-stim_times_subtract SS]
This option means to subtract 'SS' seconds from each time encountered
in any '-stim_times*' option. The purpose of this option is to make
it simple to adjust timing files for the removal of images from the
start of each imaging run. Note that this option will be useful
only if both of the following are true:
(a) each imaging run has exactly the same number of images removed
(b) the times in the 'tname' files were not already adjusted for
these image removal (i.e., the times refer to the image runs
as acquired, not as input to 3dDeconvolve).
In other words, use this option with understanding and care!
** Note that the subtraction of 'SS' applies to ALL '-stim_times'
inputs, before or after this option on the command line!
** And it applies to global times and local times alike!
** Any time (thus subtracted) below 0 will be ignored, as falling
before the start of the imaging run.
** This option, and the previous one, are simply for convenience, to
help you in setting up your '-stim_times*' timing files from
whatever source you get them.
[-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'.
NOTES:
* -basis_normall only affect -stim_times options that
appear LATER on the command line
* The main use for this option is for use with the
'EXPR' basis functions.
******* 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
'gltname'; see the document below for details:
https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/DeconSummer2004.html
******* Options to create 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.
**N.B.: This option only applies to the 'old' style of
deconvolution analysis. Do not use this with
-stim_times analyses!
[-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 for each stimulus
** F tests the null hypothesis that each and every
beta coefficient in the stimulus set is zero
** If there is only 1 stimulus class, then its
'-fout' value is redundant with the Full_Fstat
computed for all stimulus coefficients together.
[-rout] Flag to output the R^2 statistics
[-tout] Flag to output the t-statistics
** t tests a single beta coefficient against zero
** If a stimulus class has only one regressor, then
F = t^2 and the F statistic is redundant with t.
[-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.
** Will make the output dataset larger.
[-nocout] Flag to suppress output of regression coefficients
(and associated statistics)
** Useful if you just want GLT results.
[-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 [** now the default **]
[-short] Write output as scaled shorts [no longer default]
***** The following options control miscellaneous outputs *****
[-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]
** If 'filename' is 'stdout:', the file is written
to standard output, and could be piped into
1dplot (some examples are given earlier).
* This can be used for quick checks to see if your
inputs are setting up a 'reasonable' matrix.
[-nox1D] Don't save X matrix [a very bad idea]
[-x1D_uncensored ff] Save X matrix to a .xmat.1D file, but WITHOUT
ANY CENSORING. Might be useful in 3dSynthesize.
[-x1D_regcensored f] Save X matrix to a .xmat.1D file with the
censoring imposed by adding 0-1 columns instead
excising the censored rows.
[-x1D_stop] Stop running after writing .xmat.1D files.
* Useful for testing, or if you are going to
run 3dREMLfit instead -- that is, you are just
using 3dDeconvolve to set up the matrix file.
[-progress n] Write statistical results for every nth voxel
* To let you know that something is happening!
[-fdisp fval] Write statistical results to the screen, for those
voxels whose full model F-statistic is > fval
[-help] Oh go ahead, try it!
**** Multiple CPU option (local CPUs only, no networking) ****
-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 would be 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.
* Unlike other parallelized AFNI programs, this one
does not use OpenMP; it directly uses fork()
and shared memory to run multiple processes.
* For more information on parallelizing, see
https://afni.nimh.nih.gov/afni/doc/misc/afni_parallelize
* Also use -mask or -automask to get more speed; cf. 3dAutomask.
-virtvec To save memory, write the input dataset to a temporary file
and then read data vectors from it only as needed. This option
is for Javier and will probably not be useful for anyone else.
And it only takes effect if -jobs is greater than 1.
** NOTE **
This version of the program has been compiled to use
double precision arithmetic for most internal calculations.
++ Compile date = Oct 17 2024 {AFNI_24.3.03:linux_ubuntu_24_64}
