-------------------------------------------------------------------------
3dTto1D - collapse a 4D time series to a 1D time series
The program takes as input a 4D times series (a list of 1D time series)
and optionally a mask, and computes from in a 1D time series using some
method applied to the first (backward) differences. Methods include:
enorm : the Euclidean norm
rms/dvars : root mean square (DVARS)
srms : rms scaled down by global mean
shift_srms : srms shifted by the global mean
mdiff : mean abs(diff)
smdiff : mdiff scaled down by global mean
4095_count : count voxels with max of exactly 4095
4095_gcount : count global voxels with max of exactly 4095
(masked voxels over time)
4095_frac : fraction of masked voxels with max of exactly 4095
4095_warn : warn of max of exactly 4095
Note : the 4095 cases do not warn if max > 4095
--> the output is cleared (to zero)
More details are provided after the examples.
--------------------------------------------------
examples:
E1. compute SRMS of EPI time series within a brain mask
(might be good for censoring, and is comparable across subjects)
3dTto1D -input epi_r1+orig -mask mask.auto.nii.gz -method srms \
-prefix epi_srms.1D
E2. compute DVARS of EPI time series within a brain mask
(similarly good for censoring, but not comparable across subjects)
3dTto1D -input epi_r1+orig -mask mask.auto.nii.gz -method dvars \
-prefix epi_dvars.1D
E3. compute ENORM of motion parameters
(as is done by afni_proc.py via 1d_tool.py)
Note that 1D inputs will generally need the transpose operator,
applied by appending an escaped ' to the -input dataset.
3dTto1D -input dfile.r01.1D\' -method enorm -prefix enorm.r01.1D
E4. warn if max is 4095
3dTto1D -input epi+orig -method 4095_warn
E4. count global number of 4095 voxels (return 0 if it is not the max)
3dTto1D -input epi+orig -method 4095_gcount
--------------------------------------------------
methods:
Since the initial step is generally to compute the first (backwards)
difference, call that dataset TDIFF. The value at any voxel of TDIFF
is the same as the input, minus the value at the prior time point.
TDIFF is defined as 0 at time point 0.
method enorm
This is the Euclidean norm.
Starting with the TDIFF dataset, the value at each time point is
the Euclidean norm for that volume (or list of values). This is
the same as the L2-norm, and which is often applied to the motion
parameters for censoring.
enorm = sqrt(sum squares)
method rms (or dvars)
RMS = DVARS = enorm/sqrt(nvox).
The RMS (root mean square) is the same as the enorm divided by
sqrt(nvox). It is like a standard deviation, but without removal
of the mean (per time point).
rms = dvars = enorm/sqrt(nvox) = sqrt(sum squares/nvox)
This is the RMS of backward differences first described by Smyser
et. al., 2010, for motion detection, and later renamed to DVARS by
Power et. al., 2012.
* DVARS survives a resampling, where it would be unchanged if every
voxel were listed multiple times, for example.
* DVARS does not survive a scaling, it scales with the data.
This is why the SRMS method was introduced.
method srms (or cvar) (= scaled rms = dvars/mean)
This result is basically the coefficient of variation, but without
removal of each volume mean.
This is the same as dvars divided by the global mean, gmean.
srms = dvars/gmean = enorm/sqrt(nvox)/gmean
* SRMS survives both a resampling and scaling of the data. Since it
is unchanged with any data scaling (unlike DVARS), values are
comparable across subjects and studies.
*** The above 3 curves will look identical, subject to scaling.
method shift_srms (= srms - meandiff)
This is simply the SRMS curve shifted down by the global mean of
(the absolute values of) the first differences. This is probably
useless.
method mdiff (mean diff = mean abs(first diff))
Again, starting with the first backward difference, TDIFF, this
is just the mean absolute value, per time point.
method smdiff (scaled mean diff = mdiff/mean)
This is the mean diff scaled by the global mean.
method 4095_count
At each time point, output the number of (masked) voxels that are
exactly 4095 (if max is 4095).
method 4095_gcount
Output the total number of (masked) voxels that are exactly 4095.
This accumulates across voxels and time.
* This resets to output zero if the maximum > 4095.
method 4095_frac
At each time point, output the fraction of (masked) voxels that
are exactly 4095 (if max is 4095).
method 4095_warn
Simply warn whether the maximum is exactly 4095 (so no -prefix).
--------------------------------------------------
informational command arguments:
-help : show this help
-hist : show program history
-ver : show program version
--------------------------------------------------
required command arguments:
-input DSET : specify input dataset
e.g. -input epi_r1+orig
e.g. -input dfile.r01.1D\'
Specify the input dataset to be processed. This should be a set
of 3D time series. If the input is in 1D format, a transpose
operator will typically be required.
-method METHOD : specify 4D to 1D conversion method
e.g. -method srms
e.g. -method DVARS
e.g. -method dvars
e.g. -method enorm
Details of the computational methods are at the top of the help.
The methods (which are case insensitive) include:
enorm : Euclidean norm of first differences
= sqrt(sum squares(first diffs))
rms : RMS (root mean square) of first differences
= DVARS = enorm/sqrt(nvox)
srms : scaled (by grand mean) RMS of first differences
= DVARS/mean
* seems like the most useful method for censoring
s_srms : SRMS shifted by grand mean abs of first diffs
= SRMS - mean(abs(first diffs))
mdiff : mean absolute first differences
= mean(abs(first diff))
smdiff : mdiff scaled by grand mean
= mdiff/mean
*** : for the following 4095 cases, output is cleared
if the maximum is not exactly 4095
4095_count : count of voxels that are exactly 4095
4095_gcount : count of total voxels that are exactly 4095
across time (where 4095 is the global max, else 0)
4095_frac : fraction of voxels that are exactly 4095
= 4095_count/(mask size)
4095_warn : state whether global max is exactly 4095
(no 1D output)
--------------------------------------------------
optional command arguments:
-automask : restrict computation to automask
-mask MSET : restrict computation to given mask
-prefix PREFIX : specify output file
e.g. -prefix SVAR_run1.1D
default: -prefix stdout
-verb LEVEL : specify verbose level
e.g. -verb 2
default: -verb 1
--------------------------------------------------
R Reynolds July, 2017
-------------------------------------------------------------------------
3dTto1D version 1.3, 8 March 2024
compiled: Oct 17 2024
