Update tutorials

samtools · Nov 29, 2023 · 786feb3 · 786feb3
1 parent 24f390f
commit 786feb3
Show file tree

Hide file tree

Showing 5 changed files with 89 additions and 10 deletions.
diff --git a/howtos/FAQ.html b/howtos/FAQ.html
@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 2.0.15.dev">
+<meta name="generator" content="Asciidoctor 2.0.16">
 <title>Frequently Asked Questions</title>
 <link rel="stylesheet" href="./index.css">
 </head>

diff --git a/howtos/annotate.html b/howtos/annotate.html
@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 2.0.15.dev">
+<meta name="generator" content="Asciidoctor 2.0.16">
 <title>Annotating VCF/BCF files</title>
 <link rel="stylesheet" href="./index.css">
 </head>
@@ -97,6 +97,16 @@ <h2 id="_annotating_vcfbcf_files">Annotating VCF/BCF files</h2>
 <pre>bcftools annotate -x INFO,^FORMAT/GT,FORMAT/PL file.vcf</pre>
 </div>
 </div>
+<div class="listingblock">
+<div class="title"><strong>Rename annotations</strong></div>
+<div class="content">
+<pre># rename INFO tag `OldName` to `NewName`
+bcftools annotate -c INFO/NewName:=INFO/OldName file.vcf
+
+# rename FILTER `OldName` to `NewName`
+bcftools annotate -c FILTER/NewName:=FILTER/OldName file.vcf</pre>
+</div>
+</div>
 <div class="paragraph">
 <div class="title"><strong>Transfer annotations from one VCF file to another</strong></div>
 <p>Populate the columns ID, QUAL and the INFO/TAG annotation</p>
@@ -119,6 +129,14 @@ <h2 id="_annotating_vcfbcf_files">Annotating VCF/BCF files</h2>
 </div>
 </div>
 <div class="paragraph">
+<p>Carry over FILTER column</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>bcftools annotate -a src.bcf -c FILTER dst.bcf</pre>
+</div>
+</div>
+<div class="paragraph">
 <div class="title"><strong>Transfer annotations from a tab-delimited text file to a VCF</strong></div>
 <p>The following command can be used to transfer values from a tab-delimited
 file into a new INFO/TAG annotation. Note that if the TAG is not
@@ -144,7 +162,7 @@ <h2 id="_annotating_vcfbcf_files">Annotating VCF/BCF files</h2>
 </div>
 </div>
 <div class="paragraph">
-<div class="title"><strong>Overwriting / not overwriting existing tags and the handling of missing values</strong></div>
+<div class="title"><strong>Overwriting versus not overwriting existing tags and the handling of missing values</strong></div>
 <p>Modifiers that control what to do with missing values:</p>
 </div>
 <table class="tableblock frame-all grid-all" style="width: 70%;">
@@ -173,6 +191,30 @@ <h2 id="_annotating_vcfbcf_files">Annotating VCF/BCF files</h2>
 </tr>
 </tbody>
 </table>
+<div id="transfer_filter_to_info" class="listingblock">
+<div class="title"><strong>Transfer FILTER values into an INFO tag</strong></div>
+<div class="content">
+<pre># transfer FILTER column to INFO tag NewTag; notice that the -a option is not present, therefore
+# B.bcf/FILTER is the source annotation
+bcftools annotate -c INFO/NewTag:=FILTER B.bcf
+
+# transfer FILTER column from A.bcf to INFO/NewTag in B.bcf; notice that the -a option is present,
+# therefore A.bcf/FILTER is the source annotation
+bcftools annotate -c INFO/NewTag:=FILTER -a A.bcf B.bcf
+
+# transfer B.bcf/FILTER column to INFO tag NewTag; notice that although the -a option is present,
+# the notation "./FILTER" tells the program to transfer the annotation locally and make B.bcf/FILTER
+# the source annotation
+bcftools annotate -c INFO/NewTag:=./FILTER -a A.bcf B.bcf
+
+# transfer B.bcf/FILTER column to INFO/NewTag, then A.bcf/FILTER to B.bcf/FILTER
+bcftools annotate -c INFO/NewTag:=./FILTER,FILTER -a A.bcf B.bcf
+
+# transfer A.bcf/FILTER to B.bcf/FILTER, then the new B.bcf/FILTER value to INFO/NewTag; notice
+# that due to the order of operation, FILTER and INFO/NewTag will be identical
+bcftools annotate -c FILTER,INFO/NewTag:=./FILTER -a A.bcf B.bcf</pre>
+</div>
+</div>
 <div class="paragraph">
 <div class="title"><strong>Transfer annotation from INFO column to FORMAT</strong></div>
 <p>Imagine you need to transfer INFO/DP annotation to FORMAT/DP. This is currently not possible

