** NOTA BENE: For the purpose of preparing resting-state FMRI datasets ** ** for analysis (e.g., with 3dGroupInCorr), this program is now mostly ** ** superseded by the afni_proc.py script. See the ‘afni_proc.py -help’ ** ** section ‘Resting state analysis (modern)’ to get our current rs-FMRI ** ** pre-processing recommended sequence of steps. – RW Cox, et alii. **
Usage: 3dBandpass [options] fbot ftop dataset
to 3dSetupGroupInCorr. Other uses are left to your imagination.
in time from 3dTcat-ing multiple datasets together.
HOWEVER, the mean and Nyquist freq are always removed.
++ if ftop > Nyquist freq, then it’s a highpass filter only.
Set fbot=0 and ftop=99999 to do an ‘allpass’ filter. ++ Except for removal of the 0 and Nyquist frequencies, that is.
You cannot construct a ‘notch’ filter with this program! ++ You could use 3dBandpass followed by 3dcalc to get the same effect. ++ If you are understand what you are doing, that is. ++ Of course, that is the AFNI way – if you don’t want to
understand what you are doing, use Some other PrograM, and you can still get Fine StatisticaL maps.
3dBandpass will fail if fbot and ftop are too close for comfort. ++ Which means closer than one frequency grid step df,
where df = 1 / (nfft * dt) [of course]
than the input time series length for the sake of efficiency.
a power of 3 and/or 5 (up to and including the 3rd power of each of these: 3, 9, 27, and 5, 25, 125).
depend on the order in which you run these programs. That’s why 3dBandpass has the ‘-ort’ and ‘-dsort’ options, so that the time series filtering can be done properly, in one place.
The output dataset is stored in float format.
The order of processing steps is the following (most are optional):
- Check time series for initial transients [does not alter data]
- Despiking of each time series
- Removal of a constant+linear+quadratic trend in each time series
- Bandpass of data time series
- Bandpass of -ort time series, then detrending of data
with respect to the -ort time series
- Bandpass and de-orting of the -dsort dataset,
then detrending of the data with respect to -dsort
Blurring inside the mask [might be slow]
Local PV calculation [WILL be slow!]
L2 normalization [will be fast.]
- -despike = Despike each time series before other processing.
- ++ Hopefully, you don’t actually need to do this,
- which is why it is optional.
- -ort f.1D = Also orthogonalize input to columns in f.1D
- ++ Multiple ‘-ort’ options are allowed.
- -dsort fset = Orthogonalize each voxel to the corresponding
voxel time series in dataset ‘fset’, which must have the same spatial and temporal grid structure as the main input dataset.++ At present, only one ‘-dsort’ option is allowed.
- -nodetrend = Skip the quadratic detrending of the input that
occurs before the FFT-based bandpassing.
- ++ You would only want to do this if the dataset
- had been detrended already in some other program.
-dt dd = set time step to ‘dd’ sec [default=from dataset header]
-nfft N = set the FFT length to ‘N’ [must be a legal value]
- -norm = Make all output time series have L2 norm = 1
- ++ i.e., sum of squares = 1
-mask mset = Mask dataset
-automask = Create a mask from the input dataset
- -blur fff = Blur (inside the mask only) with a filter
- width (FWHM) of ‘fff’ millimeters.
- -localPV rrr = Replace each vector by the local Principal Vector
(AKA first singular vector) from a neighborhood of radius ‘rrr’ millimiters.++ Note that the PV time series is L2 normalized. ++ This option is mostly for Bob Cox to have fun with.
-input dataset = Alternative way to specify input dataset.
-band fbot ftop = Alternative way to specify passband frequencies.
-prefix ppp = Set prefix name of output dataset.
-quiet = Turn off the fun and informative messages. (Why?)
- -notrans = Don’t check for initial positive transients in the data:
- OR ++ The test is a little slow, so skipping it is OK,
- -nosat if you KNOW the data time series are transient-free.
++ Or set AFNI_SKIP_SATCHECK to YES. ++ Initial transients won’t be handled well by the
bandpassing algorithm, and in addition may seriously contaminate any further processing, such as inter-voxel correlations via InstaCorr.
- ++ No other tests are made [yet] for non-stationary behavior
- in the time series data.
automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer.
by a network (e.g., OpenMP doesn’t work with ‘cluster’ setups).
your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1).
using all CPUs available. ++ However, on some systems (such as the NIH Biowulf), it seems to be
necessary to set OMP_NUM_THREADS explicitly, or you only get one CPU.
count, since using more than (say) 16 threads is probably useless.
since OpenMP queries this variable BEFORE the program actually starts. ++ You can’t usefully set this variable in your ~/.afnirc file or on the
command line with the ‘-D’ option.
it was coded. You’ll have to experiment on your own systems!
The number of CPUs on this particular computer system is ...... 16.
The maximum number of CPUs that will be used is now set to .... 7.
At present, the only part of 3dBandpass that is parallelized is the ‘-blur’ option, which processes each sub-brick independently.
++ Compile date = Dec 16 2015