More reads.bam info

Author: armintoepfer

docs/faq/mode-all.md

@@ -5,43 +5,7 @@ title: Mode --all
 ---
 
 # Process _all_ reads
-Have you ever run _ccs_ with different cutoffs, e.g. tuning `--min-rq` , because
-out of the fear of missing out on yield?
-Similar to the CLR instrument mode, in which subreads are accompanied by
-a scraps file, _ccs_ offers a new mode to never lose a single read due to
-filtering, without massive run time increase by polishing low-pass productive ZMWs.
-
-Starting with SMRT Link v10.0 and Sequel IIe, _ccs_ v5.0 or newer is able to generate
-one representative sequence per productive ZMW, irrespective of quality and passes.
-This ensures no yield loss due to filtering and enables users to have maximum
-control over their data. Never fear again that SMRT Link or the Sequel IIe
-HiFi mode filtered precious data.
-
-The default command-line behavior has not changed;
-it still generates only HiFi quality reads by default.
-But the new `--all` mode has been set as default when running the
-_Circular Consensensus Sequencing_ SMRT Link application or
-selecting the on-instrument Sequel IIe capabilities:
-<p align="left"><img width="500px" src="../img/run-design-oiccs.png"/></p>
-
-Output will be a `reads.bam` that contains:
-
-- HiFi Reads (≥Q20)
-- Lower-quality but still polished consensus reads (<Q20)
-- Unpolished consensus reads (`rq = -1`)
-- 0- or 1-pass subreads unaltered (`rq = -1`)
-
-If you want to only use HiFi reads, SMRT Link automatically generates additional
-files for your convenience that only contain HiFi reads:
-
- - hifi_reads.**fastq**.gz
- - hifi_reads.**fasta**.gz
- - hifi_reads.**bam**
-
-If you work with the `reads.bam` file directly, be aware that CCS reads of all
-qualities are present. This file needs to be understood before piping
-into your typical HiFi application.
-
+Output of `--all` is a `reads.bam` file, please see the [`reads.bam` FAQ](/faq/reads-bam) for more info!
 ## How does `--all` work?
 With the special option `--all`, _ccs_ generates one representative
 sequence per ZMW, irrespective of quality and passes.

docs/faq/reads-bam.md

@@ -0,0 +1,73 @@
+---
+layout: default
+parent: FAQ
+title: reads.bam
+---
+
+# What is the `reads.bam`?
+Have you ever run _ccs_ with different cutoffs, e.g. tuning `--min-rq` , because
+out of the fear of missing out on yield?
+Similar to the CLR instrument mode, in which subreads are accompanied by
+a scraps file, _ccs_ offers a new mode to never lose a single read due to
+filtering, without massive run time increase by polishing low-pass productive ZMWs.
+
+Starting with SMRT Link v10.0 and Sequel IIe, _ccs_ v5.0 or newer is able to generate
+one representative sequence per productive ZMW, irrespective of quality and passes.
+This ensures no yield loss due to filtering and enables users to have maximum
+control over their data. Never fear again that SMRT Link or the Sequel IIe
+HiFi mode filtered precious data.
+
+**Attention:** If you work with the `reads.bam` file directly, be aware that CCS reads of all
+qualities are present. This file needs to be understood before piping
+into your typical HiFi application.
+
+## How to generate `reads.bam`?
+
+The default command-line behavior has not changed;
+it still generates only HiFi quality reads by default.
+But the new `--all` mode has been set as default when running the
+_Circular Consensensus Sequencing_ SMRT Link application or
+selecting the on-instrument Sequel IIe capabilities:
+<p align="left"><img width="500px" src="../img/run-design-oiccs.png"/></p>
+
+## What is in the `reads.bam`?
+
+- HiFi Reads with predicted accuracy ≥Q20 (`rq ≥ 0.99`)
+- Lower-quality but still polished consensus reads with predicted accuracy <Q20 (`rq < 0.99`)
+- Unpolished consensus reads (`rq = -1`)
+- Partial or single full-length subreads unaltered (`rq = -1`)
+
+## How to get HiFi reads
+
+### SMRT Link
+
+If you want to only use HiFi reads, SMRT Link automatically generates additional
+files for your convenience that only contain HiFi reads:
+
+ - hifi_reads.**fastq**.gz
+ - hifi_reads.**fasta**.gz
+ - hifi_reads.**bam**
+
+### Command line
+
+Following tools can be installed with
+
+    conda install -c bioconda tool_name
+
+#### extracthifi
+We provide a simple tool, called `extracthifi` to generate a HiFi-only BAM from a `reads.bam` file. Usage is:
+
+    extracthifi reads.bam extracthifi.bam
+
+#### bamtools
+Alternatively use `bamtools`:
+
+    bamtools filter -in reads.bam -out hifi_reads.bam -tag "rq":">=0.99"
+
+## FAQ: How can I filter by number of passes?
+
+We **strongly** advise against filtering by anything than predicted accuracy,
+BAM tag `rq`. The `rq` tag is the best predictor for read quality. Number of
+passes is not reliable enough and you might discard too much data. This `np`
+tag is an implementation detail that is guaranteed to be present in future
+_ccs_ versions.

docs/faq/sqiie.md

@@ -59,7 +59,7 @@ core [auxilliary files](/faq/reports-aux-files):
 The on-instrument _ccs_ version and also SMRT Link ≥v10 run in the `--all` mode
 by default. In this mode, _ccs_ outputs one representative sequence per
 productive ZMW, irrespective of quality and passes. More information
-[in the `--all` mode FAQ](/faq/mode-all).
+[in the `--all` mode FAQ](/faq/mode-all) and [in the `reads.bam` FAQ](/faq/reads-bam).
 
 ## Can you go back to `subreads.bam` from `reads.bam`?
 Not when operating the instrument in CCS mode. See next question.
@@ -115,4 +115,5 @@ the `reads.bam` files with your own tools.
 Yes, the SMRT Analysis pipeline "Export Reads" in SMRT Link v10.0 or newer can
 export HiFi reads to BAM/FASTA/FASTQ format; when adjusting minimum CCS
 predicted accuracy, you can include CCS reads <Q20. On the command line, tools
-can be used to filter the BAM file for the read quality `rq` tag.
+can be used to filter the BAM file for the read quality `rq` tag, please see
+the [`reads.bam` FAQ](/faq/reads-bam).

docs/index.md

@@ -36,7 +36,7 @@ Version **6.0.0**: [Full changelog here](/changelog)
 ## What's new!
 _ccs_ is now running on the Sequel IIe instrument, transferring HiFi reads
 directly off the instrument.\
-Read how _ccs_ works on [Sequel IIe](/faq/sqiie)!
+Read how _ccs_ works on [Sequel IIe](/faq/sqiie) and what is in the [`reads.bam` file](/faq/reads-bam)!
 
 ## Schematic Workflow
 <p align="center"><img width="1000px" src="img/generate-hifi.png"/></p>