From 7b55a6d375c0867c12aa5fc1970a4923f9754f78 Mon Sep 17 00:00:00 2001
From: Aaron <aaronquinlan@gmail.com>
Date: Mon, 14 Jan 2013 11:46:12 -0500
Subject: [PATCH] [DOCS] updates to annotate, bamtobed, and multicov
---
docs/content/tools/annotate.rst | 52 +++++-----
docs/content/tools/bamtobed.rst | 164 +++++++++++++++++++++----------
docs/content/tools/intersect.rst | 32 +++---
docs/content/tools/multicov.rst | 95 +++++++++++++++++-
docs/index.rst | 1 +
5 files changed, 253 insertions(+), 91 deletions(-)
diff --git a/docs/content/tools/annotate.rst b/docs/content/tools/annotate.rst
index 80f04a3a..6b6a03fc 100755
--- a/docs/content/tools/annotate.rst
+++ b/docs/content/tools/annotate.rst
@@ -1,13 +1,13 @@
###############
*annotate*
###############
-`bedtools annotate`, well, annotates one BED/VCF/GFF file with the coverage
+``bedtools annotate``, well, annotates one BED/VCF/GFF file with the coverage
and number of overlaps observed from multiple other BED/VCF/GFF files.
In this way, it allows one to ask to what degree one feature coincides with
multiple other feature types with a single command.
==========================================================================
-5.24.1 Usage and option summary
+Usage and option summary
==========================================================================
**Usage**:
::
@@ -22,7 +22,6 @@ multiple other feature types with a single command.
=========================== ===============================================================================================================================================================================================================
Option Description
-
=========================== ===============================================================================================================================================================================================================
**-names** A list of names (one per file) to describe each file in -i. These names will be printed as a header line.
**-counts** Report the count of features in each file that overlap -i. Default behavior is to report the fraction of -i covered by each file.
@@ -32,45 +31,46 @@ multiple other feature types with a single command.
=========================== ===============================================================================================================================================================================================================
==========================================================================
-5.24.2 Default behavior - annotate one file with coverage from others.
+Default behavior - annotate one file with coverage from others.
==========================================================================
By default, the fraction of each feature covered by each annotation file is
reported after the complete feature in the file to be annotated.
-::
- cat variants.bed
+.. code-block:: bash
+
+ $ cat variants.bed
chr1 100 200 nasty 1 -
chr2 500 1000 ugly 2 +
chr3 1000 5000 big 3 -
- cat genes.bed
+ $ cat genes.bed
chr1 150 200 geneA 1 +
chr1 175 250 geneB 2 +
chr3 0 10000 geneC 3 -
- cat conserve.bed
+ $ cat conserve.bed
chr1 0 10000 cons1 1 +
chr2 700 10000 cons2 2 -
chr3 4000 10000 cons3 3 +
- cat known_var.bed
+ $ cat known_var.bed
chr1 0 120 known1 -
chr1 150 160 known2 -
chr2 0 10000 known3 +
- bedtools annotate -i variants.bed -files genes.bed conserve.bed known_var.bed
+ $ bedtools annotate -i variants.bed -files genes.bed conserve.bed known_var.bed
chr1 100 200 nasty 1 - 0.500000 1.000000 0.300000
chr2 500 1000 ugly 2 + 0.000000 0.600000 1.000000
chr3 1000 5000 big 3 - 1.000000 0.250000 0.000000
==========================================================================
-5.24.3 Report the ***count*** of hits from the annotation files
+``-count`` Report the count of hits from the annotation files
==========================================================================
-Example usage:
-::
- bedtools annotate -counts -i variants.bed -files genes.bed conserve.bed known_var.bed
+.. code-block:: bash
+
+ $ bedtools annotate -counts -i variants.bed -files genes.bed conserve.bed known_var.bed
chr1 100 200 nasty 1 - 2 1 2
chr2 500 1000 ugly 2 + 0 1 1
chr3 1000 5000 big 3 - 1 1 0
@@ -78,12 +78,12 @@ Example usage:
=======================================================================================
-5.24.4 Report both the count of hits and the fraction covered from the annotation files
+``-both`` Report both the count of hits and the fraction covered from the annotation files
=======================================================================================
-Example usage:
-::
- bedtools annotate -both -i variants.bed -files genes.bed conserve.bed known_var.bed
+.. code-block:: bash
+
+ $ bedtools annotate -both -i variants.bed -files genes.bed conserve.bed known_var.bed
#chr start end name score +/- cnt1 pct1 cnt2 pct2 cnt3 pct3
chr1 100 200 nasty 1 - 2 0.500000 1 1.000000 2 0.300000
chr2 500 1000 ugly 2 + 0 0.000000 1 0.600000 1 1.000000
@@ -93,12 +93,12 @@ Example usage:
==========================================================================
-5.24.5 Restrict the reporting to overlaps on the ***same*** strand.
+``-s`` Restrict the reporting to overlaps on the **same** strand.
==========================================================================
-Example usage:
-::
- bedtools annotate -s -i variants.bed -files genes.bed conserve.bed known_var.bed
+.. code-block:: bash
+
+ $ bedtools annotate -s -i variants.bed -files genes.bed conserve.bed known_var.bed
chr1 100 200 nasty 1 - 0.000000 0.000000 0.000000
chr2 500 1000 ugly 2 + 0.000000 0.000000 0.000000
chr3 1000 5000 big 3 - 1.000000 0.000000 0.000000
@@ -106,12 +106,12 @@ Example usage:
==========================================================================
-5.24.6 Restrict the reporting to overlaps on the ***opposite*** strand.
+``-S`` Restrict the reporting to overlaps on the **opposite** strand.
==========================================================================
-Example usage:
-::
- bedtools annotate -S -i variants.bed -files genes.bed conserve.bed known_var.bed
+.. code-block:: bash
+
+ $ bedtools annotate -S -i variants.bed -files genes.bed conserve.bed known_var.bed
chr1 100 200 nasty 1 - 0.500000 1.000000 0.300000
chr2 500 1000 ugly 2 + 0.000000 0.600000 1.000000
chr3 1000 5000 big 3 - 0.000000 0.250000 0.000000
diff --git a/docs/content/tools/bamtobed.rst b/docs/content/tools/bamtobed.rst
index 3082c6d6..525ec7d6 100755
--- a/docs/content/tools/bamtobed.rst
+++ b/docs/content/tools/bamtobed.rst
@@ -1,64 +1,127 @@
###############
*bamtobed*
###############
+``bedtools bamtobed`` is a conversion utility that converts sequence alignments
+in BAM format into BED, BED12, and/or BEDPE records.
-**bamToBed** is a general purpose tool that will convert sequence alignments in BAM format to either
-BED6, BED12 or BEDPE format. This enables one to convert BAM files for use with all of the other
-BEDTools. The CIGAR string is used to compute the alignment end coordinate in an "ungapped"
-fashion. That is, match ("M"), deletion ("D"), and splice ("N") operations are observed when computing
-alignment ends.
-
-============================================
-5.4.1 Usage and option summary
-============================================
-**Usage:**
+==========================================================================
+Usage and option summary
+==========================================================================
+**Usage**:
::
- bamToBed [OPTIONS] -i <BAM>
-
-====================== =========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================
-Option Description
-====================== =========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================
-**-bedpe** Write BAM alignments in BEDPE format. Only one alignment from paired-end reads will be reported. Specifically, it each mate is aligned to the same chromosome, the BAM alignment reported will be the one where the BAM insert size is greater than zero. When the mate alignments are interchromosomal, the lexicographically lower chromosome will be reported first. Lastly, when an end is unmapped, the chromosome and strand will be set to "." and the start and end coordinates will be set to -1. *By default, this is disabled and the output will be reported in BED format*.
- **NOTE: When using this option, it is required that the BAM file is sorted/grouped by the read name. This allows bamToBed to extract correct alignment coordinates for each end based on their respective CIGAR strings. It also assumes that the alignments for a given pair come in groups of twos. There is not yet a standard method for reporting multiple alignments using BAM. bamToBed will fail if an aligner does not report alignments in pairs**.
- BAM files may be piped to bamToBed by specifying "-i stdin". See example below.
-**-bed12** Write "blocked" BED (a.k.a. BED12) format. This will convert "spliced" BAM alignments (denoted by the "N" CIGAR operation) to BED12.
-**-ed** Use the "edit distance" tag (NM) for the BED score field. Default for BED is to use mapping quality. Default for BEDPE is to use the *minimum* of the two mapping qualities for the pair. When -ed is used with -bedpe, the total edit distance from the two mates is reported.
-**-tag** Use other *numeric* BAM alignment tag for BED score. Default for BED is to use mapping quality. Disallowed with BEDPE output.
-**-color** An R,G,B string for the color used with BED12 format. Default is (255,0,0).
-**-split** Report each portion of a "split" BAM (i.e., having an "N" CIGAR operation) alignment as a distinct BED intervals.
-====================== =========================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================
-
-By default, each alignment in the BAM file is converted to a 6 column BED. The BED "name" field is
-comprised of the RNAME field in the BAM alignment. If mate information is available, the mate (e.g.,
-"/1" or "/2") field will be appended to the name. The "score" field is the mapping quality score from the
-BAM alignment, unless the **-ed** option is used.
-
-Examples:
+ bedtools bamtobed [OPTIONS] -i <BAM>
+
+**(or)**:
::
- bamToBed -i reads.bam | head -5
+
+ bamToBed [OPTIONS] -i <BAM>
+
+
+
+.. tabularcolumns:: |p{4.5cm}|p{8.5cm}|
+
+============= ================================================================
+Option Description
+============= ================================================================
+**-bedpe** Write BAM alignments in BEDPE format. Only one alignment from
+ paired-end reads will be reported. Specifically, it each mate
+ is aligned to the same chromosome, the BAM alignment reported
+ will be the one where the BAM insert size is greater than zero.
+ When the mate alignments are interchromosomal, the
+ lexicographically lower chromosome will be reported first.
+ Lastly, when an end is unmapped, the chromosome and strand will
+ be set to "." and the start and end coordinates will be set
+ to -1. *By default, this is disabled and the output will be
+ reported in BED format*.
+**-bed12** Write "blocked" BED (a.k.a. BED12) format. This will convert
+ "spliced" BAM alignments (denoted by the "N" CIGAR operation)
+ to BED12.
+**-split** Report each portion of a "split" BAM (i.e., having an "N" CIGAR
+ operation) alignment as a distinct BED intervals.
+**-ed** Use the "edit distance" tag (NM) for the BED score field.
+ Default for BED is to use mapping quality. Default for BEDPE is
+ to use the *minimum* of the two mapping qualities for the pair.
+ When -ed is used with -bedpe, the total edit distance from the
+ two mates is reported.
+**-tag** Use other *numeric* BAM alignment tag for BED score. Default
+ for BED is to use mapping quality. Disallowed with BEDPE output.
+**-color** An R,G,B string for the color used with BED12 format. Default
+ is (255,0,0).
+**-cigar** Add the CIGAR string to the BED entry as a 7th column.
+============= ================================================================
+
+
+==========================================================================
+Default behavior
+==========================================================================
+By default, each alignment in the BAM file is converted to a 6 column BED. The
+BED "name" field is comprised of the RNAME field in the BAM alignment. If mate
+information is available, the mate (e.g., "/1" or "/2") field will be appended
+to the name.
+
+.. code-block:: bash
+
+ $ bedtools bamtobed -i reads.bam | head -3
chr7 118970079 118970129 TUPAC_0001:3:1:0:1452#0/1 37 -
chr7 118965072 118965122 TUPAC_0001:3:1:0:1452#0/2 37 +
chr11 46769934 46769984 TUPAC_0001:3:1:0:1472#0/1 37 -
-
- bamToBed -i reads.bam -tag NM | head -5
+
+
+==========================================================================
+``-tag`` Set the score field based on BAM tags
+==========================================================================
+One can override the choice of the BAM `MAPQ` as the result BED record's `score`
+field by using the ``-tag`` option. In the example below, we use the ``-tag``
+option to select the BAM edit distance (the `NM` tag) as the score
+column in the resulting BED records.
+
+.. code-block:: bash
+
+ $ bedtools bamtobed -i reads.bam -tag NM | head -3
chr7 118970079 118970129 TUPAC_0001:3:1:0:1452#0/1 1 -
chr7 118965072 118965122 TUPAC_0001:3:1:0:1452#0/2 3 +
chr11 46769934 46769984 TUPAC_0001:3:1:0:1472#0/1 1 -
-
- bamToBed -i reads.bam -bedpe | head -3
- chr7 118965072 118965122 chr7 118970079 118970129
- TUPAC_0001:3:1:0:1452#0 37 + -
- chr11 46765606 46765656 chr11 46769934 46769984
- TUPAC_0001:3:1:0:1472#0 37 + -
- chr20 54704674 54704724 chr20 54708987 54709037
- TUPAC_0001:3:1:1:1833#0 37 +
+
+
+==========================================================================
+``-bedpe`` Set the score field based on BAM tags
+==========================================================================
+The ``-bedpe`` option converts BAM alignments to BEDPE format, thus allowing
+the two ends of a paired-end alignment to be reported on a single text line.
+Specifically, it each mate is aligned to the same chromosome,
+the BAM alignment reported will be the one where the BAM insert size is greater
+than zero. When the mate alignments are interchromosomal, the lexicographically
+lower chromosome will be reported first. Lastly, when an end is unmapped, the
+chromosome and strand will be set to "." and the start and end coordinates will
+be set to -1.
+
+.. note::
+
+ When using this option, it is required that the BAM
+ file is sorted/grouped by the read name. This allows bamToBed
+ to extract correct alignment coordinates for each end based on
+ their respective CIGAR strings. It also assumes that the
+ alignments for a given pair come in groups of twos. There is
+ not yet a standard method for reporting multiple alignments
+ using BAM. bamToBed will fail if an aligner does not report
+ alignments in pairs.
+
+.. code-block:: bash
+
+ $ bedtools bamtobed -i reads.ba -bedpe | head -3
+ chr7 118965072 118965122 chr7 118970079 118970129 TUPAC_0001:3:1:0:1452#0 37 + -
+ chr11 46765606 46765656 chr11 46769934 46769984 TUPAC_0001:3:1:0:1472#0 37 + -
+ chr20 54704674 54704724 chr20 54708987 54709037 TUPAC_0001:3:1:1:1833#0 37 +
-One can easily use samtools and bamToBed together as part of a UNIX pipe. In this example, we will
-only convert properly-paired (BAM flag == 0x2) reads to BED format.
-::
- samtools view -bf 0x2 reads.bam | bamToBed -i stdin | head
+One can easily use samtools and bamToBed together as part of a UNIX pipe. In
+this example, we will only convert properly-paired (``FLAG == 0x2``) reads to
+BED format.
+
+.. code-block:: bash
+
+ $ samtools view -bf 0x2 reads.bam | bedtools bamtobed -i stdin | head
chr7 118970079 118970129 TUPAC_0001:3:1:0:1452#0/1 37 -
chr7 118965072 118965122 TUPAC_0001:3:1:0:1452#0/2 37 +
chr11 46769934 46769984 TUPAC_0001:3:1:0:1472#0/1 37 -
@@ -72,11 +135,12 @@ only convert properly-paired (BAM flag == 0x2) reads to BED format.
==================================================================
-5.4.2 (-split)Creating BED12 features from "spliced" BAM entries.
+``-split`` Creating BED12 features from "spliced" BAM entries.
==================================================================
-bamToBed will, by default, create a BED6 feature that represents the entire span of a spliced/split
-BAM alignment. However, when using the **-split** command, a BED12 feature is reported where BED
-blocks will be created for each aligned portion of the sequencing read.
+``bedtools bamtobed`` will, by default, create a BED6 feature that represents
+the entire span of a spliced/split BAM alignment. However, when using the
+``-split`` command, a BED12 feature is reported where BED blocks will be
+created for each aligned portion of the sequencing read.
::
Chromosome ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/content/tools/intersect.rst b/docs/content/tools/intersect.rst
index d1a2d41c..91969140 100755
--- a/docs/content/tools/intersect.rst
+++ b/docs/content/tools/intersect.rst
@@ -66,16 +66,18 @@ Option Description
By default, if an overlap is found, ``bedtools intersect`` reports the shared interval between the two
overlapping features.
-For example::
+For example:
- cat A.bed
+.. code-block:: bash
+
+ $ cat A.bed
chr1 10 20
chr1 30 40
- cat B.bed
+ $ cat B.bed
chr1 15 20
- bedtools intersect -a A.bed -b B.bed
+ $ bedtools intersect -a A.bed -b B.bed
chr1 15 20
@@ -98,15 +100,17 @@ Instead, one can force ``bedtools intersect`` to report the *original* **"A"** f
shown below, the entire "A" feature is reported, not just the portion that overlaps with the "B" feature.
For example:
-::
- cat A.bed
+
+.. code-block:: bash
+
+ $ cat A.bed
chr1 10 20
chr1 30 40
- cat B.bed
+ $ cat B.bed
chr1 15 20
- bedtools intersect -a A.bed -b B.bed -wa
+ $ bedtools intersect -a A.bed -b B.bed -wa
chr1 10 20
.. plot::
@@ -129,17 +133,17 @@ just -wb is used, the overlapping portion of A will be reported followed by the
and -wb are used, the *originals* of both **"A"** and **"B"** will be reported.
For example (-wb alone):
-::
-For example:
-::
- cat A.bed
+
+.. code-block:: bash
+
+ $ cat A.bed
chr1 10 20
chr1 30 40
- cat B.bed
+ $ cat B.bed
chr1 15 20
- bedtools intersect -a A.bed -b B.bed -wb
+ $ bedtools intersect -a A.bed -b B.bed -wb
chr1 15 20 chr 15 20
diff --git a/docs/content/tools/multicov.rst b/docs/content/tools/multicov.rst
index b40b5e2b..b8d2039a 100644
--- a/docs/content/tools/multicov.rst
+++ b/docs/content/tools/multicov.rst
@@ -1,3 +1,96 @@
###############
*multicov*
-###############
\ No newline at end of file
+###############
+``bedtools multicov``, reports the count of alignments from multiple
+position-sorted and indexed BAM files that overlap intervals in a BED file.
+Specifically, for each BED interval provided, it reports a separate count of
+overlapping alignments from each BAM file.
+
+.. note::
+
+ ``bedtools multicov`` depends upon index BAM files in order to count the
+ number of overlaps in each BAM file. As such, each BAM file should be
+ position sorted (``samtool sort aln.bam aln.sort``) and
+ indexed (``samtools index aln.sort.bam``) with either samtools or bamtools.
+
+
+==========================================================================
+Usage and option summary
+==========================================================================
+**Usage**:
+::
+
+ bedtools multicov [OPTIONS] -bams BAM1 BAM2 BAM3 ... BAMn -bed <BED/GFF/VCF>
+
+**(or)**:
+::
+
+ multiBamCov [OPTIONS] -bams BAM1 BAM2 BAM3 ... BAMn -bed <BED/GFF/VCF>
+
+
+============ ================================================================
+ Option Description
+============ ================================================================
+**-split** Treat "split" BAM or BED12 entries as distinct BED intervals.
+**-s** Require same strandedness. That is, only report hits in B
+ that overlap A on the _same_ strand. By default, overlaps are
+ reported without respect to strand.
+**-S** Require different strandedness. That is, only report hits in B
+ that overlap A on the _opposite_ strand. By default, overlaps
+ are reported without respect to strand.
+**-f** Minimum overlap required as a fraction of each A. Default is
+ 1E-9 (i.e., 1bp).
+**-r** Require that the fraction overlap be reciprocal for A and B. In
+ other words, if -f is 0.90 and -r is used, this requires that
+ B overlap 90% of A and A _also_ overlaps 90% of B.
+**-q** Minimum mapping quality (MAPQ) allowed. Default is 0.
+**-D** Include duplicate reads. Default counts non-duplicates only
+**-F** Include failed-QC reads. Default counts pass-QC reads only
+**-p** Only count proper pairs. Default counts all alignments with
+ ``MAPQ > -q`` argument, regardless of the BAM FLAG field.
+============ ================================================================
+
+
+==========================================================================
+Default behavior.
+==========================================================================
+By default, ``multicov`` will report the count of alignments in each input
+BAM file that overlap.
+
+.. code-block:: bash
+
+ $ cat ivls-of-interest.bed
+ chr1 0 10000 ivl1
+ chr1 10000 20000 ivl2
+ chr1 20000 30000 ivl3
+ chr1 30000 40000 ivl4
+
+ $ bedtools multicov -bams aln1.bam aln2.bam aln3.bam
+ chr1 0 10000 ivl1 100 2234 0
+ chr1 10000 20000 ivl2 123 3245 1000
+ chr1 20000 30000 ivl3 213 2332 2034
+ chr1 30000 40000 ivl4 335 7654 0
+
+
+The output of ``multicov`` reflects a distinct report of the overlapping
+alignments for each record in the ``-bed`` file. In the example above, each
+line of the output reflects **a)** the original line from the ``-bed`` file
+followed by **b)** the count of alignments that overlap the ``-bed`` interval
+from each input ``-bam`` file. In the example above, the output consists of
+7 columns: the first four of which are the columns from the ``-bed`` file and
+the last 3 are the count of overlapping alignments from the 3 input ``-bam``
+files. The order of the counts reflects the order of the files given on the
+command line.
+
+.. note::
+
+ ``bedtools multicov`` will work with a single BAM as well.
+
+.. code-block:: bash
+
+ $ bedtools multicov -bams aln1.bam
+ chr1 0 10000 ivl1 100
+ chr1 10000 20000 ivl2 123
+ chr1 20000 30000 ivl3 213
+ chr1 30000 40000 ivl4 335
+
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index eda29763..ed1507f4 100755
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -16,6 +16,7 @@ Table of contents
=================
.. toctree::
:maxdepth: 1
+ :numbered:
content/overview
content/installation
--
GitLab