:orphan:

.. _ahelp_dsetstat2p:

**********
dsetstat2p
**********

.. contents:: :local:


| 

.. code-block:: none

    -------------------------------------------------------------------------
    
        This program converts statistic of choice to a p-value with
        reference to a particular dataset.  It is the complement of
        'p2dsetstat'.
    
        Often to convert a statistic to a p-value, supplementary
        information is needed, such as number of degrees of freedom.  AFNI
        programs that write statistics do store that info in headers, and
        this program is meant to be a useful to do conversions based on
        that: the user provides the stat value and the specific [i]th
        brick of the dataset in question, and a single p-value can be
        output to screen.
    
        This program should give equivalent results to other AFNI programs
        like ccalc and cdf, but with less work by the user.
    
        **Note that the user will have to choose explicitly whether they
          are doing one-sided or bi-sided/two-sided testing!** This is
          equivalent to choosing "Pos&Neg" or just "Pos" (or just "Neg",
          if the user multiplies the output by a negative) in the AFNI
          GUI's clickable p-to-statistic calculator.
    
        Ver. 1.3 (PA Taylor, Aug 23, 2022)
    
    -------------------------------------------------------------------------
    
      RUNNING:
    
      dsetstat2p  \
            -inset   DDD'[i]'                     \
            -statval S                            \
            -bisided|-2sided|-1sided              \
            {-quiet}
    
      where:
        -inset  DDD"[i]"
                   :specify a dataset DDD and, if it has multiple sub-bricks,
                    the [i]th subbrick with the statistic of interest MUST
                    be selected explicitly; note the use of quotation marks 
                    around the brick selector (because of the square-brackets).
                    Note that 'i' can be either a number of a string label
                    selector.
    
        -statval S :input stat-value S, which MUST be in the interval 
                    [0, infinity).
    
        -bisided
           or
        -2sided
           or
        -1sided    :one of these two options MUST be chosen, and it is up
                    to the researcher to choose which.
    
        -quiet     :an optional flag so that output ONLY the final statistic
                    value output to standard output; this can be then be
                    viewed, redirected to a text file or saved as a shell
                    variable.  (Default: display supplementary text.)
    
    -------------------------------------------------------------------------
    
      OUTPUTS: 
    
        The types of statistic values that can be calculated are:
            corr coef, t-stat, F-stat or z-score.
    
        If "-quiet" is used, then basically just a single number (the
        converted statistic value) is output.  See examples for saving
        this in a file or variable. (A 3dinfo message shown is ignorable
        and won't affect saving/writing the variable.)
    
        Without the "-quiet" option, some descriptive text is also output
        with the calculation, stating what kind of statistic is being
        output, etc.  
    
        If you want to know more about the cryptic outputs in the
        non-quiet usage of this program, you may look upon "BRICK_STATAUX"
        on this webpage:
        https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.attributes.html
        and tremble.
    
    -------------------------------------------------------------------------
    
      EXAMPLES:
    
        In all cases note the use of the single quotes around the subbrick
        selector-- these are necessary!
    
        # 1) Do a calculation and display various informations to screen:
        dsetstat2p  \
            -inset stats.sub01+tlrc'[2]'                        \
            -statval 3.313                                      \
            -bisided
        
        # 2) Do a calculation and just display a single number:
        dsetstat2p  \
            -inset stats.sub01+tlrc'[2]'                        \
            -statval 15                                         \
            -1sided                                             \
            -quiet
    
        # 3) Do a calculation and store the output number as a variable,
        #    using tcsh syntax:
        set my_stat = `dsetstat2p  \
                        -inset stats.sub02+tlrc'[8]'            \
                        -statval 3.313                          \
                        -bisided                                \
                        -quiet`
    
        # 4) Do a calculation and store the output number into a text
        #    file:
        dsetstat2p  \
            -inset stats.sub02+tlrc'[8]'                        \
            -statval 1.96                                       \
            -bisided                                            \
            -quiet > MY_PVAL_FILE.txt
    
    -------------------------------------------------------------------------