AFNI program: @compute_OC_weights

Output of -help


@compute_OC_weights           - compute optimally combined weights dataset

   Given echo times (in a text file) and one run of multi-echo EPI data,
   compute a dataset that can be used to combine the echoes.  The weight
   dataset would have one volume per echo, which can be used to combine
   the echoes into a single dataset.  The same echoes can be applied to
   all runs.

       3dMean -weightset weights+tlrc -prefix opt.combined \
              echo1+tlrc echo2+tlrc echo3+tlrc

   For clarity, a similar 3dcalc computation would look like:

       3dcalc -a echo1+tlrc        -b echo2+tlrc        -c echo3+tlrc        \
              -d weights+tlrc'[0]' -e weights+tlrc'[1]' -f weights+tlrc'[2]' \
              -expr 'a*d+b*e+c*f'  -prefix opt.combined

   

   ----------------------------------------------------------------------

   These computations are based on the system of equations from:

      o Posse, S., Wiese, S., Gembris, D., Mathiak, K., Kessler, C.,
        Grosse-Ruyken, M.L., Elghahwagi, B., Richards, T., Dager, S.R.,
        Kiselev, V.G.
        Enhancement of BOLD-contrast sensitivity by single-shot multi-echo
        functional MR imaging.
        Magnetic Resonance in Medicine 42:87–97 (1999)

      o Prantik Kundu, Souheil J. Inati, Jennifer W. Evans, Wen-Ming Luh,
        Peter A. Bandettini
        Differentiating BOLD and non-BOLD signals in fMRI time series using
        multi-echo EPI
        NeuroImage 60 (2012) 1759–1770

      o a summer 2017 presentation by Javier Gonzalez-Castillo

   ----------------------------------------------------------------------

   After solving:
  
     log(mean(S(TE_1))) ~= -mean(R2s(x))*TE_1 + log(So(x))
     log(mean(S(TE_2))) ~= -mean(R2s(x))*TE_2 + log(So(x))
     log(mean(S(TE_3))) ~= -mean(R2s(x))*TE_3 + log(So(x))
  
   then T2* = 1/mean(R2s(x)), and weights come from:
  
                  TE_n*e^-(TE_n/T2*)
     w(TE_n) = -------------------------
               sum_n[TE_n*e^-(TE_n/T2*)]

   Bad, naughty voxels are defined as those with either negative T2* values,
   or for which the sum of the weights is not sufficiently close to 1, which
   would probably mean that there were computational truncation errors, likely
   due to R2s being very close to 0.

   so "fail" if
         mean(R2s) <= 0
   or
         abs(1-sum[weights]) > 'tolerance'

   In such cases, the weights will default to the result based on the maximum
   T2* value (unless "-def_to_equal yes" is applied, in which case the default
   is 1/number_of_echoes, which is equal weighting across echoes).
  
   ----------------------------------------------------------------------

   examples:

      1. basic

         @compute_OC_weights -echo_times_file etimes.1D \
                -echo_dsets pb02*r01*volreg*.HEAD
  
      2. Specify working directory and resulting weights dataset prefix.
         Then use the weight dataset to combine the echoes.

         @compute_OC_weights -echo_times_file etimes.1D \
                -echo_dsets pb02*r01*volreg*.HEAD       \
                -prefix OC.weights.run1 -work_dir OC.work.run1

         3dMean -weightset OC.weights.run1+tlrc -prefix epi_run1_OC \
                pb02*r01*volreg*.HEAD

   ----------------------------------------------------------------------

   random babble:

      The T2* map is not actually used, but rather 1/T2* (to avoid repeated
      division).

      T2* is restricted to the range (0, T2S_LIMIT), where the default limit is
      300 (see -t2_star_limit).

      A "bad" T2* value (T2* <= 0 or T2* > T2S_LIMIT) will lead to use of the
      limit T2S_LIMIT, so that as R2 decreases and goes negative, the results
      converge.

      If the sum of the weights is not almost exactly 1.0 (see the option,
      -sum_weight_tolerance), the weights will also default to equal (see
      option -def_to_equal).

      Basically, the program is designed such that either a reasonable T2*
      is computed and applied, or the weighting result will be 1/num_echoes.

   ----------------------------------------------------------------------

   required parameters:

      -echo_times "TE1 TE2 ..." - specify echo times
                                  (use quotes to pass list as one parameter)

           e.g. -echo_times "15 30.5 41"

        Specify echo times as a list.

        Use either -echo_times or -echo_times_files.


      -echo_times_file FILE     - specify file with echo times
                                  (e.g. it could contain 15 30.5 41)

        Specify echo times from a text file.

        Use either -echo_times or -echo_times_files.


      -echo_dsets D1 D2 D3      - specify one run of multi-echo EPI data, e.g.:

           e.g. -echo_dsets pb03.SUBJ.r01.e*.volreg+tlrc.HEAD

        Provide the echo datasets for a single run of multi-echo EPI data.


   general options:

      -def_to_equal yes/no      - specify whether to default to equal weights
                                  (default = no)

        In the case where T2* seems huge or <= 0, or if the sum of the
        fractional weights is not close to 1 (see -tolerance), one might
        want to apply default weights equal to 1/num_echoes (so echoes
        are weighted equally).

        Without this, the weighting for such 'bad' voxels is based on the
        T2* limit.  See -t2_star_limit.

      -oc_method METHOD         - specify which method to employ

           e.g.     -oc_method OC_B
           default: -oc_method OC_A

        The OC_B method differs from OC_A by solving for T2* using log(mean())
        to solving log() over time, with the intention of being more accurate.

           methods:

              OC_A      : compute T2* from log(mean(time series))
                          this is the original implementation

              OC_B      : compute T2* from log(time series)

         * So far, testing has shown almost undetectable differences, so it
           may be a moot point.

      -prefix PREFIX            - specify prefix of resulting OC weights dataset

           e.g. -prefix OC.weights.SUBJ

      -sum_weight_tolerance TOL - tolerance for summed weight diff from 1.0
                                  (default = 0.001)

           e.g. -sum_weight_tolerance 0.0001

        This option only applies to the "-def_to_equal yes" case.

        If echo means (at some voxel) do not follow a decay curve, there
        could be truncation errors in weighting computation that lead to
        weights which do not sum to 1.0.  If abs(1-sum) > tolerance, such a
        voxel will be set in the tolerance.fail dataset.

        The default effect of this failure is to get equal weights across
        the echoes.

      -t2_star_limit LIMIT      - specify limit for T2* values
                                  (default = 300)

        When the system of equations does not show a reasonably fast decay,
        the slopes will be such that T2* is huge or possibly negative.  In such
        cases, it is applied as the LIMIT from this option.

      -work_dir WDIR            - specify directory to compute results in

        All the processing is done in a new sub-directory.  If this program
        is to be applied one run at a time, it is important to specify such
        working directories to keep the names unique.

      -verb                     - increase verbosity of output


   terminal options:

       -help
       -hist
       -ver

   ----------------------------------------------------------------------
   R Reynolds, Feb, 2016               Thanks to Javier Gonzalez-Castillo
  
This page auto-generated on Thu Oct 31 09:43:27 PM EDT 2024