AFNI program: 3dTto1D

Output of -help

-------------------------------------------------------------------------
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: Dec 17 2024
This page auto-generated on Tue Dec 17 06:53:47 PM EST 2024