diff --git a/docs/content/example-usage.rst b/docs/content/example-usage.rst
index 3fe5edf30f95582bae97e213d550a3f883adf8f5..43da749734afb050c5dea9b5044ec1834eddcc60 100755
--- a/docs/content/example-usage.rst
+++ b/docs/content/example-usage.rst
@@ -1,331 +1,333 @@
###############
Example usage
###############
-Below are several examples of basic BEDTools usage. Example BED files are provided in the
-/data directory of the BEDTools distribution.
+
+Below are several examples of basic bedtools usage. Example BED files are
+provided in the /data directory of the bedtools distribution.
==========================================================================
-6.1 intersectBed
+bedtools intersect
==========================================================================
-6.1.1 Report the base-pair overlap between sequence alignments and genes.
-::
- intersectBed -a reads.bed -b genes.bed
-
-
+Report the base-pair overlap between sequence alignments and genes.
-6.1.2 Report whether each alignment overlaps one or more genes. If not, the alignment is not reported.
-::
- intersectBed -a reads.bed -b genes.bed -u
-
+.. code-block:: bash
+ bedtools intersect -a reads.bed -b genes.bed
-6.1.3 Report those alignments that overlap NO genes. Like "grep -v"
-::
- intersectBed -a reads.bed -b genes.bed -v
-6.1.4 Report the number of genes that each alignment overlaps.
-::
- intersectBed -a reads.bed -b genes.bed -c
+Report whether each alignment overlaps one or more genes. If not, the alignment is not reported.
+.. code-block:: bash
+
+ bedtools intersect -a reads.bed -b genes.bed -u
+
+
+Report those alignments that overlap NO genes. Like "grep -v"
-6.1.5 Report the entire, original alignment entry for each overlap with a gene.
-::
- intersectBed -a reads.bed -b genes.bed -wa
+.. code-block:: bash
+
+ bedtools intersect -a reads.bed -b genes.bed -v
+Report the number of genes that each alignment overlaps.
-6.1.6 Report the entire, original gene entry for each overlap with a gene.
-::
- intersectBed -a reads.bed -b genes.bed -wb
+.. code-block:: bash
+ bedtools intersect -a reads.bed -b genes.bed -c
-6.1.7 Report the entire, original alignment and gene entries for each overlap.
-::
- intersectBed -a reads.bed -b genes.bed -wa -wb
-
+Report the entire, original alignment entry for each overlap with a gene.
-
-6.1.8 Only report an overlap with a repeat if it spans at least 50% of the exon.
-::
- intersectBed -a exons.bed -b repeatMasker.bed -f 0.50
+.. code-block:: bash
+
+ bedtools intersect -a reads.bed -b genes.bed -wa
-6.1.9 Only report an overlap if comprises 50% of the structural variant and 50% of the segmental duplication. Thus, it is reciprocally at least a 50% overlap.
-::
- intersectBed -a SV.bed -b segmentalDups.bed -f 0.50 -r
+Report the entire, original gene entry for each overlap with a gene.
+.. code-block:: bash
+ bedtools intersect -a reads.bed -b genes.bed -wb
-6.1.10 Read BED A from stdin. For example, find genes that overlap LINEs but not SINEs.
-::
- intersectBed -a genes.bed -b LINES.bed | intersectBed -a stdin -b SINEs.bed -v
-
-
+Report the entire, original alignment and gene entries for each overlap.
-6.1.11 Retain only single-end BAM alignments that overlap exons.
-::
- intersectBed -abam reads.bam -b exons.bed > reads.touchingExons.bam
-
-
-
+.. code-block:: bash
+ bedtools intersect -a reads.bed -b genes.bed -wa -wb
-6.1.12 Retain only single-end BAM alignments that do not overlap simple sequence
-repeats.
-::
- intersectBed -abam reads.bam -b SSRs.bed -v > reads.noSSRs.bam
+Only report an overlap with a repeat if it spans at least 50% of the exon.
-==========================================================================
-6.2 pairToBed
-==========================================================================
+.. code-block:: bash
+
+ bedtools intersect -a exons.bed -b repeatMasker.bed -f 0.50
-6.2.1 Return all structural variants (in BEDPE format) that overlap with genes on either
-end.
-::
- pairToBed -a sv.bedpe -b genes > sv.genes
+Only report an overlap if comprises 50% of the structural variant and 50% of the segmental duplication. Thus, it is reciprocally at least a 50% overlap.
+.. code-block:: bash
+
+ bedtools intersect -a SV.bed -b segmentalDups.bed -f 0.50 -r
-6.2.2 Return all structural variants (in BEDPE format) that overlap with genes on both
-end.
-::
- pairToBed -a sv.bedpe -b genes -type both > sv.genes
+Read BED A from stdin. For example, find genes that overlap LINEs but not SINEs.
+.. code-block:: bash
+ bedtools intersect -a genes.bed -b LINES.bed | intersectBed -a stdin -b SINEs.bed -v
-6.2.3 Retain only paired-end BAM alignments where neither end overlaps simple
-sequence repeats.
-::
- pairToBed -abam reads.bam -b SSRs.bed -type neither > reads.noSSRs.bam
-
-6.2.4 Retain only paired-end BAM alignments where both ends overlap segmental
-duplications.
-::
- pairToBed -abam reads.bam -b segdups.bed -type both > reads.SSRs.bam
+Retain only single-end BAM alignments that overlap exons.
+.. code-block:: bash
-
-
-6.2.5 Retain only paired-end BAM alignments where neither or one and only one end
-overlaps segmental duplications.
-::
- pairToBed -abam reads.bam -b segdups.bed -type notboth > reads.notbothSSRs.bam
+ bedtools intersect -abam reads.bam -b exons.bed > reads.touchingExons.bam
-
-
-
-
-==========================================================================
-6.3 pairToPair
-==========================================================================
+Retain only single-end BAM alignments that do not overlap simple sequence
+repeats.
-6.3.1 Find all SVs (in BEDPE format) in sample 1 that are also in sample 2.
-::
- pairToPair -a 1.sv.bedpe -b 2.sv.bedpe | cut -f 1-10 > 1.sv.in2.bedpe
+.. code-block:: bash
+
+ bedtools intersect -abam reads.bam -b SSRs.bed -v > reads.noSSRs.bam
-6.3.2 Find all SVs (in BEDPE format) in sample 1 that are not in sample 2.
-::
- pairToPair -a 1.sv.bedpe -b 2.sv.bedpe -type neither | cut -f 1-10 >
-1.sv.notin2.bedpe
+==========================================================================
+bedtools bamtobed
+==========================================================================
+Convert BAM alignments to BED format.
+.. code-block:: bash
+
+ bedtools bamtobed -i reads.bam > reads.bed
-==========================================================================
-6.4 bamToBed
-==========================================================================
+Convert BAM alignments to BED format using the BAM edit distance (NM) as the
+BED "score".
-6.4.1 Convert BAM alignments to BED format.
-::
- bamToBed -i reads.bam > reads.bed
+.. code-block:: bash
+
+ bedtools bamtobed -i reads.bam -ed > reads.bed
-6.4.2 Convert BAM alignments to BED format using the BAM edit distance (NM) as the
-BED "score".
-::
- bamToBed -i reads.bam -ed > reads.bed
+Convert BAM alignments to BEDPE format.
-6.4.3 Convert BAM alignments to BEDPE format.
-::
- bamToBed -i reads.bam -bedpe > reads.bedpe
+.. code-block:: bash
+
+ bedtools bamtobed -i reads.bam -bedpe > reads.bedpe
==========================================================================
-6.5 windowBed
+bedtools window
==========================================================================
-6.5.1 Report all genes that are within 10000 bp upstream or downstream of CNVs.
-::
- windowBed -a CNVs.bed -b genes.bed -w 10000
+Report all genes that are within 10000 bp upstream or downstream of CNVs.
+
+.. code-block:: bash
+
+ bedtools window -a CNVs.bed -b genes.bed -w 10000
-6.5.2 Report all genes that are within 10000 bp upstream or 5000 bp downstream of
+Report all genes that are within 10000 bp upstream or 5000 bp downstream of
CNVs.
-::
- windowBed -a CNVs.bed -b genes.bed -l 10000 -r 5000
+.. code-block:: bash
+
+ bedtools window -a CNVs.bed -b genes.bed -l 10000 -r 5000
-6.5.3 Report all SNPs that are within 5000 bp upstream or 1000 bp downstream of genes.
+
+Report all SNPs that are within 5000 bp upstream or 1000 bp downstream of genes.
Define upstream and downstream based on strand.
-::
- windowBed -a genes.bed -b snps.bed -l 5000 -r 1000 -sw
+
+.. code-block:: bash
+
+ bedtools window -a genes.bed -b snps.bed -l 5000 -r 1000 -sw
==========================================================================
-6.6 closestBed
+bedtools closest
==========================================================================
Note: By default, if there is a tie for closest, all ties will be reported. **closestBed** allows overlapping
features to be the closest.
-6.6.1 Find the closest ALU to each gene.
-::
- closestBed -a genes.bed -b ALUs.bed
+Find the closest ALU to each gene.
+
+.. code-block:: bash
+
+ bedtools closest -a genes.bed -b ALUs.bed
-6.6.2 Find the closest ALU to each gene, choosing the first ALU in the file if there is a
+
+Find the closest ALU to each gene, choosing the first ALU in the file if there is a
tie.
-::
- closestBed -a genes.bed -b ALUs.bed -t first
+
+.. code-block:: bash
+
+ bedtools closest -a genes.bed -b ALUs.bed -t first
-6.6.3 Find the closest ALU to each gene, choosing the last ALU in the file if there is a
+Find the closest ALU to each gene, choosing the last ALU in the file if there is a
tie.
-::
- closestBed -a genes.bed -b ALUs.bed -t last
+
+.. code-block:: bash
+
+ bedtools closest -a genes.bed -b ALUs.bed -t last
+
+
-
-
-
==========================================================================
-6.7 subtractBed
+bedtools subtract
==========================================================================
-Note: If a feature in A is entirely "spanned" by any feature in B, it will not be reported.
+.. note::
+
+ If a feature in A is entirely "spanned" by any feature in B, it will not be reported.
+
+Remove introns from gene features. Exons will (should) be reported.
+.. code-block:: bash
-6.7.1 Remove introns from gene features. Exons will (should) be reported.
-::
- subtractBed -a genes.bed -b introns.bed
+ bedtools subtract -a genes.bed -b introns.bed
==========================================================================
-6.8 mergeBed
+bedtools merge
==========================================================================
+.. note::
-6.8.1 Merge overlapping repetitive elements into a single entry.
-::
- mergeBed -i repeatMasker.bed
+ ``merge`` requires that the input is sorted by chromosome and then by start
+ coordinate. For example, for BED files, one would first sort the input
+ as follows: ``sort -k1,1 -k2,2n input.bed > input.sorted.bed``
+Merge overlapping repetitive elements into a single entry.
+.. code-block:: bash
-6.8.2 Merge overlapping repetitive elements into a single entry, returning the number of
+ bedtools merge -i repeatMasker.bed
+
+
+
+Merge overlapping repetitive elements into a single entry, returning the number of
entries merged.
-::
- mergeBed -i repeatMasker.bed -n
+
+.. code-block:: bash
+
+ bedtools merge -i repeatMasker.bed -n
-6.8.3 Merge nearby (within 1000 bp) repetitive elements into a single entry.
-::
- mergeBed -i repeatMasker.bed -d 1000
+Merge nearby (within 1000 bp) repetitive elements into a single entry.
+
+.. code-block:: bash
+
+ bedtools merge -i repeatMasker.bed -d 1000
==========================================================================
-6.9 coverageBed
+bedtools coverage
==========================================================================
-6.9.1 Compute the coverage of aligned sequences on 10 kilobase "windows" spanning the
+Compute the coverage of aligned sequences on 10 kilobase "windows" spanning the
genome.
-::
- coverageBed -a reads.bed -b windows10kb.bed | head
+
+.. code-block:: bash
+
+ bedtools coverage -a reads.bed -b windows10kb.bed | head
chr1 0 10000 0 10000 0.00
chr1 10001 20000 33 10000 0.21
chr1 20001 30000 42 10000 0.29
chr1 30001 40000 71 10000 0.36
-
-6.9.2 Compute the coverage of aligned sequences on 10 kilobase "windows" spanning the
+
+Compute the coverage of aligned sequences on 10 kilobase "windows" spanning the
genome and created a BEDGRAPH of the number of aligned reads in each window for
display on the UCSC browser.
-::
- coverageBed -a reads.bed -b windows10kb.bed | cut -f 1-4 > windows10kb.cov.bedg
+
+.. code-block:: bash
+
+ bedtools coverage -a reads.bed -b windows10kb.bed | cut -f 1-4 > windows10kb.cov.bedg
-6.9.3 Compute the coverage of aligned sequences on 10 kilobase "windows" spanning the
+Compute the coverage of aligned sequences on 10 kilobase "windows" spanning the
genome and created a BEDGRAPH of the fraction of each window covered by at least
one aligned read for display on the UCSC browser.
-::
- coverageBed -a reads.bed -b windows10kb.bed | awk ¡®{OFS="\t"; print $1,$2,$3,$6}¡¯
- > windows10kb.pctcov.bedg
+
+.. code-block:: bash
+
+ bedtools coverage -a reads.bed -b windows10kb.bed | \
+ awk '{OFS="\t"; print $1,$2,$3,$6}' \
+ > windows10kb.pctcov.bedg
==========================================================================
-6.10 complementBed
+bedtools complement
==========================================================================
-6.10.1 Report all intervals in the human genome that are not covered by repetitive
+Report all intervals in the human genome that are not covered by repetitive
elements.
-::
- complementBed -i repeatMasker.bed -g hg18.genome
+
+.. code-block:: bash
+
+ bedtools complement -i repeatMasker.bed -g hg18.genome
==========================================================================
-6.11 shuffleBed
+bedtools shuffle
==========================================================================
-6.11.1 Randomly place all discovered variants in the genome. However, prevent them
+Randomly place all discovered variants in the genome. However, prevent them
from being placed in know genome gaps.
-::
- shuffleBed -i variants.bed -g hg18.genome -excl genome_gaps.bed
+
+.. code-block:: bash
+
+ bedtools shuffle -i variants.bed -g hg18.genome -excl genome_gaps.bed
-6.11.2 Randomly place all discovered variants in the genome. However, prevent them
+
+Randomly place all discovered variants in the genome. However, prevent them
from being placed in know genome gaps and require that the variants be randomly
placed on the same chromosome.
-::
- shuffleBed -i variants.bed -g hg18.genome -excl genome_gaps.bed -chrom
+
+.. code-block:: bash
+
+ bedtools shuffle -i variants.bed -g hg18.genome -excl genome_gaps.bed -chrom
diff --git a/docs/content/general-usage.rst b/docs/content/general-usage.rst
index 7047cc550059da9fe4fe0ed01a33f1f288b17b87..cdb38f0e1d55fc9885d668831b241546eb104f85 100755
--- a/docs/content/general-usage.rst
+++ b/docs/content/general-usage.rst
@@ -3,19 +3,19 @@ General usage
###############
=======================
-4.1 Supported file formats
+Supported file formats
=======================
----------------------
-4.1.1 BED format
+BED format
----------------------
As described on the UCSC Genome Browser website (see link below), the BED format is a concise and
flexible way to represent genomic features and annotations. The BED format description supports up to
12 columns, but only the first 3 are required for the UCSC browser, the Galaxy browser and for
-BEDTools. BEDTools allows one to use the "BED12" format (that is, all 12 fields listed below).
+bedtools. bedtools allows one to use the "BED12" format (that is, all 12 fields listed below).
However, only intersectBed, coverageBed, genomeCoverageBed, and bamToBed will obey the BED12
"blocks" when computing overlaps, etc., via the **"-split"** option. For all other tools, the last six columns
-are not used for any comparisons by the BEDTools. Instead, they will use the entire span (start to end)
+are not used for any comparisons by the bedtools. Instead, they will use the entire span (start to end)
of the BED12 entry to perform any relevant feature comparisons. The last six columns will be reported
in the output of all comparisons.
@@ -34,26 +34,26 @@ The file description below is modified from: http://genome.ucsc.edu/FAQ/FAQforma
4. **name** - Defines the name of the BED feature.
- *Any string can be used*. For example, "LINE", "Exon3", "HWIEAS_0001:3:1:0:266#0/1", or "my_Feature".
- *This column is optional*.
-5. **score** - The UCSC definition requires that a BED score range from 0 to 1000, inclusive. However, BEDTools allows any string to be stored in this field in order to allow greater flexibility in annotation features. For example, strings allow scientific notation for p-values, mean enrichment values, etc. It should be noted that this flexibility could prevent such annotations from being correctly displayed on the UCSC browser.
+5. **score** - The UCSC definition requires that a BED score range from 0 to 1000, inclusive. However, bedtools allows any string to be stored in this field in order to allow greater flexibility in annotation features. For example, strings allow scientific notation for p-values, mean enrichment values, etc. It should be noted that this flexibility could prevent such annotations from being correctly displayed on the UCSC browser.
- *Any string can be used*. For example, 7.31E-05 (p-value), 0.33456 (mean enrichment value), "up", "down", etc.
- *This column is optional*.
6. **strand** - Defines the strand - either '+' or '-'.
- *This column is optional*.
7. **thickStart** - The starting position at which the feature is drawn thickly.
- - *Allowed yet ignored by BEDTools*.
+ - *Allowed yet ignored by bedtools*.
8. **thickEnd** - The ending position at which the feature is drawn thickly.
- - *Allowed yet ignored by BEDTools*.
+ - *Allowed yet ignored by bedtools*.
9. **itemRgb** - An RGB value of the form R,G,B (e.g. 255,0,0).
- - *Allowed yet ignored by BEDTools*.
+ - *Allowed yet ignored by bedtools*.
10. **blockCount** - The number of blocks (exons) in the BED line.
- - *Allowed yet ignored by BEDTools*.
+ - *Allowed yet ignored by bedtools*.
11. **blockSizes** - A comma-separated list of the block sizes.
- - *Allowed yet ignored by BEDTools*.
+ - *Allowed yet ignored by bedtools*.
12. **blockStarts** - A comma-separated list of block starts.
- - *Allowed yet ignored by BEDTools*.
+ - *Allowed yet ignored by bedtools*.
-BEDTools requires that all BED input files (and input received from stdin) are **tab-delimited**. The following types of BED files are supported by BEDTools:
+bedtools requires that all BED input files (and input received from stdin) are **tab-delimited**. The following types of BED files are supported by bedtools:
1. | **BED3**: A BED file where each feature is described by **chrom**, **start**, and **end**.
@@ -69,7 +69,7 @@ BEDTools requires that all BED input files (and input received from stdin) are *
| 11873 0 3 354,109,1189, 0,739,1347,
----------------------
-4.1.2 BEDPE format
+BEDPE format
----------------------
We have defined a new file format (BEDPE) in order to concisely describe disjoint genome features,
such as structural variations or paired-end sequence alignments. We chose to define a new format
@@ -106,7 +106,7 @@ The BEDPE format is described below. The description is modified from: http://ge
7. **name** - Defines the name of the BEDPE feature.
- *Any string can be used*. For example, "LINE", "Exon3", "HWIEAS_0001:3:1:0:266#0/1", or "my_Feature".
- *This column is optional*.
-8. **score** - The UCSC definition requires that a BED score range from 0 to 1000, inclusive. *However, BEDTools allows any string to be stored in this field in order to allow greater flexibility in annotation features*. For example, strings allow scientific notation for p-values, mean enrichment values, etc. It should be noted that this flexibility could prevent such annotations from being correctly displayed on the UCSC browser.
+8. **score** - The UCSC definition requires that a BED score range from 0 to 1000, inclusive. *However, bedtools allows any string to be stored in this field in order to allow greater flexibility in annotation features*. For example, strings allow scientific notation for p-values, mean enrichment values, etc. It should be noted that this flexibility could prevent such annotations from being correctly displayed on the UCSC browser.
- *Any string can be used*. For example, 7.31E-05 (p-value), 0.33456 (mean enrichment value), "up", "down", etc.
- *This column is optional*.
9. **strand1** - Defines the strand for the first end of the feature. Either '+' or '-'.
@@ -115,27 +115,29 @@ The BEDPE format is described below. The description is modified from: http://ge
10. **strand2** - Defines the strand for the second end of the feature. Either '+' or '-'.
- *This column is optional*.
- *Use "." for unknown*.
-11. **Any number of additional, user-defined fields** - BEDTools allows one to add as many additional fields to the normal, 10-column BEDPE format as necessary. These columns are merely "passed through" **pairToBed** and **pairToPair** and are not part of any analysis. One would use these additional columns to add extra information (e.g., edit distance for each end of an alignment, or "deletion", "inversion", etc.) to each BEDPE feature.
+11. **Any number of additional, user-defined fields** - bedtools allows one to add as many additional fields to the normal, 10-column BEDPE format as necessary. These columns are merely "passed through" **pairToBed** and **pairToPair** and are not part of any analysis. One would use these additional columns to add extra information (e.g., edit distance for each end of an alignment, or "deletion", "inversion", etc.) to each BEDPE feature.
- *These additional columns are optional*.
Entries from an typical BEDPE file:
::
+
chr1 100 200 chr5 5000 5100 bedpe_example1 30 + -
chr9 1000 5000 chr9 3000 3800 bedpe_example2 100 + -
Entries from a BEDPE file with two custom fields added to each record:
::
+
chr1 10 20 chr5 50 60 a1 30 + - 0 1
chr9 30 40 chr9 80 90 a2 100 + - 2 1
----------------------
-4.1.3 GFF format
+GFF format
----------------------
-The GFF format is described on the Sanger Institute's website (http://www.sanger.ac.uk/resources/software/gff/spec.html). The GFF description below is modified from the definition at this URL. All nine columns in the GFF format description are required by BEDTools.
+The GFF format is described on the Sanger Institute's website (http://www.sanger.ac.uk/resources/software/gff/spec.html). The GFF description below is modified from the definition at this URL. All nine columns in the GFF format description are required by bedtools.
1. **seqname** - The name of the sequence (e.g. chromosome) on which the feature exists.
- *Any string can be used*. For example, "chr1", "III", "myChrom", "contig1112.23".
@@ -147,10 +149,10 @@ The GFF format is described on the Sanger Institute's website (http://www.sanger
- *This column is required*.
4. **start** - The one-based starting position of feature on **seqname**.
- *This column is required*.
- - *BEDTools accounts for the fact the GFF uses a one-based position and BED uses a zero-based start position*.
+ - *bedtools accounts for the fact the GFF uses a one-based position and BED uses a zero-based start position*.
5. **end** - The one-based ending position of feature on **seqname**.
- *This column is required*.
-6. **score** - A score assigned to the GFF feature. Like BED format, BEDTools allows any string to be stored in this field in order to allow greater flexibility in annotation features. We note that this differs from the GFF definition in the interest of flexibility.
+6. **score** - A score assigned to the GFF feature. Like BED format, bedtools allows any string to be stored in this field in order to allow greater flexibility in annotation features. We note that this differs from the GFF definition in the interest of flexibility.
- *This column is required*.
7. **strand** - Defines the strand. Use '+', '-' or '.'
- *This column is required*.
@@ -167,13 +169,13 @@ An entry from an example GFF file :
-----------------------
-4.1.3 GFF format
-----------------------
-Some of the BEDTools (e.g., genomeCoverageBed, complementBed, slopBed) need to know the size of
+------------------------
+*Genome* file format
+------------------------
+Some of the bedtools (e.g., genomeCoverageBed, complementBed, slopBed) need to know the size of
the chromosomes for the organism for which your BED files are based. When using the UCSC Genome
Browser, Ensemble, or Galaxy, you typically indicate which which species/genome build you are
-working. The way you do this for BEDTools is to create a "genome" file, which simply lists the names of
+working. The way you do this for bedtools is to create a "genome" file, which simply lists the names of
the chromosomes (or scaffolds, etc.) and their size (in basepairs).
@@ -185,29 +187,28 @@ Genome files must be **tab-delimited** and are structured as follows (this is an
chrX 17718854
chrM 13794
-BEDTools includes pre-defined genome files for human and mouse in the **/genomes** directory included
-in the BEDTools distribution.
+bedtools includes pre-defined genome files for human and mouse in the **/genomes** directory included
+in the bedtools distribution.
----------------------
-4.1.5 SAM/BAM format
+SAM/BAM format
----------------------
The SAM / BAM format is a powerful and widely-used format for storing sequence alignment data (see
http://samtools.sourceforge.net/ for more details). It has quickly become the standard format to which
-most DNA sequence alignment programs write their output. Currently, the following BEDTools
-support inout in BAM format: *intersectBed, windowBed, coverageBed, genomeCoverageBed,
-pairToBed, bamToBed*. Support for the BAM format in BEDTools allows one to (to name a few):
+most DNA sequence alignment programs write their output. Currently, the following bedtools
+support input in BAM format: ``intersect``, ``window``, ``coverage``, ``genomecov``,
+``pairtobed``, ``bamtobed``. Support for the BAM format in bedtools allows one to (to name a few):
compare sequence alignments to annotations, refine alignment datasets, screen for potential mutations
and compute aligned sequence coverage.
-The details of how these tools work with BAM files are addressed in **Section 5** of this manual.
----------------------
-4.1.6 VCF format
+VCF format
----------------------
The Variant Call Format (VCF) was conceived as part of the 1000 Genomes Project as a standardized
means to report genetic variation calls from SNP, INDEL and structural variant detection programs
(see http://www.1000genomes.org/wiki/doku.php?id=1000_genomes:analysis:vcf4.0 for details).
-BEDTools now supports the latest version of this format (i.e, Version 4.0). As a result, BEDTools can
+bedtools now supports the latest version of this format (i.e, Version 4.0). As a result, bedtools can
be used to compare genetic variation calls with other genomic features.
diff --git a/docs/content/installation.rst b/docs/content/installation.rst
index 675cb33d4dacb53d91ff5e518b2ccdb49383997d..6b6018fcad5c116112258e3effb055d3a421cce5 100755
--- a/docs/content/installation.rst
+++ b/docs/content/installation.rst
@@ -2,24 +2,28 @@
Installation
############
-BEDTools is intended to run in a "command line" environment on UNIX, LINUX and Apple OS X
-operating systems. Installing BEDTools involves downloading the latest source code archive followed by
-compiling the source code into binaries on your local system. The following commands will install
-BEDTools in a local directory on a NIX or OS X machine. Note that the **"<version>"** refers to the
-latest posted version number on http://bedtools.googlecode.com/.
+``bedtools`` is intended to run in a "command line" environment on UNIX, LINUX
+and Apple OS X operating systems. Installing BEDTools involves downloading the
+latest source code archive followed by compiling the source code into binaries
+on your local system. The following commands will install ``bedtools`` in a
+local directory on an UNIX or OS X machine. Note that the **"<version>"**
+refers to the latest posted version number on http://bedtools.googlecode.com/.
-Note: *The BEDTools "makefiles" use the GCC compiler. One should edit the Makefiles accordingly if
-one wants to use a different compiler.*::
+.. note::
- curl http://bedtools.googlecode.com/files/BEDTools.<version>.tar.gz > BEDTools.tar.gz
- tar -zxvf BEDTools.tar.gz
- cd BEDTools-<version>
- make clean
- make all
- ls bin
+ The bedtools Makefiles utilize the GCC compiler. One should edit the
+ Makefiles accordingly if one wants to use a different compiler.
+
+.. code-block:: bash
+
+ $ curl http://bedtools.googlecode.com/files/BEDTools.<version>.tar.gz > BEDTools.tar.gz
+ $ tar -zxvf BEDTools.tar.gz
+ $ cd BEDTools-<version>
+ $ make
-At this point, one should copy the binaries in BEDTools/bin/ to either usr/local/bin/ or some
-other repository for commonly used UNIX tools in your environment. You will typically require
-administrator (e.g. "root" or "sudo") privileges to copy to usr/local/bin/. If in doubt, contact you
+At this point, one should copy the binaries in ./bin/ to either
+``usr/local/bin/`` or some other repository for commonly used UNIX tools in
+your environment. You will typically require administrator (e.g. "root" or
+"sudo") privileges to copy to ``usr/local/bin/``. If in doubt, contact you
system administrator for help.
diff --git a/docs/content/overview.rst b/docs/content/overview.rst
index a836365eed7efe9af3f73c1d5f705d9a7cc7ef8b..3275cb2dbe59b1622ae6140f024bd4faa2217ec2 100755
--- a/docs/content/overview.rst
+++ b/docs/content/overview.rst
@@ -1,73 +1,81 @@
-.. role:: red
-
############
Overview
############
==========
-1.1 Background
+Background
==========
-The development of BEDTools was motivated by a need for fast, flexible tools with which to compare large sets of genomic
+The development of bedtools was motivated by a need for fast, flexible tools with which to compare large sets of genomic
features. Answering fundamental research questions with existing tools was either too slow or required modifications to the
way they reported or computed their results. We were aware of the utilities on the UCSC Genome Browser and Galaxy websites, as
well as the elegant tools available as part of Jim Kent’s monolithic suite of tools (“Kent sourceâ€). However, we found that
the web-based tools were too cumbersome when working with large datasets generated by current sequencing technologies.
Similarly, we found that the Kent source command line tools often required a local installation of the UCSC Genome Browser.
These limitations, combined with the fact that we often wanted an extra option here or there that wasn’t available with
-existing tools, led us to develop our own from scratch. The initial version of BEDTools was publicly released in the spring of
+existing tools, led us to develop our own from scratch. The initial version of bedtools was publicly released in the spring of
2009. The current version has evolved from our research experiences and those of the scientists using the suite over the last
-year. The BEDTools suite enables one to answer common questions of genomic data in a fast and reliable manner. The fact that
+year. The bedtools suite enables one to answer common questions of genomic data in a fast and reliable manner. The fact that
almost all the utilities accept input from “stdin†allows one to “stream / pipe†several commands together to facilitate more
-complicated analyses. Also, the tools allow fine control over how output is reported. The initial version of BEDTools
+complicated analyses. Also, the tools allow fine control over how output is reported. The initial version of bedtools
supported solely 6-column `BED <http://genome.ucsc.edu/FAQ/FAQformat#format1>`_ files. *However, we have subsequently added support for sequence alignments in* `BAM <http://samtools.sourceforge.net/>`_
*format, as well as for features in* `GFF <http://genome.ucsc.edu/FAQ/FAQformat#format3>`_ , *“blocked†BED format, and*
`VCF <http://www.1000genomes.org/wiki/Analysis/Variant%20Call%20Format/vcf-variant-call-format-version-41>`_ *format*.
The tools are quite fast and typically finish in a matter of a few seconds, even for large datasets. This manual seeks to describe the behavior and
-available functionality for each BEDTool. Usage examples are scattered throughout the text, and formal examples are
+available functionality for each bedtool. Usage examples are scattered throughout the text, and formal examples are
provided in the last two sections, we hope that this document will give you a sense of the flexibility of
-the toolkit and the types of analyses that are possible with BEDTools. If you have further questions, please join the BEDTools
+the toolkit and the types of analyses that are possible with bedtools. If you have further questions, please join the bedtools
discussion group, visit the Usage Examples on the Google Code site (usage, advanced usage), or take a look at the nascent
“Usage From the Wild†page.
===========================
-1.2 Summary of available tools.
+Summary of available tools.
===========================
-BEDTools support a wide range of operations for interrogating and manipulating genomic features. The table below summarizes
+bedtools support a wide range of operations for interrogating and manipulating genomic features. The table below summarizes
the tools available in the suite.
=========================== =========================================================================================================================================================
Utility Description
=========================== =========================================================================================================================================================
-**intersectBed** Returns overlaps between two BED/GFF/VCF files.
-**pairToBed** Returns overlaps between a paired-end BED file and a regular BED/VCF/GFF file.
-**bamToBed** Converts BAM alignments to BED6, BED12, or BEDPE format.
-**bedToBam** Converts BED/GFF/VCF features to BAM format.
-**bed12ToBed6** Converts "blocked" BED12 features to discrete BED6 features.
-**bedToIgv** Creates IGV batch scripts for taking multiple snapshots from BED/GFF/VCF features.
-**coverageBed** Summarizes the depth and breadth of coverage of features in one BED versus features (e.g, windows, exons, etc.) defined in another BED/GFF/VCF file.
-**multiBamCov** Counts sequence coverage for multiple position-sorted bams at specific loci defined in a BED/GFF/VCF file
-**tagBam** Annotates a BAM file with custom tag fields based on overlaps with BED/GFF/VCF files
-**nuclBed** Profiles the nucleotide content of intervals in a fasta file
-**genomeCoverageBed** Creates either a histogram, BEDGRAPH, or a "per base" report of genome coverage.
-**unionBedGraphs** Combines multiple BedGraph? files into a single file, allowing coverage/other comparisons between them.
-**annotateBed** Annotates one BED/VCF/GFF file with overlaps from many others.
-**groupBy** Deprecated. Now in the filo package.
-**overlap** Returns the number of bases pairs of overlap b/w two features on the same line.
-**pairToPair** Returns overlaps between two paired-end BED files.
-**closestBed** Returns the closest feature to each entry in a BED/GFF/VCF file.
-**subtractBed** Removes the portion of an interval that is overlapped by another feature.
-**windowBed** Returns overlaps between two BED/VCF/GFF files based on a user-defined window.
-**mergeBed** Merges overlapping features into a single feature.
-**complementBed** Returns all intervals not spanned by the features in a BED/GFF/VCF file.
-**fastaFromBed** Creates FASTA sequences based on intervals in a BED/GFF/VCF file.
-**maskFastaFromBed** Masks a FASTA file based on BED coordinates.
-**shuffleBed** Randomly permutes the locations of a BED file among a genome.
-**slopBed** Adjusts each BED entry by a requested number of base pairs.
-**flankBed** Creates flanking intervals for each feature in a BED/GFF/VCF file.
-**sortBed** Sorts a BED file by chrom, then start position. Other ways as well.
-**linksBed** Creates an HTML file of links to the UCSC or a custom browser.
+**annotate** Annotate coverage of features from multiple files.
+**bamtobed** Convert BAM alignments to BED (& other) formats.
+**bamtofastq** Convert BAM records to FASTQ records.
+**bed12tobed6** Breaks BED12 intervals into discrete BED6 intervals.
+**bedpetobam** Convert BEDPE intervals to BAM records.
+**bedtobam** Convert intervals to BAM records.
+**closest** Find the closest, potentially non-overlapping interval.
+**cluster** Cluster (but don't merge) overlapping/nearby intervals.
+**complement** Extract intervals _not_ represented by an interval file.
+**coverage** Compute the coverage over defined intervals.
+**expand** Replicate lines based on lists of values in columns.
+**flank** Create new intervals from the flanks of existing intervals.
+**genomecov** Compute the coverage over an entire genome.
+**getfasta** Use intervals to extract sequences from a FASTA file.
+**groupby** Group by common cols. & summarize oth. cols. (~ SQL "groupBy")
+**igv** Create an IGV snapshot batch script.
+**intersect** Find overlapping intervals in various ways.
+**jaccard** Calculate the Jaccard statistic b/w two sets of intervals.
+**links** Create a HTML page of links to UCSC locations.
+**makewindows** Make interval "windows" across a genome.
+**map** Apply a function to a column for each overlapping interval.
+**maskfasta** Use intervals to mask sequences from a FASTA file.
+**merge** Combine overlapping/nearby intervals into a single interval.
+**multicov** Counts coverage from multiple BAMs at specific intervals.
+**multiinter** Identifies common intervals among multiple interval files.
+**nuc** Profile the nucleotide content of intervals in a FASTA file.
+**overlap** Computes the amount of overlap from two intervals.
+**pairtobed** Find pairs that overlap intervals in various ways.
+**pairtopair** Find pairs that overlap other pairs in various ways.
+**random** Generate random intervals in a genome.
+**reldist** Calculate the distribution of relative distances b/w two files.
+**shuffle** Randomly redistrubute intervals in a genome.
+**slop** Adjust the size of intervals.
+**sort** Order the intervals in a file.
+**subtract** Remove intervals based on overlaps b/w two files.
+**tag** Tag BAM alignments based on overlaps with interval files.
+**unionbedg** Combines coverage intervals from multiple BEDGRAPH files.
+**window** Find overlapping intervals within a window around an interval.
=========================== =========================================================================================================================================================
@@ -76,19 +84,19 @@ Utility Description
===========================
-1.3 Fundamental concepts.
+Fundamental concepts.
===========================
------------------------------------------------------
-1.3.1 What are genome features and how are they represented?
+What are genome features and how are they represented?
------------------------------------------------------
-Throughout this manual, we will discuss how to use BEDTools to manipulate, compare and ask questions of genome “featuresâ€. Genome features can be functional elements (e.g., genes), genetic polymorphisms (e.g.
+Throughout this manual, we will discuss how to use bedtools to manipulate, compare and ask questions of genome “featuresâ€. Genome features can be functional elements (e.g., genes), genetic polymorphisms (e.g.
SNPs, INDELs, or structural variants), or other annotations that have been discovered or curated by genome sequencing groups or genome browser groups. In addition, genome features can be custom annotations that
an individual lab or researcher defines (e.g., my novel gene or variant).
The basic characteristics of a genome feature are the chromosome or scaffold on which the feature “residesâ€, the base pair on which the
feature starts (i.e. the “startâ€), the base pair on which feature ends (i.e. the “endâ€), the strand on which the feature exists (i.e. “+†or “-“), and the name of the feature if one is applicable.
-The two most widely used formats for representing genome features are the BED (Browser Extensible Data) and GFF (General Feature Format) formats. BEDTools was originally written to work exclusively with genome features
+The two most widely used formats for representing genome features are the BED (Browser Extensible Data) and GFF (General Feature Format) formats. bedtools was originally written to work exclusively with genome features
described using the BED format, but it has been recently extended to seamlessly work with BED, GFF and VCF files.
Existing annotations for the genomes of many species can be easily downloaded in BED and GFF
@@ -96,7 +104,7 @@ format from the UCSC Genome Browser’s “Table Browser†(http://genome.ucsc.
Ensemble Genome Browser contains annotations in GFF/GTF format for many species (http://www.ensembl.org/info/data/ftp/index.html)
-------------------------------------
-1.3.2 Overlapping / intersecting features.
+Overlapping / intersecting features.
-------------------------------------
Two genome features (henceforth referred to as “featuresâ€) are said to overlap or intersect if they share at least one base in common.
In the figure below, Feature A intersects/overlaps Feature B, but it does not intersect/overlap Feature C.
@@ -104,26 +112,26 @@ In the figure below, Feature A intersects/overlaps Feature B, but it does not in
**TODO: place figure here**
--------------------------------------------
-1.3.3 Comparing features in file “A†and file “Bâ€.
+Comparing features in file “A†and file “Bâ€.
--------------------------------------------
-The previous section briefly introduced a fundamental naming convention used in BEDTools. Specifically, all BEDTools that compare features contained in two distinct files refer to one file as feature set “A†and the other file as feature set “Bâ€. This is mainly in the interest of brevity, but it also has its roots in set theory.
-As an example, if one wanted to look for SNPs (file A) that overlap with exons (file B), one would use intersectBed in the following manner::
+The previous section briefly introduced a fundamental naming convention used in bedtools. Specifically, all bedtools that compare features contained in two distinct files refer to one file as feature set “A†and the other file as feature set “Bâ€. This is mainly in the interest of brevity, but it also has its roots in set theory.
+As an example, if one wanted to look for SNPs (file A) that overlap with exons (file B), one would use bedtools intersect in the following manner::
- intersectBed –a snps.bed –b exons.bed
+ bedtools intersect –a snps.bed –b exons.bed
There are two exceptions to this rule: 1) When the “A†file is in BAM format, the “-abam†option must bed used. For example::
- intersectBed –abam alignedReads.bam –b exons.bed
+ bedtools intersect –abam alignedReads.bam –b exons.bed
And 2) For tools where only one input feature file is needed, the “-i†option is used. For example::
- mergeBed –i repeats.bed
+ bedtools merge –i repeats.bed
-----------------------------------------------------
-1.3.4 BED starts are zero-based and BED ends are one-based.
+BED starts are zero-based and BED ends are one-based.
-----------------------------------------------------
-BEDTools users are sometimes confused by the way the start and end of BED features are represented. Specifically, BEDTools uses the UCSC Genome Browser’s internal database convention of making the start position 0-based and the end position 1-based: (http://genome.ucsc.edu/FAQ/FAQtracks#tracks1)
-In other words, BEDTools interprets the “start†column as being 1 basepair higher than what is represented in the file. For example, the following BED feature represents a single base on chromosome 1; namely, the 1st base::
+bedtools users are sometimes confused by the way the start and end of BED features are represented. Specifically, bedtools uses the UCSC Genome Browser’s internal database convention of making the start position 0-based and the end position 1-based: (http://genome.ucsc.edu/FAQ/FAQtracks#tracks1)
+In other words, bedtools interprets the “start†column as being 1 basepair higher than what is represented in the file. For example, the following BED feature represents a single base on chromosome 1; namely, the 1st base::
chr1 0 1 first_base
@@ -131,27 +139,27 @@ Why, you might ask? The advantage of storing features this way is that when comp
the calculation would be (slightly) more complex (i.e. (end-start)+1). Thus, storing BED features this way reduces the computational burden.
-----------------------------------------------------
-1.3.5 GFF starts and ends are one-based.
+GFF starts and ends are one-based.
-----------------------------------------------------
-In contrast, the GFF format uses 1-based coordinates for both the start and the end positions. BEDTools is aware of this and adjusts the positions accordingly.
-In other words, you don’t need to subtract 1 from the start positions of your GFF features for them to work correctly with BEDTools.
+In contrast, the GFF format uses 1-based coordinates for both the start and the end positions. bedtools is aware of this and adjusts the positions accordingly.
+In other words, you don’t need to subtract 1 from the start positions of your GFF features for them to work correctly with bedtools.
-----------------------------------------------------
-1.3.6 VCF coordinates are one-based.
+VCF coordinates are one-based.
-----------------------------------------------------
-The VCF format uses 1-based coordinates. As in GFF, BEDTools is aware of this and adjusts the positions accordingly.
-In other words, you don’t need to subtract 1 from the start positions of your VCF features for them to work correctly with BEDTools.
+The VCF format uses 1-based coordinates. As in GFF, bedtools is aware of this and adjusts the positions accordingly.
+In other words, you don’t need to subtract 1 from the start positions of your VCF features for them to work correctly with bedtools.
-----------------------------------------------------
-1.3.7 File B is loaded into memory (most of the time).
+File B is loaded into memory (most of the time).
-----------------------------------------------------
-Whenever a BEDTool compares two files of features, the “B†file is loaded into memory. By contrast, the “A†file is processed line by line and compared with the features from B.
+Whenever a bedtool compares two files of features, the “B†file is loaded into memory. By contrast, the “A†file is processed line by line and compared with the features from B.
Therefore to minimize memory usage, one should set the smaller of the two files as the B file. One salient example is the comparison of aligned sequence reads from a
current DNA sequencer to gene annotations. In this case, the aligned sequence file (in BED format) may have tens of millions of features (the sequence alignments),
while the gene annotation file will have tens of thousands of features. In this case, it is wise to sets the reads as file A and the genes as file B.
-----------------------------------------------------
-1.3.8 Feature files *must* be tab-delimited.
+Feature files *must* be tab-delimited.
-----------------------------------------------------
This is rather self-explanatory. While it is possible to allow BED files to be space-delimited, we have decided to require tab delimiters for three reasons:
@@ -160,37 +168,37 @@ This is rather self-explanatory. While it is possible to allow BED files to be s
3. GFF files can contain spaces within attribute columns. This complicates the use of space-delimited files as spaces must therefore be treated specially depending on the context.
-------------------------------------------------------------
-1.3.9 All BEDTools allow features to be “piped†via standard input.
+All bedtools allow features to be “piped†via standard input.
-------------------------------------------------------------
-In an effort to allow one to combine multiple BEDTools and other UNIX utilities into more complicated “pipelinesâ€, all BEDTools allow features
-to be passed to them via standard input. Only one feature file may be passed to a BEDTool via standard input.
-The convention used by all BEDTools is to set either file A or file B to “stdin†or "-". For example::
+In an effort to allow one to combine multiple bedtools and other UNIX utilities into more complicated “pipelinesâ€, all bedtools allow features
+to be passed to them via standard input. Only one feature file may be passed to a bedtool via standard input.
+The convention used by all bedtools is to set either file A or file B to “stdin†or "-". For example::
- cat snps.bed | intersectBed –a stdin –b exons.bed
- cat snps.bed | intersectBed –a - –b exons.bed
+ cat snps.bed | bedtools intersect –a stdin –b exons.bed
+ cat snps.bed | bedtools intersect –a - –b exons.bed
-In addition, all BEDTools that simply require one main input file (the -i file) will assume that input is
+In addition, all bedtools that simply require one main input file (the -i file) will assume that input is
coming from standard input if the -i parameter is ignored. For example, the following are equivalent::
- cat snps.bed | sortBed –i stdin
- cat snps.bed | sortBed
+ cat snps.bed | bedtools sort –i stdin
+ cat snps.bed | bedtools sort
------------------------------------------------------
-1.3.10 Most BEDTools write their results to standard output.
+Most bedtools write their results to standard output.
------------------------------------------------------
-To allow one to combine multiple BEDTools and other UNIX utilities into more complicated “pipelinesâ€,
-most BEDTools report their output to standard output, rather than to a named file. If one wants to write the output to a named file, one can use the UNIX “file redirection†symbol “>†to do so.
+To allow one to combine multiple bedtools and other UNIX utilities into more complicated “pipelinesâ€,
+most bedtools report their output to standard output, rather than to a named file. If one wants to write the output to a named file, one can use the UNIX “file redirection†symbol “>†to do so.
Writing to standard output (the default)::
- intersectBed –a snps.bed –b exons.bed
+ bedtools intersect –a snps.bed –b exons.bed
chr1 100100 100101 rs233454
chr1 200100 200101 rs446788
chr1 300100 300101 rs645678
Writing to a file::
- intersectBed –a snps.bed –b exons.bed > snps.in.exons.bed
+ bedtools intersect –a snps.bed –b exons.bed > snps.in.exons.bed
cat snps.in.exons.bed
chr1 100100 100101 rs233454
@@ -198,12 +206,12 @@ Writing to a file::
chr1 300100 300101 rs645678
------------------------
-1.3.11 What is a “genome†file?
+What is a “genome†file?
------------------------
-Some of the BEDTools (e.g., genomeCoverageBed, complementBed, slopBed) need to know the size of
+Some of the bedtools (e.g., ``genomecov``, ``complement``, ``slop``) need to know the size of
the chromosomes for the organism for which your BED files are based. When using the UCSC Genome
Browser, Ensemble, or Galaxy, you typically indicate which species / genome build you are working.
-The way you do this for BEDTools is to create a “genome†file, which simply lists the names of the
+The way you do this for bedtools is to create a “genome†file, which simply lists the names of the
chromosomes (or scaffolds, etc.) and their size (in basepairs).
Genome files must be tab-delimited and are structured as follows (this is an example for C. elegans)::
@@ -213,13 +221,13 @@ Genome files must be tab-delimited and are structured as follows (this is an exa
chrX 17718854
chrM 13794
-BEDTools includes predefined genome files for human and mouse in the /genomes directory included
-in the BEDTools distribution. Additionally, the “chromInfo†files/tables available from the UCSC
+bedtools includes predefined genome files for human and mouse in the /genomes directory included
+in the bedtools distribution. Additionally, the “chromInfo†files/tables available from the UCSC
Genome Browser website are acceptable. For example, one can download the hg19 chromInfo file here:
http://hgdownload.cse.ucsc.edu/goldenPath/hg19/database/chromInfo.txt.gz
------------------------------------
-1.3.12 Paired-end BED files (BEDPE files).
+Paired-end BED files (BEDPE files).
------------------------------------
We have defined a new file format (BEDPE) to concisely describe disjoint genome features, such as
structural variations or paired-end sequence alignments. We chose to define a new format because the
@@ -227,26 +235,26 @@ existing BED block format (i.e. BED12) does not allow inter-chromosomal feature
the BED12 format feels rather bloated when one want to describe events with only two blocks.
------------------------------------------
-1.3.13 Use “-h†for help with any BEDTool.
+Use “-h†for help with any bedtool.
------------------------------------------
-Rather straightforward. If you use the “-h†option with any BEDTool, a full menu of example usage
+Rather straightforward. If you use the “-h†option with any bedtool, a full menu of example usage
and available options (when applicable) will be reported.
--------------------------------------------------
-1.3.14 BED features must not contain negative positions.
+BED features must not contain negative positions.
--------------------------------------------------
-BEDTools will typically reject BED features that contain negative positions. In special cases, however,
+bedtools will typically reject BED features that contain negative positions. In special cases, however,
BEDPE positions may be set to -1 to indicate that one or more ends of a BEDPE feature is unaligned.
---------------------------------------------------
-1.3.15 The start position must be <= to the end position.
+The start position must be <= to the end position.
---------------------------------------------------
-BEDTools will reject BED features where the start position is greater than the end position.
+bedtools will reject BED features where the start position is greater than the end position.
-----------------------------------------
-1.3.16 Headers are allowed in GFF and BED files
+Headers are allowed in GFF and BED files
-----------------------------------------
-BEDTools will ignore headers at the beginning of BED and GFF files. Valid header lines begin with a
+bedtools will ignore headers at the beginning of BED and GFF files. Valid header lines begin with a
“#†symbol, the work “trackâ€, or the word “browserâ€. For example, the following examples are valid
headers for BED or GFF files::
@@ -263,20 +271,20 @@ headers for BED or GFF files::
chr5 2380000 2386000 read2 60 -
-------------------------------------------------------------
-1.3.17 GZIP support: BED, GFF, VCF, and BEDPE file can be “gzippedâ€
+GZIP support: BED, GFF, VCF, and BEDPE file can be “gzippedâ€
-------------------------------------------------------------
-BEDTools will process gzipped BED, GFF, VCF and BEDPE files in the same manner as
+bedtools will process gzipped BED, GFF, VCF and BEDPE files in the same manner as
uncompressed files. Gzipped files are auto-detected thanks to a helpful contribution from Gordon
Assaf.
----------------------------------------------------------------------------
-1.3.18 Support for “split†or “spliced†BAM alignments and “blocked†BED features
+Support for “split†or “spliced†BAM alignments and “blocked†BED features
----------------------------------------------------------------------------
-As of Version 2.8.0, five BEDTools (``intersectBed``, ``coverageBed``, ``genomeCoverageBed``,
+As of Version 2.8.0, five bedtools (``intersect``, ``coverage``, ``genomecob``,
``bamToBed``, and ``bed12ToBed6``) can properly handle “splitâ€/â€spliced†BAM alignments (i.e., having an
“N†CIGAR operation) and/or “blocked†BED (aka BED12) features.
-``intersectBed``, ``coverageBed``, and ``genomeCoverageBed`` will optionally handle “split†BAM and/or
+``intersect``, ``coverage``, and ``genomecov`` will optionally handle “split†BAM and/or
“blocked†BED by using the ``-split`` option. This will cause intersects or coverage to be computed only
for the alignment or feature blocks. In contrast, without this option, the intersects/coverage would be
computed for the entire “span†of the alignment or feature, regardless of the size of the gaps between
@@ -293,56 +301,27 @@ be reported for the portions of the read that overlap the exons (i.e. 30bp on on
Using the -split option with bamToBed causes “spliced/split†alignments to be reported in BED12
-format. Using the -split option with bed12ToBed6 causes “blocked†BED12 features to be reported in
+format. Using the -split option with ``bed12tobed6`` causes “blocked†BED12 features to be reported in
BED6 format.
--------------------------------
-1.3.19 Writing uncompressed BAM output.
+Writing uncompressed BAM output.
--------------------------------
When working with a large BAM file using a complex set of tools in a pipe/stream, it is advantageous
to pass uncompressed BAM output to each downstream program. This minimizes the amount of time
-spent compressing and decompressing output from one program to the next. All BEDTools that create
-BAM output (e.g. ``intersectBed``, ``windowBed``) will now optionally create uncompressed BAM output
+spent compressing and decompressing output from one program to the next. All bedtools that create
+BAM output (e.g. ``intersect``, ``window``) will now optionally create uncompressed BAM output
using the ``-ubam`` option.
=====================================
-1.4 Implementation and algorithmic notes.
+Implementation and algorithmic notes.
=====================================
-BEDTools was implemented in C++ and makes extensive use of data structures and fundamental
+bedtools was implemented in C++ and makes extensive use of data structures and fundamental
algorithms from the Standard Template Library (STL). Many of the core algorithms are based upon the
genome binning algorithm described in the original UCSC Genome Browser paper (Kent et al, 2002).
The tools have been designed to inherit core data structures from central source files, thus allowing
rapid tool development and deployment of improvements and corrections. Support for BAM files is
made possible through Derek Barnett’s elegant C++ API called BamTools.
-
-
-=====================================
-1.5 License and availability.
-=====================================
-BEDTools is freely available under a GNU Public License (Version 2) at:
-http://bedtools.googlecode.com
-
-
-
-=====================================
-1.6 Mailing list.
-=====================================
-A discussion group for reporting bugs, asking questions of the developer and of the user community, as
-well as for requesting new features is available at:
-http://groups.google.com/group/bedtools-discuss
-
-
-
-=====================================
-1.7 Contributors.
-=====================================
-As open-source software, BEDTools greatly benefits from contributions made by other developers and
-users of the tools. We encourage and welcome suggestions, contributions and complaints. This is how
-software matures, improves and stays on top of the needs of its user community. The Google Code
-(GC) site maintains a list of individuals who have contributed either source code or useful ideas for
-improving the tools. In the near future, we hope to maintain a source repository on the GC site in
-order to facilitate further contributions. We are currently unable to do so because we use Git for
-version control, which is not yet supported by GC.
\ No newline at end of file
diff --git a/docs/content/quick-start.rst b/docs/content/quick-start.rst
index 64f2df32c3f342cf9c53adeb7949653276afec59..7443ce92bf72fbab3ee9d083d67410f824858a17 100755
--- a/docs/content/quick-start.rst
+++ b/docs/content/quick-start.rst
@@ -3,54 +3,67 @@ Quick start
###########
================
-Install BEDTools
+Install bedtools
================
-::
+
+.. code-block:: bash
curl http://bedtools.googlecode.com/files/BEDTools.<version>.tar.gz > BEDTools.tar.gz
tar -zxvf BEDTools.tar.gz
cd BEDTools
- make clean
- make all
+ make
sudo cp bin/* /usr/local/bin/
+
===============
-Use BEDTools
+Use bedtools
===============
-Below are examples of typical BEDTools usage. **Additional usage examples are described in
-section 6 of this manual.** Using the "-h" option with any BEDTools will report a list of all command
-line options.
+Below are examples of typical bedtools usage. Using the "-h" option with any
+bedtools will report a list of all command line options.
+
+
+Report the base-pair overlap between the features in two BED files.
+
+.. code-block:: bash
+
+ bedtools intersect -a reads.bed -b genes.bed
+
-A. Report the base-pair overlap between the features in two BED files.
-::
+Report those entries in A that overlap NO entries in B. Like "grep -v"
- intersectBed -a reads.bed -b genes.bed
+.. code-block:: bash
-B. Report those entries in A that overlap NO entries in B. Like "grep -v"
-::
+ bedtools intersect -a reads.bed -b genes.bed
- intersectBed -a reads.bed -b genes.bed ¨Cv
-C. Read BED A from stdin. Useful for stringing together commands. For example, find genes that overlap LINEs
-but not SINEs.
-::
+Read BED A from STDIN. Useful for stringing together commands. For example,
+find genes that overlap LINEs but not SINEs.
- intersectBed -a genes.bed -b LINES.bed | intersectBed -a stdin -b SINEs.bed ¨Cv
+.. code-block:: bash
-D. Find the closest ALU to each gene.
-::
+ bedtools intersect -a genes.bed -b LINES.bed | \
+ bedtools intersect -a stdin -b SINEs.bed
- closestBed -a genes.bed -b ALUs.bed
+
+Find the closest ALU to each gene.
+
+.. code-block:: bash
+
+ bedtools closest -a genes.bed -b ALUs.bed
-E. Merge overlapping repetitive elements into a single entry, returning the number of entries merged.
-::
- mergeBed -i repeatMasker.bed -n
+Merge overlapping repetitive elements into a single entry, returning the number of entries merged.
+
+.. code-block:: bash
+
+ bedtools merge -i repeatMasker.bed -n
-F. Merge nearby repetitive elements into a single entry, so long as they are within 1000 bp of one another.
-::
- mergeBed -i repeatMasker.bed -d 1000
+Merge nearby repetitive elements into a single entry, so long as they are within 1000 bp of one another.
+
+.. code-block:: bash
+
+ bedtools merge -i repeatMasker.bed -d 1000
diff --git a/docs/index.rst b/docs/index.rst
index ed1507f41f926c12da96b126b3706cea0044d1d7..c307d1732b912f601185d4addf72386084a13540 100755
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -2,14 +2,16 @@
**bedtools**: *a powerful toolset for genome arithmetic*
================================================================
-=================
-Overview
-=================
-
-.. todo::
-
- Brief paragraph of the software.
+Collectively, the **bedtools** utilities are a swiss-army knife of tools
+for a wide-range of genomics analysis tasks. The most widely-used
+tools enable *genome arithmetic*: that is, set theory on the genome. For
+example, **bedtools** allows one to *intersect*, *merge*, *count*, *complement*,
+and *shuffle* genomic intervals from multiple files in widely-used
+genomic file formats such as BAM, BED, GFF/GTF, VCF.
+While each individual tool is designed to do a relatively simple task (e.g.,
+*intersect* two interval files), quite sophisticated analyses can be conducted
+by combining multiple bedtools operations on the UNIX command line.
=================
Table of contents
@@ -25,11 +27,51 @@ Table of contents
content/bedtools-suite
content/example-usage
content/advanced-usage
- content/FAQ
+ content/tips-and-tricks
+ content/faq
+
+
+=================
+Brief example
+=================
+Let's imagine you have a BED file of ChiP-seq peaks from two different]
+experiments. You want to identify peaks that were observed in *both* experiments
+(requiring 50% reciprocal overlap) and for those peaks, you want to find to
+find the closest, non-overlapping gene. Such an analysis could be conducted
+with two, relatively simple bedtools commands.
+
+.. code-block:: bash
+
+ # intersect the peaks from both experiments.
+ # -f 0.50 combined with -r requires 50% reciprocal overlap between the
+ # peaks from each experiment.
+ $ bedtools intersect -a exp1.bed -b exp2.bed -f 0.50 -r > both.bed
+
+ # find the closest, non-overlapping gene for each interval where
+ # both experiments had a peak
+ # -io ignores overlapping intervals and returns only the closest,
+ # non-overlapping interval (in this case, genes)
+ $ bedtools closest -a both.bed -b genes.bed -io > both.nearest.genes.txt
+
+==========
+License
+==========
+bedtools is freely available under a GNU Public License (Version 2).
+=====================================
+Contributors.
+=====================================
+As open-source software, BEDTools greatly benefits from contributions made by other developers and
+users of the tools. We encourage and welcome suggestions, contributions and complaints. This is how
+software matures, improves and stays on top of the needs of its user community. The Google Code
+(GC) site maintains a list of individuals who have contributed either source code or useful ideas for
+improving the tools. In the near future, we hope to maintain a source repository on the GC site in
+order to facilitate further contributions. We are currently unable to do so because we use Git for
+version control, which is not yet supported by GC.
=================
Mailing list
=================
-Refer to the mailing list.
+If you have questions, requests, or bugs to report, please email the
+`bedtools mailing list <https://groups.google.com/forum/?fromgroups#!forum/bedtools-discuss>`_