AFNI program: find_variance_lines.tcsh

Output of -help

---------------------------------------------------------------------------
Overview: ~1~

find_variance_lines.tcsh   - look for high temporal variance columns

   usage : find_variance_lines.tcsh [options] datasets ..."

Look for bars of high variance that might suggest scanner interference.

   inputs: multiple runs of EPI datasets
   output: a directory containing
           - variance maps per run: original and scaled
           - cluster reports and x,y coordinates at high averages
           - a JPEG image showing locations of high variance

This program takes one or more runs of (presumably) EPI time series data,
and looks for slice locations with consistently high temporal variance across
the (masked) slices.

   steps:
      - (possibly) automask, erode and require columns of 7 voxels
      - (possibly) detrend at regress polort level, default = A
      - compute temporal variance volume
      - get p90 = 90th %ile in volume mask, default %ile = 90
      - scale variance to val/p90, with max of 1
      - Localstat -mask mean over columns
      - find separate clusters of them,
        where a vline is a column with Localstat mean >= 0.90

------------------------------------------------------------
Examples: ~1~

  1. Run using defaults.

        find_variance_lines.tcsh epi_r1.nii epi_r2.nii epi_r3.nii
          OR
        find_variance_lines.tcsh epi_r*.nii

  2. What would afni_proc.py do?

        find_variance_lines.tcsh -rdir vlines.pb00.tcat -nerode 2 \
            pb00*tcat*.HEAD |& tee out.vlines.pb00.tcat.txt

  3. Provide a mask (and do not erode).  Do not detrend time series.
     Use the default output directory, vlines.result.

        find_variance_lines.tcsh -mask my_mask.nii.gz -polort -1 \
              epi_run*.nii.gz

------------------------------------------------------------
Options (terminal): ~1~

   -help                : show this help
   -hist                : show the version history
   -ver                 : show the current version

Options (processing): ~1~

   -do_clean VAL        : do we clean up a little? (def=1)

                             VAL in {0,1}

                          Remove likely unneeded datasets, particular the
                          large time series datasets.

   -do_img VAL          : make vline images? (def=1)

                             VAL in {0,1}

                          Specify whether to make jpeg images of high
                          variance locations.

   -echo                : run script with shell 'echo' set (def=no)
                          (this is VERY verbose)

                          With this set, it is as if running the (tcsh) as in:

                             tcsh -x .../find_variance_lines.tcsh ...

                          So all shell commands (including setting variables,
                          "if" evaluations, etc.) are shown.  This is useful
                          for debugging.

   -mask VAL            : mask for computations (def=AUTO)

                             VAL in {AUTO, NONE, dataset}

                          Specify a mask dataset to restrict variance
                          computations to.  VAL should be a dataset, with
                          exception for special cases:

                             AUTO : generate automask with 3dAutomask
                             NONE : do not mask

   -min_cvox VAL        : min voxels for valid mask column (def=7)

                             VAL in Z+ (positive integers)

                          In the input or automask, after any eroding, remove
                          voxels that do not have at least 'VAL' voxels in the
                          vertical column.  Otherwise, edge voxels might end
                          up in the result.

   -min_nt VAL          : minimum number of time points required (def=10)

                             VAL > 1 (integer)

                          This is just a minimum limit to be sure the input
                          time series are long enough to be reasonable.

   -nerode VAL          : how much to erode input or auto-mask (def=0)

                             VAL >= 0 (integer)

                          Specify the number of levels to erode any mask by.
                          "3dmask_tool -dilate -VAL " is used.

   -nfirst VAL          : discard the first VAL time points (def=0)

                             VAL >= 0 (integer)

                          Specify the number of time points to discard from
                          the start of each run (pre-steady state, presumably).

   -perc VAL            : percentile of variance vals to scale to (def=90)

                             VAL in {0..99}

                          When looking for high variance, the values are scaled
                          by this percentile value, with a scaled limit of 1.
                          So if the 90%-ile of variance values were 876.5, then
                          variance would be scaled using v_new = v_old/876.5,
                          with v_new limited to the range [0,1].

                          This allows evaluation relative to a modestly extreme
                          value, without worrying about the exact numbers.

   -polort VAL          : polynomial detrending degree (def=A)

                             VAL >= -1 (integer), or in {A,AUTO,NONE}

                          Specify the polynomial degree to use for time series
                          detrending prior to the variance computation.  This
                          should be an integer >= -1 (or a special case).  The
                          default is the same as that used by afni_proc.py and
                          3dDeconvolve, which is based on the duration of the
                          run, in seconds.

                          Special cases or examples:

                                A       : auto = floor(run_duration/150)+1
                                AUTO    : auto = floor(run_duration/150)+1
                                NONE    : do not detrend (same as -1)
                                -1      : do not detrend
                                0       : only remove the mean
                                3       : remove a cubic polynomial trend

   -rdir VAL            : name of the output directory (def=vlines.result)

                             VAL is a new directory name

                          All output is put into this results directory.

   -suffix_qc VAL       : string to append to QC* file outputs, as well as any
                          stats*.nii.gz file output if using -num_pc (def="")

                             VAL is a string appended to "QC_var_lines"
                             files;  it would also be appended to "stats" in
                             the NIFTI file output associated with any PCs;
                             it should likely start with "_".

                          Including the subject ID in the files in this way
                          might be useful at times.

   -ignore_edges VAL    : ignore vline clusters at edges (def=1)

                             VAL in {0,1}

                          Set this option to ignore clusters at the R,L,A,P
                          edges, so vlines near those edges are not reported.

                          If a vline cluster traces the outer edge of the brain
                          (in the j-axis direction), it is probably just due to
                          motion.  Use this option to ignore such clusters, and
                          therefore not report vlines connected to edges.

                          Such edges are defined as the outermost edges in the
                          i and j directions of the 3-D mask.  This is because
                          lines are along the k axis (usually I/S), and the
                          limits should be perpendicular to the vline axis.

   -stdev_power POW     : power on stdev to apply before ave/thresh

                             default :  -stdev_power 2
                             example :  -stdev_power 4 -thresh 0.92

                          The is the power the stdandard deviation is taken to
                          before any subsequent computations.  Higher values
                          (powers) allow for better contrast when close to 1.0.
                          Higher values might allow for lower -thresh.

                          A value of 1 will lead to computations with stdev.
                          A value of 2 will imply variance.
                          Higher values continues the pattern.


   -thresh THRESH       : variance threshold to be considered a variance line

                             default : -thresh 0.90

                          This is the minimum 3dLocalstat variance average for
                          a column to be consider a variance line.  A value
                          just under 1.0 might be reasonable.

   -num_pc NUM          : number of PCs to calculate per variance line 

                             default : -num_pc 0  (i.e., none estimated)

                          Preliminary tests with this have found 2 to be a 
                          reasonable value to use, if you want PCs output. 
                          As an example of naming, the info from component #3
                          in run 2 is named: pc.inner.r02.c03*.
                          The outputs from the intersection vline dset are 
                          named like: pc.inter.enum.c*.

   -do_pc_3dD VAL       : if '-num_pc ..' is used and variance lines are found
                          in a run, then by default this program will
                          build+execute a 3dDeconvolve command with those
                          PCs as '-stim_file ..' regressors; this opt controls
                          whether 3dD would be run or not (def=1)

                             VAL in {0,1}

                          This will help highlight where the variance
                          line influence appears to be more/less
                          across the dataset. See the Note on 'Outputs
                          when -num_pc is used' for more details.

   -do_pc_vstat VAL     : if '-num_pc ..' is used and variance lines are found
                          in a run (and 3dDeconvolve is _not_ turned off via
                          '-do_pc_3dD 0'), then by default this program will
                          build+execute an @chauffeur_afni command to make
                          images of the Full_Fstat volume in the stats dset
                          of each run with vlines (stats*.r*.image*jpg), as well
                          as an executable script to surf that dset and volume
                          in the AFNI GUI (run_stats*.r*_pc.tcsh); this opt
                          controls whether @chauffeur would be run or not 
                          (def=1)

                             VAL in {0,1}

                          This will help with quality control (QC)
                          checks of where the variance line influence
                          appears to be more/less across the dataset.
                          Note that image montage slices might miss
                          some of the variance lines themselves, so
                          executing the run script might be the most
                          useful. This can be done as follows (if no -suffix_qc
                          was used):
                          
                             tcsh run_stats.r01.tcsh

                          See the Note on 'Outputs when -num_pc is
                          used' for more details.

