++ 3dDeconvolve: AFNI version=AFNI_2011_12_21_1014 (Dec 16 2015) [64-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 model
regression (AKA ‘pre-whitened’ least squares) combined with REML estimation of an ARMA(1,1) temporal correlation structure:
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.
http://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:
**** 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):
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). ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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.
Usage Details: 3dDeconvolve command-line-arguments ...
**** Input data and control options:
[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.]
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=YESon 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].
for initial saturation transients, which should normally have been excised before data analysis. If you want to have it do this somewhat time consuming check, use the option ‘-sat’.
‘-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.
(will be slow for long time series datasets)
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’.
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.
to be removed from the analysis. Each string is of one of the following forms:
37 => remove global time index #372: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.
‘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.
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)
-polort option that allows the use of ‘A’ to set the polynomial order automatically!!!
[default is -legendre]
** Don’t do this unless you are crazy!
[-dmbase] de-mean baseline time series [default if polort>=0]
[-svd] Use SVD instead of Gaussian elimination [default]
bad problems (e.g., duplicate columns, large condition number, etc.).
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.
the type of error that -GOFORIT is needed to ignore.
*** Input stimulus options ***
(0 <= num) [default: num = 0]
*N.B.: ‘Baseline model’ == Null Hypothesis model *N.B.: The most common baseline components to add are
the 6 estimated motion parameters from 3dvolreg.
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.
count that you provide.
*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.
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
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:
put a single ‘*’ on the line, or
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 amplitude varies.
- *** Models with more than 1 parameter have multiple basis
- functions, and the parameters are their amplitudes. The estimated shape of the response to a stimulus will be different in different voxels.
- *** 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.
- *** 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 * NEVER convolved: TENT CSPLIN POLY SIN EXPR * OPTIONALLY convolved: GAM SPMGx WAV
- ‘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.3*sqrt(p)*q.
- ==> ** 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]
- ‘SPMG1’ = 1 parameter SPM gamma variate basis function
exp(-t)*(A1*t^P1-A2*t^P2) whereA1 = 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
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 -thickYou 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.
** 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 this * * 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
- 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 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).
complicated ‘-stim_times_*’ options below!!
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.
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_*.
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!!
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).
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
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!! **
-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 embarassed in front of your friends.)
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:
- ‘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.
- ‘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.)
-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: |
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. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
‘-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!
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.
[-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.
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:
- each imaging run has exactly the same number of images removed
- 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.
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 ***
(0 <= num) [default: num = 0]
[-glt_label k glabel] glabel = label for kth general linear test
‘gltname’; see the document below for details:
http://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/DeconSummer2004.html
*** Options to create 3D+time datasets ***
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.
**** Options to control the contents of the output bucket dataset ****
[-rout] Flag to output the R^2 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
(and associated statistics)
** Useful if you just want GLT results.
[-nofull_first] Flag to specify that full model statistics go last
[-noxsave] Don’t save X matrix [this is the default]
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].
[-short] Write output as scaled shorts [no longer default]
* The following options control miscellanous outputs *
[-quiet] Flag to suppress most screen output
[-xout] Flag to write X and inv(X’X) matrices to screen
to standard output, and could be piped into 1dplot (some examples are given earlier).
[-nox1D] Don’t save X matrix [a very bad idea]
[-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 http://afni.nimh.nih.gov/afni/doc/misc/afni_parallelize
Also use -mask or -automask 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 = Dec 16 2015