Add filtering/annotation support for Fishers exact test

There are multiple ways how to query and annotate, for example as

    bcftools +fill-tags test.vcf -- -t 'INFO/FT=phred(fisher(INFO/DP4))'

Resolves #1582

Author: pd3

NEWS

@@ -4,9 +4,11 @@ Changes affecting the whole of bcftools, or multiple commands:
 
 * Add support for matching lines by ID via the --pair-logic and --collapse options (#1739)
 
-* The -i/-e filtering expressions now properly match the regex negation of missing
-  values, e.g. -i 'TAG!~"\."' (#2355)
+* The -i/-e filtering expressions
+
+    - The expressions now properly match the regex negation of missing values, e.g. -i 'TAG!~"\."' (#2355)
 
+    - Added support for Fisher's exact test
 
 Changes affecting specific commands:
 
@@ -32,6 +34,11 @@ Changes affecting specific commands:
     - Check the input GFF for features outside transcript boundaries and extend the transcript
       to contain the feature fully (#2323)
 
+* bcftools +fill-tags
+
+    - Thanks to the extension of filtering expressions with Fisher's exact test, the plugin
+      can now be used to add FT annotation (#1582)
+
 * bcftools merge
 
     - Preserve phasing in half-missing genotypes (#2331)

doc/bcftools.1

@@ -2,12 +2,12 @@
 .\"     Title: bcftools
 .\"    Author: [see the "AUTHOR(S)" section]
 .\" Generator: Asciidoctor 2.0.20
-.\"      Date: 2025-01-29
+.\"      Date: 2025-02-27
 .\"    Manual: \ \&
 .\"    Source: \ \&
 .\"  Language: English
 .\"
-.TH "BCFTOOLS" "1" "2025-01-29" "\ \&" "\ \&"
+.TH "BCFTOOLS" "1" "2025-02-27" "\ \&" "\ \&"
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
 .ss \n[.ss] 0
@@ -51,7 +51,7 @@ standard input (stdin) and outputs to the standard output (stdout). Several
 commands can thus be  combined  with  Unix pipes.
 .SS "VERSION"
 .sp
-This manual page was last updated \fB2025\-01\-29 08:37 CET\fP and refers to bcftools git version \fB1.21\-72\-g724713f+\fP.
+This manual page was last updated \fB2025\-02\-27 12:33 CET\fP and refers to bcftools git version \fB1.21\-79\-gcef68bc+\fP.
 .SS "BCF1"
 .sp
 The obsolete BCF1 format output by versions of samtools <= 0.1.19 is \fBnot\fP
@@ -6344,8 +6344,8 @@ sMAX, sMIN, sAVG, sMEAN, sMEDIAN, sSTDEV, sSUM
 .  sp -1
 .  IP \(bu 2.3
 .\}
-two\-tailed binomial test. Note that for N=0 the test evaluates to a missing value
-and when FORMAT/GT is used to determine the vector indices, it evaluates to 1 for
+two\-tailed binomial and fisher test. Note that for N=0 the test evaluates to a missing
+value and when FORMAT/GT is used to determine the vector indices, it evaluates to 1 for
 homozygous genotypes.
 .sp
 .if n .RS 4
@@ -6357,6 +6357,17 @@ phred(binom())               .. the same as binom but phred\-scaled
 .fam
 .fi
 .if n .RE
+.sp
+.if n .RS 4
+.nf
+.fam C
+fisher(INFO/DP4)
+fisher(FORMAT/DP4)
+fisher(FMT/ADF,FMT/ADR)              .. GT can be used to determine the correct indices
+fisher(FMT/ADF[:0,1],FMT/ADR[:0,1])  .. or the fields can be given explicitly
+.fam
+.fi
+.if n .RE
 .RE
 .sp
 .RS 4

doc/bcftools.html

@@ -50,7 +50,7 @@ <h2 id="_description">DESCRIPTION</h2>
 <div class="sect2">
 <h3 id="_version">VERSION</h3>
 <div class="paragraph">
-<p>This manual page was last updated <strong>2025-01-29 08:37 CET</strong> and refers to bcftools git version <strong>1.21-72-g724713f+</strong>.</p>
+<p>This manual page was last updated <strong>2025-02-27 12:33 CET</strong> and refers to bcftools git version <strong>1.21-79-gcef68bc+</strong>.</p>
 </div>
 </div>
 <div class="sect2">
@@ -5409,8 +5409,8 @@ <h2 id="expressions">FILTERING EXPRESSIONS</h2>
 </div>
 </li>
 <li>
-<p>two-tailed binomial test. Note that for N=0 the test evaluates to a missing value
-and when FORMAT/GT is used to determine the vector indices, it evaluates to 1 for
+<p>two-tailed binomial and fisher test. Note that for N=0 the test evaluates to a missing
+value and when FORMAT/GT is used to determine the vector indices, it evaluates to 1 for
 homozygous genotypes.</p>
 <div class="literalblock">
 <div class="content">
@@ -5419,6 +5419,14 @@ <h2 id="expressions">FILTERING EXPRESSIONS</h2>
 phred(binom())               .. the same as binom but phred-scaled</pre>
 </div>
 </div>
+<div class="literalblock">
+<div class="content">
+<pre>fisher(INFO/DP4)
+fisher(FORMAT/DP4)
+fisher(FMT/ADF,FMT/ADR)              .. GT can be used to determine the correct indices
+fisher(FMT/ADF[:0,1],FMT/ADR[:0,1])  .. or the fields can be given explicitly</pre>
+</div>
+</div>
 </li>
 <li>
 <p>variables calculated on the fly if not present: number of alternate alleles;
@@ -5723,7 +5731,7 @@ <h2 id="_copying">COPYING</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-01-29 08:37:53 +0100
+Last updated 2025-02-27 12:28:57 +0100
 </div>
 </div>
 </body>

doc/bcftools.txt

@@ -4019,14 +4019,19 @@ they will evaluate to a vector of per-sample values when applied on FORMAT tags:
         SMPL_MAX, SMPL_MIN, SMPL_AVG, SMPL_MEAN, SMPL_MEDIAN, SMPL_STDEV, SMPL_SUM,
         sMAX, sMIN, sAVG, sMEAN, sMEDIAN, sSTDEV, sSUM
 
-* two-tailed binomial test. Note that for N=0 the test evaluates to a missing value
-  and when FORMAT/GT is used to determine the vector indices, it evaluates to 1 for
+* two-tailed binomial and fisher test. Note that for N=0 the test evaluates to a missing
+  value and when FORMAT/GT is used to determine the vector indices, it evaluates to 1 for
   homozygous genotypes.
 
         binom(FMT/AD)                .. GT can be used to determine the correct index
         binom(AD[0],AD[1])           .. or the fields can be given explicitly
         phred(binom())               .. the same as binom but phred-scaled
 
+        fisher(INFO/DP4)
+        fisher(FORMAT/DP4)
+        fisher(FMT/ADF,FMT/ADR)              .. GT can be used to determine the correct indices
+        fisher(FMT/ADF[:0,1],FMT/ADR[:0,1])  .. or the fields can be given explicitly
+
 * variables calculated on the fly if not present: number of alternate alleles;
 number of samples; count of alternate alleles; minor allele count (similar to
 AC but always picks the allele with frequency smaller than 0.5); frequency of alternate alleles (AF=AC/AN);