-----------------------------------------------------------------------------
Notes: ~1~

Outputs when -num_pc is used: ~2~

When '-num_pc ..' is used, 3dpc will be used to perform a principal
component analysis (PCA) decomposition of each variance line.  For
each line, the specified number of PCs will be saved in a text file
called pc.inner.*.val_vec.1D (one per column).

Additionally, a 3dDeconvolve command will be executed for each run
that has at least one variance line.  The full set of PCs for that run
will be used at '-stim_file ..' inputs to the command, and a Full
F-stat is calculated.  This shows the amount of variance explained in
the detrended input time series by the full set of the PC
components. That is, where the F is larger, some combination of PCs is
explaining more of the time series variability (i.e., having more
influence on the time series pattern).  The result is stored in the
stats*.nii.gz file.

A copy of the 3dDeconvolve command for each run is stored in a text
file within the output vlines directory, called
a_cmd_01_3dD.r*.tcsh.

Furthermore, an @chauffeur_afni command will be executed for each run
that has at least one variance line and for which a stats*.nii.gz has
been created.  This will make multislice image montages of the
Full_Fstat volume for each run (stats.r*.image*.jpg), which show
where any linear combination of the detected variance lines' PCs fit
the input time series data well.  The Full_Fstat volume is used for
both the overlay and thresholding datasets. The overlay color range
comes from a high percentile value of the data itself, and the
threshold value corresponds to p=0.01---of course, the transparent
alpha thresholding is also turned on.

The executed @chauffeur_afni also creates a run_stats.r*_pc.tcsh
script that will drive the AFNI GUI to load up the stats dataset with
the same data, to enable deeper checks of it in an efficient way. Each
script can be run just like:

    tcsh run_stats.r01.tcsh

A copy of the @chauffeur_afni command for each run is stored in a text
file within the output vlines directory, called
a_cmd_02_vstat.r*.tcsh.


------------------------------
- R Reynolds, P Taylor, D Glen
  Nov, 2022
  version 1.5, 23 May, 2025
This page auto-generated on Fri May 23 06:04:20 PM EDT 2025