diff --git a/howtos/annotate.txt b/howtos/annotate.txt
@@ -17,12 +17,20 @@ Remove all INFO fields and all FORMAT fields except for GT and PL
 bcftools annotate -x INFO,^FORMAT/GT,FORMAT/PL file.vcf
 ----
 
+.**Rename annotations**
+
+----
+# rename INFO tag `OldName` to `NewName`
+bcftools annotate -c INFO/NewName:=INFO/OldName file.vcf
+
+# rename FILTER `OldName` to `NewName`
+bcftools annotate -c FILTER/NewName:=FILTER/OldName file.vcf
+----
 
 
 .**Transfer annotations from one VCF file to another**
 
 Populate the columns ID, QUAL and the INFO/TAG annotation
-
 ----
 # do not replace TAG if already present
 bcftools annotate -a src.bcf -c ID,QUAL,+TAG dst.bcf
@@ -32,11 +40,15 @@ bcftools annotate -a src.bcf -c ID,QUAL,TAG dst.bcf
 ----
 
 Carry over all INFO and FORMAT annotations except FORMAT/GT
-
 ----
 bcftools annotate -a src.bcf -c INFO,^FORMAT/GT dst.bcf
 ----
 
+Carry over FILTER column
+----
+bcftools annotate -a src.bcf -c FILTER dst.bcf
+----
+
 
 
 .**Transfer annotations from a tab-delimited text file to a VCF**
@@ -65,7 +77,7 @@ bcftools annotate -a annots.bed.gz -h annots.hdr -c CHROM,FROM,TO,TAG input.vcf
 
 
 
-.**Overwriting / not overwriting existing tags and the handling of missing values**
+.**Overwriting versus not overwriting existing tags and the handling of missing values**
 
 Modifiers that control what to do with missing values:
 [cols="2,10",width=70%]
@@ -88,6 +100,31 @@ Modifiers that control what to do with missing values:
 
 
 
+[[transfer_filter_to_info]]
+.**Transfer FILTER values into an INFO tag**
+
+----
+# transfer FILTER column to INFO tag NewTag; notice that the -a option is not present, therefore
+# B.bcf/FILTER is the source annotation
+bcftools annotate -c INFO/NewTag:=FILTER B.bcf
+
+# transfer FILTER column from A.bcf to INFO/NewTag in B.bcf; notice that the -a option is present,
+# therefore A.bcf/FILTER is the source annotation
+bcftools annotate -c INFO/NewTag:=FILTER -a A.bcf B.bcf
+
+# transfer B.bcf/FILTER column to INFO tag NewTag; notice that although the -a option is present,
+# the notation "./FILTER" tells the program to transfer the annotation locally and make B.bcf/FILTER
+# the source annotation
+bcftools annotate -c INFO/NewTag:=./FILTER -a A.bcf B.bcf
+
+# transfer B.bcf/FILTER column to INFO/NewTag, then A.bcf/FILTER to B.bcf/FILTER
+bcftools annotate -c INFO/NewTag:=./FILTER,FILTER -a A.bcf B.bcf
+
+# transfer A.bcf/FILTER to B.bcf/FILTER, then the new B.bcf/FILTER value to INFO/NewTag; notice
+# that due to the order of operation, FILTER and INFO/NewTag will be identical
+bcftools annotate -c FILTER,INFO/NewTag:=./FILTER -a A.bcf B.bcf
+----
+
 
 .**Transfer annotation from INFO column to FORMAT**
 

diff --git a/howtos/cnv-calling.html b/howtos/cnv-calling.html
@@ -2,9 +2,9 @@
 <html lang="en">
 <head>
 <meta charset="UTF-8">
-<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
+<meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 1.5.2">
+<meta name="generator" content="Asciidoctor 2.0.16">
 <title>Copy Number Variation</title>
 <link rel="stylesheet" href="./index.css">
 </head>
@@ -226,7 +226,7 @@ <h3 id="_references">References</h3>
 <div class="sect2">
 <h3 id="_feedback">Feedback</h3>
 <div class="paragraph">
-<p>We welcome your feedback, please help us improve this page by
+<p>We welcome your feedback, please help us improve this page by 
 either opening an <a href="https://github.com/samtools/bcftools/issues">issue on github</a> or <a href="https://github.com/samtools/bcftools/tree/gh-pages/howtos">editing it directly</a> and sending
 a pull request.</p>
 </div>

diff --git a/howtos/consensus-sequence.html b/howtos/consensus-sequence.html
@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<meta name="generator" content="Asciidoctor 2.0.15.dev">
+<meta name="generator" content="Asciidoctor 2.0.16">
 <title>Consensus sequence</title>
 <link rel="stylesheet" href="./index.css">
 </head>