:orphan:
.. _ahelp_3dFDR:
*****
3dFDR
*****
.. contents:: :local:

.. codeblock:: none
This program implements the False Discovery Rate (FDR) algorithm for
thresholding of voxelwise statistics.
Program input consists of a functional dataset containing one (or more)
statistical subbricks. Output consists of a bucket dataset with one
subbrick for each input subbrick. For nonstatistical input subbricks,
the output is a copy of the input. However, statistical input subbricks
are replaced by their corresponding FDR values, as follows:
For each voxel, the minimum value of q is determined such that
E(FDR) <= q
leads to rejection of the null hypothesis in that voxel. Only voxels inside
the user specified mask will be considered. These qvalues are then mapped
to zscores for compatibility with the AFNI statistical threshold display:
stat ==> pvalue ==> FDR qvalue ==> FDR zscore
The reason for the final conversion from q to z is so that larger values
are more 'significant', which is how the usual thresholding procedure
in the AFNI GUI works.
Usage:
3dFDR
input fname fname = filename of input 3d functional dataset
OR
input1D dname dname = .1D file containing column of pvalues
mask_file mname Use mask values from file mname.
*OR* Note: If file mname contains more than 1 subbrick,
mask mname the mask subbrick must be specified!
Default: No mask
** Generally speaking, you really should use a mask
to avoid counting nonbrain voxels. However, with
the changes described below, the program will
automatically ignore voxels where the statistics
are set to 0, so if the program that created the
dataset used a mask, then you don't need one here.
mask_thr m Only voxels whose corresponding mask value is
greater than or equal to m in absolute value will
be considered. Default: m=1
Constant c(N) depends on assumption about pvalues:
cind c(N) = 1 pvalues are independent across N voxels
cdep c(N) = sum(1/i), i=1,...,N any joint distribution
Default: c(N) = 1
quiet Flag to suppress screen output
list Write sorted list of voxel qvalues to screen
prefix pname Use 'pname' for the output dataset prefix name.
OR
output pname
===========================================================================
January 2008: Changes to 3dFDR

The default mode of operation of 3dFDR has altered somewhat:
* Voxel pvalues of exactly 1 (e.g., from t=0 or F=0 or correlation=0)
are ignored by default; in the old mode of operation, they were
included in the count which goes into the FDR algorithm. The old
process tends to increase the qvalues and so decrease the zscores.
* The array of voxel pvalues are now sorted via Quicksort, rather than
by binning, as in the old mode. This (by itself) probably has no
discernible effect on the results, but should be faster.
New Options:

old = Use the old mode of operation (for compatibility/nostalgia)
new = Use the new mode of operation [now the default]
N.B.: 'list' does not work in the new mode!
pmask = Instruct the program to ignore p=1 voxels
[the default in the new mode, but not in the old mode]
N.B.: voxels that were masked in 3dDeconvolve (etc.)
will have their statistics set to 0, which means p=1,
which means that such voxels are implicitly masked
with 'new', and so don't need to be explicitly
masked with the 'mask' option.
nopmask = Instruct the program to count p=1 voxels
[the default in the old mode, but NOT in the new mode]
force = Force the conversion of all subbricks, even if they
are not marked as with a statistical code; such
subbricks are treated as though they were pvalues.
float = Force the output of zscores in floating point format.
qval = Force the output of qvalues rather than zscores.
N.B.: A smaller qvalue is more significant!
[float is strongly recommended when qval is used]
* To be clear, you can use 'new nopmask' to have the new mode of computing
carried out, but with p=1 voxels included (which should give results
nearly identical to 'old').
* Or you can use 'old pmask' to use the old mode of computing but where
p=1 voxels are not counted (which should give results virtually
identical to 'new').
* However, the combination of 'new', 'nopmask' and 'mask_file' does not
work  if you try it, 'pmask' will be turned back on and a warning
message printed to aid your path towards elucidation and enlightenment.
Other Notes:

* '3drefit addFDR' can be used to add FDR curves of z(q) as a function
of threshold for all statistic subbricks in a dataset; in turn, these
curves let you see the (estimated) qvalue as you move the threshold
slider in AFNI.
 Since 3drefit doesn't have a 'mask' option, you will have to mask
statistical subbricks yourself via 3dcalc (if desired):
3dcalc a stat+orig b mask+orig expr 'a*step(b)' prefix statmm
 'addFDR' runs as if 'new pmask' were given to 3dFDR, so that
stat values == 0 are ignored in the FDR calculations.
 most AFNI statistical programs now automatically add FDR curves to
the output dataset header, so you can see the qvalue as you adjust
the threshold slider.
* qvalues are estimates of the False Discovery Rate at a given threshold;
that is, about 5% of all voxels with q <= 0.05 (z >= 1.96) are
(presumably) 'false positive' detections, and the other 95% are
(presumably) 'true positives'. Of course, there is no way to tell
which abovethreshold voxels are 'true' detections and which are 'false'.
* Note the use of the words 'estimate' and 'about' in the above statement!
In particular, the accuracy of the qvalue calculation depends on the
assumption that the pvalues calculated from the input statistics are
correctly distributed (e.g., that the DOF parameters are correct).
* The zscore is the conversion of the qvalue to a doublesided tail
probability of the unit Gaussian N(0,1) distribution; that is, z(q)
is the value such that if x is a N(0,1) random variable, then
Prob[x>z] = q: for example, z(0.05) = 1.95996.
The reason for using zscores here is simply that their range is
highly compressed relative to the range of qvalues
(e.g., z(1e9) = 6.10941), so zscores are easily stored as shorts,
whereas qvalues are much better stored as floats.
* Changes above by RWCox  18 Jan 2008 == Cary Grant's Birthday!
26 Mar 2009  Yet Another Change [RWCox]

* FDR calculations in AFNI now 'adjust' the qvalues downwards by
estimating the number of true negatives [m0 in the statistics
literature], and then reporting
q_new = q_old * m0 / m, where m = number of voxels being tested.
If you do NOT want this adjustment, then set environment variable
AFNI_DONT_ADJUST_FDR to YES. You can do this on the 3dFDR command
line with the option 'DAFNI_DONT_ADJUST_FDR=YES'
For Further Reading and Amusement

* cf. http://en.wikipedia.org/wiki/False_discovery_rate [Easy overview of FDR]
* cf. http://dx.doi.org/10.1093/bioinformatics/bti448 [False Negative Rate]
* cf. http://dx.doi.org/10.1093/biomet/93.3.491 [m0 adjustment idea]
* cf. C implementation in mri_fdrize.c [trust in the Source]
* cf. https://afni.nimh.nih.gov/pub/dist/doc/misc/FDR/FDR_Jan2008.pdf
++ Compile date = May 20 2022 {AFNI_22.1.10:linux_ubuntu_16_64}