AFNI program: afni_proc.py
Output of -help
===========================================================================
afni_proc.py - generate a tcsh script for an AFNI process stream
This python script can generate a processing script via a command-line
interface, with an optional question/answer session (-ask_me), or by a tk
GUI (eventually).
The user should provide at least the input datasets (-dsets) and stimulus
files (-regress_stim_*), in order to create an output script. See the
'DEFAULTS' section for a description of the default options for each block.
The output script, when executed will create a results directory, copy
input files into it, and perform all processing there. So the user can
delete the results directory and re-run the script at their whim.
Note that the user need not actually run the output script. The user
should feel free to modify the script for their own evil purposes, before
running it.
The text interface can be accessed via the -ask_me option. It invokes a
question & answer session, during which this program sets user options on
the fly. The user may elect to enter some of the options on the command
line, even if using -ask_me. See "-ask_me EXAMPLES", below.
==================================================
PROCESSING BLOCKS (of the output script):
The output script will go through the following steps, unless the user
specifies otherwise.
automatic blocks (the tcsh script will always perform these):
setup : check subject arg, set run list, create output dir, and
copy stim files
tcat : copy input datasets and remove unwanted initial TRs
default blocks (the user may skip these, or alter their order):
tshift : slice timing alignment on volumes (default is -time 0)
volreg : volume registration (default to third volume)
blur : blur each volume (default is 4mm fwhm)
mask : create a 'brain' mask from the EPI data (dilate 1 voxel)
scale : scale each run mean to 100, for each voxel (max of 200)
regress : regression analysis (default is GAM, peak 1, with motion
params)
optional blocks (the default is to _not_ apply these blocks)
align : align EPI anat anatomy (via align_epi_anat.py)
despike : truncate spikes in each voxel's time series
empty : placeholder for some user command (uses 3dTcat as sample)
ricor : RETROICOR - removal of cardiac/respiratory regressors
tlrc : warp anat to standard space
==================================================
DEFAULTS: basic defaults for each block (not all defaults)
setup: - use 'SUBJ' for the subject id
(option: -subj_id SUBJ)
- create a t-shell script called 'proc_subj'
(option: -script proc_subj)
- use results directory 'SUBJ.results'
(option: -out_dir SUBJ.results)
tcat: - do not remove any of the first TRs
empty: - do nothing (just copy the data using 3dTcat)
despike: - NOTE: by default, this block is _not_ used
- automasking is not done (requires -despike_mask)
ricor: - NOTE: by default, this block is _not_ used
- polort based on twice the actual run length
- solver is OLSQ, not REML
- do not remove any first TRs from the regressors
tshift: - align slices to the beginning of the TR
- use quintic interpolation for time series resampling
(option: -tshift_interp -quintic)
align: - align the anatomy to match the EPI
(also required for the option of aligning EPI to anat)
volreg: - align to third volume of first run, -zpad 1
(option: -volreg_align_to third)
(option: -volreg_zpad 1)
- use cubic interpolation for volume resampling
(option: -volreg_interp -cubic)
- apply motion params as regressors across all runs at once
- do not align EPI to anat
- do not warp to standard space
blur: - blur data using a 4 mm FWHM filter with 3dmerge
(option: -blur_filter -1blur_fwhm)
(option: -blur_size 4)
(option: -blur_in_mask no)
mask: - create a union of masks from 3dAutomask on each run
- not applied in regression without -regress_apply_mask
- if possible, create a subject anatomy mask
- if possible, create a group anatomy mask (tlrc base)
scale: - scale each voxel to mean of 100, clip values at 200
regress: - use GAM regressor for each stim
(option: -regress_basis)
- compute the baseline polynomial degree, based on run length
(e.g. option: -regress_polort 2)
- do not censor large motion
- output fit time series
- output ideal curves for GAM/BLOCK regressors
- output iresp curves for non-GAM/non-BLOCK regressors
tlrc: - use TT_N27+tlrc as the base (-tlrc_base TT_N27+tlrc)
- no additional suffix (-tlrc_suffix NONE)
==================================================
EXAMPLES (options can be provided in any order):
1. Minimum use.
Provide datasets and stim files (or stim_times files). Note that a
dataset suffix (e.g. HEAD) must be used with wildcards, so that
datasets are not applied twice. In this case, a stim_file with many
columns is given, where the script to changes it to stim_times files.
afni_proc.py -dsets epiRT*.HEAD \
-regress_stim_files stims.1D
or without any wildcard, the .HEAD suffix is not needed:
afni_proc.py -dsets epiRT_r1+orig epiRT_r2+orig epiRT_r3+orig \
-regress_stim_files stims.1D
***********************************************************
* New and improved! Examples that apply to AFNI_data4. *
***********************************************************
The following examples can be run from the AFNI_data4 directory, and
are examples of how one might process the data for subject sb23.
2. Very simple. Use all defaults, except remove 3 TRs and use basis
function BLOCK(30,1). The default basis function is GAM.
afni_proc.py -subj_id sb23.e2.simple \
-dsets sb23/epi_r??+orig.HEAD \
-tcat_remove_first_trs 3 \
-regress_stim_times sb23/stim_files/blk_times.*.1D \
-regress_basis 'BLOCK(30,1)'
3. The current class example. This may change of course.
Copy the anatomy into the results directory, register EPI data to
the last TR, specify stimulus labels, compute blur estimates, and
provide GLT options directly to 3dDeconvolve. The GLTs will be
ignored after this, as they take up too many lines.
afni_proc.py -subj_id sb23.blk \
-dsets sb23/epi_r??+orig.HEAD \
-copy_anat sb23/sb23_mpra+orig \
-tcat_remove_first_trs 3 \
-volreg_align_to last \
-regress_make_ideal_sum sum_ideal.1D \
-regress_stim_times sb23/stim_files/blk_times.*.1D \
-regress_stim_labels tneg tpos tneu eneg epos \
eneu fneg fpos fneu \
-regress_basis 'BLOCK(30,1)' \
-regress_est_blur_epits \
-regress_est_blur_errts \
-regress_opts_3dD \
-gltsym 'SYM: +eneg -fneg' \
-glt_label 1 eneg_vs_fneg \
-gltsym 'SYM: 0.5*fneg 0.5*fpos -1.0*fneu' \
-glt_label 2 face_contrast \
-gltsym 'SYM: tpos epos fpos -tneg -eneg -fneg'\
-glt_label 3 pos_vs_neg
4. Similar to the class example, but specify the processing blocks,
adding despike and tlrc, and removing tshift. Note that the tlrc
block is to run @auto_tlrc on the anat. Ignore the GLTs.
afni_proc.py -subj_id sb23.e4.blocks \
-dsets sb23/epi_r??+orig.HEAD \
-blocks despike volreg blur mask scale regress tlrc\
-copy_anat sb23/sb23_mpra+orig \
-tcat_remove_first_trs 3 \
-regress_stim_times sb23/stim_files/blk_times.*.1D \
-regress_stim_labels tneg tpos tneu eneg epos \
eneu fneg fpos fneu \
-regress_basis 'BLOCK(30,1)' \
-regress_est_blur_epits \
-regress_est_blur_errts
5a. RETROICOR example a, resting state data.
Assuming the class data is for resting-state and that we have the
appropriate slice-based regressors from RetroTS.m, apply the despike
and ricor processing blocks. Note that '-do_block' is used to add
non-default blocks into their default positions. Here the 'despike'
and 'ricor' processing blocks would come before 'tshift'.
Remove 3 TRs from the ricor regressors to match the EPI data. Also,
since degrees of freedom are not such a worry, regress the motion
parameters per-run (each run gets a separate set of 6 regressors).
The regression will use 198 regressors (all of "no interest"):
27 baseline regressors ( 3 per run * 9 runs)
54 motion regressors ( 6 per run * 9 runs)
117 RETROICOR regressors (13 per run * 9 runs)
To example #3, add -do_block, -ricor_* and -volreg_regress_per_run.
afni_proc.py -subj_id sb23.e5a.ricor \
-dsets sb23/epi_r??+orig.HEAD \
-do_block despike ricor \
-tcat_remove_first_trs 3 \
-ricor_regs_nfirst 3 \
-ricor_regs sb23/RICOR/r*.slibase.1D \
-ricor_regress_method 'per-run' \
-volreg_regress_per_run
If tshift, blurring and masking are not desired, consider replacing
the -do_block option with an explicit list of blocks:
-blocks despike ricor volreg regress
5b. RETROICOR example b, while running a normal regression.
Add the ricor regressors to a normal regression-based processing
stream. Apply the RETROICOR regressors across runs (so using 13
concatenated regressors, not 13*9). Note that concatenation is
normally done with the motion regressors too.
To example #3, add -do_block and three -ricor options.
afni_proc.py -subj_id sb23.e5b.ricor \
-dsets sb23/epi_r??+orig.HEAD \
-do_block despike ricor \
-copy_anat sb23/sb23_mpra+orig \
-tcat_remove_first_trs 3 \
-ricor_regs_nfirst 3 \
-ricor_regs sb23/RICOR/r*.slibase.1D \
-ricor_regress_method 'across-runs' \
-volreg_align_to last \
-regress_make_ideal_sum sum_ideal.1D \
-regress_stim_times sb23/stim_files/blk_times.*.1D \
-regress_stim_labels tneg tpos tneu eneg epos \
eneu fneg fpos fneu \
-regress_basis 'BLOCK(30,1)' \
-regress_est_blur_epits \
-regress_est_blur_errts
6. A modern example. GOOD TO CONSIDER.
Align the EPI to the anatomy. Also, process in standard space.
For alignment in either direction, add the 'align' block, which
aligns the anatomy to the EPI. To then align the EPI to the anat,
apply -volreg_align_e2a, where that transform (inverse) is applied
along with the motion alignment.
On top of that, complete the processing in standard space by running
@auto_tlrc on the anat (via the 'tlrc' block) and applying the same
transformation to the EPI via -volreg_tlrc_warp. Again, the EPI
transformation is applied along with the motion alignment.
So add the 2 processing blocks and 2 extra volreg warps to #3 via
'-do_block align tlrc', '-volreg_align_e2a', '-volreg_tlrc_warp'.
As an added bonus, censor TR pairs where the Euclidean Norm of the
motion derivative exceeds 1.0.
afni_proc.py -subj_id sb23.e6.align \
-dsets sb23/epi_r??+orig.HEAD \
-do_block align tlrc \
-copy_anat sb23/sb23_mpra+orig \
-tcat_remove_first_trs 3 \
-volreg_align_to last \
-volreg_align_e2a \
-volreg_tlrc_warp \
-regress_make_ideal_sum sum_ideal.1D \
-regress_stim_times sb23/stim_files/blk_times.*.1D \
-regress_stim_labels tneg tpos tneu eneg epos \
eneu fneg fpos fneu \
-regress_basis 'BLOCK(30,1)' \
-regress_censor_motion 1.0 \
-regress_est_blur_epits \
-regress_est_blur_errts \
-regress_opts_3dD \
-gltsym 'SYM: +eneg -fneg' \
-glt_label 1 eneg_vs_fneg \
To process in orig space, remove -volreg_tlrc_warp.
To apply manual tlrc transformation, use -volreg_tlrc_adwarp.
To process as anat aligned to EPI, remove -volreg_align_e2a.
--------------------------------------------------
-ask_me EXAMPLES:
a1. Apply -ask_me in the most basic form, with no other options.
afni_proc.py -ask_me
a2. Supply input datasets.
afni_proc.py -ask_me -dsets ED/ED_r*.HEAD
a3. Same as a2, but supply the datasets in expanded form.
No suffix (.HEAD) is needed when wildcards are not used.
afni_proc.py -ask_me \
-dsets ED/ED_r01+orig ED/ED_r02+orig \
ED/ED_r03+orig ED/ED_r04+orig \
ED/ED_r05+orig ED/ED_r06+orig \
ED/ED_r07+orig ED/ED_r08+orig \
ED/ED_r09+orig ED/ED_r10+orig
a4. Supply datasets, stim_times files and labels.
afni_proc.py -ask_me \
-dsets ED/ED_r*.HEAD \
-regress_stim_times misc_files/stim_times.*.1D \
-regress_stim_labels ToolMovie HumanMovie \
ToolPoint HumanPoint
==================================================
Many NOTE sections:
==================================================
TIMING FILE NOTE:
One issue that the user must be sure of is the timing of the stimulus
files (whether -regress_stim_files or -regress_stim_times is used).
The 'tcat' step will remove the number of pre-steady-state TRs that the
user specifies (defaulting to 0). The stimulus files, provided by the
user, must match datasets that have had such TRs removed (i.e. the stim
files should start _after_ steady state has been reached).
--------------------------------------------------
MASKING NOTE:
The default operation of afni_proc.py has changed (as of 24 Mar, 2009).
Prior to that date, the default was to apply the 'epi' mask. As of
17 Jun 2009, only the 'extents' mask is, if appropriate.
---
There may be 4 masks created by default, 3 for user evaluation and all for
possible application to the EPI data (though it may not be recommended).
The 4th mask (extents) is a special one that will be applied at volreg when
appropriate, unless the user specifies otherwise.
If the user chooses to apply one of the masks to the EPI regression (again,
not necessarily recommended), it is done via the option -mask_apply while
providing the given mask type (epi, anat, group or extents).
--> To apply a mask during regression, use -mask_apply.
Mask descriptions (afni_proc.py name, dataset name, short description):
1. epi ("full_mask") : EPI Automask
An EPI mask dataset will be created by running '3dAutomask -dilate 1'
on the EPI data after blurring. The 3dAutomask command is executed per
run, after which the masks are combined via a union operation.
2. anat ("mask_anat.$subj") : anatomical skull-stripped mask
If possible, a subject anatomy mask will be created. This anatomical
mask will be created from the appropriate skull-stripped anatomy,
resampled to match the EPI (that is output by 3dvolreg) and changed into
a binary mask.
This requires either the 'align' block or a tlrc anatomy (from the
'tlrc' block, or just copied via '-copy_anat'). Basically, it requires
afni_proc.py to know of a skull-stripped anatomical dataset.
3. group ("mask_group") : skull-stripped @auto_tlrc base
If possible, a group mask will be created. This requires the 'tlrc'
block, from which the @auto_tlrc -base dataset is chosen as the group
anatomy. It also requires '-volreg_warp_epi' so that the EPI is in
standard space. The group anatomy is then resampled to match the EPI
and changed into a binary mask.
4. extents ("mask_extents") : mask based on warped EPI extents
In the case of transforming the EPI volumes to match the anatomical
volume (via either -volreg_align_e2a or -volreg_tlrc_warp), an extents
mask will be created. This is to avoid a motion artifact that arises
when transforming from a smaller volume (EPI) to a larger one (anat).
** Danger Will Robinson! **
This mask is considered necessary because the align/warp transformation
that is applied on top of the volreg alignment transformation (applied
at once), meaning the transformation from the EPI grid to the anatomy
grid will vary per TR.
The effect of this is seen at the edge voxels (extent edge), where a
time series could be zero for many of the TRs, but have valid data for
the rest of them. If this timing just happens to correlate with any
regressor, the result could be a strong "activation" for that regressor,
but which would be just a motion based artifact.
What makes this particularly bad is that if it does happen, it tends to
happen for *a cluster* of many voxels at once, possibly an entire slice.
Such an effect is compounded by any additional blur. The result can be
an entire cluster of false activation, large enough to survive multiple
comparison corrections.
Thanks to Laura Thomas and Brian Bones for finding this artifact.
--> To deal with this, a time series of all 1s is created on the original
EPI grid space. Then for each run it is warped with to the same list of
transformations that is applied to the EPI data in the volreg step
(volreg xform and either alignment to anat or warp to standard space).
The result is a time series of extents of each original volume within
the new grid.
These volumes are then intersected over all TRs of all runs. The final
mask is the set of voxels that have valid data at every TR of every run.
Yay.
--- masking, continued...
Note that it may still not be a good idea to apply any of the masks to the
regression, as it would then be necessary to intersect the masks across all
subjects, though applying the 'group' mask might be reasonable.
** Why has the default been changed?
It seems much better not to mask the regression data in the single-subject
analysis at all, send _all_ of the results to group space, and apply an
anatomically-based mask there. That could be computed from the @auto_tlrc
reference dataset or from the union of skull-stripped subject anatomies.
Since subjects have varying degrees of signal dropout in valid brain areas
of the EPI data, the resulting EPI intersection mask that would be required
in group space may exclude edge regions that are otherwise desirable.
Also, it is helpful to see if much 'activation' appears outside the brain.
This could be due to scanner or interpolation artifacts, and is useful to
note, rather than to simply mask out and never see.
Rather than letting 3dAutomask decide which brain areas should not be
considered valid, create a mask based on the anatomy _after_ the results
have been warped to a standard group space. Then perhaps dilate the mask
by one voxel. Example #11 from '3dcalc -help' shows how one might dilate.
** Note that the EPI data can now be warped to standard space at the volreg
step. In that case, it might be appropriate to mask the EPI data based
on the Talairach template, such as what is used for -base in @auto_tlrc.
This can be done via '-mask_apply group'.
---
** For those who have processed some of their data with the older method:
Note that this change should not be harmful to those who have processed
data with older versions of afni_proc.py, as it only adds non-zero voxel
values to the output datasets. If some subjects were analyzed with the
older version, the processing steps should not need to change. It is still
necessary to apply an intersection mask across subjects in group space.
It might be okay to create the intersection mask from only those subjects
which were masked in the regression, however one might say that biases the
voxel choices toward those subjects, though maybe that does not matter.
Any voxels used would still be across all subjects.
---
A mask dataset is necessary when computing blur estimates from the epi and
errts datasets. Also, since it is nice to simply see what the mask looks
like, its creation has been left in by default.
The '-regress_no_mask' option is now unnecessary.
---
Note that if no mask were applied in the 'scaling' step, large percent
changes could result. Because large values would be a detriment to the
numerical resolution of the scaled short data, the default is to truncate
scaled values at 200 (percent), which should not occur in the brain.
--------------------------------------------------
WARP TO TLRC NOTE:
afni_proc.py can now apply a +tlrc transformation to the EPI data as part
of the volreg step via the option '-volreg_tlrc_warp'. Note that it can
also align the EPI and anatomy at the volreg step via '-volreg_align_e2a'.
Manual Talairach transformations can also be applied, but separately, after
volreg. See '-volreg_tlrc_adwarp'.
This tlrc transformation is recommended for many reasons, though some are
not yet implemented. Advantages include:
- single interpolation of the EPI data
Done separately, volume registration, EPI to anat alignment and/or
the +tlrc transformation interpolate the EPI data 2 or 3 times. By
combining these transformations into a single one, there is no
resampling penalty for the alignment or the warp to standard space.
Thanks to D Glen for the steps used in align_epi_anat.py.
- EPI time series become directly comparable across subjects
Since the volreg output is now in standard space, there is already
voxel correspondence across subjects with the EPI data.
- group masks and/or atlases can be applied to the EPI data without
additional warping
It becomes trivial to extract average time series data over ROIs
from standard atlases, say.
This could even be done automatically with afni_proc.py, as part
of the single-subject processing stream (not yet implemented).
One would have afni_proc.py extract average time series (or maybe
principle components) from all the ROIs in a dataset and apply
them as regressors of interest or of no interest.
- with 3dBlurToFWHM, using an AlphaSim look-up table might be possible
Since the blur and data grid could both be isotropic and integral,
and since the transformation could depend on a known anatomy (such
as the N27 Colin brain or icbm_452), it would be easy to create a
look-up table of AlphaSim results (so users would not actually need
to run it).
The known numbers would correspond to a cluster size (each for a
given, common voxel-wise threshold). This correction could then
be applied automatically. Again, not yet implemented...
- no interpolation of statistics
If the user wishes to include statistics as part of the group
analysis (e.g. using 3dMEMA.R), this warping becomes more needed.
Warping to standard space *after* statistics are generated is not
terribly valid.
--------------------------------------------------
RETROICOR NOTE:
** Cardiac and respiratory regressors must be created from an external
source, such as the RetroTS.m matlab program written by Z Saad. The
input to that would be the 2+ signals. The output would be a single
file per run, containing 13 or more regressors for each slice. That
set of output files would be applied here in afni_proc.py.
Removal of cardiac and respiratory regressors can be done using the 'ricor'
processing block. By default, this would be done after 'despike', but
before any other processing block.
These card/resp signals would be regressed out of the MRI data in the
'ricor' block, after which processing would continue normally. In the final
'regress' block, regressors for slice 0 would be applied (to correctly
account for the degrees of freedom and also to remove residual effects).
Users have the option of removing the signal "per-run" or "across-runs".
Example R1: 7 runs of data, 13 card/resp regressors, process "per-run"
Since the 13 regressors are processed per run, the regressors can have
different magnitudes each run. So the 'regress' block will actually
get 91 extra regressors (13 regressors times 7 runs each).
Example R2: process "across-run"
In this case the regressors are catenated across runs when they are
removed from the data. The major difference between this and "per-run"
is that now only 1 best fit magnitude is applied per regressor (not the
best for each run). So there would be only the 13 catenated regressors
for slice 0 added to the 'regress' block.
Those analyzing resting-state data might prefer the per-run method, as it
would remove more variance and degrees of freedom might not be as valuable.
Those analyzing a normal signal model might prefer doing it across-runs,
giving up only 13 degrees of freedom, and helping not to over-model the
data.
** The minimum options would be specifying the 'ricor' block (preferably
after despike), along with -ricor_regs and -ricor_regress_method.
Example R3: afni_proc.py option usage:
Provide additional options to afni_proc.py to apply the despike and
ricor blocks (which will be the first 2 blocks by default), with each
regressor named 'slibase*.1D' going across all runs, and where the
first 3 TRs are removed from each run (matching -tcat_remove_first_trs,
most likely).
-do_block despike ricor
-ricor_regs slibase*.1D
-ricor_regress_method across-runs
-ricor_regs_nfirst 3
--------------------------------------------------
RUNS OF DIFFERENT LENGTHS NOTE:
In the case that the EPI datasets are not all of the same length, here
are some issues that may come up, listed by relevant option:
-volreg_align_to OK, as of version 1.49.
* -ricor_regress_method If across-runs, $volsperrun is not appropriate.
-regress_polort Probably no big deal.
If this option is not used, then the degree of
polynomial used for the baseline will come from
the first run. Only 1 polort may be applied.
-regress_est_blur_epits OK, as of version 1.49.
* -regress_use_stim_files This may fail, as make_stim_times.py is not
currently prepared to handle runs of different
lengths.
-regress_censor_motion OK, as of version 2.14
* probably will be fixed (please let me know of interest)
--------------------------------------------------
SCRIPT EXECUTION NOTE:
The suggested way to run the output processing SCRIPT is via...
a) if you use tcsh: tcsh -xef SCRIPT |& tee output.SCRIPT
b) if you use bash: tcsh -xef SCRIPT 2>&1 | tee output.SCRIPT
c) if you use tcsh and the script is executable, maybe use one of:
./SCRIPT |& tee output.SCRIPT
./SCRIPT 2>&1 | tee output.SCRIPT
Consider usage 'a' for example: tcsh -xef SCRIPT |& tee output.SCRIPT
That command means to invoke a new tcsh with the -xef options (so that
commands echo to the screen before they are executed, exit the script
upon any error, do not process the ~/.cshrc file) and have it process the
SCRIPT file, piping all output to the 'tee' program, which will duplicate
output back to the screen, as well as to the given output file.
parsing the command: tcsh -xef SCRIPT |& tee output.SCRIPT
a. tcsh
The script itself is written in tcsh syntax and must be run that way.
It does not mean the user must use tcsh. Note uses 'a' and 'b'.
There tcsh is specified by the user. The usage in 'c' applies tcsh
implicitly, because the SCRIPT itself specifies tcsh at the top.
b. tcsh -xef
The -xef options are applied to tcsh and have the following effects:
-x : echo commands to screen before executing them
-e : exit (terminate) the processing on any errors
-f : do not process user's ~/.cshrc file
The -x option is very useful so one see not just output from the
programs, but the actual commands that produce the output. It
makes following the output much easier.
The -e option tells the shell to terminate on any error. This is
useful for multiple reasons. First, it allows the user to easily
see the failing command and error message. Second, it would be
confusing and useless to have the script try to continue, without
all of the needed data.
The -f option tells the shell not to process the user's ~/.cshrc
(or ~/.tcshrc) file. The main reason for including this is because
of the -x option. If there were any errors in the user's ~/.cshrc
file and -x option were used, they would terminate the shell before
the script even started, probably leaving the user confused.
c. tcsh -xef SCRIPT
The T-shell is invoked as described above, executing the contents
of the specified text file (called 'SCRIPT', for example) as if the
user had typed the included commands in their terminal window.
d. |&
These symbols are for piping the output of one program to the input
of another. Many people know how to do 'afni_proc.py -help | less'
(or maybe '| more'). This script will output a lot of text, and we
want to get a copy of that into a text file (see below).
Piping with '|' captures only stdout (standard output), and would
not capture errors and warnings that appear. Piping with '|&'
captures both stdout and stderr (standard error). The user may not
be able to tell any difference between those file streams on the
screen, but since programs write to both, we want to capture both.
e. tee output.SCRIPT
Where do we want to send this captured stdout and stderr text? Send
it to the 'tee' program. Like a plumber's tee, the 'tee' program
splits the data (not water) stream off into 2 directions.
Here, one direction that tee sends the output is back to the screen,
so the user can still see what is happening.
The other direction is to the user-specified text file. In this
example it would be 'output.SCRIPT'. With this use of 'tee', all
screen output will be duplicated in that text file.
==================================================
OPTIONS: (information options, general options, block options)
(block options are ordered by block)
------------ information options ------------
-help : show this help
-hist : show the module history
-show_valid_opts : show all valid options (brief format)
-ver : show the version number
------------ general execution and setup options ------------
-ask_me : ask the user about the basic options to apply
When this option is used, the program will ask the user how they
wish to set the basic options. The intention is to give the user
a feel for what options to apply (without using -ask_me).
-bash : show example execution command in bash form
After the script file is created, this program suggests how to run
it (piping stdout/stderr through 'tee'). If the user is running
the bash shell, this option will suggest the 'bash' form of a
command to execute the newly created script.
example of tcsh form for execution:
tcsh -x proc.ED.8.glt |& tee output.proc.ED.8.glt
example of bash form for execution:
tcsh -x proc.ED.8.glt 2>&1 | tee output.proc.ED.8.glt
Please see "man bash" or "man tee" for more information.
-blocks BLOCK1 ... : specify the processing blocks to apply
e.g. -blocks volreg blur scale regress
e.g. -blocks despike tshift align volreg blur scale regress
default: tshift volreg blur mask scale regress
The user may apply this option to specify which processing blocks
are to be included in the output script. The order of the blocks
may be varied, and blocks may be skipped.
See also '-do_block' (e.g. '-do_block despike').
-copy_anat ANAT : copy the ANAT dataset to the results dir
e.g. -copy_anat Elvis/mprage+orig
This will apply 3dcopy to copy the anatomical dataset(s) to the
results directory. Note that if a +view is not given, 3dcopy will
attempt to copy +acpc and +tlrc datasets, also.
See also '3dcopy -help'.
-copy_files file1 ... : copy file1, etc. into the results directory
e.g. -copy_files glt_AvsB.txt glt_BvsC.1D glt_eat_cheese.txt
e.g. -copy_files contrasts/glt_*.txt
This option allows the user to copy some list of files into the
results directory. This would happen before the tcat block, so
such files may be used for other commands in the script (such as
contrast files in 3dDeconvolve, via -regress_opts_3dD).
-do_block BLOCK_NAME ...: add extra blocks in their default positions
e.g. -do_block despike ricor
e.g. -do_block align
With this option, any 'optional block' can be applied in its
default position. This includes the following blocks, along with
their default positions:
align : after tlrc, before volreg
despike : first (between tcat and tshift)
empty : NO DEFAULT, cannot be applied via -do_block
ricor : just after despike (else first)
tlrc : before volreg, after align
Any block not included in -blocks can be added via this option
(except for 'empty').
See also '-blocks', as well as the "PROCESSING BLOCKS" section of
the -help output.
-dsets dset1 dset2 ... : (REQUIRED) specify EPI run datasets
e.g. -dsets Elvis_run1+orig Elvis_run2+orig Elvis_run3+orig
e.g. -dsets Elvis_run*.HEAD
The user must specify the list of EPI run datasets to analyze.
When the runs are processed, they will be written to start with
run 1, regardless of whether the input runs were just 6, 7 and 21.
Note that when using a wildcard it is essential for the EPI
datasets to be alphabetical, as that is how the shell will list
them on the command line. For instance, epi_run1+orig through
epi_run11+orig is not alphabetical. If they were specified via
wildcard their order would end up as run1 run10 run11 run2 ...
Note also that when using a wildcard it is essential to specify
the datasets suffix, so that the shell doesn't put both the .BRIK
and .HEAD filenames on the command line (which would make it twice
as many runs of data).
-execute : execute the created processing script
If this option is applied, not only will the processing script be
created, but it will then be executed in the "suggested" manner,
such as via:
tcsh -xef proc.sb23 |& tee output.proc.sb23
Note that it will actually use the bash format of the command,
since the system command (C and therefore python) uses /bin/sh.
tcsh -xef proc.sb23 2>&1 | tee output.proc.sb23
-keep_rm_files : do not have script delete rm.* files at end
e.g. -keep_rm_files
The output script may generate temporary files in a block, which
would be given names with prefix 'rm.'. By default, those files
are deleted at the end of the script. This option blocks that
deletion.
-move_preproc_files : move preprocessing files to preproc.data dir
At the end of the output script, create a 'preproc.data' directory,
and move most of the files there (dfile, outcount, pb*, rm*).
See also -remove_preproc_files.
-no_proc_command : do not print afni_proc.py command in script
e.g. -no_proc_command
If this option is applied, the command used to generate the output
script will be stored at the end of the script.
-out_dir DIR : specify the output directory for the script
e.g. -out_dir ED_results
default: SUBJ.results
The AFNI processing script will create this directory and perform
all processing in it.
-remove_preproc_files : delete pre-processed data
At the end of the output script, delete the intermediate data (to
save disk space). Delete dfile*, outcount*, pb* and rm*.
See also -move_preproc_files.
-script SCRIPT_NAME : specify the name of the resulting script
e.g. -script ED.process.script
default: proc_subj
The output of this program is a script file. This option can be
used to specify the name of that file.
See also -scr_overwrite, -subj_id.
-scr_overwrite : overwrite any existing script
e.g. -scr_overwrite
If the output script file already exists, it will be overwritten
only if the user applies this option.
See also -script.
-sep_char CHAR : apply as separation character in filenames
e.g. -sep_char _
default: .
The separation character is used in many output filenames, such as
the default '.' in:
pb04.Nancy.r07.scale+orig.BRIK
If (for some crazy reason) an underscore (_) character would be
preferable, the result would be:
pb04_Nancy_r07_scale+orig.BRIK
If "-sep_char _" is applied, so is -subj_curly.
See also -subj_curly.
-subj_curly : apply $subj as ${subj}
The subject ID is used in dataset names is typically used without
curly brackets (i.e. $subj). If something is done where this would
result in errors (e.g. "-sep_char _"), the curly brackets might be
useful to delimit the variable (i.e. ${subj}).
Note that this option is automatically applied in the case of
"-sep_char _".
See also -sep_char.
-subj_id SUBJECT_ID : specify the subject ID for the script
e.g. -subj_id elvis
default: SUBJ
The subject ID is used in dataset names and in the output directory
name (unless -out_dir is used). This option allows the user to
apply an appropriate naming convention.
-verb LEVEL : specify the verbosity of this script
e.g. -verb 2
default: 1
Print out extra information during execution.
------------ block options (in default block order) ------------
These options pertain to individual processing blocks. Each option
starts with the block name.
-tcat_remove_first_trs NUM : specify how many TRs to remove from runs
e.g. -tcat_remove_first_trs 3
default: 0
Since it takes several seconds for the magnetization to reach a
steady state (at the beginning of each run), the initial TRs of
each run may have values that are significantly greater than the
later ones. This option is used to specify how many TRs to
remove from the beginning of every run.
-despike_mask : allow Automasking in 3dDespike
By default, -nomask is applied to 3dDespike. Since anatomical
masks will probably not be contained within the Automask operation
of 3dDespike (which uses methods akin to '3dAutomask -dilate 4'),
it is left up to the user to speed up this operation via masking.
Note that the only case in which this should be done is when
applying the EPI mask to the regression.
Please see '3dDespike -help' and '3dAutomask -help' for more
information.
-despike_opts_3dDes OPTS... : specify additional options for 3dDespike
e.g. -despike_opts_3dDes -nomask -ignore 2
By default, 3dDespike is used with only -prefix and -nomask
(unless -despike_mask is applied). Any other options must be
applied via -despike_opts_3dDes.
Note that the despike block is not applied by default. To apply
despike in the processing script, use either '-do_block despike'
or '-blocks ... despike ...'.
Please see '3dDespike -help' for more information.
See also '-do_blocks', '-blocks', '-despike_mask'.
-ricor_datum DATUM : specify output data type from ricor block
e.g. -ricor_datum float
By default, if the input is unscaled shorts, the output will be
unscaled shorts. Otherwise the output will be floats.
The user may override this default with the -ricor_datum option.
Currently only 'short' and 'float' are valid parameters.
Note that 3dREMLfit only outputs floats at the moment. Recall
that the down-side of float data is that it takes twice the disk
space, compared with shorts (scaled or unscaled).
Please see '3dREMLfit -help' for more information.
-ricor_polort POLORT : set the polynomial degree for 3dREMLfit
e.g. -ricor_polort 4
default: 1 + floor(run_length / 75.0)
The default polynomial degree to apply during the 'ricor' block is
similar to that of the 'regress' block, but is based on twice the
run length (and so should be almost twice as large). This is to
account for motion, since volreg has typically not happened yet.
Use -ricor_polort to override the default.
-ricor_regress_method METHOD : process per-run or across-runs
e.g. -ricor_regress_method across-runs
default: NONE: this option is required for a 'ricor' block
* valid METHOD parameters: per-run, across-runs
The cardiac and respiratory signals can be regressed out of each
run separately, or out of all runs at once. The user must choose
the method, there is no default.
See "RETROICOR NOTE" for more details about the methods.
-ricor_regress_solver METHOD : regress using OLSQ or REML
e.g. -ricor_regress_solver REML
default: OLSQ
* valid METHOD parameters: OLSQ, REML
Use this option to specify the regression method for removing the
cardiac and respiratory signals. The default method is ordinary
least squares, removing the "best fit" of the card/resp signals
from the data (also subject to the polort baseline).
To apply the REML (REstricted Maximum Likelihood) method, use this
option.
Note that 3dREMLfit is used for the regression in either case,
particularly since the regressors are slice-based (they are
different for each slice).
Please see '3dREMLfit -help' for more information.
-ricor_regs REG1 REG2 ... : specify ricor regressors (1 per run)
e.g. -ricor_regs slibase*.1D
This option is required with a 'ricor' processing block.
The expected format of the regressor files for RETROICOR processing
is one file per run, where each file contains a set of regressors
per slice. If there are 5 runs and 27 slices, and if there are 13
regressors per slice, then there should be 5 files input, each with
351 (=27*13) columns.
This format is based on the output of RetroTS.m, included in the
AFNI distribution (as part of the matlab package), by Z Saad.
-ricor_regs_nfirst NFIRST : ignore the first regressor timepoints
e.g. -ricor_regs_nfirst 2
default: 0
This option is similar to -tcat_remove_first_trs. It is used to
remove the first few TRs from the -ricor_regs regressor files.
Since it is likely that the number of TRs in the ricor regressor
files matches the number of TRs in the original input dataset (via
-dsets), it is likely that -ricor_regs_nfirst should match
-tcat_remove_first_trs.
See also '-tcat_remove_first_trs', '-ricor_regs', '-dsets'.
-tshift_align_to TSHIFT OP : specify 3dTshift alignment option
e.g. -tshift_align_to -slice 14
default: -tzero 0
By default, each time series is aligned to the beginning of the
TR. This option allows the users to change the alignment, and
applies the option parameters directly to the 3dTshift command
in the output script.
It is likely that the user will use either '-slice SLICE_NUM' or
'-tzero ZERO_TIME'.
Note that when aligning to an offset other than the beginning of
the TR, and when applying the -regress_stim_files option, then it
may be necessary to also apply -regress_stim_times_offset, to
offset timing for stimuli to later within each TR.
Please see '3dTshift -help' for more information.
See also '-regress_stim_times_offset'.
-tshift_interp METHOD : specify the interpolation method for tshift
e.g. -tshift_interp -Fourier
e.g. -tshift_interp -cubic
default -quintic
Please see '3dTshift -help' for more information.
-tshift_opts_ts OPTS ... : specify extra options for 3dTshift
e.g. -tshift_opts_ts -tpattern alt+z
This option allows the user to add extra options to the 3dTshift
command. Note that only one -tshift_opts_ts should be applied,
which may be used for multiple 3dTshift options.
Please see '3dTshift -help' for more information.
-tlrc_anat : run @auto_tlrc on '-copy_anat' dataset
e.g. -tlrc_anat
After the regression block, run @auto_tlrc on the anatomical
dataset provided by '-copy_anat'. By default, warp the anat to
align with TT_N27+tlrc, unless the '-tlrc_base' option is given.
The -copy_anat option specifies which anatomy to transform.
** Note, use of this option has the same effect as application of the
'tlrc' block.
Please see '@auto_tlrc -help' for more information.
See also -copy_anat, -tlrc_base, -tlrc_no_ss and the 'tlrc' block.
-tlrc_base BASE_DSET : run "@auto_tlrc -base BASE_DSET"
e.g. -tlrc_base TT_icbm452+tlrc
default: -tlrc_base TT_N27+tlrc
This option is used to supply an alternate -base dataset for
@auto_tlrc. Otherwise, TT_N27+tlrc will be used.
Note that the default operation of @auto_tlrc is to "skull strip"
the input dataset. If this is not appropriate, consider also the
'-tlrc_no_ss' option.
Please see '@auto_tlrc -help' for more information.
See also -tlrc_anat, -tlrc_no_ss.
-tlrc_no_ss : add the -no_ss option to @auto_tlrc
e.g. -tlrc_no_ss
This option is used to tell @auto_tlrc not to perform the skull
strip operation.
Please see '@auto_tlrc -help' for more information.
-tlrc_rmode RMODE : apply RMODE resampling in @auto_tlrc
e.g. -tlrc_rmode NN
This option is used to apply '-rmode RMODE' in @auto_tlrc.
Please see '@auto_tlrc -help' for more information.
-tlrc_suffix SUFFIX : apply SUFFIX to result of @auto_tlrc
e.g. -tlrc_suffix auto_tlrc
This option is used to apply '-suffix SUFFIX' in @auto_tlrc.
Please see '@auto_tlrc -help' for more information.
-align_epi_ext_dset DSET : specify dset/brick for align_epi_anat EPI
e.g. -align_epi_ext_dset subj10/epi_r01+orig'[0]'
This option allows the user to specify an external volume for the
EPI and base used in align_epi_anat.py in the align block. The
user should apply sub-brick selection if the dataset has more than
one volume. This volume would be used for both the -epi and the
-epi_base options in align_epi_anat.py.
This user might want to align to an EPI volume that is not in the
processing stream for the case where there is not sufficient EPI
contrast left after the magnetization has reached a steady state.
Perhaps volume 0 has sufficient contrast for alignment, but is not
appropriate for analysis. In such a case, the user may elect to
align to volume 0, while excluding it from the analysis as part of
the first volumes removed in -tcat_remove_first_trs.
e.g. -dsets subj10/epi_r*_orig.HEAD
-tcat_remove_first_trs 3
-align_epi_ext_dset subj10/epi_r01+orig'[0]'
-volreg_align_to first
Note that if the anatomy were acquired after the EPI, the user may
want to still align it to the beginning of some run, and all the
EPIs to a time point close to that.
Please see "align_epi_anat.py -help" for more information.
-align_opts_aea OPTS ... : specify extra options for align_epi_anat.py
e.g. -align_opts_aea -big_move
e.g. -align_opts_aea -giant_move -AddEdge -epi_strip 3dAutomask
This option allows the user to add extra options to the alignment
command, align_epi_anat.py.
Note that only one -align_opts_aea option should be given, with
possibly many parameters to be passed on to align_epi_anat.py.
Please see "align_epi_anat.py -help" for more information.
-volreg_align_e2a : align EPI to anatomy at volreg step
This option is used to align the EPI data to match the anatomy.
It is done by applying the inverse of the anatomy to EPI alignment
matrix to the EPI data at the volreg step. The 'align' processing
block is required.
At the 'align' block, the anatomy is aligned to the EPI data.
When applying the '-volreg_align_e2a' option, the inverse of that
a2e transformation (so now e2a) is instead applied to the EPI data.
Note that this e2a transformation is catenated with the volume
registration transformations, so that the EPI data is still only
resampled the one time. If the user requests -volreg_tlrc_warp,
the +tlrc transformation will also be applied at that step in a
single transformation.
See also the 'align' block and '-volreg_tlrc_warp'.
-volreg_align_to POSN : specify the base position for volume reg
e.g. -volreg_align_to last
default: third
This option takes 'first', 'third' or 'last' as a parameter.
It specifies whether the EPI volumes are registered to the first
or third volume (of the first run) or the last volume (of the last
run). The choice of 'first' or 'third' should correspond to when
the anatomy was acquired before the EPI data. The choice of 'last'
should correspond to when the anatomy was acquired after the EPI
data.
The default of 'third' was chosen to go a little farther into the
steady state data.
Note that this is done after removing any volumes in the initial
tcat operation.
Please see '3dvolreg -help' for more information.
See also -tcat_remove_first_trs, -volreg_base_ind and
-volreg_base_dset.
-volreg_base_dset DSET : specify dset/sub-brick for volreg base
e.g. -volreg_base_dset subj10/vreg_base+orig'[4]'
This option allows the user to specify an external dataset for the
volreg base. The user should apply sub-brick selection if the
dataset has more than one volume.
-volreg_base_ind RUN SUB : specify run/sub-brick indices for base
e.g. -volreg_base_ind 10 123
default: 0 0
This option allows the user to specify exactly which dataset and
sub-brick to use as the base registration image. Note that the
SUB index applies AFTER the removal of pre-steady state images.
* The RUN number is 1-based, matching the run list in the output
shell script. The SUB index is 0-based, matching the sub-brick of
EPI time series #RUN. Yes, one is 1-based, the other is 0-based.
Life is hard.
The user can apply only one of the -volreg_align_to and
-volreg_base_ind options.
See also -volreg_align_to, -tcat_remove_first_trs and
-volreg_base_dset.
-volreg_interp METHOD : specify the interpolation method for volreg
e.g. -volreg_interp -quintic
e.g. -volreg_interp -Fourier
default -cubic
Please see '3dvolreg -help' for more information.
-volreg_opts_vr OPTS ... : specify extra options for 3dvolreg
e.g. -volreg_opts_vr -noclip -nomaxdisp
This option allows the user to add extra options to the 3dvolreg
command. Note that only one -volreg_opts_vr should be applied,
which may be used for multiple 3dvolreg options.
Please see '3dvolreg -help' for more information.
-volreg_regress_per_run : regress motion parameters from each run
default: regress motion parameters catenated across runs
By default, motion parameters from the volreg block are catenated
across all runs, providing 6 (assuming 3dvolreg) regressors of no
interest in the regression block.
With -volreg_regress_per_run, the motion parameters from each run
are used as separate regressors, providing a total of (6 * nruns)
regressors.
This allows for the magnitudes of the regressors to vary over each
run, rather than using a single (best) magnitude over all runs.
So more motion-correlated variance can be accounted for, at the
cost of the extra degrees of freedom (6*(nruns-1)).
-volreg_tlrc_adwarp : warp EPI to +tlrc space at end of volreg step
default: stay in +orig space
With this option, the EPI data will be warped to standard space
(via adwarp) at the end of the volreg processing block. Further
processing through regression will be done in standard space.
This option is useful for applying a manual Talairach transform,
which does not work with -volreg_tlrc_warp. To apply one from
@auto_tlrc, -volreg_tlrc_warp is recommended.
The resulting voxel grid is the minimum dimension, truncated to 3
significant bits. See -volreg_warp_dxyz for details.
Note: this step requires a transformed anatomy, which can come from
the -tlrc_anat option or from -copy_anat importing an existing one.
Please see 'WARP TO TLRC NOTE' above, for additional details.
See also -volreg_tlrc_warp, -volreg_warp_dxyz, -tlrc_anat,
-copy_anat.
-volreg_tlrc_warp : warp EPI to +tlrc space at volreg step
default: stay in +orig space
With this option, the EPI data will be warped to standard space
in the volreg processing block. All further processing through
regression will be done in standard space.
Warping is done with volreg to apply both the volreg and tlrc
transformations in a single step (so a single interpolation of the
EPI data). The volreg transformations (for each volume) are stored
and multiplied by the +tlrc transformation, while the volume
registered EPI data is promptly ignored.
The volreg/tlrc transformation is then applied as a single warp to
the unregistered data.
Note that this is only possible when using @auto_tlrc, not the 12
piece manual transformation. See -volreg_tlrc_adwarp for applying
a manual transformation.
The resulting voxel grid is the minimum dimension, truncated to 3
significant bits. See -volreg_warp_dxyz for details.
Note: this step requires a transformed anatomy, which can come from
the -tlrc_anat option or from -copy_anat importing an existing one.
Please see 'WARP TO TLRC NOTE' above, for additional details.
See also -volreg_tlrc_adwarp, -volreg_warp_dxyz, -tlrc_anat,
-copy_anat.
-volreg_warp_dxyz DXYZ : grid dimensions for _align_e2a or _tlrc_warp
e.g. -volreg_warp_dxyz 3.5
default: min dim truncated to 3 significant bits
(see description, below)
This option allows the user to specify the grid size for output
datasets from the -volreg_tlrc_warp and -volreg_align_e2a options.
In either case, the output grid will be isotropic voxels (cubes).
By default, DXYZ is the minimum input dimension, truncated to
3 significant bits (for integers, starts affecting them at 9, as
9 requires 4 bits to represent).
Some examples:
---------------------------- (integer range, so >= 4)
8.00 ... 9.99 --> 8.0
...
4.00 ... 4.99 --> 4.0
---------------------------- (3 significant bits)
2.50 ... 2.99 --> 2.5
2.00 ... 2.49 --> 2.0
1.75 ... 1.99 --> 1.75
1.50 ... 1.74 --> 1.5
1.25 ... 1.49 --> 1.25
1.00 ... 1.24 --> 1.0
0.875 ... 0.99 --> 0.875
0.75 ... 0.874 --> 0.75
0.625 ... 0.74 --> 0.625
0.50 ... 0.624 --> 0.50
0.4375 ... 0.49 --> 0.4375
0.375 ... 0.4374 --> 0.375
...
-volreg_zpad N_SLICES : specify number of slices for -zpad
e.g. -volreg_zpad 4
default: -volreg_zpad 1
This option allows the user to specify the number of slices applied
via the -zpad option to 3dvolreg.
-blur_filter FILTER : specify 3dmerge filter option
e.g. -blur_filter -1blur_rms
default: -1blur_fwhm
This option allows the user to specify the filter option from
3dmerge. Note that only the filter option is set here, not the
filter size. The two parts were separated so that users might
generally worry only about the filter size.
Please see '3dmerge -help' for more information.
See also -blur_size.
-blur_in_automask : apply 3dBlurInMask -automask
This option forces use of 3dBlurInMask -automask, regardless of
whether other masks exist and are being applied.
Note that one would not want to apply -automask via -blur_opts_BIM,
as that might result in failure because of multiple -mask options.
Note that -blur_in_automask implies '-blur_in_mask yes'.
Please see '3dBlurInMask -help' for more information.
See also -blur_in_mask, -blur_opts_BIM.
-blur_in_mask yes/no : specify whether to restrict blur to a mask
e.g. -blur_in_mask yes
default: no
This option allows the user to specify whether to use 3dBlurInMask
instead of 3dmerge for blurring.
Note that the algorithms are a little different, and 3dmerge comes
out a little more blurred.
Note that 3dBlurInMask uses only FWHM kernel size units, so the
-blur_filter should be either -1blur_fwhm or -FWHM.
Please see '3dBlurInMask -help' for more information.
Please see '3dmerge -help' for more information.
See also -blur_filter.
-blur_opts_BIM OPTS ... : specify extra options for 3dBlurInMask
e.g. -blur_opts_BIM -automask
This option allows the user to add extra options to the 3dBlurInMask
command. Only one -blur_opts_BIM should be applied, which may be
used for multiple 3dBlurInMask options.
This option is only useful when '-blur_in_mask yes' is applied.
Please see '3dBlurInMask -help' for more information.
See also -blur_in_mask.
-blur_opts_merge OPTS ... : specify extra options for 3dmerge
e.g. -blur_opts_merge -2clip -20 50
This option allows the user to add extra options to the 3dmerge
command. Note that only one -blur_opts_merge should be applied,
which may be used for multiple 3dmerge options.
Please see '3dmerge -help' for more information.
-blur_size SIZE_MM : specify the size, in millimeters
e.g. -blur_size 6.0
default: 4
This option allows the user to specify the size of the blur used
by 3dmerge. It is applied as the 'bmm' parameter in the filter
option (such as -1blur_fwhm).
Note the relationship between blur sizes, as used in 3dmerge:
sigma = 0.57735027 * rms = 0.42466090 * fwhm
(implying rms = 1.359556 * fwhm)
Please see '3dmerge -help' for more information.
See also -blur_filter.
-mask_apply TYPE : specify which mask to apply in regression
e.g. -mask_apply group
If possible, masks will be made for the EPI data, the subject
anatomy, the group anatomy and EPI warp extents. This option is
used to specify which of those masks to apply to the regression.
Valid choices: epi, anat, group, extents.
A subject 'anat' mask will be created if the EPI anat anatomy are
aligned, or if the EPI data is warped to standard space via the
anat transformation. In any case, a skull-stripped anat will exist.
A 'group' anat mask will be created if the 'tlrc' block is used
(via the -block or -tlrc_anat options). In such a case, the anat
template will be made into a binary mask.
This option makes -regress_apply_mask obsolete.
See "MASKING NOTE" and "DEFAULTS" for details.
See also -blocks.
-mask_type TYPE : specify 'union' or 'intersection' mask type
e.g. -mask_type intersection
default: union
This option is used to specify whether the mask applied to the
analysis is the union of masks from each run, or the intersection.
The only valid values for TYPE are 'union' and 'intersection'.
This is not how to specify whether a mask is created, that is
done via the 'mask' block with the '-blocks' option.
Please see '3dAutomask -help', '3dMean -help' or '3dcalc -help'.
See also -mask_dilate, -blocks.
-mask_dilate NUM_VOXELS : specify the automask dilation
e.g. -mask_dilate 3
default: 1
By default, the masks generated from the EPI data are dilated by
1 step (voxel), via the -dilate option in 3dAutomask. With this
option, the user may specify the dilation. Valid integers must
be at least zero.
Note that 3dAutomask dilation is a little different from the
natural voxel-neighbor dilation.
Please see '3dAutomask -help' for more information.
See also -mask_type.
-scale_max_val MAX : specify the maximum value for scaled data
e.g. -scale_max_val 1000
default 200
The scale step multiples the time series for each voxel by a
scalar so that the mean for that particular run is 100 (allowing
interpretation of EPI values as a percentage of the mean).
Values of 200 represent a 100% change above the mean, and so can
probably be considered garbage (or the voxel can be considered
non-brain). The output values are limited so as not to sacrifice
the precision of the values of short datasets. Note that in a
short (2-byte integer) dataset, a large range of values means
bits of accuracy are lost for the representation.
No max will be applied if MAX is <= 100.
Please see 'DATASET TYPES' in the output of '3dcalc -help'.
See also -scale_no_max.
-scale_no_max : do not apply a limit to the scaled values
The default limit for scaled data is 200. Use of this option will
remove any limit from being applied.
A limit on the scaled data is highly encouraged when working with
'short' integer data, especially when not applying a mask.
See also -scale_max_val.
-regress_3dD_stop : 3dDeconvolve should stop after X-matrix gen
Use this option to tell 3dDeconvolve to stop after generating the
X-matrix (via -x1D_stop). This is useful if the user only wishes
to run the regression through 3dREMLfit.
See also -regress_reml_exec.
-regress_apply_mask : apply the mask during scaling and regression
By default, any created union mask is not applied to the analysis.
Use this option to apply it.
** This option is essentially obsolete. Please consider -mask_apply
as a preferable option to choose which mask to apply.
See "MASKING NOTE" and "DEFAULTS" for details.
See also -blocks, -mask_apply.
-regress_basis BASIS : specify the regression basis function
e.g. -regress_basis 'BLOCK(4,1)'
e.g. -regress_basis 'BLOCK(5)'
e.g. -regress_basis 'TENT(0,14,8)'
default: GAM
This option is used to set the basis function used by 3dDeconvolve
in the regression step. This basis function will be applied to
all user-supplied regressors (please let me know if there is need
to apply different basis functions to different regressors).
** Note that use of dmBLOCK requires -stim_times_AM1 (or AM2). Until
that is handled properly by afni_proc.py, users will need to edit
the processing script, changing -stim_times to the appropriate
_AM1 or _AM2.
Please see '3dDeconvolve -help' for more information, or the link:
http://afni.nimh.nih.gov/afni/doc/misc/3dDeconvolveSummer2004
See also -regress_basis_normall, -regress_stim_times.
-regress_basis_normall NORM : specify the magnitude of basis functions
e.g. -regress_basis_normall 1.0
This option is used to set the '-basis_normall' parameter in
3dDeconvolve. It specifies the height of each basis function.
For the example basis functions, -basis_normall is not recommended.
Please see '3dDeconvolve -help' for more information.
See also -regress_basis.
-regress_censor_motion LIMIT : censor TRs with excessive motion
e.g. -regress_censor_motion 1.0
This option is used to censor TRs where the subject moved too much.
"Too much" is decided by taking the derivative of the motion
parameters (ignoring shifts between runs) and the sqrt(sum squares)
per TR. If this Euclidean Norm exceeds the given LIMIT, the TR
will be censored.
This option will result in the creation of 3 censor files:
motion_$subj_censor.1D
motion_$subj_CENSORTR.txt
motion_$subj_enorm.1D
motion_$subj_censor.1D is a 0/1 columnar file to be applied to
3dDeconvolve via -censor. A row with a 1 means to include that TR,
while a 0 means to exclude (censor) it.
motion_$subj_CENSORTR.txt is a short text file listing censored
TRs, suitable for use with the -CENSORTR option in 3dDeconvolve.
The -censor option is the one applied however, so this file is not
used, but may be preferable for users to have a quick peek at.
motion_$subj_enorm.1D is the time series that the LIMIT is applied
to in deciding which TRs to censor. It is the Euclidean norm of
the derivatives of the motion parameters. Plotting this will give
users a visual indication of why TRs were censored.
By default, the TR prior to the large motion derivative will also
be censored. To turn off that behavior, use -regress_censor_prev
with parameter 'no'.
Please see '1d_tool.py -help' for information on censoring motion.
See also -regress_censor_prev.
-regress_censor_prev yes/no : censor TRs preceding large motion
default: -regress_censor_prev yes
Since motion spans two TRs, the derivative is not quite enough
information to decide whether it is more appropriate to censor
the earlier or later TR. To error on the safe side, many users
choose to censor both.
Use this option to specify whether to include the previous TR
when censoring.
By default this option is applied as 'yes'. Users may elect not
not to censor the previous TRs by setting this to 'no'.
See also -regress_censor_motion.
-regress_est_blur_epits : estimate the smoothness of the EPI data
This option specifies to run 3dFWHMx on each of the EPI datasets
used for regression, the results of which are averaged. These blur
values are saved to the file blur_est.$subj.1D, along with any
similar output from errts.
These blur estimates may be input to AlphaSim, for any multiple
testing correction done for this subject. If AlphaSim is run at
the group level, it is reasonable to average these estimates
across all subjects (assuming they were scanned with the same
protocol and at the same scanner).
The mask block is required for this operation (without which the
estimates are not reliable).
Please see '3dFWHMx -help' for more information.
See also -regress_est_blur_errts.
-regress_est_blur_errts : estimate the smoothness of the errts
This option specifies to run 3dFWHMx on the errts dataset, output
from the regression (by 3dDeconvolve).
These blur estimates may be input to AlphaSim, for any multiple
testing correction done for this subject. If AlphaSim is run at
the group level, it is reasonable to average these estimates
across all subjects (assuming they were scanned with the same
protocol and at the same scanner).
Note that the errts blur estimates should be not only slightly
more accurate than the epits blur estimates, but they should be
slightly smaller, too (which is beneficial).
The mask block is required for this operation (without which the
estimates are not reliable).
Please see '3dFWHMx -help' for more information.
See also -regress_est_blur_epits.
-regress_errts_prefix PREFIX : specify a prefix for the -errts option
e.g. -regress_fitts_prefix errts
This option is used to add a -errts option to 3dDeconvolve. As
with -regress_fitts_prefix, only the PREFIX is specified, to which
the subject ID will be added.
Please see '3dDeconvolve -help' for more information.
See also -regress_fitts_prefix.
-regress_fitts_prefix PREFIX : specify a prefix for the -fitts option
e.g. -regress_fitts_prefix model_fit
default: fitts
By default, the 3dDeconvolve command in the script will be given
a '-fitts fitts' option. This option allows the user to change
the prefix applied in the output script.
The -regress_no_fitts option can be used to eliminate use of -fitts.
Please see '3dDeconvolve -help' for more information.
See also -regress_no_fitts.
-regress_global_times : specify -stim_times as global times
default: 3dDeconvolve figures it out, if it can
By default, the 3dDeconvolve determines whether -stim_times files
are local or global times by the first line of the file. If it
contains at least 2 times (which include '*' characters), it is
considered as local_times, otherwise as global_times.
The -regress_global_times option is mostly added to be symmetric
with -regress_local_times, as the only case where it would be
needed is when there are other times in the first row, but the
should still be viewed as global.
See also -regress_local_times.
-regress_local_times : specify -stim_times as local times
default: 3dDeconvolve figures it out, if it can
By default, the 3dDeconvolve determines whether -stim_times files
are local or global times by the first line of the file. If it
contains at least 2 times (which include '*' characters), it is
considered as local_times, otherwise as global_times.
In the case where the first run has only 1 stimulus (maybe even
every run), the user would need to put an extra '*' after the
first stimulus time. If the first run has no stimuli, then two
would be needed ('* *'), but only for the first run.
Since this may get confusing, being explicit by adding this option
is a reasonable thing to do.
See also -regress_global_times.
-regress_iresp_prefix PREFIX : specify a prefix for the -iresp option
e.g. -regress_iresp_prefix model_fit
default: iresp
This option allows the user to change the -iresp prefix applied in
the 3dDeconvolve command of the output script.
By default, the 3dDeconvolve command in the script will be given a
set of '-iresp iresp' options, one per stimulus type, unless the
regression basis function is GAM. In the case of GAM, the response
form is assumed to be known, so there is no need for -iresp.
The stimulus label will be appended to this prefix so that a sample
3dDeconvolve option might look one of these 2 examples:
-iresp 7 iresp_stim07
-iresp 7 model_fit_donuts
The -regress_no_iresp option can be used to eliminate use of -iresp.
Please see '3dDeconvolve -help' for more information.
See also -regress_no_iresp, -regress_basis.
-regress_make_ideal_sum IDEAL.1D : create IDEAL.1D file from regressors
e.g. -regress_make_ideal_sum ideal_all.1D
If the -regress_basis function is a single parameter function
(either GAM or some form of BLOCK), then this option can be
applied to create an ideal response curve which is the sum of
the individual stimulus response curves.
Use of this option will add a 3dTstat command to sum the regressor
(of interest) columns of the 1D X-matrix, output by 3dDeconvolve.
This is similar to the default behavior of creating ideal_STIM.1D
files for each stimulus label, STIM.
Please see '3dDeconvolve -help' and '3dTstat -help'.
See also -regress_basis, -regress_no_ideals.
-regress_motion_file FILE.1D : use FILE.1D for motion parameters
e.g. -regress_motion_file motion.1D
Particularly if the user performs motion correction outside of
afni_proc.py, they may wish to specify a motion parameter file
other than dfile.rall.1D (the default generated in the volreg
block).
If the motion parameter file is in an external directory, the
user should copy it via the -copy_files option.
See also -copy_files.
-regress_no_fitts : do not supply -fitts to 3dDeconvolve
e.g. -regress_no_fitts
This option prevents the program from adding a -fitts option to
the 3dDeconvolve command in the output script.
See also -regress_fitts_prefix.
-regress_no_ideals : do not generate ideal response curves
e.g. -regress_no_ideals
By default, if the GAM or BLOCK basis function is used, ideal
response curve files are generated for each stimulus type (from
the output X matrix using '3dDeconvolve -x1D'). The names of the
ideal response function files look like 'ideal_LABEL.1D', for each
stimulus label, LABEL.
This option is used to suppress generation of those files.
See also -regress_basis, -regress_stim_labels.
-regress_no_iresp : do not supply -iresp to 3dDeconvolve
e.g. -regress_no_iresp
This option prevents the program from adding a set of -iresp
options to the 3dDeconvolve command in the output script.
By default -iresp will be used unless the basis function is GAM.
See also -regress_iresp_prefix, -regress_basis.
-regress_no_mask : do not apply the mask in regression
** This is now the default, making the option unnecessary.
This option prevents the program from applying the mask dataset
in the scaling or regression steps.
If the user does not want to apply a mask in the regression
analysis, but wants the full_mask dataset for other reasons
(such as computing blur estimates), this option can be used.
See also -regress_est_blur_epits, -regress_est_blur_errts.
-regress_no_motion : do not apply motion params in 3dDeconvolve
e.g. -regress_no_motion
This option prevents the program from adding the registration
parameters (from volreg) to the 3dDeconvolve command.
-regress_opts_3dD OPTS ... : specify extra options for 3dDeconvolve
e.g. -regress_opts_3dD -gltsym ../contr/contrast1.txt \
-glt_label 1 FACEvsDONUT \
-xjpeg Xmat
This option allows the user to add extra options to the 3dDeconvolve
command. Note that only one -regress_opts_3dD should be applied,
which may be used for multiple 3dDeconvolve options.
Please see '3dDeconvolve -help' for more information, or the link:
http://afni.nimh.nih.gov/afni/doc/misc/3dDeconvolveSummer2004
-regress_polort DEGREE : specify the polynomial degree of baseline
e.g. -regress_polort 2
default: 1 + floor(run_length / 150.0)
3dDeconvolve models the baseline for each run separately, using
Legendre polynomials (by default). This option specifies the
degree of polynomial. Note that this will create DEGREE * NRUNS
regressors.
The default is computed from the length of a run, in seconds, as
shown above. For example, if each run were 320 seconds, then the
default polort would be 3 (cubic).
Please see '3dDeconvolve -help' for more information.
-regress_reml_exec : execute 3dREMLfit, matching 3dDeconvolve cmd
3dDeconvolve automatically creates a 3dREMLfit command script to
match the regression model of 3dDeconvolve. Via this option, the
user can have that command executed.
Note that the X-matrix used in 3dREMLfit is actually generated by
3dDeconvolve. The 3dDeconvolve command generates both the X-matrix
and the 3dREMLfit command script, and so it must be run regardless
of whether it actually performs the regression.
To terminate 3dDeconvolve after creation of the X-matrix and
3dREMLfit command script, apply -regress_3dD_stop.
See also -regress_3dD_stop.
-regress_RONI IND1 ... : specify a list of regressors of no interest
e.g. -regress_RONI 1 17 22
Use this option flag regressors as ones of no interest, meaning
they are applied to the baseline (for full-F) and the corresponding
beta weights are not output (by default at least).
The indices in the list should match those given to 3dDeconvolve.
They start at 1 first with the main regressors, and then with any
extra regressors (given via -regress_extra_stim_files). Note that
these do not apply to motion regressors.
The user is encouraged to check the 3dDeconvolve command in the
processing script, to be sure they are applied correctly.
-regress_stim_labels LAB1 ... : specify labels for stimulus types
e.g. -regress_stim_labels houses faces donuts
default: stim01 stim02 stim03 ...
This option is used to apply a label to each stimulus type. The
number of labels should equal the number of files used in the
-regress_stim_times option, or the total number of columns in the
files used in the -regress_stim_files option.
These labels will be applied as '-stim_label' in 3dDeconvolve.
Please see '3dDeconvolve -help' for more information.
See also -regress_stim_times, -regress_stim_labels.
-regress_stim_times FILE1 ... : specify files used for -stim_times
e.g. -regress_stim_times ED_stim_times*.1D
e.g. -regress_stim_times times_A.1D times_B.1D times_C.1D
3dDeconvolve will be run using '-stim_times'. This option is
used to specify the stimulus timing files to be applied, one
file per stimulus type. The order of the files given on the
command line will be the order given to 3dDeconvolve. Each of
these timing files will be given along with the basis function
specified by '-regress_basis'.
The user must specify either -regress_stim_times or
-regress_stim_files if regression is performed, but not both.
Note the form of the files is one row per run. If there is at
most one stimulus per run, please add a trailing '*'.
Labels may be specified using the -regress_stim_labels option.
These two examples of such files are for a 3-run experiment. In
the second example, there is only 1 stimulus at all, occurring in
run #2.
e.g. 0 12.4 27.3 29
*
30 40 50
e.g. *
20 *
*
Please see '3dDeconvolve -help' for more information, or the link:
http://afni.nimh.nih.gov/afni/doc/misc/3dDeconvolveSummer2004
See also -regress_stim_files, -regress_stim_labels, -regress_basis,
-regress_basis_normall, -regress_polort.
-regress_stim_files FILE1 ... : specify TR-locked stim files
e.g. -regress_stim_times ED_stim_file*.1D
e.g. -regress_stim_times stim_A.1D stim_B.1D stim_C.1D
Without the -regress_use_stim_files option, 3dDeconvolve will be
run using '-stim_times', not '-stim_file'. The user can still
specify the 3dDeconvolve -stim_file files here, but they would
then be converted to -stim_times files using the script,
make_stim_times.py .
It might be more educational for the user to run make_stim_times.py
outside afni_proc.py (such as was done before example 2, above), or
to create the timing files directly.
Each given file can be for multiple stimulus classes, where one
column is for one stim class, and each row represents a TR. So
each file should have NUM_RUNS * NUM_TRS rows.
The stim_times files will be labeled stim_times.NN.1D, where NN
is the stimulus index.
Note that if the stimuli were presented at a fixed time after
the beginning of a TR, the user should consider the option,
-regress_stim_times_offset, to apply that offset.
---
If the -regress_use_stim_files option is provided, 3dDeconvolve
will be run using each stim_file as a regressor. The order of the
regressors should match the order of any labels, provided via the
-regress_stim_labels option.
Please see '3dDeconvolve -help' for more information, or the link:
http://afni.nimh.nih.gov/afni/doc/misc/3dDeconvolveSummer2004
See also -regress_stim_times, -regress_stim_labels, -regress_basis,
-regress_basis_normall, -regress_polort,
-regress_stim_times_offset, -regress_use_stim_files.
-regress_extra_stim_files FILE1 ... : specify extra stim files
e.g. -regress_extra_stim_files resp.1D cardiac.1D
e.g. -regress_extra_stim_files regs_of_no_int_*.1D
Use this option to specify extra files to be applied with the
-stim_file option in 3dDeconvolve (as opposed to the more usual
-stim_times). These files will not be converted to stim_times.
Corresponding labels can be given with -regress_extra_stim_labels.
See also -regress_extra_stim_labels, -regress_RONI.
-regress_extra_stim_labels LAB1 ... : specify extra stim file labels
e.g. -regress_extra_stim_labels resp cardiac
If -regress_extra_stim_files is given, the user may want to specify
labels for those extra stimulus files. This option provides that
mechanism. If this option is not given, default labels will be
assigned (like stim17, for example).
Note that the number of entries in this list should match the
number of extra stim files.
See also -regress_extra_stim_files.
-regress_stim_times_offset OFFSET : add OFFSET to -stim_times files
e.g. -stim_times_offset 1.25
default: 0
If the -regress_stim_files option is used (so the script converts
-stim_files to -stim_times before 3dDeconvolve), the user may want
to add an offset to the times in the output timing files.
For example, if -tshift_align_to is applied, and the user chooses
to align volumes to the middle of the TR, it would be appropriate
to add TR/2 to the times of the stim_times files.
This OFFSET will be applied to the make_stim_times.py command in
the output script.
Please see 'make_stim_times.py -help' for more information.
See also -regress_stim_files, -regress_use_stim_files,
-tshift_align_to.
-regress_use_stim_files : use -stim_file in regression, not -stim_times
The default operation of afni_proc.py is to convert TR-locked files
for the 3dDeconvolve -stim_file option to timing files for the
3dDeconvolve -stim_times option.
If the -regress_use_stim_times option is provided, then no such
conversion will take place. This assumes the -regress_stim_files
option is applied to provide such -stim_file files.
This option has been renamed from '-regress_no_stim_times'.
Please see '3dDeconvolve -help' for more information.
See also -regress_stim_files, -regress_stim_times,
-regress_stim_labels.
- R Reynolds Dec, 2006 thanks to Z Saad
===========================================================================
This page auto-generated on
Tue Nov 24 05:01:01 EST 2009