This program converts a statistic value to a p-value, with
reference to a particular dataset.

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 info.  Here, the user provides the stat value and the specific [i]th
brick of the dataset in question, and a p-value (either as single number,
or with supplementary info) is output to screen.

This program should give equivalent results to other AFNI programs
like ccalc and cdf, but with less work by the user.

See also the complementary program for doing the inverse, converting
a p-value to an equivalent statistic:  p2dsetstat.

**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.

written by : PA Taylor and RC Reynolds (SSCC, NIMH, NIH)
version    : 2.0
rev date   : Nov 04, 2023


dsetstat2p                                  \
      -inset   DDD"[i]"                     \
      -statval S                            \
      -bisided|-2sided|-1sided              \

  -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
              NB: we refer to "sub-bricks" here, but the inset\
              could also be a surface dataset, too.\

  -statval S :input stat-value S, which MUST be in the interval
               [0, infinity).

  -1sided    :one of these sidedness options MUST be chosen, and it is
              up to the researcher to choose which is appropriate.

  -quiet     :an optional flag so that output ONLY the final p-value
              is 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.)


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
p-value) is output.  See examples for saving this in a file or

Without the "-quiet" option, some descriptive text is also output with
the calculation, stating what kind of statistic is being used, etc.

Sidenote: another way to get stat+parameter information is via 3dAttribute,
and in particular asking for the "BRICK_STATAUX" information. That output
is probably a bit more cryptic, but it is described on the attributes page,
which users may look upon here:
and tremble.


In all cases note the use of the single quotes around the subbrick
selector-- these are necessary in some shell types!

1) Do a calculation and display various information to screen:
     dsetstat2p                                       \
         -inset   stats.sub01+tlrc"[2]"               \
         -statval 3.313                               \

2) Do a calculation and just display a single number (and also
   use a string label to conveniently select the subbrick):
     dsetstat2p                                       \
         -inset   stats.sub01+tlrc"[Full_Fstat]"    \
         -statval 155                                 \
         -1sided                                      \

3) Do a calculation and store the output number as a variable,
   here using tcsh syntax:
     set my_stat = `dsetstat2p                        \
                     -inset   stats.sub02+tlrc"[8]"   \
                     -statval 3.313                   \
                     -bisided                         \

4) Do a calculation and store the output number into a text
     dsetstat2p                                       \
         -inset   stats.sub02+tlrc"[8]"               \
         -statval 1.96                                \
         -bisided                                     \
         -quiet > MY_STAT_FILE.txt