% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\usepackage[utf8]{inputenc}
\DeclareUnicodeCharacter{00A0}{\nobreakspace}
\usepackage[T1]{fontenc}
\usepackage{babel}
\usepackage{times}
\usepackage[Bjarne]{fncychap}
\usepackage{longtable}
\usepackage{sphinx}
\usepackage{multirow}


\title{Bedtools Documentation}
\date{January 27, 2013}
\release{2.17.0}
\author{Quinlan lab @ UVa}
\newcommand{\sphinxlogo}{}
\renewcommand{\releasename}{Release}
\makeindex

\makeatletter
\def\PYG@reset{\let\PYG@it=\relax \let\PYG@bf=\relax%
    \let\PYG@ul=\relax \let\PYG@tc=\relax%
    \let\PYG@bc=\relax \let\PYG@ff=\relax}
\def\PYG@tok#1{\csname PYG@tok@#1\endcsname}
\def\PYG@toks#1+{\ifx\relax#1\empty\else%
    \PYG@tok{#1}\expandafter\PYG@toks\fi}
\def\PYG@do#1{\PYG@bc{\PYG@tc{\PYG@ul{%
    \PYG@it{\PYG@bf{\PYG@ff{#1}}}}}}}
\def\PYG#1#2{\PYG@reset\PYG@toks#1+\relax+\PYG@do{#2}}

\expandafter\def\csname PYG@tok@gd\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.63,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gu\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.50,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@gt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.25,0.82}{##1}}}
\expandafter\def\csname PYG@tok@gs\endcsname{\let\PYG@bf=\textbf}
\expandafter\def\csname PYG@tok@gr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{1.00,0.00,0.00}{##1}}}
\expandafter\def\csname PYG@tok@cm\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@vg\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@m\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@cs\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\colorbox[rgb]{1.00,0.94,0.94}{\strut ##1}}}
\expandafter\def\csname PYG@tok@ge\endcsname{\let\PYG@it=\textit}
\expandafter\def\csname PYG@tok@vc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@il\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@go\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.19,0.19,0.19}{##1}}}
\expandafter\def\csname PYG@tok@cp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@gi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.63,0.00}{##1}}}
\expandafter\def\csname PYG@tok@gh\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.00,0.50}{##1}}}
\expandafter\def\csname PYG@tok@ni\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.84,0.33,0.22}{##1}}}
\expandafter\def\csname PYG@tok@nl\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.13,0.44}{##1}}}
\expandafter\def\csname PYG@tok@nn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@no\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.38,0.68,0.84}{##1}}}
\expandafter\def\csname PYG@tok@na\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@nb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.05,0.52,0.71}{##1}}}
\expandafter\def\csname PYG@tok@nd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.33,0.33,0.33}{##1}}}
\expandafter\def\csname PYG@tok@ne\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@nf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.49}{##1}}}
\expandafter\def\csname PYG@tok@si\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.44,0.63,0.82}{##1}}}
\expandafter\def\csname PYG@tok@s2\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@vi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@nt\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.02,0.16,0.45}{##1}}}
\expandafter\def\csname PYG@tok@nv\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.38,0.84}{##1}}}
\expandafter\def\csname PYG@tok@s1\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@gp\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@sh\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@ow\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@sx\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.78,0.36,0.04}{##1}}}
\expandafter\def\csname PYG@tok@bp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c1\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@kc\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@c\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.50,0.56}{##1}}}
\expandafter\def\csname PYG@tok@mf\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@err\endcsname{\def\PYG@bc##1{\setlength{\fboxsep}{0pt}\fcolorbox[rgb]{1.00,0.00,0.00}{1,1,1}{\strut ##1}}}
\expandafter\def\csname PYG@tok@kd\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@ss\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.32,0.47,0.09}{##1}}}
\expandafter\def\csname PYG@tok@sr\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.14,0.33,0.53}{##1}}}
\expandafter\def\csname PYG@tok@mo\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@mi\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.13,0.50,0.31}{##1}}}
\expandafter\def\csname PYG@tok@kn\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@o\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.40,0.40,0.40}{##1}}}
\expandafter\def\csname PYG@tok@kr\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@s\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@kp\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@w\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.73,0.73,0.73}{##1}}}
\expandafter\def\csname PYG@tok@kt\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.56,0.13,0.00}{##1}}}
\expandafter\def\csname PYG@tok@sc\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sb\endcsname{\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@k\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.00,0.44,0.13}{##1}}}
\expandafter\def\csname PYG@tok@se\endcsname{\let\PYG@bf=\textbf\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}
\expandafter\def\csname PYG@tok@sd\endcsname{\let\PYG@it=\textit\def\PYG@tc##1{\textcolor[rgb]{0.25,0.44,0.63}{##1}}}

\def\PYGZbs{\char`\\}
\def\PYGZus{\char`\_}
\def\PYGZob{\char`\{}
\def\PYGZcb{\char`\}}
\def\PYGZca{\char`\^}
\def\PYGZam{\char`\&}
\def\PYGZlt{\char`\<}
\def\PYGZgt{\char`\>}
\def\PYGZsh{\char`\#}
\def\PYGZpc{\char`\%}
\def\PYGZdl{\char`\$}
\def\PYGZti{\char`\~}
% for compatibility with earlier versions
\def\PYGZat{@}
\def\PYGZlb{[}
\def\PYGZrb{]}
\makeatother

\begin{document}

\maketitle
\tableofcontents
\phantomsection\label{index::doc}


Collectively, the \textbf{bedtools} utilities are a swiss-army knife of tools
for a wide-range of genomics analysis tasks. The most widely-used
tools enable \emph{genome arithmetic}: that is, set theory on the genome.  For
example, \textbf{bedtools} allows one to \emph{intersect}, \emph{merge}, \emph{count}, \emph{complement},
and \emph{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.,
\emph{intersect} two interval files), quite sophisticated analyses can be conducted
by combining multiple bedtools operations on the UNIX command line.


\chapter{Table of contents}
\label{index:bedtools-a-powerful-toolset-for-genome-arithmetic}\label{index:table-of-contents}

\section{Overview}
\label{content/overview:overview}\label{content/overview::doc}

\subsection{Background}
\label{content/overview:background}
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
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
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
supported solely 6-column \href{http://genome.ucsc.edu/FAQ/FAQformat\#format1}{BED} files. \emph{However, we have subsequently added support for sequence alignments in} \href{http://samtools.sourceforge.net/}{BAM}
\emph{format, as well as for features in} \href{http://genome.ucsc.edu/FAQ/FAQformat\#format3}{GFF} , \emph{“blocked” BED format, and}
\href{http://www.1000genomes.org/wiki/Analysis/Variant\%20Call\%20Format/vcf-variant-call-format-version-41}{VCF} \emph{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
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
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.


\subsection{Summary of available tools.}
\label{content/overview:summary-of-available-tools}
bedtools support a  wide range of operations for  interrogating and manipulating genomic features. The table below summarizes
the tools available in the suite.

\begin{longtable}{|l|l|}
\hline
\textbf{
Utility
} & \textbf{
Description
}\\\hline
\endfirsthead

\multicolumn{2}{c}%
{{\bfseries \tablename\ \thetable{} -- continued from previous page}} \\
\hline
\textbf{
Utility
} & \textbf{
Description
}\\\hline
\endhead

\hline \multicolumn{2}{|r|}{{Continued on next page}} \\ \hline
\endfoot

\hline
\endlastfoot


\textbf{annotate}
 & 
Annotate coverage of features from multiple files.
\\\hline

\textbf{bamtobed}
 & 
Convert BAM alignments to BED (\& other) formats.
\\\hline

\textbf{bamtofastq}
 & 
Convert BAM records to FASTQ records.
\\\hline

\textbf{bed12tobed6}
 & 
Breaks BED12 intervals into discrete BED6 intervals.
\\\hline

\textbf{bedpetobam}
 & 
Convert BEDPE intervals to BAM records.
\\\hline

\textbf{bedtobam}
 & 
Convert intervals to BAM records.
\\\hline

\textbf{closest}
 & 
Find the closest, potentially non-overlapping interval.
\\\hline

\textbf{cluster}
 & 
Cluster (but don't merge) overlapping/nearby intervals.
\\\hline

\textbf{complement}
 & 
Extract intervals \_not\_ represented by an interval file.
\\\hline

\textbf{coverage}
 & 
Compute the coverage over defined intervals.
\\\hline

\textbf{expand}
 & 
Replicate lines based on lists of values in columns.
\\\hline

\textbf{flank}
 & 
Create new intervals from the flanks of existing intervals.
\\\hline

\textbf{genomecov}
 & 
Compute the coverage over an entire genome.
\\\hline

\textbf{getfasta}
 & 
Use intervals to extract sequences from a FASTA file.
\\\hline

\textbf{groupby}
 & 
Group by common cols. \& summarize oth. cols. (\textasciitilde{} SQL ``groupBy'')
\\\hline

\textbf{igv}
 & 
Create an IGV snapshot batch script.
\\\hline

\textbf{intersect}
 & 
Find overlapping intervals in various ways.
\\\hline

\textbf{jaccard}
 & 
Calculate the Jaccard statistic b/w two sets of intervals.
\\\hline

\textbf{links}
 & 
Create a HTML page of links to UCSC locations.
\\\hline

\textbf{makewindows}
 & 
Make interval ``windows'' across a genome.
\\\hline

\textbf{map}
 & 
Apply a function to a column for each overlapping interval.
\\\hline

\textbf{maskfasta}
 & 
Use intervals to mask sequences from a FASTA file.
\\\hline

\textbf{merge}
 & 
Combine overlapping/nearby intervals into a single interval.
\\\hline

\textbf{multicov}
 & 
Counts coverage from multiple BAMs at specific intervals.
\\\hline

\textbf{multiinter}
 & 
Identifies common intervals among multiple interval files.
\\\hline

\textbf{nuc}
 & 
Profile the nucleotide content of intervals in a FASTA file.
\\\hline

\textbf{overlap}
 & 
Computes the amount of overlap from two intervals.
\\\hline

\textbf{pairtobed}
 & 
Find pairs that overlap intervals in various ways.
\\\hline

\textbf{pairtopair}
 & 
Find pairs that overlap other pairs in various ways.
\\\hline

\textbf{random}
 & 
Generate random intervals in a genome.
\\\hline

\textbf{reldist}
 & 
Calculate the distribution of relative distances b/w two files.
\\\hline

\textbf{shuffle}
 & 
Randomly redistrubute intervals in a genome.
\\\hline

\textbf{slop}
 & 
Adjust the size of intervals.
\\\hline

\textbf{sort}
 & 
Order the intervals in a file.
\\\hline

\textbf{subtract}
 & 
Remove intervals based on overlaps b/w two files.
\\\hline

\textbf{tag}
 & 
Tag BAM alignments based on overlaps with interval files.
\\\hline

\textbf{unionbedg}
 & 
Combines coverage intervals from multiple BEDGRAPH files.
\\\hline

\textbf{window}
 & 
Find overlapping intervals within a window around an interval.
\\\hline
\end{longtable}



\subsection{Fundamental concepts.}
\label{content/overview:fundamental-concepts}

\subsubsection{What are genome features and how are they represented?}
\label{content/overview: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.
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
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
format from the UCSC Genome Browser’s “Table Browser” (\href{http://genome.ucsc.edu/cgi-bin/hgTables?command=start}{http://genome.ucsc.edu/cgi-bin/hgTables?command=start}) or from the “Bulk Downloads” page (\href{http://hgdownload.cse.ucsc.edu/downloads.html}{http://hgdownload.cse.ucsc.edu/downloads.html}). In addition, the
Ensemble Genome Browser contains annotations in GFF/GTF format for many species (\href{http://www.ensembl.org/info/data/ftp/index.html}{http://www.ensembl.org/info/data/ftp/index.html})


\subsubsection{Overlapping / intersecting features.}
\label{content/overview: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.

\textbf{TODO: place figure here}


\subsubsection{Comparing features in file “A” and file “B”.}
\label{content/overview: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 bedtools intersect in the following manner:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect –a snps.bed –b exons.bed
\end{Verbatim}

There are two exceptions to this rule: 1) When the “A” file is in BAM format, the “-abam” option must bed used. For example:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect –abam alignedReads.bam –b exons.bed
\end{Verbatim}

And 2) For tools where only one input feature file is needed, the “-i” option is used. For example:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools merge –i repeats.bed
\end{Verbatim}


\subsubsection{BED starts are zero-based and BED ends are one-based.}
\label{content/overview: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: (\href{http://genome.ucsc.edu/FAQ/FAQtracks\#tracks1}{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:

\begin{Verbatim}[commandchars=\\\{\}]
chr1   0        1    first\_base
\end{Verbatim}

Why, you might ask? The advantage of storing features this way is that when computing the length of a feature, one must simply subtract the start from the end. Were the start position 1-based,
the calculation would be (slightly) more complex (i.e. (end-start)+1). Thus, storing BED features this way reduces the computational burden.


\subsubsection{GFF starts and ends are one-based.}
\label{content/overview: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.


\subsubsection{VCF coordinates are one-based.}
\label{content/overview: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.


\subsubsection{File B is loaded into memory (most of the time).}
\label{content/overview: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.
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.


\subsubsection{Feature files \emph{must} be tab-delimited.}
\label{content/overview: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:
\begin{enumerate}
\item {} 
By requiring one delimiter type, the processing time is minimized.

\item {} 
Tab-delimited files are more amenable to other UNIX utilities.

\item {} 
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.

\end{enumerate}


\subsubsection{All bedtools allow features to be “piped” via standard input.}
\label{content/overview: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:

\begin{Verbatim}[commandchars=\\\{\}]
cat snps.bed \textbar{} bedtools intersect –a stdin –b exons.bed
cat snps.bed \textbar{} bedtools intersect –a - –b exons.bed
\end{Verbatim}

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:

\begin{Verbatim}[commandchars=\\\{\}]
cat snps.bed \textbar{} bedtools sort –i stdin
cat snps.bed \textbar{} bedtools sort
\end{Verbatim}


\subsubsection{Most bedtools write their results to standard output.}
\label{content/overview: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 “\textgreater{}” to do so.
Writing to standard output (the default):

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect –a snps.bed –b exons.bed
chr1 100100 100101 rs233454
chr1 200100 200101 rs446788
chr1 300100 300101 rs645678
\end{Verbatim}

Writing to a file:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect –a snps.bed –b exons.bed \textgreater{} snps.in.exons.bed

cat snps.in.exons.bed
chr1 100100 100101 rs233454
chr1 200100 200101 rs446788
chr1 300100 300101 rs645678
\end{Verbatim}


\subsubsection{What is a “genome” file?}
\label{content/overview:what-is-a-genome-file}
Some of the bedtools (e.g., \code{genomecov}, \code{complement}, \code{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
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):

\begin{Verbatim}[commandchars=\\\{\}]
chrI 15072421
chrII 15279323
...
chrX 17718854
chrM 13794
\end{Verbatim}

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:
\href{http://hgdownload.cse.ucsc.edu/goldenPath/hg19/database/chromInfo.txt.gz}{http://hgdownload.cse.ucsc.edu/goldenPath/hg19/database/chromInfo.txt.gz}


\subsubsection{Paired-end BED files (BEDPE files).}
\label{content/overview: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
existing BED block format (i.e. BED12) does not allow inter-chromosomal feature definitions. Moreover,
the BED12 format feels rather bloated when one want to describe events with only two blocks.


\subsubsection{Use “-h” for help with any bedtool.}
\label{content/overview:use-h-for-help-with-any-bedtool}
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.


\subsubsection{BED features must not contain negative positions.}
\label{content/overview:bed-features-must-not-contain-negative-positions}
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.


\subsubsection{The start position must be \textless{}= to the end position.}
\label{content/overview:the-start-position-must-be-to-the-end-position}
bedtools will reject BED features where the start position is greater than the end position.


\subsubsection{Headers are allowed in GFF and BED files}
\label{content/overview: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
“\#” symbol, the work “track”, or the word “browser”. For example, the following examples are valid
headers for BED or GFF files:

\begin{Verbatim}[commandchars=\\\{\}]
track name=aligned\_read description="Illumina aligned reads”
chr5 100000 500000 read1 50 +
chr5 2380000 2386000 read2 60 -

\#This is a fascinating dataset
chr5 100000 500000 read1 50 +
chr5 2380000 2386000 read2 60 -

browser position chr22:1-20000
chr5 100000 500000 read1 50 +
chr5 2380000 2386000 read2 60 -
\end{Verbatim}


\subsubsection{GZIP support: BED, GFF, VCF, and BEDPE file can be “gzipped”}
\label{content/overview: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
uncompressed files. Gzipped files are auto-detected thanks to a helpful contribution from Gordon
Assaf.


\subsubsection{Support for “split” or “spliced” BAM alignments and “blocked” BED features}
\label{content/overview:support-for-split-or-spliced-bam-alignments-and-blocked-bed-features}
As of Version 2.8.0, five bedtools (\code{intersect}, \code{coverage}, \code{genomecob},
\code{bamToBed}, and \code{bed12ToBed6}) can properly handle “split”/”spliced” BAM alignments (i.e., having an
“N” CIGAR operation) and/or “blocked” BED (aka BED12) features.

\code{intersect}, \code{coverage}, and \code{genomecov} will optionally handle “split” BAM and/or
“blocked” BED by using the \code{-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
each alignment or feature block. For example, imagine you have a RNA-seq read that originates from
the junction of two exons that were spliced together in a mRNA. In the genome, these two exons
happen to be 30Kb apart. Thus, when the read is aligned to the reference genome, one portion of the
read will align to the first exon, while another portion of the read will align ca. 30Kb downstream to the
other exon. The corresponding CIGAR string would be something like (assuming a 76bp read):
30M*3000N*46M. In the genome, this alignment “spans” 3076 bp, yet the nucleotides in the sequencing
read only align “cover” 76bp. Without the \code{-split} option, coverage or overlaps would be reported for the
entire 3076bp span of the alignment. However, with the \code{-split} option, coverage or overlaps will only
be reported for the portions of the read that overlap the exons (i.e. 30bp on one exon, and
46bp on the other).

Using the -split option with bamToBed causes “spliced/split” alignments to be reported in BED12
format. Using the -split option with \code{bed12tobed6} causes “blocked” BED12 features to be reported in
BED6 format.


\subsubsection{Writing uncompressed BAM output.}
\label{content/overview: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. \code{intersect}, \code{window}) will now optionally create uncompressed BAM output
using the \code{-ubam} option.


\subsection{Implementation and algorithmic notes.}
\label{content/overview:implementation-and-algorithmic-notes}
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.


\section{Installation}
\label{content/installation:installation}\label{content/installation::doc}
\code{bedtools} is intended to run in a ``command line'' environment on UNIX, LINUX
and Apple OS X operating systems. Installing \code{bedtools} involves either
downloading the source code and compiling it manually, or installing stable
release from package managers such as
\href{http://mxcl.github.com/homebrew/}{homebrew (for OS X)}.


\subsection{Installing stable releases}
\label{content/installation:installing-stable-releases}

\subsubsection{Compiling from source via Google Code}
\label{content/installation:compiling-from-source-via-google-code}
Stable, versioned releases of bedtools are made available The following commands
will install \code{bedtools} in a local directory on an UNIX or OS X machine.
Note that the \textbf{``\textless{}version\textgreater{}''} refers to the latest posted version number
on \href{http://bedtools.googlecode.com/}{http://bedtools.googlecode.com/}.

\begin{notice}{note}{Note:}
The bedtools Makefiles utilize the GCC compiler. One should edit the
Makefiles accordingly if one wants to use a different compiler.
\end{notice}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }curl http://bedtools.googlecode.com/files/BEDTools.\PYGZlt{}version\PYGZgt{}.tar.gz \PYGZgt{} BEDTools.tar.gz
\PYG{n+nv}{\PYGZdl{} }tar -zxvf BEDTools.tar.gz
\PYG{n+nv}{\PYGZdl{} }\PYG{n+nb}{cd }BEDTools-\PYGZlt{}version\PYGZgt{}
\PYG{n+nv}{\PYGZdl{} }make
\end{Verbatim}

At this point, one should copy the binaries in ./bin/ to either
\code{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 \code{usr/local/bin/}. If in doubt, contact you
system administrator for help.


\subsubsection{Installing with package managers}
\label{content/installation:installing-with-package-managers}
In addition, stable releases of \code{bedtools} are also available through package
managers such as \href{http://mxcl.github.com/homebrew/}{homebrew (for OS X)},
\code{apt-get} and \code{yum}.

\textbf{Fedora/Centos}. Adam Huffman has created a Red Hat package for bedtools so
that one can easily install the latest release using ``yum'', the Fedora
package manager. It should work with Fedora 13, 14 and EPEL5/6 (
for Centos, Scientific Linux, etc.).

\begin{Verbatim}[commandchars=\\\{\}]
yum install BEDTools
\end{Verbatim}

\textbf{Debian/Ubuntu.} Charles Plessy also maintains a Debian package for bedtools
that is likely to be found in its derivatives like Ubuntu. Many thanks to
Charles for doing this.

\begin{Verbatim}[commandchars=\\\{\}]
apt-get install bedtools
\end{Verbatim}

\textbf{Homebrew}. Carlos Borroto has made BEDTools available on the bedtools
package manager for OSX.

\begin{Verbatim}[commandchars=\\\{\}]
brew install bedtools
\end{Verbatim}


\subsection{Development versions}
\label{content/installation:development-versions}
The development version of bedtools is maintained in a Github
\href{https://www.github.com/arq5x/bedtools}{repository}. Bug fixes are addressed
in this repository prior to release, so there may be situations where you will
want to use a development version of bedtools prior to its being promoted to
a stable release.  One would either clone the repository with \code{git}, as
follows and then compile the source code as describe above:

\begin{Verbatim}[commandchars=\\\{\}]
git clone https://github.com/arq5x/bedtools.git
\end{Verbatim}

or, one can download the source code as a \code{.zip} file using the Github
website.  Once the zip file is downloaded and uncompressed with the \code{unzip}
command, one can compile and install using the instructions above.
\begin{quote}

\includegraphics{github-zip-button.png}
\end{quote}


\section{Quick start}
\label{content/quick-start:quick-start}\label{content/quick-start::doc}

\subsection{Install bedtools}
\label{content/quick-start:install-bedtools}
\begin{Verbatim}[commandchars=\\\{\}]
curl http://bedtools.googlecode.com/files/BEDTools.\PYGZlt{}version\PYGZgt{}.tar.gz \PYGZgt{} BEDTools.tar.gz
tar -zxvf BEDTools.tar.gz
\PYG{n+nb}{cd }BEDTools
make
sudo cp bin/* /usr/local/bin/
\end{Verbatim}


\subsection{Use bedtools}
\label{content/quick-start:use-bedtools}
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.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a reads.bed -b genes.bed
\end{Verbatim}

Report those entries in A that overlap NO entries in B. Like ``grep -v''

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect  -a reads.bed -b genes.bed
\end{Verbatim}

Read BED A from STDIN. Useful for stringing together commands. For example,
find genes that overlap LINEs but not SINEs.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a genes.bed -b LINES.bed \textbar{} \PYG{l+s+se}{\PYGZbs{}}
  bedtools intersect -a stdin -b SINEs.bed
\end{Verbatim}

Find the closest ALU to each gene.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools closest -a genes.bed -b ALUs.bed
\end{Verbatim}

Merge overlapping repetitive elements into a single entry, returning the number of entries merged.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools merge -i repeatMasker.bed -n
\end{Verbatim}

Merge nearby repetitive elements into a single entry, so long as they are within 1000 bp of one another.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools merge -i repeatMasker.bed -d 1000
\end{Verbatim}


\section{General usage}
\label{content/general-usage::doc}\label{content/general-usage:general-usage}

\subsection{Supported file formats}
\label{content/general-usage:supported-file-formats}

\subsubsection{BED format}
\label{content/general-usage: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).
However, only intersectBed, coverageBed, genomeCoverageBed, and bamToBed will obey the BED12
``blocks'' when computing overlaps, etc., via the \textbf{``-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)
of the BED12 entry to perform any relevant feature comparisons. The last six columns will be reported
in the output of all comparisons.

The file description below is modified from: \href{http://genome.ucsc.edu/FAQ/FAQformat\#format1}{http://genome.ucsc.edu/FAQ/FAQformat\#format1}.
\begin{enumerate}
\item {} 
\textbf{chrom} - The name of the chromosome on which the genome feature exists.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, ``chr1'', ``III'', ``myChrom'', ``contig1112.23''.

\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{1}
\item {} 
\textbf{start} - The zero-based starting position of the feature in the chromosome.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{The first base in a chromosome is numbered 0}.

\item {} 
\emph{The start position in each BED feature is therefore interpreted to be 1 greater than the start position listed in the feature. For example, start=9, end=20 is interpreted to span bases 10 through 20,inclusive}.

\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{2}
\item {} 
\textbf{end} - The one-based ending position of the feature in the chromosome.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{The end position in each BED feature is one-based. See example above}.

\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{3}
\item {} 
\textbf{name} - Defines the name of the BED feature.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, ``LINE'', ``Exon3'', ``HWIEAS\_0001:3:1:0:266\#0/1'', or ``my\_Feature''.

\item {} 
\emph{This column is optional}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{4}
\item {} 
\textbf{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.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, 7.31E-05 (p-value), 0.33456 (mean enrichment value), ``up'', ``down'', etc.

\item {} 
\emph{This column is optional}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{5}
\item {} 
\textbf{strand} - Defines the strand - either `+' or `-`.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is optional}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{6}
\item {} 
\textbf{thickStart} - The starting position at which the feature is drawn thickly.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Allowed yet ignored by bedtools}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{7}
\item {} 
\textbf{thickEnd} - The ending position at which the feature is drawn thickly.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Allowed yet ignored by bedtools}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{8}
\item {} 
\textbf{itemRgb} - An RGB value of the form R,G,B (e.g. 255,0,0).

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Allowed yet ignored by bedtools}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{9}
\item {} 
\textbf{blockCount} - The number of blocks (exons) in the BED line.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Allowed yet ignored by bedtools}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{10}
\item {} 
\textbf{blockSizes} - A comma-separated list of the block sizes.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Allowed yet ignored by bedtools}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{11}
\item {} 
\textbf{blockStarts} - A comma-separated list of block starts.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Allowed yet ignored by bedtools}.

\end{itemize}

bedtools requires that all BED input files (and input received from stdin) are \textbf{tab-delimited}. The following types of BED files are supported by bedtools:
\begin{enumerate}
\item {} 
\begin{DUlineblock}{0em}
\item[] \textbf{BED3}: A BED file where each feature is described by \textbf{chrom}, \textbf{start}, and \textbf{end}.
\item[] For example: chr1          11873   14409
\end{DUlineblock}

\item {} 
\begin{DUlineblock}{0em}
\item[] \textbf{BED4}: A BED file where each feature is described by \textbf{chrom}, \textbf{start}, \textbf{end}, and \textbf{name}.
\item[] For example: chr1  11873  14409  uc001aaa.3
\end{DUlineblock}

\item {} 
\begin{DUlineblock}{0em}
\item[] \textbf{BED5}: A BED file where each feature is described by \textbf{chrom}, \textbf{start}, \textbf{end}, \textbf{name}, and \textbf{score}.
\item[] For example: chr1 11873 14409 uc001aaa.3 0
\end{DUlineblock}

\item {} 
\begin{DUlineblock}{0em}
\item[] \textbf{BED6}: A BED file where each feature is described by \textbf{chrom}, \textbf{start}, \textbf{end}, \textbf{name}, \textbf{score}, and \textbf{strand}.
\item[] For example: chr1 11873 14409 uc001aaa.3 0 +
\end{DUlineblock}

\item {} 
\begin{DUlineblock}{0em}
\item[] \textbf{BED12}: A BED file where each feature is described by all twelve columns listed above.
\item[] For example: chr1 11873 14409 uc001aaa.3 0 + 11873
\item[] 11873 0 3 354,109,1189, 0,739,1347,
\end{DUlineblock}

\end{enumerate}


\subsubsection{BEDPE format}
\label{content/general-usage: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
because the existing ``blocked'' BED format (a.k.a. BED12) does not allow inter-chromosomal feature
definitions. In addition, BED12 only has one strand field, which is insufficient for paired-end sequence
alignments, especially when studying structural variation.

The BEDPE format is described below. The description is modified from: \href{http://genome.ucsc.edu/FAQ/FAQformat\#format1}{http://genome.ucsc.edu/FAQ/FAQformat\#format1}.
\begin{enumerate}
\item {} 
\textbf{chrom1} - The name of the chromosome on which the \textbf{first} end of the feature exists.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, ``chr1'', ``III'', ``myChrom'', ``contig1112.23''.

\item {} 
\emph{This column is required}.

\item {} 
\emph{Use ''.'' for unknown}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{1}
\item {} 
\textbf{start1} - The zero-based starting position of the \textbf{first} end of the feature on \textbf{chrom1}.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{The first base in a chromosome is numbered 0}.

\item {} 
\emph{As with BED format, the start position in each BEDPE feature is therefore interpreted to be 1 greater than the start position listed in the feature. This column is required}.

\item {} 
\emph{Use -1 for unknown}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{2}
\item {} 
\textbf{end1} - The one-based ending position of the first end of the feature on \textbf{chrom1}.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{The end position in each BEDPE feature is one-based}.

\item {} 
\emph{This column is required}.

\item {} 
\emph{Use -1 for unknown}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{3}
\item {} 
\textbf{chrom2} - The name of the chromosome on which the \textbf{second} end of the feature exists.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, ``chr1'', ``III'', ``myChrom'', ``contig1112.23''.

\item {} 
\emph{This column is required}.

\item {} 
\emph{Use ''.'' for unknown}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{4}
\item {} 
\textbf{start2} - The zero-based starting position of the \textbf{second} end of the feature on \textbf{chrom2}.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{The first base in a chromosome is numbered 0}.

\item {} 
\emph{As with BED format, the start position in each BEDPE feature is therefore interpreted to be 1 greater than the start position listed in the feature. This column is required}.

\item {} 
\emph{Use -1 for unknown}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{5}
\item {} 
\textbf{end2} - The one-based ending position of the \textbf{second} end of the feature on \textbf{chrom2}.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{The end position in each BEDPE feature is one-based}.

\item {} 
\emph{This column is required}.

\item {} 
\emph{Use -1 for unknown}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{6}
\item {} 
\textbf{name} - Defines the name of the BEDPE feature.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, ``LINE'', ``Exon3'', ``HWIEAS\_0001:3:1:0:266\#0/1'', or ``my\_Feature''.

\item {} 
\emph{This column is optional}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{7}
\item {} 
\textbf{score} - The UCSC definition requires that a BED score range from 0 to 1000, inclusive. \emph{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.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, 7.31E-05 (p-value), 0.33456 (mean enrichment value), ``up'', ``down'', etc.

\item {} 
\emph{This column is optional}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{8}
\item {} 
\textbf{strand1} - Defines the strand for the first end of the feature. Either `+' or `-`.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is optional}.

\item {} 
\emph{Use ''.'' for unknown}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{9}
\item {} 
\textbf{strand2} - Defines the strand for the second end of the feature. Either `+' or `-`.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is optional}.

\item {} 
\emph{Use ''.'' for unknown}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{10}
\item {} 
\textbf{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'' \textbf{pairToBed} and \textbf{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.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{These additional columns are optional}.

\end{itemize}

Entries from an typical BEDPE file:

\begin{Verbatim}[commandchars=\\\{\}]
chr1  100   200   chr5  5000  5100  bedpe\_example1  30   +  -
chr9  1000  5000  chr9  3000  3800  bedpe\_example2  100  +  -
\end{Verbatim}

Entries from a BEDPE file with two custom fields added to each record:

\begin{Verbatim}[commandchars=\\\{\}]
chr1  10    20    chr5  50    60    a1     30       +    -  0  1
chr9  30    40    chr9  80    90    a2     100      +    -  2  1
\end{Verbatim}


\subsubsection{GFF format}
\label{content/general-usage:gff-format}
The GFF format is described on the Sanger Institute's website (\href{http://www.sanger.ac.uk/resources/software/gff/spec.html}{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.
\begin{enumerate}
\item {} 
\textbf{seqname} - The name of the sequence (e.g. chromosome) on which the feature exists.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, ``chr1'', ``III'', ``myChrom'', ``contig1112.23''.

\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{1}
\item {} 
\textbf{source} - The source of this feature. This field will normally be used to indicate the program making the prediction, or if it comes from public database annotation, or is experimentally verified, etc.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{2}
\item {} 
\textbf{feature} - The feature type name. Equivalent to BED's \textbf{name} field.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{Any string can be used}. For example, ``exon'', etc.

\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{3}
\item {} 
\textbf{start} - The one-based starting position of feature on \textbf{seqname}.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is required}.

\item {} 
\emph{bedtools accounts for the fact the GFF uses a one-based position and BED uses a zero-based start position}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{4}
\item {} 
\textbf{end} - The one-based ending position of feature on \textbf{seqname}.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{5}
\item {} 
\textbf{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.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{6}
\item {} 
\textbf{strand} - Defines the strand. Use `+', `-` or `.'

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{7}
\item {} 
\textbf{frame} -  The frame of the coding sequence. Use `0', `1', `2', or `.'.

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is required}.

\end{itemize}
\begin{enumerate}
\setcounter{enumi}{8}
\item {} 
\textbf{attribute} - Taken from \href{http://www.sanger.ac.uk/resources/software/gff/spec.html}{http://www.sanger.ac.uk/resources/software/gff/spec.html}: From version 2 onwards, the attribute field must have an tag value structure following the syntax used within objects in a .ace file, flattened onto one line by semicolon separators. Tags must be standard identifiers ({[}A-Za-z{]}{[}{\color{red}\bfseries{}AZa-z0-9\_}{]}*). Free text values must be quoted with double quotes. \emph{Note: all non-printing characters in such free text value strings (e.g. newlines, tabs, control characters, etc) must be explicitly represented by their C (UNIX) style backslash-escaped representation (e.g. newlines as `n', tabs as `t')}. As in ACEDB, multiple values can follow a specific tag. The aim is to establish consistent use of particular tags, corresponding to an underlying implied ACEDB model if you want to think that way (but acedb is not required).

\end{enumerate}
\begin{itemize}
\item {} 
\emph{This column is required}.

\end{itemize}

An entry from an example GFF file :

\begin{Verbatim}[commandchars=\\\{\}]
seq1 BLASTX similarity 101 235 87.1 + 0 Target "HBA\_HUMAN" 11 55 ;
E\_value 0.0003 dJ102G20 GD\_mRNA coding\_exon 7105 7201 . - 2 Sequence
"dJ102G20.C1.1"
\end{Verbatim}


\subsubsection{\emph{Genome} file format}
\label{content/general-usage: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
the chromosomes (or scaffolds, etc.) and their size (in basepairs).

Genome files must be \textbf{tab-delimited} and are structured as follows (this is an example for \emph{C. elegans}):

\begin{Verbatim}[commandchars=\\\{\}]
chrI  15072421
chrII 15279323
...
chrX  17718854
chrM  13794
\end{Verbatim}

bedtools includes pre-defined genome files for human and mouse in the \textbf{/genomes} directory included
in the bedtools distribution.


\subsubsection{SAM/BAM format}
\label{content/general-usage:sam-bam-format}
The SAM / BAM format is a powerful and widely-used format for storing sequence alignment data (see
\href{http://samtools.sourceforge.net/}{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 input in BAM format: \code{intersect}, \code{window}, \code{coverage}, \code{genomecov},
\code{pairtobed}, \code{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.


\subsubsection{VCF format}
\label{content/general-usage: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 \href{http://www.1000genomes.org/wiki/doku.php?id=1000\_genomes:analysis:vcf4.0}{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
be used to compare genetic variation calls with other genomic features.


\section{The BEDTools suite}
\label{content/bedtools-suite:the-bedtools-suite}\label{content/bedtools-suite::doc}
\emph{bedtools} consists of a suite of sub-commands that are invoked as follows:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n}{bedtools} \PYG{p}{[}\PYG{n}{sub}\PYG{o}{-}\PYG{n}{command}\PYG{p}{]} \PYG{p}{[}\PYG{n}{options}\PYG{p}{]}
\end{Verbatim}

For example, to intersect two BED files, one would invoke the following:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a a.bed -b b.bed
\end{Verbatim}


\subsection{The full list of \emph{bedtools} sub-commands.}
\label{content/bedtools-suite:the-full-list-of-bedtools-sub-commands}

\subsubsection{\emph{annotate}}
\label{content/tools/annotate:annotate}\label{content/tools/annotate::doc}
\code{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.


\paragraph{Usage and option summary}
\label{content/tools/annotate:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools annotate [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{} -files FILE1 FILE2 FILE3 ... FILEn
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
annotateBed [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{} -files FILE1 FILE2 FILE3 ... FILEn
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-names}
 & 
A list of names (one per file) to describe each file in -i. These names will be printed as a header line.
\\\hline

\textbf{-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.
\\\hline

\textbf{-both}
 & 
Report the count of features followed by the \% coverage for each annotation file. Default is to report solely the fraction of -i covered by each file.
\\\hline

\textbf{-s}
 & 
Force strandedness. That is, only include hits in A that overlap B on the same strand. By default, hits are included without respect to strand.
\\\hline

\textbf{-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.
\\\hline
\end{tabulary}



\paragraph{Default behavior - annotate one file with coverage from others.}
\label{content/tools/annotate: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.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat variants.bed
chr1 100  200   nasty 1  -
chr2 500  1000  ugly  2  +
chr3 1000 5000  big   3  -

\PYG{n+nv}{\PYGZdl{} }cat genes.bed
chr1 150  200   geneA 1  +
chr1 175  250   geneB 2  +
chr3 0    10000 geneC 3  -

\PYG{n+nv}{\PYGZdl{} }cat conserve.bed
chr1 0    10000 cons1 1  +
chr2 700  10000 cons2 2  -
chr3 4000 10000 cons3 3  +

\PYG{n+nv}{\PYGZdl{} }cat known\PYGZus{}var.bed
chr1 0    120   known1   -
chr1 150  160   known2   -
chr2 0    10000 known3   +

\PYG{n+nv}{\PYGZdl{} }bedtools annotate -i variants.bed -files genes.bed conserve.bed known\PYGZus{}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
\end{Verbatim}


\paragraph{\texttt{-count} Report the count of hits from the annotation files}
\label{content/tools/annotate:count-report-the-count-of-hits-from-the-annotation-files}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools annotate -counts -i variants.bed -files genes.bed conserve.bed known\PYGZus{}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
\end{Verbatim}


\paragraph{\texttt{-both} Report both the count of hits and the fraction covered from the annotation files}
\label{content/tools/annotate:both-report-both-the-count-of-hits-and-the-fraction-covered-from-the-annotation-files}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools annotate -both -i variants.bed -files genes.bed conserve.bed known\PYGZus{}var.bed
\PYG{c}{\PYGZsh{}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
chr3  1000    5000    big     3       -       1       1.000000        1       0.250000        0       0.000000
\end{Verbatim}


\paragraph{\texttt{-s} Restrict the reporting to overlaps on the \textbf{same} strand.}
\label{content/tools/annotate:s-restrict-the-reporting-to-overlaps-on-the-same-strand}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools annotate -s -i variants.bed -files genes.bed conserve.bed known\PYGZus{}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
\end{Verbatim}


\paragraph{\texttt{-S} Restrict the reporting to overlaps on the \textbf{opposite} strand.}
\label{content/tools/annotate:s-restrict-the-reporting-to-overlaps-on-the-opposite-strand}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools annotate -S -i variants.bed -files genes.bed conserve.bed known\PYGZus{}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
\end{Verbatim}


\subsubsection{\emph{bamtobed}}
\label{content/tools/bamtobed:bamtobed}\label{content/tools/bamtobed::doc}
\code{bedtools bamtobed} is a conversion utility that converts sequence alignments
in BAM format into BED, BED12, and/or BEDPE records.


\paragraph{Usage and option summary}
\label{content/tools/bamtobed:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools bamtobed [OPTIONS] -i \textless{}BAM\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
bamToBed [OPTIONS] -i \textless{}BAM\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|p{4.5cm}|p{8.5cm}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-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. \emph{By default, this is disabled and the output will be
reported in BED format}.
\\\hline

\textbf{-bed12}
 & 
Write ``blocked'' BED (a.k.a. BED12) format. This will convert
``spliced'' BAM alignments (denoted by the ``N'' CIGAR operation)
to BED12.
\\\hline

\textbf{-split}
 & 
Report each portion of a ``split'' BAM (i.e., having an ``N'' CIGAR
operation) alignment as a distinct BED intervals.
\\\hline

\textbf{-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 \emph{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.
\\\hline

\textbf{-tag}
 & 
Use other \emph{numeric} BAM alignment tag for BED score. Default
for BED is to use mapping quality. Disallowed with BEDPE output.
\\\hline

\textbf{-color}
 & 
An R,G,B string for the color used with BED12 format. Default
is (255,0,0).
\\\hline

\textbf{-cigar}
 & 
Add the CIGAR string to the BED entry as a 7th column.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/bamtobed: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.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools bamtobed -i reads.bam \textbar{} head -3
chr7   118970079   118970129   TUPAC\PYGZus{}0001:3:1:0:1452\PYGZsh{}0/1   37   -
chr7   118965072   118965122   TUPAC\PYGZus{}0001:3:1:0:1452\PYGZsh{}0/2   37   +
chr11  46769934    46769984    TUPAC\PYGZus{}0001:3:1:0:1472\PYGZsh{}0/1   37   -
\end{Verbatim}


\paragraph{\texttt{-tag} Set the score field based on BAM tags}
\label{content/tools/bamtobed:tag-set-the-score-field-based-on-bam-tags}
One can override the choice of the BAM \emph{MAPQ} as the result BED record's \emph{score}
field by using the \code{-tag} option.  In the example below, we use the \code{-tag}
option to select the BAM edit distance (the \emph{NM} tag) as the score
column in the resulting BED records.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools bamtobed -i reads.bam -tag NM \textbar{} head -3
chr7   118970079   118970129   TUPAC\PYGZus{}0001:3:1:0:1452\PYGZsh{}0/1   1    -
chr7   118965072   118965122   TUPAC\PYGZus{}0001:3:1:0:1452\PYGZsh{}0/2   3    +
chr11  46769934    46769984    TUPAC\PYGZus{}0001:3:1:0:1472\PYGZsh{}0/1   1    -
\end{Verbatim}


\paragraph{\texttt{-bedpe} Set the score field based on BAM tags}
\label{content/tools/bamtobed:bedpe-set-the-score-field-based-on-bam-tags}
The \code{-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.

\begin{notice}{note}{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.
\end{notice}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools bamtobed -i reads.ba -bedpe \textbar{} head -3
chr7   118965072   118965122   chr7   118970079   118970129 TUPAC\PYGZus{}0001:3:1:0:1452\PYGZsh{}0 37     +     -
chr11  46765606    46765656    chr11  46769934    46769984 TUPAC\PYGZus{}0001:3:1:0:1472\PYGZsh{}0 37     +     -
chr20  54704674    54704724    chr20  54708987    54709037 TUPAC\PYGZus{}0001:3:1:1:1833\PYGZsh{}0 37     +
\end{Verbatim}

One can easily use samtools and bamToBed together as part of a UNIX pipe. In
this example, we will only convert properly-paired (\code{FLAG == 0x2}) reads to
BED format.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }samtools view -bf 0x2 reads.bam \textbar{} bedtools bamtobed -i stdin \textbar{} head
chr7   118970079   118970129   TUPAC\PYGZus{}0001:3:1:0:1452\PYGZsh{}0/1   37   -
chr7   118965072   118965122   TUPAC\PYGZus{}0001:3:1:0:1452\PYGZsh{}0/2   37   +
chr11  46769934    46769984    TUPAC\PYGZus{}0001:3:1:0:1472\PYGZsh{}0/1   37   -
chr11  46765606    46765656    TUPAC\PYGZus{}0001:3:1:0:1472\PYGZsh{}0/2   37   +
chr20  54704674    54704724    TUPAC\PYGZus{}0001:3:1:1:1833\PYGZsh{}0/1   37   +
chr20  54708987    54709037    TUPAC\PYGZus{}0001:3:1:1:1833\PYGZsh{}0/2   37   -
chrX   9380413     9380463     TUPAC\PYGZus{}0001:3:1:1:285\PYGZsh{}0/1    0    -
chrX   9375861     9375911     TUPAC\PYGZus{}0001:3:1:1:285\PYGZsh{}0/2    0    +
chrX   131756978   131757028   TUPAC\PYGZus{}0001:3:1:2:523\PYGZsh{}0/1    37   +
chrX   131761790   131761840   TUPAC\PYGZus{}0001:3:1:2:523\PYGZsh{}0/2    37   -
\end{Verbatim}


\paragraph{\texttt{-split} Creating BED12 features from ``spliced'' BAM entries.}
\label{content/tools/bamtobed:split-creating-bed12-features-from-spliced-bam-entries}
\code{bedtools bamtobed} will, by default, create a BED6 feature that represents
the entire span of a spliced/split BAM alignment. However, when using the
\code{-split} command, a BED12 feature is reported where BED blocks will be
created for each aligned portion of the sequencing read.

\begin{Verbatim}[commandchars=\\\{\}]
Chromosome  \textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}

Exons       ***************                                    **********

BED/BAM A      \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}....................................\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}

Result      ===============                                    ====
\end{Verbatim}


\subsubsection{\emph{bamtofastq}}
\label{content/tools/bamtofastq:bamtofastq}\label{content/tools/bamtofastq::doc}
\code{bedtools bamtofastq} is a conversion utility for extracting FASTQ records
from sequence alignments in BAM format.


\paragraph{Usage and option summary}
\label{content/tools/bamtofastq:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools bamtofastq [OPTIONS] -i \textless{}BAM\textgreater{} -fq \textless{}FASTQ\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
bamToFastq [OPTIONS] -i \textless{}BAM\textgreater{} -fq \textless{}FASTQ\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|p{4.5cm}|p{8.5cm}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-fq2}
 & 
FASTQ for second end.  Used if BAM contains paired-end data.
BAM should be sorted by query name
(\code{samtools sort -n aln.bam aln.qsort}) if creating
paired FASTQ with this option.
\\\hline

\textbf{-tags}
 & 
Create FASTQ based on the mate info in the BAM R2 and Q2 tags.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/bamtofastq:default-behavior}
By default, each alignment in the BAM file is converted to a FASTQ record
in the \code{-fq} file. The order of the records in the resulting FASTQ exactly
follows the order of the records in the BAM input file.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools bamtofastq -i NA18152.bam -fq NA18152.fq

\PYG{n+nv}{\PYGZdl{} }head -8 NA18152.fq
@NA18152-SRR007381.35051
GGAGACATATCATATAAGTAATGCTAGGGTGAGTGGTAGGAAGTTTTTTCATAGGAGGTGTATGAGTTGGTCGTAGCGGAATCGGGGGTATGCTGTTCGAATTCATAAGAACAGGGAGGTTAGAAGTAGGGTCTTGGTGACAAAATATGTTGTATAGAGTTCAGGGGAGAGTGCGTCATATGTTGTTCCTAGGAAGATTGTAGTGGTGAGGGTGTTTATTATAATAATGTTTGTGTATTCGGCTATGAAGAATAGGGCGAAGGGGCCTGCGGCGTATTCGATGTTGAAGCCTGAGACTAGTTCGGACTCCCCTTCGGCAAGGTCGAA
+
\PYGZlt{}\PYGZlt{}\PYGZlt{};;\PYGZlt{};\PYGZlt{};;\PYGZlt{};;;;;;;;;;;;\PYGZlt{}\PYGZlt{}\PYGZlt{}:;;;;;;;;;;;;;;;;::::::;;;;\PYGZlt{}\PYGZlt{};;;;;;;;;;;;;;;;;;;;;;;;;;;;\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;\PYGZlt{}\PYGZlt{};;;;;:;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;;;;;;\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;;;;;:;;;;;;;;;;;;;;;;;;;:;;;;8;;8888;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;8966689666666299866669:899
@NA18152-SRR007381.637219
AATGCTAGGGTGAGTGGTAGGAAGTTTTTTCATAGGAGGTGTATGAGTTGGTCGTAGCGGAATCGGGGGTATGCTGTTCGAATTCATAAGAACAGGGAGGTTAGAAGTAGGGTCTTGGTGACAAAATATGTTGTATAGAGTTCAGGGGAGAGTGCGTCATATGTTGTTCCTAGGAAGATTGTAGTGGTGAGGGTGTTTATTATAATAATGTTTGTGTATTCGGCTATGAAGAATAGGGCGAAGGGGCCTGCGGCGTATTCGATGTTGAAGCCTGAGACTAGTTCGGACTCCCCTTCCGGCAAGGTCGAA
+
\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;\PYGZlt{};\PYGZlt{};;;;\PYGZlt{}\PYGZlt{};\PYGZlt{}888888899\PYGZlt{};;;;;;\PYGZlt{};;;;;;;;;;;;;;;;;;;;;;;;\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;;;;;\PYGZlt{};\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;;;;;;;;;\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;;;:::;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;;;;;;;;;;;;;;;;;;;\PYGZlt{};;;;;;;;;;;;;;;;;;;;;;\PYGZlt{}888\PYGZlt{};\PYGZlt{}\PYGZlt{};;;;\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{}\PYGZlt{};;;;;;;;;:;;;;888888899:::;;8;;;;;;;;;;;;;;;;;;;99;;99666896666966666600;96666669966
\end{Verbatim}


\paragraph{\texttt{-fq2} Creating two FASTQ files for paired-end sequences.}
\label{content/tools/bamtofastq:fq2-creating-two-fastq-files-for-paired-end-sequences}
If your BAM alignments are from paired-end sequence data, one can use the
\code{-fq2} option to create two distinct FASTQ output files --- one for
end 1 and one for end 2.

\begin{notice}{note}{Note:}
When using this option, it is required that the BAM
file is sorted/grouped by the read name. This keeps the resulting records
in the two output FASTQ files in the same order. One can sort the BAM
file by query name with \code{samtools sort -n aln.bam aln.qsort}.
\end{notice}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }samtools sort -n aln.bam aln.qsort

\PYG{n+nv}{\PYGZdl{} }bedtools bamtofastq -i aln.qsort.bam \PYG{l+s+se}{\PYGZbs{}}
                      -fq aln.end1.fq \PYG{l+s+se}{\PYGZbs{}}
                      -fq2 aln.end2.fq

\PYG{n+nv}{\PYGZdl{} }head -8 aln.end1.fq
@SRR069529.2276/1
CAGGGAGAAGGAGGTAGGAAAGAGAAAGGACCAGGGAGGGGCGCATACACAGGACGCTCCGTGCGGTGATAGCAGCACCACACTGTGTTCAGTCGTCTGGC
+
\PYG{o}{=};@\PYGZgt{}\PYG{o}{=}\PYG{o}{=}\PYG{c}{\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}}
@SRR069529.2406/1
GCTGGGAAAAGGATTCAGGATGTTGGTTTCTATCTTTGAGTTGCTGCTGTGCGGCTGTCCCTACACTCGCAGTACCCCTCGGACACCGTCTACTGTGGAGG
+
\PYG{o}{=}5@\PYGZgt{}\PYGZlt{}\PYGZlt{}:?\PYGZlt{}?

\PYG{n+nv}{\PYGZdl{} }head -8 aln.end2.fq
@SRR069529.2276/2
AGACCCAGAGAGGGACAGGATCTGTCCCAGATCATAAAATAGGGGGAGTGCTCCGTAGAGGCGTGCGCGGTGGCACCGTGCAGTAGTACGGGTGAGCGGGG
+
\PYG{c}{\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}}
@SRR069529.2406/2
TTCCCTACCCCTGGGGTCAGGGACTACAGCCAAGGGGAGAACTTTAGCAAGTAGACGTTAGTTATTTTGATTCCAGTGGGGACGCGCGTGTAGCGAGTTGT
+
@\PYGZgt{}\PYG{o}{=}AABB?AAACABBA\PYGZgt{}@?AAAA\PYGZgt{}B@@AB@AA:B@AA@??\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}\PYGZsh{}
\end{Verbatim}


\subsubsection{\emph{bed12tobed6}}
\label{content/tools/bed12tobed6::doc}\label{content/tools/bed12tobed6:bed12tobed6}
\textbf{bed12ToBed6} is a convenience tool that converts BED features in BED12 (a.k.a. ``blocked'' BED
features such as genes) to discrete BED6 features. For example, in the case of a gene with six exons,
bed12ToBed6 would create six separate BED6 features (i.e., one for each exon).


\paragraph{Usage and option summary}
\label{content/tools/bed12tobed6:usage-and-option-summary}
Usage:

\begin{Verbatim}[commandchars=\\\{\}]
bed12ToBed6 [OPTIONS] -i \textless{}BED12\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-i}
 & 
The BED12 file that should be split into discrete BED6 features. \emph{Use ``stdin'' when using piped input}.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/bed12tobed6:default-behavior}
Figure:

\begin{Verbatim}[commandchars=\\\{\}]
head data/knownGene.hg18.chr21.bed \textbar{} tail -n 3
chr21 10079666  10120808   uc002yiv.1  0  -  10081686  1 0 1 2 0 6 0 8
      0     4   528,91,101,215, 0,1930,39750,40927,
chr21 10080031  10081687   uc002yiw.1  0  -  10080031  1 0 0 8 0 0 3 1
      0     2   200,91,    0,1565,
chr21 10081660  10120796   uc002yix.2  0  -  10081660  1 0 0 8 1 6 6 0
      0     3   27,101,223,0,37756,38913,

head data/knownGene.hg18.chr21.bed \textbar{} tail -n 3 \textbar{} bed12ToBed6 -i stdin
chr21 10079666  10080194  uc002yiv.1 0  -
chr21 10081596  10081687  uc002yiv.1 0  -
chr21 10119416  10119517  uc002yiv.1 0  -
chr21 10120593  10120808  uc002yiv.1 0  -
chr21 10080031  10080231  uc002yiw.1 0  -
chr21 10081596  10081687  uc002yiw.1 0  -
chr21 10081660  10081687  uc002yix.2 0  -
chr21 10119416  10119517  uc002yix.2 0  -
chr21 10120573  10120796  uc002yix.2 0  -
\end{Verbatim}


\subsubsection{\emph{bedpetobam}}
\label{content/tools/bedpetobam::doc}\label{content/tools/bedpetobam:bedpetobam}

\subsubsection{\emph{bedtobam}}
\label{content/tools/bedtobam::doc}\label{content/tools/bedtobam:bedtobam}
\textbf{bedToBam} converts features in a feature file to BAM format. This is useful as an efficient means of
storing large genome annotations in a compact, indexed format for visualization purposes.


\paragraph{Usage and option summary}
\label{content/tools/bedtobam:usage-and-option-summary}
Usage:

\begin{Verbatim}[commandchars=\\\{\}]
bedToBam [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{} -g \textless{}GENOME\textgreater{} \textgreater{} \textless{}BAM\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-mapq}
 & 
Set a mapping quality (SAM MAPQ field) value for all BED entries. \emph{Default: 255}
\\\hline

\textbf{-ubam}
 & 
Write uncompressed BAM output. The default is write compressed BAM output.
\\\hline

\textbf{-bed12}
 & 
Indicate that the input BED file is in BED12 (a.k.a ``blocked'' BED) format. In this case, bedToBam will convert blocked BED features (e.g., gene annotaions) into ``spliced'' BAM alignments by creating an appropriate CIGAR string.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/bedtobam:default-behavior}
The default behavior is to assume that the input file is in unblocked format. For example:

\begin{Verbatim}[commandchars=\\\{\}]
head -5 rmsk.hg18.chr21.bed
chr21 9719768  9721892  ALR/Alpha  1004  +
chr21 9721905  9725582  ALR/Alpha  1010  +
chr21 9725582  9725977  L1PA3 3288 +
chr21 9726021  9729309  ALR/Alpha  1051  +
chr21 9729320  9729809  L1PA3 3897 -

bedToBam -i rmsk.hg18.chr21.bed -g human.hg18.genome \textgreater{} rmsk.hg18.chr21.bam

samtools view rmsk.hg18.chr21.bam \textbar{} head -5
ALR/Alpha  0   chr21 9719769  255  2124M *  0  0  *  *
ALR/Alpha  0   chr21 9721906  255  3677M *  0  0  *  *
L1PA3      0   chr21 9725583  255  395M  *  0  0  *  *
ALR/Alpha  0   chr21 9726022  255  3288M *  0  0  *  *
L1PA3      16  chr21 9729321  255  489M  *  0  0  *  *
\end{Verbatim}


\paragraph{Creating ``spliced'' BAM entries from ``blocked'' BED features}
\label{content/tools/bedtobam:creating-spliced-bam-entries-from-blocked-bed-features}
Optionally, \textbf{bedToBam} will create spliced BAM entries from ``blocked'' BED features by using the
-bed12 option. This will create CIGAR strings in the BAM output that will be displayed as ``spliced''
alignments. The image illustrates this behavior, as the top track is a BAM representation (using
bedToBam) of a BED file of UCSC genes.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
bedToBam -i knownGene.hg18.chr21.bed -g human.hg18.genome -bed12 \textgreater{} knownGene.bam

samtools view knownGene.bam \textbar{} head -2
uc002yip.1  16   chr21 9928614   2                       5                        5

298M1784N71M1411N93M3963N80M1927N106M3608N81M1769N62M11856N89M98N82M816N61M6910N65M
738N64M146N100M1647N120M6478N162M1485N51M6777N60M9274N54M880N54M1229N54M2377N54M112
68N58M2666N109M2885N158M     *   0  0  *  *
uc002yiq.1  16   chr21 9928614   2                       5                        5

298M1784N71M1411N93M3963N80M1927N106M3608N81M1769N62M11856N89M98N82M816N61M6910N65M
738N64M146N100M1647N120M6478N162M1485N51M6777N60M10208N54M1229N54M2377N54M11268N58M
2666N109M2885N158M       *   0   0  *  *
\end{Verbatim}


\subsubsection{\emph{closest}}
\label{content/tools/closest::doc}\label{content/tools/closest:closest}
Similar to \textbf{intersectBed, closestBed} searches for overlapping features in A and B. In the event that
no feature in B overlaps the current feature in A, \textbf{closestBed} will report the \emph{closest} (that is, least
genomic distance from the start or end of A) feature in B. For example, one might want to find which
is the closest gene to a significant GWAS polymorphism. Note that \textbf{closestBed} will report an
overlapping feature as the closest---that is, it does not restrict to closest \emph{non-overlapping} feature.


\paragraph{5.6.1 Usage and option summary}
\label{content/tools/closest:usage-and-option-summary}
\textbf{Usage:}

\begin{Verbatim}[commandchars=\\\{\}]
closestBed [OPTIONS] -a \textless{}BED/GFF/VCF\textgreater{} -b \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-s}
 & 
Force strandedness. That is, find the closest feature in B overlaps A on the same strand. \emph{By default, this is disabled}.
\\\hline

\textbf{-d}
 & 
In addition to the closest feature in B, report its distance to A as an extra column. The reported distance for overlapping features will be 0.
\\\hline

\textbf{-t}
 & 
How ties for closest feature should be handled. This occurs when two features in B have exactly the same overlap with a feature in A. \emph{By default, all such features in B are reported}.
\begin{quote}

Here are the other choices controlling how ties are handled:

\emph{all-}   Report all ties (default).

\emph{first-}   Report the first tie that occurred in the B file.

\emph{last-}   Report the last tie that occurred in the B file.
\end{quote}
\\\hline
\end{tabular}



\paragraph{Default behavior}
\label{content/tools/closest:default-behavior}
\textbf{closestBed} first searches for features in B that overlap a feature in A. If overlaps are found, the feature
in B that overlaps the highest fraction of A is reported. If no overlaps are found, \textbf{closestBed} looks for
the feature in B that is \emph{closest} (that is, least genomic distance to the start or end of A) to A. For
example, in the figure below, feature B1 would be reported as the closest feature to A1.

\begin{Verbatim}[commandchars=\\\{\}]
Chromosome  \textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}

BED FILE A                             *************

BED File B         \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}                            \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}

Result                                                 ======
\end{Verbatim}

For example:

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  100  200

cat B.bed
chr1  500  1000
chr1  1300 2000

closestBed -a A.bed -b B.bed
chr1  100  200  chr1  500  1000
\end{Verbatim}


\paragraph{\texttt{-s} Enforcing ``strandedness''}
\label{content/tools/closest:s-enforcing-strandedness}
This option behaves the same as the -s option for intersectBed while scanning for the closest
(overlapping or not) feature in B. See the discussion in the intersectBed section for details.


\paragraph{\texttt{-t} Controlling how ties for ``closest'' are broken}
\label{content/tools/closest:t-controlling-how-ties-for-closest-are-broken}
When there are two or more features in B that overlap the \emph{same fraction} of A, \textbf{closestBed} will, by
default, report both features in B. Imagine feature A is a SNP and file B contains genes. It can often
occur that two gene annotations (e.g. opposite strands) in B will overlap the SNP. As mentioned, the
default behavior is to report both such genes in B. However, the -t option allows one to optionally
choose the just first or last feature (in terms of where it occurred in the input file, not chromosome
position) that occurred in B.

For example (note the difference between -l 200 and -l 300):

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  100  101  rs1234

cat B.bed
chr1  0  1000  geneA  100  +
chr1  0  1000  geneB  100  -

closestBed -a A.bed -b B.bed
chr1  100  101  rs1234  chr1  0  1000  geneA  100  +
chr1  100  101  rs1234  chr1  0  1000  geneB  100  -

closestBed -a A.bed -b B.bed -t all
chr1  100  101  rs1234  chr1  0  1000  geneA  100  +
chr1  100  101  rs1234  chr1  0  1000  geneB  100  -

closestBed -a A.bed -b B.bed -t first
chr1  100  101  rs1234  chr1  0  1000  geneA  100  +

closestBed -a A.bed -b B.bed -t last
chr1  100  101  rs1234  chr1  0  1000  geneB  100  -
\end{Verbatim}


\paragraph{\texttt{-d} Reporting the distance to the closest feature in base pairs}
\label{content/tools/closest:d-reporting-the-distance-to-the-closest-feature-in-base-pairs}
ClosestBed will optionally report the distance to the closest feature in the B file using the \textbf{-d} option.
When a feature in B overlaps a feature in A, a distance of 0 is reported.

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  100  200
chr1  500  600

cat B.bed
chr1  500  1000
chr1  1300 2000

closestBed -a A.bed -b B.bed -d
chr1  100  200  chr1  500  1000  300
chr1  500  600  chr1  500  1000  0
\end{Verbatim}


\subsubsection{\emph{cluster}}
\label{content/tools/cluster:cluster}\label{content/tools/cluster::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{cluster-glyph.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

Similar to {\hyperref[content/tools/merge::doc]{\emph{merge}}}, \code{cluster} report each set of overlapping or
``book-ended'' features in an interval file.  In contrast to \code{merge},
\code{cluster} does not flatten the cluster of intervals into a new meta-interval;
instead, it assigns an unique cluster ID to each record in each cluster.  This
is useful for having fine control over how sets of overlapping intervals in
a single interval file are combined.

\begin{notice}{note}{Note:}
\code{bedtools cluster} requires that you presort your data by chromosome and
then by start position (e.g., \code{sort k1,1 -k2,2n in.bed \textgreater{} in.sorted.bed}
for BED files).
\end{notice}


\strong{See Also:}


{\hyperref[content/tools/merge::doc]{\emph{merge}}}




\paragraph{Usage and option summary}
\label{content/tools/cluster:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools cluster [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
clusterBed [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-s}
 & 
Force strandedness. That is, only cluster features that are the same strand. \emph{By default, this is disabled}.
\\\hline

\textbf{-d}
 & 
Maximum distance between features allowed for features to be clustered. \emph{Default is 0. That is, overlapping and/or book-ended features are clustered}.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/cluster:default-behavior}
By default, \code{bedtools cluster} collects overlapping (by at least 1 bp) and/or
bookended intervals into distinct clusters.  In the example below, the 4th
column is the cluster ID.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200
chr1  180  250
chr1  250  500
chr1  501  1000

\PYG{n+nv}{\PYGZdl{} }bedtools cluster -i A.bed
chr1  100     200     1
chr1  180     250     1
chr1  250     500     1
chr1  501     1000    2
\end{Verbatim}


\paragraph{\texttt{-s} Enforcing ``strandedness''}
\label{content/tools/cluster:s-enforcing-strandedness}
The \code{-s} option will only cluster intervals that are overlapping/bookended
\emph{and} are on the same strand.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200   a1  1 +
chr1  180  250   a2  2 +
chr1  250  500   a3  3 -
chr1  501  1000  a4  4 +

\PYG{n+nv}{\PYGZdl{} }bedtools cluster -i A.bed -s
chr1  100     200     a1      1       +       1
chr1  180     250     a2      2       +       1
chr1  501     1000    a4      4       +       2
chr1  250     500     a3      3       -       3
\end{Verbatim}


\paragraph{\texttt{-d} Controlling how close two features must be in order to cluster}
\label{content/tools/cluster:d-controlling-how-close-two-features-must-be-in-order-to-cluster}
By default, only overlapping or book-ended features are combined into a new
feature. However, one can force \code{cluster} to combine more distant features
with the \code{-d} option. For example, were one to set \code{-d} to 1000, any
features that overlap or are within 1000 base pairs of one another will be
clustered.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200
chr1  501  1000

\PYG{n+nv}{\PYGZdl{} }bedtools cluster -i A.bed
chr1  100  200    1
chr1  501  1000   2

\PYG{n+nv}{\PYGZdl{} }bedtools cluster -i A.bed -d 1000
chr1  100  200    1
chr1  501  1000   1
\end{Verbatim}


\subsubsection{\emph{complement}}
\label{content/tools/complement:complement}\label{content/tools/complement::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{complement-glyph.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\code{bedtools complement} returns all intervals in a genome that are \textbf{not}
covered by at least one interval in the input BED/GFF/VCF file.


\strong{See Also:}


{\hyperref[content/tools/merge::doc]{\emph{merge}}}




\paragraph{Usage and option summary}
\label{content/tools/complement:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools complement -i \textless{}BED/GFF/VCF\textgreater{} -g \textless{}GENOME\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
complementBed -i \textless{}BED/GFF/VCF\textgreater{} -g \textless{}GENOME\textgreater{}
\end{Verbatim}


\paragraph{Default behavior}
\label{content/tools/complement:default-behavior}
By default, \code{bedtools complement} returns all genomic intervals that are not
covered by at least one record from the input file.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200
chr1  400  500
chr1  500  800

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1  1000
chr2  800

\PYG{n+nv}{\PYGZdl{} }bedtools complement -i A.bed -g my.genome
chr1  0   100
chr1  200 400
chr1  800 1000
chr2  0   800
\end{Verbatim}


\subsubsection{\emph{coverage}}
\label{content/tools/coverage::doc}\label{content/tools/coverage:coverage}
\textbf{coverageBed} computes both the \emph{depth} and \emph{breadth} of coverage of features in file A across the features
in file B. For example, \textbf{coverageBed} can compute the coverage of sequence alignments (file A) across 1
kilobase (arbitrary) windows (file B) tiling a genome of interest. One advantage that \textbf{coverageBed}
offers is that it not only \emph{counts} the number of features that overlap an interval in file B, it also
computes the fraction of bases in B interval that were overlapped by one or more features. Thus,
\textbf{coverageBed} also computes the \emph{breadth} of coverage for each interval in B.


\paragraph{Usage and option summary}
\label{content/tools/coverage:usage-and-option-summary}
Usage:

\begin{Verbatim}[commandchars=\\\{\}]
coverageBed [OPTIONS] -a \textless{}BED/GFF/VCF\textgreater{} -b \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-abam}
 & \begin{quote}

BAM file A. Each BAM alignment in A is compared to B in search of overlaps. Use ``stdin'' if passing A with a UNIX pipe: For example:
\end{quote}

\begin{DUlineblock}{0em}
\item[] samtools view -b \textless{}BAM\textgreater{} \textbar{} intersectBed -abam stdin -b genes.bed
\end{DUlineblock}
\\\hline

\textbf{-s}
 & 
Force strandedness. That is, only features in A are only counted towards coverage in B if they are the same strand. \emph{By default, this is disabled and coverage is counted without respect to strand}.
\\\hline

\textbf{-hist}
 & 
Report a histogram of coverage for each feature in B as well as a summary histogram for \_all\_ features in B.

\begin{DUlineblock}{0em}
\item[] Output (tab delimited) after each feature in B:
\end{DUlineblock}
\begin{quote}

\begin{DUlineblock}{0em}
\item[] 1) depth
\item[] 2) \# bases at depth
\item[] 3) size of B
\item[] 4) \% of B at depth
\end{DUlineblock}
\end{quote}
\\\hline

\textbf{-d}
 & 
Report the depth at each position in each B feature. Positions reported are one based. Each position and depth follow the complete B feature.
\\\hline

\textbf{-split}
 & 
Treat ``split'' BAM or BED12 entries as distinct BED intervals when computing coverage. For BAM files, this uses the CIGAR ``N'' and ``D'' operations to infer the blocks for computing coverage. For BED12 files, this uses the BlockCount, BlockStarts, and BlockEnds fields (i.e., columns 10,11,12).
\\\hline
\end{tabular}



\paragraph{Default behavior}
\label{content/tools/coverage:default-behavior}
After each interval in B, \textbf{coverageBed} will report:
\begin{enumerate}
\item {} 
The number of features in A that overlapped (by at least one base pair) the B interval.

\item {} 
The number of bases in B that had non-zero coverage from features in A.

\item {} 
The length of the entry in B.

\item {} 
The fraction of bases in B that had non-zero coverage from features in A.

\end{enumerate}

Below are the number of features in A (N=...) overlapping B and fraction of bases in B with coverage.

\begin{Verbatim}[commandchars=\\\{\}]
Chromosome  \textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}

BED FILE B  ***************     ***************     ******    **************

BED File A  \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{} \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}              \textasciicircum{}\textasciicircum{}             \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}    \textasciicircum{}\textasciicircum{}\textasciicircum{} \textasciicircum{}\textasciicircum{} \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}
              \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}                                      \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{} \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{} \textasciicircum{}\textasciicircum{}

Result      [  N=3, 10/15 ]     [  N=1, 2/16 ]     [N=1,6/6]   [N=5, 11/12 ]
\end{Verbatim}

For example:

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  10  20
chr1  20  30
chr1  30  40
chr1  100 200

cat B.bed
chr1  0   100
chr1  100 200
chr2  0   100

coverageBed -a A.bed -b B.bed
chr1  0   100  3  30  100 0.3000000
chr1  100 200  1  100 100 1.0000000
chr2  0   100  0  0   100 0.0000000
\end{Verbatim}


\paragraph{\texttt{-s} Calculating coverage by strand}
\label{content/tools/coverage:s-calculating-coverage-by-strand}
Use the ``\textbf{-s}'' option if one wants to only count coverage if features in A are on the same strand as the
feature / window in B. This is especially useful for RNA-seq experiments.

For example (note the difference in coverage with and without \textbf{-s}:

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  10  20  a1  1  -
chr1  20  30  a2  1  -
chr1  30  40  a3  1  -
chr1  100 200 a4  1  +

cat B.bed
chr1  0   100 b1  1  +
chr1  100 200 b2  1  -
chr2  0   100 b3  1  +

coverageBed -a A.bed -b B.bed
chr1  0   100 b1  1  +  3  30  100  0.3000000
chr1  100 200 b2  1  -  1  100 100  1.0000000
chr2  0   100 b3  1  +  0  0   100  0.0000000

coverageBed -a A.bed -b B.bed -s
chr1  0   100 b1  1  +  0  0   100  0.0000000
chr1  100 200 b2  1  -  0  0   100  0.0000000
chr2  0   100 b3  1  +  0  0   100  0.0000000
\end{Verbatim}


\paragraph{\texttt{-hist} Creating a histogram of coverage for each feature in the B file}
\label{content/tools/coverage:hist-creating-a-histogram-of-coverage-for-each-feature-in-the-b-file}
One should use the ``\textbf{-hist}'' option to create, for each interval in B, a histogram of coverage of the
features in A across B.

In this case, each entire feature in B will be reported, followed by the depth of coverage, the number of
bases at that depth, the size of the feature, and the fraction covered. After all of the features in B have
been reported, a histogram summarizing the coverage among all features in B will be reported.

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  10  20  a1  1  -
chr1  20  30  a2  1  -
chr1  30  40  a3  1  -
chr1  100 200 a4  1  +

cat B.bed
chr1  0   100 b1  1  +
chr1  100 200 b2  1  -
chr2  0   100 b3  1  +

coverageBed -a A.bed -b B.bed -hist
chr1  0   100 b1  1  +  0  70  100  0.7000000
chr1  0   100 b1  1  +  1  30  100  0.3000000
chr1  100 200 b2  1  -  1  100 100  1.0000000
chr2  0   100 b3  1  +  0  100 100  1.0000000
all   0   170 300 0.5666667
all   1   130 300 0.4333333
\end{Verbatim}


\paragraph{\texttt{-hist} Reporting the per-base of coverage for each feature in the B file}
\label{content/tools/coverage:hist-reporting-the-per-base-of-coverage-for-each-feature-in-the-b-file}
One should use the ``\textbf{-d}'' option to create, for each interval in B, a detailed list of coverage at each of the
positions across each B interval.

The output will consist of a line for each one-based position in each B feature, followed by the coverage
detected at that position.

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  0  5
chr1  3  8
chr1  4  8
chr1  5  9

cat B.bed
chr1  0  10

coverageBed -a A.bed -b B.bed -d
chr1  0  10  B  1  1
chr1  0  10  B  2  1
chr1  0  10  B  3  1
chr1  0  10  B  4  2
chr1  0  10  B  5  3
chr1  0  10  B  6  3
chr1  0  10  B  7  3
chr1  0  10  B  8  3
chr1  0  10  B  9  1
chr1  0  10  B  10 0
\end{Verbatim}


\paragraph{\texttt{-split} Reporting coverage with spliced alignments or blocked BED features}
\label{content/tools/coverage:split-reporting-coverage-with-spliced-alignments-or-blocked-bed-features}
As described in section 1.3.19, coverageBed will, by default, screen for overlaps against the entire span
of a spliced/split BAM alignment or blocked BED12 feature. When dealing with RNA-seq reads, for
example, one typically wants to only tabulate coverage for the portions of the reads that come from
exons (and ignore the interstitial intron sequence). The \textbf{-split} command allows for such coverage to be
performed.


\subsubsection{\emph{expand}}
\label{content/tools/expand::doc}\label{content/tools/expand:expand}

\subsubsection{\emph{flank}}
\label{content/tools/flank:flank}\label{content/tools/flank::doc}

\subsubsection{\emph{genomecov}}
\label{content/tools/genomecov:genomecov}\label{content/tools/genomecov::doc}
\textbf{genomeCoverageBed} computes a histogram of feature coverage (e.g., aligned sequences) for a given
genome. Optionally, by using the \textbf{-d} option, it will report the depth of coverage at \emph{each base} on each
chromosome in the genome file (\textbf{-g}).


\paragraph{Usage and option summary}
\label{content/tools/genomecov:usage-and-option-summary}
Usage:

\begin{Verbatim}[commandchars=\\\{\}]
genomeCoverageBed [OPTIONS] -i \textless{}BED\textgreater{} -g \textless{}GENOME\textgreater{}
\end{Verbatim}

NOTE: genomeCoverageBed requires that the input BED file be sorted by
chromosome. A simple sort -k1,1 will suffice.

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-ibam}
 & \begin{quote}

BAM file as input for coverage. Each BAM alignment in A added to the total coverage for the genome. Use ``stdin'' if passing it with a UNIX pipe: For example:
\end{quote}

\begin{DUlineblock}{0em}
\item[] samtools view -b \textless{}BAM\textgreater{} \textbar{} genomeCoverageBed -ibam stdin -g hg18.genome
\end{DUlineblock}
\\\hline

\textbf{-d}
 & 
Report the depth at each genome position. \emph{Default behavior is to report a histogram}.
\\\hline

\textbf{-max}
 & 
Combine all positions with a depth \textgreater{}= max into a single bin in the histogram.
\\\hline

\textbf{-bg}
 & 
Report depth in BedGraph format. For details, see: \href{http://genome.ucsc.edu/goldenPath/help/bedgraph.html}{http://genome.ucsc.edu/goldenPath/help/bedgraph.html}
\\\hline

\textbf{-bga}
 & 
Report depth in BedGraph format, as above (i.e., -bg). However with this option, regions with zero coverage are also reported. This allows one to quickly extract all regions of a genome with 0 coverage by applying: ``grep -w 0\$'' to the output.
\\\hline

\textbf{-split}
 & 
Treat ``split'' BAM or BED12 entries as distinct BED intervals when computing coverage. For BAM files, this uses the CIGAR ``N'' and ``D'' operations to infer the blocks for computing coverage. For BED12 files, this uses the BlockCount, BlockStarts, and BlockEnds fields (i.e., columns 10,11,12).
\\\hline

\textbf{-strand}
 & 
Calculate coverage of intervals from a specific strand. With BED files, requires at least 6 columns (strand is column 6).
\\\hline
\end{tabular}



\paragraph{Default behavior}
\label{content/tools/genomecov:default-behavior}
By default, \textbf{genomeCoverageBed} will compute a histogram of coverage for the genome file provided.
The default output format is as follows:
1. chromosome (or entire genome)
2. depth of coverage from features in input file
3. number of bases on chromosome (or genome) with depth equal to column 2.
4. size of chromosome (or entire genome) in base pairs
5. fraction of bases on chromosome (or entire genome) with depth equal to column 2.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  10  20
chr1  20  30
chr2  0   500

cat my.genome
chr1  1000
chr2  500

genomeCoverageBed -i A.bed -g my.genome
chr1   0  980  1000  0.98
chr1   1  20   1000  0.02
chr2   1  500  500   1
genome 0  980  1500  0.653333
genome 1  520  1500  0.346667
\end{Verbatim}


\paragraph{\texttt{-max} Controlling the histogram's maximum depth}
\label{content/tools/genomecov:max-controlling-the-histogram-s-maximum-depth}
Using the \textbf{-max} option, \textbf{genomeCoverageBed} will ``lump'' all positions in the genome having feature coverage greater than or equal to \textbf{max} into
the \textbf{max} histogram bin. For example, if one sets \textbf{-max}
equal to 50, the max depth reported in the output will be 50 and all positions
with a depth \textgreater{}= 50 will be represented in bin 50.


\paragraph{\texttt{-d} Reporting ``per-base'' genome coverage}
\label{content/tools/genomecov:d-reporting-per-base-genome-coverage}
Using the \textbf{-d} option, \textbf{genomeCoverageBed} will compute the depth of feature coverage for each base
on each chromosome in genome file provided.

The ``per-base'' output format is as follows:
1. chromosome
2. chromosome position
3. depth (number) of features overlapping this chromosome position.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1  10  20
chr1  20  30
chr2  0   500

cat my.genome
chr1  1000
chr2  500

genomeCoverageBed -i A.bed -g my.genome -d \textbar{} head -15 \textbar{} tail -n 10
chr1  6  0
chr1  7  0
chr1  8  0
chr1  9  0
chr1  10 0
chr1  11 1
chr1  12 1
chr1  13 1
chr1  14 1
chr1  15 1
\end{Verbatim}


\paragraph{\texttt{-split} Reporting coverage with spliced alignments or blocked BED features}
\label{content/tools/genomecov:split-reporting-coverage-with-spliced-alignments-or-blocked-bed-features}
As described in section 1.3.19, genomeCoverageBed will, by default, screen for overlaps against the
entire span of a spliced/split BAM alignment or blocked BED12 feature. When dealing with RNA-seq
reads, for example, one typically wants to only screen for overlaps for the portions of the reads that
come from exons (and ignore the interstitial intron sequence). The \textbf{-split} command allows for such
overlaps to be performed.

For additional details, please visit the Usage From The Wild site and have a look at example 5,
contributed by Assaf Gordon.


\subsubsection{\emph{getfasta}}
\label{content/tools/getfasta:getfasta}\label{content/tools/getfasta::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{getfasta-glyph.png}

\code{bedtools getfasta} extracts sequences from a FASTA file for each of the
intervals defined in a BED/GFF/VCF file.

\begin{notice}{tip}{Tip:}
1. The headers in the input FASTA file must \emph{exactly} match the chromosome
column in the BED file.

2. You can use the UNIX \code{fold} command to set the line width of the
FASTA output.  For example, \code{fold -w 60} will make each line of the FASTA
file have at most 60 nucleotides for easy viewing.
\end{notice}


\strong{See Also:}


{\hyperref[content/tools/maskfasta::doc]{\emph{maskfasta}}}




\paragraph{Usage and option summary}
\label{content/tools/getfasta:usage-and-option-summary}
\textbf{Usage}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools getfasta \PYG{o}{[}OPTIONS\PYG{o}{]} -fi \PYGZlt{}input FASTA\PYGZgt{} -bed \PYGZlt{}BED/GFF/VCF\PYGZgt{} -fo \PYGZlt{}output FASTA\PYGZgt{}
\end{Verbatim}

\textbf{(or):}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }getFastaFromBed \PYG{o}{[}OPTIONS\PYG{o}{]} -fi \PYGZlt{}input FASTA\PYGZgt{} -bed \PYGZlt{}BED/GFF/VCF\PYGZgt{} -fo \PYGZlt{}output FASTA\PYGZgt{}
\end{Verbatim}

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-name}
 & 
Use the ``name'' column in the BED file for the FASTA headers in the output FASTA file.
\\\hline

\textbf{-tab}
 & 
Report extract sequences in a tab-delimited format instead of in FASTA format.
\\\hline

\textbf{-s}
 & 
Force strandedness. If the feature occupies the antisense strand, the sequence will be reverse complemented. \emph{Default: strand information is ignored}.
\\\hline

\textbf{-split}
 & 
Given BED12 input, extract and concatenate the sequences from the BED ``blocks'' (e.g., exons)
\\\hline

\textbf{-s}
 & 
\begin{DUlineblock}{0em}
\item[] Force strandedness. If the feature occupies the antisense strand, the sequence will be reverse complemented.
\textbar{} By default, strand information is ignored.
\end{DUlineblock}
\\\hline
\end{tabular}



\paragraph{Default behavior}
\label{content/tools/getfasta:default-behavior}
\code{bedtools getfasta} will extract the sequence defined by the coordinates
in a BED interval and create a new FASTA entry in the output file for each
extracted sequence. By default, the FASTA header for each
extracted sequence will be formatted as follows: ``\textless{}chrom\textgreater{}:\textless{}start\textgreater{}-\textless{}end\textgreater{}''.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat test.fa
\PYGZgt{}chr1
AAAAAAAACCCCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG

\PYG{n+nv}{\PYGZdl{} }cat test.bed
chr1 5 10

\PYG{n+nv}{\PYGZdl{} }bedtools getfasta -fi test.fa -bed test.bed -fo test.fa.out

\PYG{n+nv}{\PYGZdl{} }cat test.fa.out
\PYGZgt{}chr1:5-10
AAACC
\end{Verbatim}


\paragraph{\texttt{-name} Using the BED ``name'' column as a FASTA header.}
\label{content/tools/getfasta:name-using-the-bed-name-column-as-a-fasta-header}
Using the \code{-name} option, one can set the FASTA header for each extracted
sequence to be the ``name'' columns from the BED feature.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat test.fa
\PYGZgt{}chr1
AAAAAAAACCCCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG

\PYG{n+nv}{\PYGZdl{} }cat test.bed
chr1 5 10 myseq

\PYG{n+nv}{\PYGZdl{} }bedtools getfasta -fi test.fa -bed test.bed -fo test.fa.out -name

\PYG{n+nv}{\PYGZdl{} }cat test.fa.out
\PYGZgt{}myseq
AAACC
\end{Verbatim}


\paragraph{\texttt{-tab} Creating a tab-delimited output file in lieu of FASTA output.}
\label{content/tools/getfasta:tab-creating-a-tab-delimited-output-file-in-lieu-of-fasta-output}
Using the \code{-tab} option, the \code{-fo} output file will be tab-delimited
instead of in FASTA format.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat test.fa
\PYGZgt{}chr1
AAAAAAAACCCCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG

\PYG{n+nv}{\PYGZdl{} }cat test.bed
chr1 5 10 myseq

\PYG{n+nv}{\PYGZdl{} }bedtools getfasta -fi test.fa -bed test.bed -fo test.fa.out.tab -name -tab

\PYG{n+nv}{\PYGZdl{} }cat test.fa.out
myseq AAACC
\end{Verbatim}


\paragraph{\texttt{-s} Forcing the extracted sequence to reflect the requested strand}
\label{content/tools/getfasta:s-forcing-the-extracted-sequence-to-reflect-the-requested-strand}
\code{bedtools getfasta} will extract the sequence in the orientation defined in
the strand column when the ``-s'' option is used.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat test.fa
\PYGZgt{}chr1
AAAAAAAACCCCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG

\PYG{n+nv}{\PYGZdl{} }cat test.bed
chr1 20 25 forward 1 +
chr1 20 25 reverse 1 -

\PYG{n+nv}{\PYGZdl{} }bedtools getfasta -fi test.fa -bed test.bed -s -name -fo test.fa.out

\PYG{n+nv}{\PYGZdl{} }cat test.fa.out
\PYGZgt{}forward
CGCTA
\PYGZgt{}reverse
TAGCG
\end{Verbatim}


\paragraph{\texttt{-split} Extracting BED ``blocks''.}
\label{content/tools/getfasta:split-extracting-bed-blocks}
One can optionally request that FASTA records be extracting and concatenating
each block in a BED12 record.  For example, consider a BED12 record describing a
transcript.  By default, \code{getfasta} will extract the sequence representing the
entire transcript (intons, exons, UTRs).  Using the -split option, \code{getfasta}
will instead produce separate a FASTA record representing a transcript that
splices together each BED12 block (e.g., exons
and UTRs in the case of genes described with BED12).

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat genes.bed12
chr1  164404  173864  ENST00000466557.1       0       -       173864  173864  0       6       387,59,66,216,132,112,  0,1479,3695,4644,8152,9348,
chr1  235855  267253  ENST00000424587.1       0       -       267253  267253  0       4       2100,150,105,158,       0,2562,23161,31240,
chr1  317810  328455  ENST00000426316.1       0       +       328455  328455  0       2       323,145,        0,10500,

\PYG{n+nv}{\PYGZdl{} }bedtools getfasta -fi chr1.fa -bed genes.bed12 -split -name -fo stdout
\PYGZgt{}ENST00000466557.1
gaggcgggaagatcacttgatatcaggagtcgaggcgggaagatcacttgacgtcaggagttcgagactggcccggccaacatggtgaaaccgcatctccactaaaaatacaaaaattagcctggtatggtggtgggcacctgtaatcccagtgacttgggaggctaaggcaggagaatttcttgaacccaggaggcagaggttgcagtgaccagcaaggttgcgccattgcaccccagcctgggcgataagagtgaaaactccatctcaaaaaaaaaaaaaaaaaaaaaaTTCCTTTGGGAAGGCCTTCTACATAAAAATCTTCAACATGAGACTGGAAAAAAGGGTATGGGATCATCACCGGACCTTTGGCTTTTACAGCTCGAGCTGACAAAGTTGATTTATCAAGTTGTAAATCTTCACCTGTTGAATTCATAAGTTCATGTCATATTTTCTTTCAGACAATTCTTCAGTTTGTTTACGTAGATCAGCGATACGATGATTCCATTTCTtcggatccttgtaagagcagagcaggtgatggagagggtgggaggtgtagtgacagaagcaggaaactccagtcattcgagacgggcagcacaagctgcggagtgcaggccacctctacggccaggaaacggattctcccgcagagcctcggaagctaccgaccctgctcccaccttgactcagtaggacttactgtagaattctggccttcagacCTGAGCCTGGCAGCTCTCTCCAACTTTGGAAGCCCAGGGGCATGGCCCCTGTCCACAGATGCACCTGGCATGAGGCGTGCCCAGAGGGACAGAGGCAGATGAGTttcgtctcctccactggattgtgagggcCAGAGTTGAACTCCCTCATTTTCCGTTCCCCAGCATTGGCAGGTTCTGGGACTGGTGGCTGTGGTGGCTCGTTGGTCTTTGTCTCTTAGAAGGTGGGGAATAATCATCATCT
\PYGZgt{}ENST00000424587.1
ccaggaagtgaaaatgacactttactgttttaatttgcatttctctgcttacaagtggattacacacattttcgtgtgctgttggctacttatTCATTCAGAAAACATACTAAGTGCTGGCTCTTTTTCATGTCCTTTATCAAGTTTGGATCATGTCATTTGCTATTTTCTTTCTGATGTAAACTCTCAAAGTCTGAAGTGTATTGTCTTTTCCTGACACATATGTTGTAAATAATTTTCTGGCTTACATTTTGACTTTTAATTTCATTCACGATGTTTTTAATGAATAATTTTAATTTTTATGAATGCAAGTTAAAATAATTCTTTCATTGTGGTCTCTGACATGTCATGCCAATAAGGGTCTTCTCCTCCAAGAGCACAGAAATATTTGCCAATACTGTCCTTAAAATCGGTCACAGTTTCATTTTTTATATATGCATTTTACTTCAATTGGGGCTTCATTTTACTGAATGCCCTATTTGAAGCAAGTTTCTCAGTTAATTCTTTTCTCAAAGGGCTAAGTATGGTAGATTGCAAACATAAGTGGCCACATAATGCTCTCACCTCctttgcctcctctcccaggaggagatagcgtccatctttccactccttaatctgggcttggccgtgtgacttgcactggccaatgggatattaacaagtctgatgtgcacagaggctgtagaatgtgcacgggggcttggtctctcttgctgccctggagaccagctgccCCACGAAGGAACCAGAGCCAACCTGCTGCTTCCTGGAGGAAGACAGTCCCTCTGTCCCTCTGTCTCTGCCAACCAGTTAACCTGCTGCTTCCTGGAGGGAGACAGTCCCTCAGTCCCTCTGTCTCTGCCAACCAGTTAACCTGCTGCTTCCTGGAGGAAGACAGTCACTCTGTCTCTGccaacccagttgaccgcagacatgcaggtctgctcaggtaagaccagcacagtccctgccctgtgagccaaaccaaatggtccagccacagaatcgtgagcaaataagtgatgcttaagtcactaagatttgggCAAAAGCTGAGCATTTATCCCAATCCCAATACTGTTTGTCCTTCTGTTTATCTGTCTGTCCTTCCCTGCTCATTTAAAATGCCCCCACTGCATCTAGTACATTTTTATAGGATCAGGGATCTGCTCTTGGATTAATGTTGTGTTCCCACCTCGAGGCAGCTTTGTAAGCTTCTGAGCACTTCCCAATTCCGGGTGACTTCAGGCACTGGGAGGCCTGTGCATCAGCTGCTGCTGTCTGTAGCTGACTTCCTTCACCCCTCTGCTGTCCTCAGCTCCTTCACCCCTGGGCCTCAGGAAATCAATGTCATGCTGACATCACTCTAGATCTAAAAGTTGGGTTCTTGgaccaggcgtggtggctcacacctgtaatcccagcactttgggaggccgaggcgggtggatcacaaggtcaggagatcaagacgattctggctaacacggtgaaaccccgtctctactaaaaatacaaaaaaattagccgggtgtggtggcaggtgcctgtagccccagctacttgggaggctgaggcaggagaatggcttgaacctgggaggtggagcttgcagtgagccaagatcacgccactgcactccagaatgggagagagagcgagactttctcaaaaaaaaaaaaaaaaCTTAGGTTCTTGGATGTTCGGGAAAGGGGGTTATTATCTAGGATCCTTGAAGCACCCCCAAGGGCATCTTCTCAAAGTTGGATGTGTGCATTTTCCTGAGAGGAAAGCTTTCCCACATTATACAGCTTCTGAAAGGGTTGCTTGACCCACAGATGTGAAGCTGAGGCTGAAGGAGACTGATGTGGTTTCTCCTCAGTTTCTCTGTGCAGCACCAGGTGGCAGCAGAGGTCAGCAAGGCAAACCCGAGCCCGGGGATGCGGAGTGGGGGCAGCTACGTCCTCTCTTGAGCTACAGCAGATTCACTCTGTTCTGTTTCATTGTTGTTTAGTTTGCGTTGTGTTTCTCCAACTTTGTGCCTCATCAGGAAAAGCTTTGGATCACAATTCCCAGtgctgaagaaaaggccaaactcttggttgtgttctttgattAGTgcctgtgacgcagcttcaggaggtcctgagaacgtgtgcacagtttagtcggcagaaacttagggaaatgtaagaccaccatcagcacataggagttctgcattggtttggtctgcattggtttggtCTTTTCCTGGATACAGGTCTTGATAGGTCTCTTGATGTCATTTCACTTCAGATTCTTCTTTAGAAAACTTGGACAATAGCATTTGCTGTCTTGTCCAAATTGTTACTTCAAGTTTGCTCTTAGCAAGTAATTGTTTCAGTATCTATATCAAAAATGGCTTAAGCCTGCAACATGTTTCTGAATGATTAACAAGGTGATAGTCAGTTCTTCATTGAATCCTGGATGCTTTATTTTTCTTAATAAGAGGAATTCATATGGATCAG
\PYGZgt{}ENST00000426316.1
AATGATCAAATTATGTTTCCCATGCATCAGGTGCAATGGGAAGCTCTTctggagagtgagagaagcttccagttaaggtgacattgaagccaagtcctgaaagatgaggaagagttgtatgagagtggggagggaagggggaggtggagggaTGGGGAATGGGCCGGGATGGGATAGCGCAAACTGCCCGGGAAGGGAAACCAGCACTGTACAGACCTGAACAACGAAGATGGCATATTTTGTTCAGGGAATGGTGAATTAAGTGTGGCAGGAATGCTTTGTAGACACAGTAATTTGCTTGTATGGAATTTTGCCTGAGAGACCTCATTCCTCACGTCGGCCATTCCAGGCCCCGTTTTTCCCTTCCGGCAGCCTCTTGGCCTCTAATTTGTTTATCTTTTGTGTATAAATCCCAAAATATTGAATTTTGGAATATTTCCACCATTATGTAAATATTTTGATAGGTAA

\PYG{c}{\PYGZsh{} use the UNIX fold command to wrap the FASTA sequence such that each line}
\PYG{c}{\PYGZsh{} has at most 60 characters}
\PYG{n+nv}{\PYGZdl{} }bedtools getfasta -fi chr1.fa -bed genes.bed12 -split -name -fo stdout \textbar{} \PYG{l+s+se}{\PYGZbs{}}
      fold -w 60
\PYGZgt{}ENST00000466557.1
gaggcgggaagatcacttgatatcaggagtcgaggcgggaagatcacttgacgtcaggag
ttcgagactggcccggccaacatggtgaaaccgcatctccactaaaaatacaaaaattag
cctggtatggtggtgggcacctgtaatcccagtgacttgggaggctaaggcaggagaatt
tcttgaacccaggaggcagaggttgcagtgaccagcaaggttgcgccattgcaccccagc
ctgggcgataagagtgaaaactccatctcaaaaaaaaaaaaaaaaaaaaaaTTCCTTTGG
GAAGGCCTTCTACATAAAAATCTTCAACATGAGACTGGAAAAAAGGGTATGGGATCATCA
CCGGACCTTTGGCTTTTACAGCTCGAGCTGACAAAGTTGATTTATCAAGTTGTAAATCTT
CACCTGTTGAATTCATAAGTTCATGTCATATTTTCTTTCAGACAATTCTTCAGTTTGTTT
ACGTAGATCAGCGATACGATGATTCCATTTCTtcggatccttgtaagagcagagcaggtg
atggagagggtgggaggtgtagtgacagaagcaggaaactccagtcattcgagacgggca
gcacaagctgcggagtgcaggccacctctacggccaggaaacggattctcccgcagagcc
tcggaagctaccgaccctgctcccaccttgactcagtaggacttactgtagaattctggc
cttcagacCTGAGCCTGGCAGCTCTCTCCAACTTTGGAAGCCCAGGGGCATGGCCCCTGT
CCACAGATGCACCTGGCATGAGGCGTGCCCAGAGGGACAGAGGCAGATGAGTttcgtctc
ctccactggattgtgagggcCAGAGTTGAACTCCCTCATTTTCCGTTCCCCAGCATTGGC
AGGTTCTGGGACTGGTGGCTGTGGTGGCTCGTTGGTCTTTGTCTCTTAGAAGGTGGGGAA
TAATCATCATCT
\PYGZgt{}ENST00000424587.1
ccaggaagtgaaaatgacactttactgttttaatttgcatttctctgcttacaagtggat
tacacacattttcgtgtgctgttggctacttatTCATTCAGAAAACATACTAAGTGCTGG
CTCTTTTTCATGTCCTTTATCAAGTTTGGATCATGTCATTTGCTATTTTCTTTCTGATGT
AAACTCTCAAAGTCTGAAGTGTATTGTCTTTTCCTGACACATATGTTGTAAATAATTTTC
TGGCTTACATTTTGACTTTTAATTTCATTCACGATGTTTTTAATGAATAATTTTAATTTT
TATGAATGCAAGTTAAAATAATTCTTTCATTGTGGTCTCTGACATGTCATGCCAATAAGG
GTCTTCTCCTCCAAGAGCACAGAAATATTTGCCAATACTGTCCTTAAAATCGGTCACAGT
TTCATTTTTTATATATGCATTTTACTTCAATTGGGGCTTCATTTTACTGAATGCCCTATT
TGAAGCAAGTTTCTCAGTTAATTCTTTTCTCAAAGGGCTAAGTATGGTAGATTGCAAACA
TAAGTGGCCACATAATGCTCTCACCTCctttgcctcctctcccaggaggagatagcgtcc
atctttccactccttaatctgggcttggccgtgtgacttgcactggccaatgggatatta
acaagtctgatgtgcacagaggctgtagaatgtgcacgggggcttggtctctcttgctgc
cctggagaccagctgccCCACGAAGGAACCAGAGCCAACCTGCTGCTTCCTGGAGGAAGA
CAGTCCCTCTGTCCCTCTGTCTCTGCCAACCAGTTAACCTGCTGCTTCCTGGAGGGAGAC
AGTCCCTCAGTCCCTCTGTCTCTGCCAACCAGTTAACCTGCTGCTTCCTGGAGGAAGACA
GTCACTCTGTCTCTGccaacccagttgaccgcagacatgcaggtctgctcaggtaagacc
agcacagtccctgccctgtgagccaaaccaaatggtccagccacagaatcgtgagcaaat
aagtgatgcttaagtcactaagatttgggCAAAAGCTGAGCATTTATCCCAATCCCAATA
CTGTTTGTCCTTCTGTTTATCTGTCTGTCCTTCCCTGCTCATTTAAAATGCCCCCACTGC
ATCTAGTACATTTTTATAGGATCAGGGATCTGCTCTTGGATTAATGTTGTGTTCCCACCT
CGAGGCAGCTTTGTAAGCTTCTGAGCACTTCCCAATTCCGGGTGACTTCAGGCACTGGGA
GGCCTGTGCATCAGCTGCTGCTGTCTGTAGCTGACTTCCTTCACCCCTCTGCTGTCCTCA
GCTCCTTCACCCCTGGGCCTCAGGAAATCAATGTCATGCTGACATCACTCTAGATCTAAA
AGTTGGGTTCTTGgaccaggcgtggtggctcacacctgtaatcccagcactttgggaggc
cgaggcgggtggatcacaaggtcaggagatcaagacgattctggctaacacggtgaaacc
ccgtctctactaaaaatacaaaaaaattagccgggtgtggtggcaggtgcctgtagcccc
agctacttgggaggctgaggcaggagaatggcttgaacctgggaggtggagcttgcagtg
agccaagatcacgccactgcactccagaatgggagagagagcgagactttctcaaaaaaa
aaaaaaaaaCTTAGGTTCTTGGATGTTCGGGAAAGGGGGTTATTATCTAGGATCCTTGAA
GCACCCCCAAGGGCATCTTCTCAAAGTTGGATGTGTGCATTTTCCTGAGAGGAAAGCTTT
CCCACATTATACAGCTTCTGAAAGGGTTGCTTGACCCACAGATGTGAAGCTGAGGCTGAA
GGAGACTGATGTGGTTTCTCCTCAGTTTCTCTGTGCAGCACCAGGTGGCAGCAGAGGTCA
GCAAGGCAAACCCGAGCCCGGGGATGCGGAGTGGGGGCAGCTACGTCCTCTCTTGAGCTA
CAGCAGATTCACTCTGTTCTGTTTCATTGTTGTTTAGTTTGCGTTGTGTTTCTCCAACTT
TGTGCCTCATCAGGAAAAGCTTTGGATCACAATTCCCAGtgctgaagaaaaggccaaact
cttggttgtgttctttgattAGTgcctgtgacgcagcttcaggaggtcctgagaacgtgt
gcacagtttagtcggcagaaacttagggaaatgtaagaccaccatcagcacataggagtt
ctgcattggtttggtctgcattggtttggtCTTTTCCTGGATACAGGTCTTGATAGGTCT
CTTGATGTCATTTCACTTCAGATTCTTCTTTAGAAAACTTGGACAATAGCATTTGCTGTC
TTGTCCAAATTGTTACTTCAAGTTTGCTCTTAGCAAGTAATTGTTTCAGTATCTATATCA
AAAATGGCTTAAGCCTGCAACATGTTTCTGAATGATTAACAAGGTGATAGTCAGTTCTTC
ATTGAATCCTGGATGCTTTATTTTTCTTAATAAGAGGAATTCATATGGATCAG
\PYGZgt{}ENST00000426316.1
AATGATCAAATTATGTTTCCCATGCATCAGGTGCAATGGGAAGCTCTTctggagagtgag
agaagcttccagttaaggtgacattgaagccaagtcctgaaagatgaggaagagttgtat
gagagtggggagggaagggggaggtggagggaTGGGGAATGGGCCGGGATGGGATAGCGC
AAACTGCCCGGGAAGGGAAACCAGCACTGTACAGACCTGAACAACGAAGATGGCATATTT
TGTTCAGGGAATGGTGAATTAAGTGTGGCAGGAATGCTTTGTAGACACAGTAATTTGCTT
GTATGGAATTTTGCCTGAGAGACCTCATTCCTCACGTCGGCCATTCCAGGCCCCGTTTTT
CCCTTCCGGCAGCCTCTTGGCCTCTAATTTGTTTATCTTTTGTGTATAAATCCCAAAATA
TTGAATTTTGGAATATTTCCACCATTATGTAAATATTTTGATAGGTAA
\end{Verbatim}


\subsubsection{\emph{groupby}}
\label{content/tools/groupby::doc}\label{content/tools/groupby:groupby}
\code{bedtools groupby} is a useful tool that mimics the ``group by'' clause in database
systems. Given a file or stream that is sorted by the appropriate ``grouping
columns'' (\code{-g}), \code{groupby} will compute summary statistics on another
column (\code{-c}) in the file or stream. This will work with output from all
BEDTools as well as any other tab-delimited file or stream.  As such, this is a
generally useful tool for all command-line analyses, not just genomics related
research.

\begin{notice}{note}{Note:}
When using \code{bedtools groupby}, the input data must be ordered by the same
columns as specified with the \code{-grp} argument, which establish which
columns should be used to define a group of similar data. For example,
if \code{-grp} is 1,2,3, the data should be pre-grouped accordingly. When
\code{bedtools groupby} detects changes in the group columns it then summarizes
all lines with that group.  For example, \code{sort -k1,1 -k2,2 -k3,3 data.txt
\textbar{} bedtools groupby -g 1,2,3 -c 4 -o mean}.
\end{notice}


\paragraph{Usage and option summary}
\label{content/tools/groupby:usage-and-option-summary}
Usage

\begin{Verbatim}[commandchars=\\\{\}]
bedtools groupby [OPTIONS] -i \textless{}input\textgreater{} -g \textless{}group columns\textgreater{} -c \textless{}op. column\textgreater{} -o \textless{}operation\textgreater{}
\end{Verbatim}

or:

\begin{Verbatim}[commandchars=\\\{\}]
groupBy [OPTIONS] -i \textless{}input\textgreater{} -g \textless{}group columns\textgreater{} -c \textless{}op. column\textgreater{} -o \textless{}operation\textgreater{}
\end{Verbatim}

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-i}
 & 
The input file that should be grouped and summarized. \emph{Use ``stdin'' when using piped input}.
\textbf{Note: if -i is omitted, input is assumed to come from standard input (stdin)}
\\\hline

\textbf{-g (-grp)}
 & 
Specifies which column(s) (1-based) should be used to group the input. The columns must be comma-separated and each column must be explicitly listed. No ranges (e.g. 1-4) yet allowed. \emph{Default: 1,2,3}
\\\hline

\textbf{-c (-opCol)}
 & 
Specify the column (1-based) that should be summarized. \emph{Required}.
\\\hline

\textbf{-o (-op)}
 & 
Specify the operation that should be applied to \textbf{opCol}.

\begin{DUlineblock}{0em}
\item[] Valid operations:
\end{DUlineblock}

\begin{DUlineblock}{0em}
\item[] \textbf{sum} - \emph{numeric only}
\item[] \textbf{count} - \emph{numeric or text}
\item[] \textbf{count\_distinct} - \emph{numeric or text}
\item[] \textbf{min} - \emph{numeric only}
\item[] \textbf{max} - \emph{numeric only}
\item[] \textbf{mean} - \emph{numeric only}
\item[] \textbf{median} - \emph{numeric only}
\item[] \textbf{mode} - \emph{numeric or text}
\item[] \textbf{antimode} - \emph{numeric or text}
\item[] \textbf{stdev} - \emph{numeric only}
\item[] \textbf{sstdev} - \emph{numeric only}
\item[] \textbf{collapse} (i.e., print a comma separated list) - \emph{numeric or text}
\item[] \textbf{distinct} (i.e., print a comma separated list) - \emph{numeric or text}
\item[] \textbf{concat} (i.e., print a comma separated list) - \emph{numeric or text}
\item[] \textbf{freqasc} - \emph{print a comma separated list of values observed and the number of times they were observed.}
\item[]
\begin{DUlineblock}{\DUlineblockindent}
\item[] Reported in ascending order of frequency*
\end{DUlineblock}
\item[] \textbf{freqdesc} - \emph{print a comma separated list of values observed and the number of times they were observed.}
\item[]
\begin{DUlineblock}{\DUlineblockindent}
\item[] Reported in descending order of frequency*
\end{DUlineblock}
\item[] \textbf{first} - \emph{numeric or text}
\item[] \textbf{last} - \emph{numeric or text}
\item[] \emph{Default: sum}
\end{DUlineblock}
\\\hline
\end{tabular}



\paragraph{Default behavior.}
\label{content/tools/groupby:default-behavior}
Let's imagine we have three incredibly interesting genetic variants that we are
studying and we are interested in what annotated repeats these variants overlap.

\begin{Verbatim}[commandchars=\\\{\}]
cat variants.bed
chr21  9719758 9729320 variant1
chr21  9729310 9757478 variant2
chr21  9795588 9796685 variant3

bedtools intersect -a variants.bed -b repeats.bed -wa -wb \textgreater{} variantsToRepeats.bed
cat variantsToRepeats.bed
chr21  9719758 9729320 variant1   chr21  9719768 9721892 ALR/Alpha   1004  +
chr21  9719758 9729320 variant1   chr21  9721905 9725582 ALR/Alpha   1010  +
chr21  9719758 9729320 variant1   chr21  9725582 9725977 L1PA3       3288  +
chr21  9719758 9729320 variant1   chr21  9726021 9729309 ALR/Alpha   1051  +
chr21  9729310 9757478 variant2   chr21  9729320 9729809 L1PA3       3897  -
chr21  9729310 9757478 variant2   chr21  9729809 9730866 L1P1        8367  +
chr21  9729310 9757478 variant2   chr21  9730866 9734026 ALR/Alpha   1036  -
chr21  9729310 9757478 variant2   chr21  9734037 9757471 ALR/Alpha   1182  -
chr21  9795588 9796685 variant3   chr21  9795589 9795713 (GAATG)n    308   +
chr21  9795588 9796685 variant3   chr21  9795736 9795894 (GAATG)n    683   +
chr21  9795588 9796685 variant3   chr21  9795911 9796007 (GAATG)n    345   +
chr21  9795588 9796685 variant3   chr21  9796028 9796187 (GAATG)n    756   +
chr21  9795588 9796685 variant3   chr21  9796202 9796615 (GAATG)n    891   +
chr21  9795588 9796685 variant3   chr21  9796637 9796824 (GAATG)n    621   +
\end{Verbatim}

We can see that variant1 overlaps with 3 repeats, variant2 with 4 and variant3
with 6. We can use bedtools groupby to summarize the hits for each variant in
several useful ways. The default behavior is to compute the \emph{sum} of the opCol.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools groupby -i variantsToRepeats.bed -g 1,2,3 -c 9
chr21 9719758 9729320 6353
chr21 9729310 9757478 14482
chr21 9795588 9796685 3604
\end{Verbatim}


\paragraph{Computing the min and max.}
\label{content/tools/groupby:computing-the-min-and-max}
Now let's find the \emph{min} and \emph{max} repeat score for each variant. We do this
by ``grouping'' on the variant coordinate columns (i.e. cols. 1,2 and 3) and
ask for the min and max of the repeat score column (i.e. col. 9).

\begin{Verbatim}[commandchars=\\\{\}]
bedtools groupby -i variantsToRepeats.bed -g 1,2,3 -c 9 -o min
chr21 9719758 9729320 1004
chr21 9729310 9757478 1036
chr21 9795588 9796685 308
\end{Verbatim}

We can also group on just the \emph{name} column with similar effect.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools groupby -i variantsToRepeats.bed -g 4 -c 9 -o min
variant1 1004
variant2 1036
variant3 308
\end{Verbatim}

What about the \emph{max} score? Let's keep the coordinates and the name of the
variants so that we stay in BED format.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools groupby -i variantsToRepeats.bed -grp 1-4 -c 9 -o max
chr21 9719758 9729320 variant1 3288
chr21 9729310 9757478 variant2 8367
chr21 9795588 9796685 variant3 891
\end{Verbatim}


\paragraph{Computing the mean and median.}
\label{content/tools/groupby:computing-the-mean-and-median}
Now let's find the \emph{mean} and \emph{median} repeat score for each variant.

\begin{Verbatim}[commandchars=\\\{\}]
cat variantsToRepeats.bed \textbar{} bedtools groupby -g 1-4 -c 9 -o mean
chr21 9719758 9729320 variant1 1588.25
chr21 9729310 9757478 variant2 3620.5
chr21 9795588 9796685 variant3 600.6667

bedtools groupby -i variantsToRepeats.bed -g 1-4 -c 9 -op median
chr21 9719758 9729320 variant1 1030.5
chr21 9729310 9757478 variant2 2539.5
chr21 9795588 9796685 variant3 652
\end{Verbatim}


\paragraph{Computing the mode and ``antimode''.}
\label{content/tools/groupby:computing-the-mode-and-antimode}
Now let's find the \emph{mode} and \emph{antimode} (i.e., the least frequent) repeat
score for each variant (in this case they are identical).

\begin{Verbatim}[commandchars=\\\{\}]
bedtools groupby -i variantsToRepeats.bed -g 1-4 -c 9 -o mode
chr21 9719758 9729320 variant1 1004
chr21 9729310 9757478 variant2 1036
chr21 9795588 9796685 variant3 308

bedtools groupby -i variantsToRepeats.bed -g 1-4 -c 9 -o antimode
chr21 9719758 9729320 variant1 1004
chr21 9729310 9757478 variant2 1036
chr21 9795588 9796685 variant3 308
\end{Verbatim}


\paragraph{Computing the count of lines for a given group.}
\label{content/tools/groupby:computing-the-count-of-lines-for-a-given-group}
Figure:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools groupby -i variantsToRepeats.bed -g 1-4 -c 9 -c count
chr21 9719758 9729320 variant1 4
chr21 9729310 9757478 variant2 4
chr21 9795588 9796685 variant3 6
\end{Verbatim}


\paragraph{Collapsing: listing all of the values in the opCol for a given group.}
\label{content/tools/groupby:collapsing-listing-all-of-the-values-in-the-opcol-for-a-given-group}
Now for something different. What if we wanted all of the names of the repeats
listed on the same line as the variants? Use the collapse option. This
``denormalizes'' things. Now you have a list of all the repeats on a single line.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools groupby -i variantsToRepeats.bed -grp 1-4 -c 9 -o collapse
chr21 9719758 9729320 variant1 ALR/Alpha,ALR/Alpha,L1PA3,ALR/Alpha,
chr21 9729310 9757478 variant2 L1PA3,L1P1,ALR/Alpha,ALR/Alpha,
chr21 9795588 9796685 variant3 (GAATG)n,(GAATG)n,(GAATG)n,(GAATG)n,(GAATG)n,(GAATG)n,
\end{Verbatim}


\paragraph{Computing frequencies: freqasc and freqdesc.}
\label{content/tools/groupby:computing-frequencies-freqasc-and-freqdesc}
What if we want to report each distinct value along with its number of
occurrence (much like uniq -c)?  The \code{freqasc} and freqdesc{}`{}` operations
handle this.

\begin{Verbatim}[commandchars=\\\{\}]
cat variantsToRepeats.bed \textbar{} bedtools groupby -g 1 -c 8 -o freqdesc
chr21 (GAATG)n:6,ALR/Alpha:5,L1PA3:2,L1P1:1,

cat variantsToRepeats.bed \textbar{} bedtools groupby -g 1 -c 8 -o freqasc
chr21 L1P1:1,L1PA3:2,ALR/Alpha:5,(GAATG)n:6,
\end{Verbatim}


\subsubsection{\emph{intersect}}
\label{content/tools/intersect::doc}\label{content/tools/intersect:intersect}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{intersect-glyph.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

By far, the most common question asked of two sets of genomic features
is whether or not any of the features in the two sets ``overlap''
with one another. This is known as feature intersection.
\code{bedtools intersect} allows one to screen for overlaps between
two sets of genomic features. Moreover, it allows one to have fine control
as to how the intersections are reported. \code{bedtools intersect} works
with both BED/GFF/VCF and BAM files as input.

\begin{notice}{note}{Note:}
If you are trying to intersect very large files and are having trouble
with excessive memory usage, please presort your data by chromosome and
then by start position (e.g., \code{sort k1,1 -k2,2n in.bed \textgreater{} in.sorted.bed}
for BED files) and then use the \code{-sorted} option.  This invokes a
memory-efficient algorithm designed for large files.
\end{notice}


\strong{See Also:}


{\hyperref[content/tools/subtract::doc]{\emph{subtract}}}
{\hyperref[content/tools/window::doc]{\emph{window}}}




\paragraph{Usage and option summary}
\label{content/tools/intersect:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect [OPTIONS] [-a\textbar{}-abam] -b \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
intersectBed [OPTIONS] [-a\textbar{}-abam] -b \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-a}
 & 
BED/GFF/VCF file A. Each feature in A is compared to B in search of overlaps. Use ``stdin'' if passing A with a UNIX pipe.
\\\hline

\textbf{-b}
 & 
BED/GFF/VCF file B. Use ``stdin'' if passing B with a UNIX pipe.
\\\hline

\textbf{-abam}
 & 
BAM file A. Each BAM alignment in A is compared to B in search of overlaps. Use ``stdin'' if passing A with a UNIX pipe: For example: samtools view -b \textless{}BAM\textgreater{} \textbar{} bedtools intersect -abam stdin -b genes.bed
\\\hline

\textbf{-ubam}
 & 
Write uncompressed BAM output. The default is write compressed BAM output.
\\\hline

\textbf{-bed}
 & 
When using BAM input (-abam), write output as BED. The default is to write output in BAM when using -abam. For example:   \code{bedtools intersect -abam reads.bam -b genes.bed -bed}
\\\hline

\textbf{-wa}
 & 
Write the original entry in A for each overlap.
\\\hline

\textbf{-wb}
 & 
Write the original entry in B for each overlap. Useful for knowing what A overlaps. Restricted by -f and -r.
\\\hline

\textbf{-loj}
 & 
Perform a ``left outer join''. That is, for each feature in A report each overlap with B.  If no overlaps are found, report a NULL feature for B.
\\\hline

\textbf{-wo}
 & 
Write the original A and B entries plus the number of base pairs of overlap between the two features. Only A features with overlap are reported. Restricted by -f and -r.
\\\hline

\textbf{-wao}
 & 
Write the original A and B entries plus the number of base pairs of overlap between the two features. However, A features w/o overlap are also reported with a NULL B feature and overlap = 0. Restricted by -f and -r.
\\\hline

\textbf{-u}
 & 
Write original A entry once if any overlaps found in B. In other words, just report the fact at least one overlap was found in B. Restricted by -f and -r.
\\\hline

\textbf{-c}
 & 
For each entry in A, report the number of hits in B while restricting to -f. Reports 0 for A entries that have no overlap with B. Restricted by -f and -r.
\\\hline

\textbf{-v}
 & 
Only report those entries in A that have no overlap in B. Restricted by -f and -r.
\\\hline

\textbf{-f}
 & 
Minimum overlap required as a fraction of A. Default is 1E-9 (i.e. 1bp).
\\\hline

\textbf{-r}
 & 
Require that the fraction of overlap be reciprocal for A and B. In other words, if -f is 0.90 and -r is used, this requires that B overlap at least 90\% of A and that A also overlaps at least 90\% of B.
\\\hline

\textbf{-s}
 & 
Force ``strandedness''. That is, only report hits in B that overlap A on the same strand. By default, overlaps are reported without respect to strand.
\\\hline

\textbf{-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.
\\\hline

\textbf{-split}
 & 
Treat ``split'' BAM (i.e., having an ``N'' CIGAR operation) or BED12 entries as distinct BED intervals.
\\\hline

\textbf{-sorted}
 & 
For very large B files, invoke a ``sweeping'' algorithm that requires position-sorted (e.g., \code{sort -k1,1 -k2,2n} for BED files) input.  When using -sorted, memory usage remains low even for very large files.
\\\hline

\textbf{-header}
 & 
Print the header from the A file prior to results.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/intersect:default-behavior}
By default, if an overlap is found, \code{bedtools intersect} reports the shared interval between the two
overlapping features.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20
chr1  30  40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15   20

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed
chr1  15   20
\end{Verbatim}


\paragraph{\texttt{-wa} Reporting the original A feature}
\label{content/tools/intersect:wa-reporting-the-original-a-feature}
Instead, one can force \code{bedtools intersect} to report the \emph{original} \textbf{``A''} feature when an overlap is found. As
shown below, the entire ``A'' feature is reported, not just the portion that overlaps with the ``B'' feature.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20
chr1  30   40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15  20

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -wa
chr1  10   20
\end{Verbatim}


\paragraph{\texttt{-wb} Reporting the original B feature}
\label{content/tools/intersect:wb-reporting-the-original-b-feature}
Similarly, one can force \code{bedtools intersect} to report the \emph{original} \textbf{``B''} feature when an overlap is found. If
just -wb is used, the overlapping portion of A will be reported followed by the \emph{original} \textbf{``B''}. If both -wa
and -wb are used, the \emph{originals} of both \textbf{``A''} and \textbf{``B''} will be reported.

For example (-wb alone):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20
chr1  30  40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15   20

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -wb
chr1  15  20  chr 15  20
\end{Verbatim}

Now -wa and -wb:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20
chr1  30  40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15   20

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -wa -wb
chr1  10  20  chr 15  20
\end{Verbatim}


\paragraph{\texttt{-loj} Left outer join. Report features in A with and without overlaps}
\label{content/tools/intersect:loj-left-outer-join-report-features-in-a-with-and-without-overlaps}
By default, \code{bedtools intersect} will only report features in A that
have an overlap in B.  The \code{-loj} option will report every A feature
no matter what.  When there is an overlap (or more than 1), it will report
A with its overlaps. Yet when there are no overlaps, an A feature will be
reported with a NULL B feature to indicate that there were no overlaps

For example (\emph{without} \code{-loj}):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20
chr1  30  40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15   20

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed
chr1  10  20  chr 15  20
\end{Verbatim}

Now \emph{with} \code{-loj}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20
chr1  30  40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15   20

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -loj
chr1  10  20  chr 15  20
chr1  30  40  . -1  -1
\end{Verbatim}


\paragraph{\texttt{-wo} Write the \emph{amount} of overlap between intersecting features}
\label{content/tools/intersect:wo-write-the-amount-of-overlap-between-intersecting-features}
The \code{-wo} option reports a column after each combination of intersecting
``A'' and ``B'' features indicating the \emph{amount} of overlap in bases pairs that
is observed between the two features.

\begin{notice}{note}{Note:}
When an interval in A does not intersect an interval in B, it will not be
reported.  If you would like to report such intervals with an overlap equal
to 0, see the \code{-wao} option.
\end{notice}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1    10    20
chr1    30    40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1    15  20
chr1    18  25

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -wo
chr1    10    20    chr1    15  20  5
chr1    10    20    chr1    18  25  2
\end{Verbatim}


\paragraph{\texttt{-wao} Write \emph{amounts} of overlap for all features.}
\label{content/tools/intersect:wao-write-amounts-of-overlap-for-all-features}
The \code{-wao} option extends upon the \code{-wo} option in that, unlike \code{-wo},
it reports an overlap of 0 for features in A that do not have an intersection
in B.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1    10    20
chr1    30    40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1    15  20
chr1    18  25

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -wao
chr1    10    20    chr1    15  20  5
chr1    10    20    chr1    18  25  2
chr1    30    40    .       -1  -1  0
\end{Verbatim}


\paragraph{\texttt{-u} (unique) Reporting the mere presence of \emph{any} overlapping features}
\label{content/tools/intersect:u-unique-reporting-the-mere-presence-of-any-overlapping-features}
Often you'd like to simply know a feature in ``A'' overlaps one or more
features in B without reporting each and every intersection.  The \code{-u}
option will do exactly this: if an one or more overlaps exists, the
A feature is reported.  Otherwise, nothing is reported.

For example, without \code{-u}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15  20
chr1  17  22

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed
chr1  10   20
chr1  10   20
\end{Verbatim}

Now with \code{-u}:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15  20
chr1  17  22

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -u
chr1  10   20
\end{Verbatim}


\paragraph{\texttt{-c} Reporting the number of overlapping features}
\label{content/tools/intersect:c-reporting-the-number-of-overlapping-features}
The -c option reports a column after each ``A'' feature indicating the \emph{number} (0 or more) of overlapping
features found in ``B''. Therefore, \emph{each feature in A is reported once}.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1    10    20
chr1    30    40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1    15  20
chr1    18  25

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -c
chr1    10    20    2
chr1    30    40    0
\end{Verbatim}


\paragraph{\texttt{-v} Reporting the absence of any overlapping features}
\label{content/tools/intersect:v-reporting-the-absence-of-any-overlapping-features}
There will likely be cases where you'd like to know which ``A'' features
do not overlap with any of the ``B'' features. Perhaps you'd like to know
which SNPs don't overlap with any gene annotations. The \code{-v}
(an homage to ``grep -v'') option will only report those ``A'' features
that have no overlaps in ``B''.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10  20
chr1  30  40

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  15  20

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -v
chr1  30   40
\end{Verbatim}


\paragraph{\texttt{-f} Requiring a minimal overlap fraction}
\label{content/tools/intersect:f-requiring-a-minimal-overlap-fraction}
By default, \code{bedtools intersect} will report an overlap between A and B so long as there is at least one base
pair is overlapping. Yet sometimes you may want to restrict reported overlaps between A and B to cases
where the feature in B overlaps at least X\% (e.g. 50\%) of the A feature. The -f option does exactly
this.

For example (note that the second B entry is not reported):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1 100 200

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1 130 201
chr1 180 220

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -f 0.50 -wa -wb
chr1 100 200 chr1 130 201
\end{Verbatim}


\paragraph{\texttt{-r, and -f} Requiring reciprocal minimal overlap fraction}
\label{content/tools/intersect:r-and-f-requiring-reciprocal-minimal-overlap-fraction}
Similarly, you may want to require that a minimal fraction of both the A and the B features is
overlapped. For example, if feature A is 1kb and feature B is 1Mb, you might not want to report the
overlap as feature A can overlap at most 1\% of feature B. If one set -f to say, 0.02, and one also
enable the -r (reciprocal overlap fraction required), this overlap would not be reported.

For example (note that the second B entry is not reported):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1 100 200

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1 130 201
chr1 130 200000

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -f 0.50 -r -wa -wb
chr1 100 200 chr1 130 201
\end{Verbatim}


\paragraph{\texttt{-s} Enforcing \emph{same} strandedness}
\label{content/tools/intersect:s-enforcing-same-strandedness}
By default, \code{bedtools intersect} will report overlaps between features
even if the features are on opposite strands. However, if strand information
is present in both BED files and the ``-s'' option is used, overlaps will only
be reported when features are on the same strand.

For example (note that the first B entry is not reported):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1 100 200 a1 100 +

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1 130 201 b1 100 -
chr1 132 203 b2 100 +

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -wa -wb -s
chr1 100 200 a1 100 + chr1 132 203 b2 100 +
\end{Verbatim}


\paragraph{\texttt{-S} Enforcing \emph{opposite} ``strandedness''}
\label{content/tools/intersect:s-enforcing-opposite-strandedness}
The \code{-s} option enforces that overlaps be on the \emph{same} strand.  In some
cases, you may want to enforce that overlaps be found on \emph{opposite} strands.
In this, case use the \code{-S} option.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1 100 200 a1 100 +

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1 130 201 b1 100 -
chr1 132 203 b2 100 +

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a A.bed -b B.bed -wa -wb -S
chr1 100 200 a1 100 + chr1 130 201 b1 100 -
\end{Verbatim}


\paragraph{\texttt{-abam} Default behavior when using BAM input}
\label{content/tools/intersect:abam-default-behavior-when-using-bam-input}
When comparing alignments in BAM format (\textbf{-abam}) to features in BED format (\textbf{-b}), \code{bedtools intersect}
will, \textbf{by default}, write the output in BAM format. That is, each alignment in the BAM file that meets
the user's criteria will be written (to standard output) in BAM format. This serves as a mechanism to
create subsets of BAM alignments are of biological interest, etc. Note that only the mate in the BAM
alignment is compared to the BED file. Thus, if only one end of a paired-end sequence overlaps with a
feature in B, then that end will be written to the BAM output. By contrast, the other mate for the
pair will not be written. One should use \textbf{pairToBed(Section 5.2)} if one wants each BAM alignment
for a pair to be written to BAM output.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools intersect -abam reads.unsorted.bam -b simreps.bed \textbar{} \PYG{l+s+se}{\PYGZbs{}}
       samtools view - \textbar{} \PYG{l+s+se}{\PYGZbs{}}
           head -3

BERTHA\PYGZus{}0001:3:1:15:1362\PYGZsh{}0 99 chr4 9236904 0 \PYG{n+nv}{50M} \PYG{o}{=} 9242033 5 1 7 9
AGACGTTAACTTTACACACCTCTGCCAAGGTCCTCATCCTTGTATTGAAG W c T U \PYG{o}{]} b \PYG{l+s+se}{\PYGZbs{} }g c e g X g f c b f c c b d d g g V Y P W W \PYGZus{}
\PYG{l+s+se}{\PYGZbs{}c}\PYG{l+s+sb}{{}`}dcdabdfW\PYGZca{}a\PYGZca{}gggfgd XT:A:R NM:i:0 SM:i:0 AM:i:0 X0:i:19 X1:i:2 XM:i:0 XO:i:0 XG:i:0 MD:Z:50
BERTHA \PYGZus{}0001:3:1:16:994\PYGZsh{}0 83 chr6 114221672 37 \PYG{n+nv}{25S6M1I11M7S} \PYG{o}{=}
114216196 -5493 G A A A G G C C A G A G T A T A G A A T A A A C A C A A C A A T G T C C A A G G T A C A C T G T T A
gffeaaddddggggggedgcgeggdegggggffcgggggggegdfggfgf XT:A:M NM:i:3 SM:i:37 AM:i:37 XM:i:2 X O : i :
1 XG:i:1 MD:Z:6A6T3
BERTHA \PYGZus{}0001:3:1:16:594\PYGZsh{}0 147 chr8 43835330 0 \PYG{n+nv}{50M} \PYG{o}{=}
43830893 -4487 CTTTGGGAGGGCTTTGTAGCCTATCTGGAAAAAGGAAATATCTTCCCATG U
\PYG{l+s+se}{\PYGZbs{}e}\PYGZca{}bgeTdg\PYGZus{}Kgcg\PYG{l+s+sb}{{}`}ggeggg\PYGZus{}gggggggggddgdggVg\PYG{l+s+se}{\PYGZbs{}g}Wdfgfgff XT:A:R NM:i:2 SM:i:0 AM:i:0 X0:i:10 X1:i:7 X M : i :
2 XO:i:0 XG:i:0 MD:Z:1A2T45
\end{Verbatim}


\paragraph{\texttt{-ubam} Default behavior when using BAM input}
\label{content/tools/intersect:ubam-default-behavior-when-using-bam-input}
The \code{-ubam} option writes \emph{uncompressed} BAM output to stdout.  This is
useful for increasing the speed of pipelines that accept the output of
\code{bedtools} intersect as input, since the receiving tool does not need to
uncompress the data.


\paragraph{\texttt{-bed} Output BED format when using BAM input}
\label{content/tools/intersect:bed-output-bed-format-when-using-bam-input}
When comparing alignments in BAM format (\textbf{-abam}) to features in BED format (\textbf{-b}), \code{bedtools intersect}
will \textbf{optionally} write the output in BED format. That is, each alignment in the BAM file is converted
to a 6 column BED feature and if overlaps are found (or not) based on the user's criteria, the BAM
alignment will be reported in BED format. 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.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools intersect -abam reads.unsorted.bam -b simreps.bed -bed \textbar{} head -20

chr4  9236903   9236953   BERTHA\PYGZus{}0001:3:1:15:1362\PYGZsh{}0/1  0   +
chr6  114221671 114221721 BERTHA\PYGZus{}0001:3:1:16:994\PYGZsh{}0/1   37  -
chr8  43835329  43835379  BERTHA\PYGZus{}0001:3:1:16:594\PYGZsh{}0/2   0   -
chr4  49110668  49110718  BERTHA\PYGZus{}0001:3:1:31:487\PYGZsh{}0/1   23  +
chr19 27732052  27732102  BERTHA\PYGZus{}0001:3:1:32:890\PYGZsh{}0/2   46  +
chr19 27732012  27732062  BERTHA\PYGZus{}0001:3:1:45:1135\PYGZsh{}0/1  37  +
chr10 117494252 117494302 BERTHA\PYGZus{}0001:3:1:68:627\PYGZsh{}0/1   37  -
chr19 27731966  27732016  BERTHA\PYGZus{}0001:3:1:83:931\PYGZsh{}0/2   9   +
chr8  48660075  48660125  BERTHA\PYGZus{}0001:3:1:86:608\PYGZsh{}0/2   37  -
chr9  34986400  34986450  BERTHA\PYGZus{}0001:3:1:113:183\PYGZsh{}0/2  37  -
chr10 42372771  42372821  BERTHA\PYGZus{}0001:3:1:128:1932\PYGZsh{}0/1 3   -
chr19 27731954  27732004  BERTHA\PYGZus{}0001:3:1:130:1402\PYGZsh{}0/2 0   +
chr10 42357337  42357387  BERTHA\PYGZus{}0001:3:1:137:868\PYGZsh{}0/2  9   +
chr1  159720631 159720681 BERTHA\PYGZus{}0001:3:1:147:380\PYGZsh{}0/2  37  -
chrX  58230155  58230205  BERTHA\PYGZus{}0001:3:1:151:656\PYGZsh{}0/2  37  -
chr5  142612746 142612796 BERTHA\PYGZus{}0001:3:1:152:1893\PYGZsh{}0/1 37  -
chr9  71795659  71795709  BERTHA\PYGZus{}0001:3:1:177:387\PYGZsh{}0/1  37  +
chr1  106240854 106240904 BERTHA\PYGZus{}0001:3:1:194:928\PYGZsh{}0/1  37  -
chr4  74128456  74128506  BERTHA\PYGZus{}0001:3:1:221:724\PYGZsh{}0/1  37  -
chr8  42606164  42606214  BERTHA\PYGZus{}0001:3:1:244:962\PYGZsh{}0/1  37  +
\end{Verbatim}


\paragraph{\texttt{-split} Reporting overlaps with spliced alignments or blocked BED features}
\label{content/tools/intersect:split-reporting-overlaps-with-spliced-alignments-or-blocked-bed-features}
As described in section 1.3.19, bedtools intersect will, by default, screen for overlaps against the entire span
of a spliced/split BAM alignment or blocked BED12 feature. When dealing with RNA-seq reads, for
example, one typically wants to only screen for overlaps for the portions of the reads that come from
exons (and ignore the interstitial intron sequence). The \textbf{-split} command allows for such overlaps to be
performed.

For example, the diagram below illustrates the \emph{default} behavior. The blue dots represent the ``split/
spliced'' portion of the alignment (i.e., CIGAR ``N'' operation). In this case, the two exon annotations
are reported as overlapping with the ``split'' BAM alignment, but in addition, a third feature that
overlaps the ``split'' portion of the alignment is also reported.

\begin{Verbatim}[commandchars=\\\{\}]
Chromosome  \textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}

Exons       ---------------                                       ----------

BED/BAM  A     ************.......................................****

BED File B  \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}                     \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}          \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}

Result      ===============                     ========          ==========
\end{Verbatim}

In contrast, when using the \textbf{-split} option, only the exon overlaps are reported.

\begin{Verbatim}[commandchars=\\\{\}]
Chromosome  \textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}

Exons       ---------------                                       ----------

BED/BAM  A     ************.......................................****

BED File B  \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}                     \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}          \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}

Result      ===============                                       ==========
\end{Verbatim}


\paragraph{\texttt{-sorted} Invoke a memory-efficient algorithm for very large files.}
\label{content/tools/intersect:sorted-invoke-a-memory-efficient-algorithm-for-very-large-files}
The default algorithm for detecting overlaps loads the B file into an R-tree
structure in memory.  While fast, it can consume substantial memory for large
files.  For these reason, we provide an alternative, memory efficient algorithm
that depends upon inout files that have been sorted by chromosome and then by
start position. When both input files are position-sorted, the algorithm can
``sweep'' through the data and detect overlaps on the fly in a manner much
like the way database systems join two tables.  This option is invoked with the
\code{-sorted} option.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }sort -k1,1 -k2,2n big.bed \PYGZgt{} big.sorted.bed

\PYG{n+nv}{\PYGZdl{} }sort -k1,1 -k2,2n huge.bed \PYGZgt{} huge.sorted.bed

\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a big.sorted.bed -b huge.sorted.bed -sorted
\end{Verbatim}


\paragraph{\texttt{-header} Print the header for the A file before reporting results.}
\label{content/tools/intersect:header-print-the-header-for-the-a-file-before-reporting-results}
By default, if your A file has a header, it is ignored when reporting results.
This option will instead tell bedtools to first print the header for the
A file prior to reporting results.


\subsubsection{\emph{jaccard}}
\label{content/tools/jaccard::doc}\label{content/tools/jaccard:jaccard}

\subsubsection{\emph{links}}
\label{content/tools/links::doc}\label{content/tools/links:links}
Creates an HTML file with links to an instance of the UCSC Genome Browser for all features /
intervals in a file. This is useful for cases when one wants to manually inspect through a large set of
annotations or features.


\paragraph{Usage and option summary}
\label{content/tools/links:usage-and-option-summary}
Usage:

\begin{Verbatim}[commandchars=\\\{\}]
linksBed [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{} \textgreater{} \textless{}HTML file\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-base}
 & 
The ``basename'' for the UCSC browser. \emph{Default: http://genome.ucsc.edu}
\\\hline

\textbf{-org}
 & 
The organism (e.g. mouse, human). \emph{Default: human}
\\\hline

\textbf{-db}
 & 
The genome build. \emph{Default: hg18}
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/links:default-behavior}
By default, \textbf{linksBed} creates links to the public UCSC Genome Browser.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
head genes.bed
chr21 9928613  10012791  uc002yip.1 0  -
chr21 9928613  10012791  uc002yiq.1 0  -
chr21 9928613  10012791  uc002yir.1 0  -
chr21 9928613  10012791  uc010gkv.1 0  -
chr21 9928613  10061300  uc002yis.1 0  -
chr21 10042683 10120796  uc002yit.1 0  -
chr21 10042683 10120808  uc002yiu.1 0  -
chr21 10079666 10120808  uc002yiv.1 0  -
chr21 10080031 10081687  uc002yiw.1 0  -
chr21 10081660 10120796  uc002yix.2 0  -

linksBed -i genes.bed \textgreater{} genes.html
\end{Verbatim}

When genes.html is opened in a web browser, one should see something like the following, where each
link on the page is built from the features in genes.bed:


\paragraph{Creating HTML links to a local UCSC Browser installation}
\label{content/tools/links:creating-html-links-to-a-local-ucsc-browser-installation}
Optionally, \textbf{linksBed} will create links to a local copy of the UCSC Genome Browser.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
head -3 genes.bed
chr21 9928613 10012791 uc002yip.1 0 -
chr21 9928613 10012791 uc002yiq.1 0 -

linksBed -i genes.bed -base http://mirror.uni.edu \textgreater{} genes.html
\end{Verbatim}

One can point the links to the appropriate organism and genome build as well:

\begin{Verbatim}[commandchars=\\\{\}]
head -3 genes.bed
chr21 9928613 10012791 uc002yip.1 0 -
chr21 9928613 10012791 uc002yiq.1 0 -

linksBed -i genes.bed -base http://mirror.uni.edu -org mouse -db mm9 \textgreater{} genes.html
\end{Verbatim}


\subsubsection{\emph{makewindows}}
\label{content/tools/makewindows::doc}\label{content/tools/makewindows:makewindows}

\subsubsection{\emph{map}}
\label{content/tools/map:map}\label{content/tools/map::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

{\hfill\includegraphics[width=600pt]{map-glyph.png}\hfill}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\code{bedtools map} allows one to map overlapping features in a B file onto
features in an A file and apply statistics and/or summary operations on those
features.

For example, one could use \code{bedtools map} to compute the average
score of BEDGRAPH records that overlap genes. Since the fourth column in
BEDGRAPH is the score, the following command illustrates how this would be done:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools map -a genes.bed -b peaks.bedgraph -c 4 -o mean
\end{Verbatim}

Another example is discussed in this Biostars
\href{http://www.biostars.org/p/61653/}{post}.

\begin{notice}{note}{Note:}
\code{bedtools map} requires each input file to be sorted by genome coordinate.
For BED files, this can be done with \code{sort -k1,1 -k2,2n}.
\end{notice}


\paragraph{Usage and option summary}
\label{content/tools/map:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools map [OPTIONS] -a \textless{}bed/gff/vcf\textgreater{} -b \textless{}bed/gff/vcf\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
mapBed [OPTIONS] -a \textless{}bed/gff/vcf\textgreater{} -b \textless{}bed/gff/vcf\textgreater{}
\end{Verbatim}

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-c}
 & 
\begin{DUlineblock}{0em}
\item[] Specify the column from the B file to map onto intervals in A.
\item[] \code{Default: 5}
\end{DUlineblock}
\\\hline

\textbf{-o}
 & 
Specify the operation that should be applied to \code{-c}.

\begin{DUlineblock}{0em}
\item[] Valid operations:
\end{DUlineblock}

\begin{DUlineblock}{0em}
\item[] \textbf{sum} - \emph{numeric only}
\item[] \textbf{count} - \emph{numeric or text}
\item[] \textbf{count\_distinct} - \emph{numeric or text}
\item[] \textbf{min} - \emph{numeric only}
\item[] \textbf{max} - \emph{numeric only}
\item[] \textbf{mean} - \emph{numeric only}
\item[] \textbf{median} - \emph{numeric only}
\item[] \textbf{antimode} - \emph{numeric or text}
\item[] \textbf{collapse} (i.e., print a comma separated list) - \emph{numeric or text}
\item[] \textbf{distinct} (i.e., print a comma separated list) - \emph{numeric or text}
\item[] \textbf{concat} (i.e., print a comma separated list) - \emph{numeric or text}
\item[] 
\item[] \code{Default: 5}
\end{DUlineblock}
\\\hline

\textbf{-f}
 & 
Minimum overlap required as a fraction of A. Default is 1E-9 (i.e. 1bp).
\\\hline

\textbf{-r}
 & 
Require that the fraction of overlap be reciprocal for A and B. In other words, if -f is 0.90 and -r is used, this requires that B overlap at least 90\% of A and that A also overlaps at least 90\% of B.
\\\hline

\textbf{-s}
 & 
Force ``strandedness''. That is, only report hits in B that overlap A on the same strand. By default, overlaps are reported without respect to strand.
\\\hline

\textbf{-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.
\\\hline

\textbf{-null}
 & 
\begin{DUlineblock}{0em}
\item[] The value to print if no overlaps are found for an A interval.
\item[] \code{Default: "."}
\end{DUlineblock}
\\\hline

\textbf{-header}
 & 
Print the header from the A file prior to results.
\\\hline
\end{tabular}



\paragraph{Default behavior - compute the \texttt{sum} of the \texttt{score} column for all overlaps.}
\label{content/tools/map:default-behavior-compute-the-sum-of-the-score-column-for-all-overlaps}
By default, \code{map} computes the sum of the 5th column (the \code{score} field for
BED format) for all intervals in B that overlap each interval in A.

\begin{notice}{tip}{Tip:}
Records in A that have no overlap will, by default, return \code{.} for the
computed value from B.  This can be changed with the \code{-null} option.
\end{notice}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat a.bed
chr1        10      20      a1      1       +
chr1        50      60      a2      2       -
chr1        80      90      a3      3       -

\PYG{n+nv}{\PYGZdl{} }cat b.bed
chr1        12      14      b1      2       +
chr1        13      15      b2      5       -
chr1        16      18      b3      5       +
chr1        82      85      b4      2       -
chr1        85      87      b5      3       +

\PYG{n+nv}{\PYGZdl{} }bedtools map -a a.bed -b b.bed
chr1        10      20      a1      1       +       12
chr1        50      60      a2      2       -       .
chr1        80      90      a3      3       -       5
\end{Verbatim}


\paragraph{\texttt{mean} Compute the mean of a column from overlapping intervals}
\label{content/tools/map:mean-compute-the-mean-of-a-column-from-overlapping-intervals}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat a.bed
chr1        10      20      a1      1       +
chr1        50      60      a2      2       -
chr1        80      90      a3      3       -

\PYG{n+nv}{\PYGZdl{} }cat b.bed
chr1        12      14      b1      2       +
chr1        13      15      b2      5       -
chr1        16      18      b3      5       +
chr1        82      85      b4      2       -
chr1        85      87      b5      3       +

\PYG{n+nv}{\PYGZdl{} }bedtools map -a a.bed -b b.bed -c 5 -o mean
chr1        10      20      a1      1       +       4
chr1        50      60      a2      2       -       .
chr1        80      90      a3      3       -       2.5
\end{Verbatim}


\paragraph{\texttt{collapse} List each value of a column from overlapping intervals}
\label{content/tools/map:collapse-list-each-value-of-a-column-from-overlapping-intervals}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools map -a a.bed -b b.bed -c 5 -o collapse
chr1        10      20      a1      1       +       2,5,5
chr1        50      60      a2      2       -       .
chr1        80      90      a3      3       -       2,3
\end{Verbatim}


\paragraph{\texttt{distinct} List each \emph{unique} value of a column from overlapping intervals}
\label{content/tools/map:distinct-list-each-unique-value-of-a-column-from-overlapping-intervals}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools map -a a.bed -b b.bed -c 5 -o distinct
chr1        10      20      a1      1       +       2,5
chr1        50      60      a2      2       -       .
chr1        80      90      a3      3       -       2,3
\end{Verbatim}


\paragraph{\texttt{-s} Only include intervals that overlap on the \emph{same} strand.}
\label{content/tools/map:s-only-include-intervals-that-overlap-on-the-same-strand}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools map -a a.bed -b b.bed -c 5 -o collapse -s
chr1        10      20      a1      1       +       2,5
chr1        50      60      a2      2       -       .
chr1        80      90      a3      3       -       2
\end{Verbatim}


\paragraph{\texttt{-S} Only include intervals that overlap on the \emph{opposite} strand.}
\label{content/tools/map:s-only-include-intervals-that-overlap-on-the-opposite-strand}
\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools map -a a.bed -b b.bed -c 5 -o collapse -S
chr1        10      20      a1      1       +       5
chr1        50      60      a2      2       -       .
chr1        80      90      a3      3       -       3
\end{Verbatim}


\subsubsection{\emph{maskfasta}}
\label{content/tools/maskfasta::doc}\label{content/tools/maskfasta:maskfasta}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{maskfasta-glyph.png}

\code{bedtools maskfasta} masks sequences in a FASTA file based on intervals defined in a feature file. The
headers in the input FASTA file must exactly match the chromosome column in the feature file. This
may be useful fro creating your own masked genome file based on custom annotations or for masking all
but your target regions when aligning sequence data from a targeted capture experiment.


\paragraph{Usage and option summary}
\label{content/tools/maskfasta:usage-and-option-summary}
\textbf{Usage}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools maskfasta \PYG{o}{[}OPTIONS\PYG{o}{]} -fi \PYGZlt{}input FASTA\PYGZgt{} -bed \PYGZlt{}BED/GFF/VCF\PYGZgt{} -fo \PYGZlt{}output FASTA\PYGZgt{}
\end{Verbatim}

\textbf{(or):}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }maskFastaFromBed \PYG{o}{[}OPTIONS\PYG{o}{]} -fi \PYGZlt{}input FASTA\PYGZgt{} -bed \PYGZlt{}BED/GFF/VCF\PYGZgt{} -fo \PYGZlt{}output FASTA\PYGZgt{}
\end{Verbatim}

\begin{notice}{note}{Note:}
The input (\code{-fi}) and output (\code{-fo}) FASTA files must be different.
\end{notice}


\strong{See Also:}


{\hyperref[content/tools/getfasta::doc]{\emph{getfasta}}}



\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-soft}
 & 
Soft-mask (that is, convert to lower-case bases) the FASTA sequence. \emph{By default, hard-masking (that is, conversion to Ns) is performed}.
\\\hline

\textbf{-mc}
 & 
Replace masking character.  That is, instead of masking with Ns, use another character.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/maskfasta:default-behavior}
\textbf{bedtools maskfasta} will mask a FASTA file based on the intervals in a
BED file. The newly masked FASTA file is written to the output FASTA file.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat test.fa
\PYGZgt{}chr1
AAAAAAAACCCCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG

\PYG{n+nv}{\PYGZdl{} }cat test.bed
chr1 5 10

\PYG{n+nv}{\PYGZdl{} }bedtools maskfasta -fi test.fa -bed test.bed -fo test.fa.out

\PYG{n+nv}{\PYGZdl{} }cat test.fa.out
\PYGZgt{}chr1
AAAAANNNNNCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG
\end{Verbatim}


\paragraph{\texttt{-soft} Soft-masking the FASTA file.}
\label{content/tools/maskfasta:soft-soft-masking-the-fasta-file}
Using the \textbf{-soft} option, one can optionally ``soft-mask'' the FASTA file.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat test.fa
\PYGZgt{}chr1
AAAAAAAACCCCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG

\PYG{n+nv}{\PYGZdl{} }cat test.bed
chr1 5 10

\PYG{n+nv}{\PYGZdl{} }bedtools maskfasta -fi test.fa -bed test.bed -fo test.fa.out -soft

\PYG{n+nv}{\PYGZdl{} }cat test.fa.out
\PYGZgt{}chr1
AAAAAaaaccCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG
\end{Verbatim}


\paragraph{\texttt{-mc} Specify a masking character.}
\label{content/tools/maskfasta:mc-specify-a-masking-character}
Using the \textbf{-mc} option, one can optionally choose a masking character to each
base that will be masked by the BED file.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat test.fa
\PYGZgt{}chr1
AAAAAAAACCCCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG

\PYG{n+nv}{\PYGZdl{} }cat test.bed
chr1 5 10

\PYG{n+nv}{\PYGZdl{} }bedtools maskfasta -fi test.fa -bed test.bed -fo test.fa.out -mc X

\PYG{n+nv}{\PYGZdl{} }cat test.fa.out
\PYGZgt{}chr1
AAAAAXXXXXCCCCCCCCCCGCTACTGGGGGGGGGGGGGGGGGG
\end{Verbatim}


\subsubsection{\emph{merge}}
\label{content/tools/merge:merge}\label{content/tools/merge::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{merge-glyph.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\code{bedtools merge} combines overlapping or ``book-ended'' features in an interval
file into a single feature which spans all of the combined features.

\begin{notice}{note}{Note:}
\code{bedtools merge} requires that you presort your data by chromosome and
then by start position (e.g., \code{sort k1,1 -k2,2n in.bed \textgreater{} in.sorted.bed}
for BED files).
\end{notice}


\strong{See Also:}


{\hyperref[content/tools/cluster::doc]{\emph{cluster}}}
{\hyperref[content/tools/complement::doc]{\emph{complement}}}




\paragraph{Usage and option summary}
\label{content/tools/merge:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools merge [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
mergeBed [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-s}
 & 
Force strandedness. That is, only merge features that are the same strand. \emph{By default, this is disabled}.
\\\hline

\textbf{-n}
 & 
Report the number of BED entries that were merged. \emph{1 is reported if no merging occurred}.
\\\hline

\textbf{-d}
 & 
Maximum distance between features allowed for features to be merged. \emph{Default is 0. That is, overlapping and/or book-ended features are merged}.
\\\hline

\textbf{-nms}
 & 
Report the names of the merged features separated by semicolons.
\\\hline

\textbf{-scores}
 & 
\begin{DUlineblock}{0em}
\item[] Report the scores of the merged features. Specify one of
\textbar{} the following options for reporting scores:
\textbar{} sum, min, max,
\textbar{} mean, median, mode, antimode,
\textbar{} collapse (i.e., print a semicolon-separated list)
\end{DUlineblock}
\\\hline
\end{tabular}



\paragraph{Default behavior}
\label{content/tools/merge:default-behavior}
By default, \code{bedtools merge} combines overlapping (by at least 1 bp) and/or
bookended intervals into a single, ``flattened'' or ``merged'' interval.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200
chr1  180  250
chr1  250  500
chr1  501  1000

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed
chr1  100  500
chr1  501  1000
\end{Verbatim}


\paragraph{\texttt{-s} Enforcing ``strandedness''}
\label{content/tools/merge:s-enforcing-strandedness}
The \code{-s} option will only merge intervals that are overlapping/bookended
\emph{and} are on the same strand.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200   a1  1 +
chr1  180  250   a2  2 +
chr1  250  500   a3  3 -
chr1  501  1000  a4  4 +

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed -s
chr1  100  250    +
chr1  501  1000   +
chr1  250  500    -
\end{Verbatim}


\paragraph{\texttt{-n} Reporting the number of features that were merged}
\label{content/tools/merge:n-reporting-the-number-of-features-that-were-merged}
The -n option will report the number of features that were combined from the
original file in order to make the newly merged feature. If a feature in the
original file was not merged with any other features, a ``1'' is reported.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200
chr1  180  250
chr1  250  500
chr1  501  1000

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed -n
chr1  100  500  3
chr1  501  1000 1
\end{Verbatim}


\paragraph{\texttt{-d} Controlling how close two features must be in order to merge}
\label{content/tools/merge:d-controlling-how-close-two-features-must-be-in-order-to-merge}
By default, only overlapping or book-ended features are combined into a new
feature. However, one can force \code{merge} to combine more distant features
with the \code{-d} option. For example, were one to set \code{-d} to 1000, any
features that overlap or are within 1000 base pairs of one another will be
combined.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200
chr1  501  1000

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed
chr1  100  200
chr1  501  1000

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed -d 1000
chr1  100  200  1000
\end{Verbatim}


\paragraph{\texttt{-nms} Reporting the names of the features that were merged}
\label{content/tools/merge:nms-reporting-the-names-of-the-features-that-were-merged}
Occasionally, one might like to know that names of the features that were
merged into a new feature. The \code{-nms} option will add an extra column to the
\code{merge} output which lists (separated by semicolons) the names of the
merged features.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200  A1
chr1  150  300  A2
chr1  250  500  A3

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed -nms
chr1  100  500  A1;A2;A3
\end{Verbatim}


\paragraph{\texttt{-scores} Reporting the scores of the features that were merged}
\label{content/tools/merge:scores-reporting-the-scores-of-the-features-that-were-merged}
Similarly, we might like to know that scores of the features that were
merged into a new feature. Enter the \code{-scores} option.  One can specify
how the scores from each overlapping interval should be reported.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200  A1 1
chr1  150  300  A2 2
chr1  250  500  A3 3

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed -scores mean
chr1  100  500  2

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed -scores max
chr1  100  500  3

\PYG{n+nv}{\PYGZdl{} }bedtools merge -i A.bed -scores collapse
chr1  100  500  1,2,3
\end{Verbatim}


\subsubsection{\emph{multicov}}
\label{content/tools/multicov:multicov}\label{content/tools/multicov::doc}
\code{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.

\begin{notice}{note}{Note:}
\code{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 (\code{samtool sort aln.bam aln.sort}) and
indexed (\code{samtools index aln.sort.bam}) with either samtools or bamtools.
\end{notice}


\paragraph{Usage and option summary}
\label{content/tools/multicov:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools multicov [OPTIONS] -bams BAM1 BAM2 BAM3 ... BAMn -bed  \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
multiBamCov [OPTIONS] -bams BAM1 BAM2 BAM3 ... BAMn -bed  \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-split}
 & 
Treat ``split'' BAM or BED12 entries as distinct BED intervals.
\\\hline

\textbf{-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.
\\\hline

\textbf{-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.
\\\hline

\textbf{-f}
 & 
Minimum overlap required as a fraction of each A. Default is
1E-9 (i.e., 1bp).
\\\hline

\textbf{-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.
\\\hline

\textbf{-q}
 & 
Minimum mapping quality (MAPQ) allowed. Default is 0.
\\\hline

\textbf{-D}
 & 
Include duplicate reads.  Default counts non-duplicates only
\\\hline

\textbf{-F}
 & 
Include failed-QC reads.  Default counts pass-QC reads only
\\\hline

\textbf{-p}
 & 
Only count proper pairs.  Default counts all alignments with
\code{MAPQ \textgreater{} -q} argument, regardless of the BAM FLAG field.
\\\hline
\end{tabulary}



\paragraph{Default behavior.}
\label{content/tools/multicov:default-behavior}
By default, \code{multicov} will report the count of alignments in each input
BAM file that overlap.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat ivls-of-interest.bed
chr1 0   10000   ivl1
chr1 10000   20000   ivl2
chr1 20000   30000   ivl3
chr1 30000   40000   ivl4

\PYG{n+nv}{\PYGZdl{} }bedtools multicov -bams aln1.bam aln2.bam aln3.bam -bed ivls-of-interest.bed
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
\end{Verbatim}

The output of \code{multicov} reflects a distinct report of the overlapping
alignments for each record in the \code{-bed} file.  In the example above, each
line of the output reflects \textbf{a)} the original line from the \code{-bed} file
followed by \textbf{b)} the count of alignments that overlap the \code{-bed} interval
from each input \code{-bam} file.  In the example above, the output consists of
7 columns: the first four of which are the columns from the \code{-bed} file and
the last 3 are the count of overlapping alignments from the 3 input \code{-bam}
files.  The order of the counts reflects the order of the files given on the
command line.

\begin{notice}{note}{Note:}
\code{bedtools multicov} will work with a single BAM as well.
\end{notice}

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools multicov -bams aln1.bam -bed ivls-of-interest.bed
chr1 0       10000   ivl1    100
chr1 10000   20000   ivl2    123
chr1 20000   30000   ivl3    213
chr1 30000   40000   ivl4    335
\end{Verbatim}


\subsubsection{\emph{multiinter}}
\label{content/tools/multiinter:multiinter}\label{content/tools/multiinter::doc}

\subsubsection{\emph{nuc}}
\label{content/tools/nuc::doc}\label{content/tools/nuc:nuc}

\subsubsection{\emph{overlap}}
\label{content/tools/overlap::doc}\label{content/tools/overlap:overlap}
\textbf{overlap} computes the amount of overlap (in the case of positive values) or distance (in the case of
negative values) between feature coordinates occurring on the same input line and reports the result at
the end of the same line. In this way, it is a useful method for computing custom overlap scores from
the output of other BEDTools.


\paragraph{Usage and option summary}
\label{content/tools/overlap:usage-and-option-summary}
Usage:

\begin{Verbatim}[commandchars=\\\{\}]
overlap [OPTIONS] -i \textless{}input\textgreater{} -cols s1,e1,s2,e2
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-i}
 & 
Input file. Use ``stdin'' for pipes.
\\\hline

\textbf{-cols}
 & 
Specify the columns (1-based) for the starts and ends of the features for which you'd like to compute the overlap/distance. The columns must be listed in the following order: \emph{start1,end1,start2,end2}
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/overlap:default-behavior}
The default behavior is to compute the amount of overlap between the features you specify based on the
start and end coordinates. For example:

\begin{Verbatim}[commandchars=\\\{\}]
windowBed -a A.bed -b B.bed -w 10
chr1  10  20  A  chr1  15  25  B
chr1  10  20  C  chr1  25  35  D
\end{Verbatim}

\# Now let's say we want to compute the number of base pairs of overlap
\# between the overlapping features from the output of windowBed.

\begin{Verbatim}[commandchars=\\\{\}]
windowBed -a A.bed -b B.bed -w 10 \textbar{} overlap -i stdin -cols 2,3,6,7
chr1  10  20  A  chr1  15  25  B  5
chr1  10  20  C  chr1  25  35  D  -5
\end{Verbatim}


\subsubsection{\emph{pairtobed}}
\label{content/tools/pairtobed::doc}\label{content/tools/pairtobed:pairtobed}

\subsubsection{\emph{pairtopair}}
\label{content/tools/pairtopair:pairtopair}\label{content/tools/pairtopair::doc}
\textbf{pairToPair} compares two BEDPE files in search of overlaps where each end of a BEDPE feature in A
overlaps with the ends of a feature in B. For example, using pairToPair, one could screen for the exact
same discordant paired-end alignment in two files. This could suggest (among other things) that the
discordant pair suggests the same structural variation in each file/sample.


\paragraph{Usage and option summary}
\label{content/tools/pairtopair:usage-and-option-summary}
\textbf{Usage:}

\begin{Verbatim}[commandchars=\\\{\}]
pairToPair [OPTIONS] -a \textless{}BEDPE\textgreater{} -b \textless{}BEDPE\textgreater{}
\end{Verbatim}

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-a}
 & 
BEDPE file A. Each feature in A is compared to B in search of overlaps. Use ``stdin'' if passing A with a UNIX pipe.
\\\hline

\textbf{-b}
 & 
BEDPE file B. Use ``stdin'' if passing B with a UNIX pipe.
\\\hline

\textbf{-f}
 & 
Minimum overlap required as a fraction of A. Default is 1E-9 (i.e. 1bp).
\\\hline

\textbf{-is}
 & 
Force ``strandedness''. That is, only report hits in B that overlap A on the same strand. By default, overlaps are reported without respect to strand.
\\\hline

\textbf{-type}
 & \begin{quote}

Approach to reporting overlaps between BEDPE and BED.
\end{quote}

\begin{DUlineblock}{0em}
\item[] \textbf{either} Report overlaps if either ends of A overlap B.
\end{DUlineblock}
\begin{quote}

\begin{DUlineblock}{0em}
\item[] \textbf{neither} Report A if neither end of A overlaps B.
\end{DUlineblock}

\begin{DUlineblock}{0em}
\item[] \textbf{both} Report overlaps if both ends of A overlap B.   -\emph{Default behavior.}
\end{DUlineblock}
\end{quote}
\\\hline
\end{tabular}



\paragraph{Default behavior}
\label{content/tools/pairtopair:default-behavior}
By default, a BEDPE feature from A will be reported if \emph{both} ends overlap a feature in the BEDPE B
file. If strand information is present for the two BEDPE files, it will be further required that the
overlaps on each end be on the same strand. This way, an otherwise overlapping (in terms of genomic
locations) F/R alignment will not be matched with a R/R alignment.

Default: Report A if \emph{both} ends overlaps B.

\begin{Verbatim}[commandchars=\\\{\}]
Chromosome  \textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}

BEDPE/BAM A         *****.................................*****

BED File B         \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}                                          \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}

Result              =====.................................=====
\end{Verbatim}

Default when strand information is present in both BEDPE files: Report A if \emph{both} ends overlaps B \emph{on
the same strands}.

\begin{Verbatim}[commandchars=\\\{\}]
Chromosome  \textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}

BEDPE A         \textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}.................................\textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}

BEDPE B            \textless{}\textless{}\textless{}\textless{}\textless{}.............................\textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}

Result



BEDPE A         \textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}.................................\textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}

BEDPE B            \textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}.............................\textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}

Result          \textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}.................................\textgreater{}\textgreater{}\textgreater{}\textgreater{}\textgreater{}
\end{Verbatim}


\paragraph{\texttt{-type neither} Optional overlap requirements}
\label{content/tools/pairtopair:type-neither-optional-overlap-requirements}
Using then \textbf{-type neither, pairToPair} will only report A if \emph{neither} end overlaps with a BEDPE
feature in B.

\textbf{-type neither}: Report A only if \emph{neither} end overlaps B.

\begin{Verbatim}[commandchars=\\\{\}]
Chromosome  \textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}\textasciitilde{}

BEDPE/BAM A         *****.................................*****

BED File B         \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}......................................\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}

Result



BEDPE/BAM A         *****.................................*****

BED File B    \textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}................................................\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}\textasciicircum{}

Result              =====.................................=====
\end{Verbatim}


\subsubsection{\emph{random}}
\label{content/tools/random:random}\label{content/tools/random::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{random-glyph.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\emph{bedtools random} will generate a random set of intervals in BED6 format. One
can specify both the number (\code{-n}) and the size (\code{-l}) of the intervals
that should be generated.


\strong{See Also:}


{\hyperref[content/tools/shuffle::doc]{\emph{shuffle}}}
{\hyperref[content/tools/jaccard::doc]{\emph{jaccard}}}




\paragraph{Usage and option summary}
\label{content/tools/random:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools random [OPTIONS] -g \textless{}GENOME\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
randomBed [OPTIONS] -g \textless{}GENOME\textgreater{}
\end{Verbatim}

\begin{tabular}{|p{0.475\linewidth}|p{0.475\linewidth}|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-l}
 & 
\begin{DUlineblock}{0em}
\item[] The length of the intervals to generate.
\item[] \code{Default = 100}
\end{DUlineblock}
\\\hline

\textbf{-n}
 & 
\begin{DUlineblock}{0em}
\item[] The number of intervals to generate.
\item[] \code{Default = 1,000,000}
\end{DUlineblock}
\\\hline

\textbf{-seed}
 & 
Supply an integer seed for the shuffling. This will allow feature shuffling experiments to be recreated exactly as the seed for the pseudo-random number generation will be constant. \emph{By default, the seed is chosen automatically}.
\\\hline
\end{tabular}



\paragraph{Default behavior}
\label{content/tools/random:default-behavior}
By default, \emph{bedtools random} generate 1 million intervals of length 100
placed randomly in the genome specificed with \code{-g}.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools random -g hg19.genome
chr2  87536758        87536858        1       100     -
chrX  46051735        46051835        2       100     +
chr18 5237041 5237141 3       100     -
chr12 45809998        45810098        4       100     +
chrX  42034890        42034990        5       100     -
chr10 77510935        77511035        6       100     -
chr3  39844278        39844378        7       100     -
chr6  101012700       101012800       8       100     +
chr12 38123482        38123582        9       100     +
chr7  88508598        88508698        10      100     -

\PYG{n+nv}{\PYGZdl{} }bedtools random -g hg19.genome
chr3  141987850       141987950       1       100     +
chr5  137643331       137643431       2       100     +
chr2  155523858       155523958       3       100     -
chr5  147874094       147874194       4       100     +
chr1  71838335        71838435        5       100     -
chr8  71154323        71154423        6       100     -
chr2  133240474       133240574       7       100     +
chr9  131495427       131495527       8       100     +
chrX  125952943       125953043       9       100     +
chr3  59685545        59685645        10      100     +
\end{Verbatim}


\paragraph{\texttt{-n} Specify the \emph{number} of intervals to generate.}
\label{content/tools/random:n-specify-the-number-of-intervals-to-generate}
The \emph{-n} option allows one to override the default of generating 1 million
intervals.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools random -g hg19.genome -n 3
chr20 47975280        47975380        1       100     -
chr16 23381222        23381322        2       100     +
chr3  104913816       104913916       3       100     -
\end{Verbatim}


\paragraph{\texttt{-l} Specify the \emph{length} of intervals to generate.}
\label{content/tools/random:l-specify-the-length-of-intervals-to-generate}
The \emph{-l} option allows one to override the default interval length of 100bp.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools random -g hg19.genome -l 5
chr9  54133731        54133736        1       5       +
chr1  235288830       235288835       2       5       -
chr8  26744718        26744723        3       5       +
chr3  187313616       187313621       4       5       -
chr11 88996846        88996851        5       5       -
chr13 84714855        84714860        6       5       -
chr13 10759738        10759743        7       5       -
chr6  122569739       122569744       8       5       +
chr17 50884025        50884030        9       5       -
chr11 38576901        38576906        10      5       +
\end{Verbatim}


\paragraph{\texttt{-seed} Defining a ``seed'' for the random interval creation.}
\label{content/tools/random:seed-defining-a-seed-for-the-random-interval-creation}
\emph{bedtools random} uses a pseudo-random number generator to permute the
locations of BED features. Therefore, each run should produce a different
result. This can be problematic if one wants to exactly recreate an experiment.
By using the \emph{seed} option, one can supply a custom integer seed for
\emph{bedtools random}. In turn, each execution of \emph{bedtools random} with the same
seed and input files should produce identical results.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools random -g hg19.genome -seed 71346
chrY  23380696        23380796        1       100     -
chr14 94368315        94368415        2       100     +
chr14 45353323        45353423        3       100     -
chr14 100546766       100546866       4       100     -
chr12 43294368        43294468        5       100     -
chr1  141470585       141470685       6       100     -
chr10 31273665        31273765        7       100     +
chr5  19102979        19103079        8       100     +
chr3  116730634       116730734       9       100     -
chr3  101222965       101223065       10      100     -

\PYG{c}{\PYGZsh{} (same seed, thus same as above)}
\PYG{n+nv}{\PYGZdl{} }bedtools random -g hg19.genome -seed 71346
chrY  23380696        23380796        1       100     -
chr14 94368315        94368415        2       100     +
chr14 45353323        45353423        3       100     -
chr14 100546766       100546866       4       100     -
chr12 43294368        43294468        5       100     -
chr1  141470585       141470685       6       100     -
chr10 31273665        31273765        7       100     +
chr5  19102979        19103079        8       100     +
chr3  116730634       116730734       9       100     -
chr3  101222965       101223065       10      100     -
\end{Verbatim}


\subsubsection{\emph{shuffle}}
\label{content/tools/shuffle:shuffle}\label{content/tools/shuffle::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{shuffle-glyph.png}

\emph{bedtools shuffle} will randomly permute the genomic locations of a feature
file among a genome defined in a genome file. One can also provide an
``exclusions'' BED/GFF/VCF file that lists regions where you do
not want the permuted features to be placed. For example, one might want to
prevent features from being placed in known genome gaps. \emph{shuffle} is useful
as a \emph{null} basis against which to test the significance of associations
of one feature with another.


\strong{See Also:}


{\hyperref[content/tools/random::doc]{\emph{random}}}
{\hyperref[content/tools/jaccard::doc]{\emph{jaccard}}}




\paragraph{Usage and option summary}
\label{content/tools/shuffle:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools shuffle [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{} -g \textless{}GENOME\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
shuffleBed [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{} -g \textless{}GENOME\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-excl}
 & 
A BED file of coordinates in which features from -i should \emph{not} be placed (e.g., genome gaps).
\\\hline

\textbf{-incl}
 & 
A BED file of coordinates in which features from -i \emph{should} be placed.
\\\hline

\textbf{-chrom}
 & 
Keep features in -i on the same chromosome. Solely permute their location on the chromosome. \emph{By default, both the chromosome and position are randomly chosen}.
\\\hline

\textbf{-seed}
 & 
Supply an integer seed for the shuffling. This will allow feature shuffling experiments to be recreated exactly as the seed for the pseudo-random number generation will be constant. \emph{By default, the seed is chosen automatically}.
\\\hline

\textbf{-f}
 & 
Maximum overlap (as a fraction of the \code{-i} feature) with an \code{-excl} feature that is tolerated before searching for a new, randomized locus.
\\\hline

\textbf{-chromFirst}
 & 
Instead of choosing a position randomly among the entire genome (the default), first choose a chrom randomly, and then choose a random start coordinate on that chrom.  This leads to features being \textasciitilde{}uniformly distributed among the chroms, as opposed to features being distribute as a function of chrom size.
\\\hline

\textbf{-bedpe}
 & 
Indicate that the A file is in BEDPE format.
\\\hline

\textbf{-maxTries}
 & 
Max. number of attempts to find a home for a shuffled interval in the presence of -incl or -excl. \emph{Default = 1000.}
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/shuffle:default-behavior}
By default, \emph{bedtools shuffle} will reposition each feature in the input BED
file on a random chromosome at a random position. The size and strand of each
feature are preserved.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  0  100  a1  1  +
chr1  0  1000 a2  2  -

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1  10000
chr2  8000
chr3  5000
chr4  2000

\PYG{n+nv}{\PYGZdl{} }bedtools shuffle -i A.bed -g my.genome
chr4  1498  1598  a1  1  +
chr3  2156  3156  a2  2  -
\end{Verbatim}


\paragraph{\texttt{-chrom} Requiring that features be shuffled on the same chromosome}
\label{content/tools/shuffle:chrom-requiring-that-features-be-shuffled-on-the-same-chromosome}
The \emph{-chrom} option behaves the same as the default behavior except that
features are randomly placed on the same chromosome as defined in the BED file.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  0  100  a1  1  +
chr1  0  1000 a2  2  -

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1  10000
chr2  8000
chr3  5000
chr4  2000

\PYG{n+nv}{\PYGZdl{} }bedtools shuffle -i A.bed -g my.genome -chrom
chr1  9560  9660  a1  1  +
chr1  7258  8258  a2  2  -
\end{Verbatim}


\paragraph{\texttt{-excl} Excluding certain genome regions from \texttt{bedtools shuffle}}
\label{content/tools/shuffle:excl-excluding-certain-genome-regions-from-bedtools-shuffle}
One may want to prevent BED features from being placed in certain regions of
the genome. For example, one may want to exclude genome gaps from permutation
experiment. The \emph{excl} option defines a BED file of regions that should be
excluded. \code{bedtools shuffle} will attempt to permute the locations of all features
while adhering to the exclusion rules. However it will stop looking for an
appropriate location if it cannot find a valid spot for a feature
after 1,000,000 tries.

For example (\emph{note that the exclude file excludes all but 100 base pairs of the chromosome}):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  0  100   a1  1  +
chr1  0  1000  a2  2  -

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1  10000

\PYG{n+nv}{\PYGZdl{} }cat exclude.bed
chr1  100  10000

\PYG{n+nv}{\PYGZdl{} }bedtools shuffle -i A.bed -g my.genome -excl exclude.bed
chr1  0  100  a1  1  +
Error, line 2: tried 1000000 potential loci \PYG{k}{for }entry, but could not avoid excluded
regions. Ignoring entry and moving on.
\end{Verbatim}

For example (\emph{now the exclusion file only excludes the first 100 bases of the chromosome}):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  0  100  a1  1  +
chr1  0  1000 a2  2  -

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1  10000

\PYG{n+nv}{\PYGZdl{} }cat exclude.bed
chr1  0  100

\PYG{n+nv}{\PYGZdl{} }bedtools shuffle -i A.bed -g my.genome -excl exclude.bed
chr1  147  247  a1  1  +
chr1  2441 3441 a2  2  -
\end{Verbatim}


\paragraph{\texttt{-seed} Defining a ``seed'' for the random replacement.}
\label{content/tools/shuffle:seed-defining-a-seed-for-the-random-replacement}
\emph{bedtools shuffle} uses a pseudo-random number generator to permute the
locations of BED features. Therefore, each run should produce a different
result. This can be problematic if one wants to exactly recreate an experiment.
By using the \emph{seed} option, one can supply a custom integer seed for
\emph{bedtools shuffle}. In turn, each execution of \emph{bedtools shuffle} with the same
seed and input files should produce identical results.

For example (\emph{note that the exclude file below excludes all but 100 base pairs
of the chromosome}):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1 0 100 a1 1 +
chr1 0 1000 a2 2 -

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1 10000

\PYG{n+nv}{\PYGZdl{} }bedtools shuffle -i A.bed -g my.genome -seed 927442958
chr1 6177 6277 a1 1 +
chr1 8119 9119 a2 2 -

\PYG{n+nv}{\PYGZdl{} }bedtools shuffle -i A.bed -g my.genome -seed 927442958
chr1 6177 6277 a1 1 +
chr1 8119 9119 a2 2 -

. . .

\PYG{n+nv}{\PYGZdl{} }bedtools shuffle -i A.bed -g my.genome -seed 927442958
chr1 6177 6277 a1 1 +
chr1 8119 9119 a2 2 -
\end{Verbatim}


\subsubsection{\emph{slop}}
\label{content/tools/slop:slop}\label{content/tools/slop::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{slop-glyph.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\code{bedtools slop} will increase the size of each feature in a feature file be a
user-defined number of bases. While something like this could be done with an
\code{awk '\{OFS="\textbackslash{}t" print \$1,\$2-\textless{}slop\textgreater{},\$3+\textless{}slop\textgreater{}\}'},
\code{bedtools slop} will restrict the resizing to the size of the chromosome
(i.e. no start \textless{} 0 and no end \textgreater{} chromosome size).

\begin{notice}{note}{Note:}
In order to prevent the extension of intervals beyond chromosome boundaries,
\code{bedtools slop} requires a \emph{genome} file defining the length of each
chromosome or contig.
\end{notice}


\paragraph{Usage and option summary}
\label{content/tools/slop:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools slop [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{} -g \textless{}GENOME\textgreater{} [-b or (-l and -r)]
\end{Verbatim}

\textbf{(or):}

\begin{Verbatim}[commandchars=\\\{\}]
bedtools slop [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{} -g \textless{}GENOME\textgreater{} [-b or (-l and -r)]
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-b}
 & 
Increase the BED/GFF/VCF entry by the same number base pairs in each direction. \emph{Integer}.
\\\hline

\textbf{-l}
 & 
The number of base pairs to subtract from the start coordinate. \emph{Integer}.
\\\hline

\textbf{-r}
 & 
The number of base pairs to add to the end coordinate. \emph{Integer}.
\\\hline

\textbf{-s}
 & 
Define -l and -r based on strand. For example. if used, -l 500 for a negative-stranded feature, it will add 500 bp to the \emph{end} coordinate.
\\\hline

\textbf{-pct}
 & 
Define -l and -r as a fraction of the feature's length. E.g. if used on a 1000bp feature, -l 0.50, will add 500 bp ``upstream''.  Default = false.
\\\hline

\textbf{-header}
 & 
Print the header from the input file prior to results.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/slop:default-behavior}
By default, \code{bedtools slop} will either add a fixed number of bases in each
direction (\code{-b}) or an asymmetric number of bases in each direction
with \code{-l} and \code{-r}.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1 5 100
chr1 800 980

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1 1000

\PYG{n+nv}{\PYGZdl{} }bedtools slop -i A.bed -g my.genome -b 5
chr1 0 105
chr1 795 985

\PYG{n+nv}{\PYGZdl{} }bedtools slop -i A.bed -g my.genome -l 2 -r 3
chr1 3 103
chr1 798 983
\end{Verbatim}

However, if the requested number of bases exceeds the boundaries of the
chromosome, \code{bedtools slop} will ``clip'' the feature accordingly.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  5   100
chr1  800 980

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1  1000

\PYG{n+nv}{\PYGZdl{} }bedtools slop -i A.bed -g my.genome -b 5000
chr1  0   1000
chr1  0   1000
\end{Verbatim}


\paragraph{\texttt{-s} Resizing features according to strand}
\label{content/tools/slop:s-resizing-features-according-to-strand}
\textbf{bedtools slop} will optionally increase the size of a feature based on strand.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1 100 200 a1 1 +
chr1 100 200 a2 2 -

\PYG{n+nv}{\PYGZdl{} }cat my.genome
chr1 1000

\PYG{n+nv}{\PYGZdl{} }bedtools slop  -i A.bed -g my.genome -l 50 -r 80 -s
chr1 50  280 a1 1 +
chr1 20  250 a2 2 -
\end{Verbatim}


\paragraph{\texttt{-pct} Resizing features by a given fraction}
\label{content/tools/slop:pct-resizing-features-by-a-given-fraction}
\textbf{bedtools slop} will optionally increase the size of a feature by a
user-specific fraction.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1 100 200 a1 1 +

\PYG{n+nv}{\PYGZdl{} }bedtools slop -i A.bed -g my.genome -b 0.5 -pct
chr1 50  250 a1 1 +

\PYG{n+nv}{\PYGZdl{} }bedtools slop -i a.bed -l 0.5 -r 0.0 -pct -g my.genome
chr1  50      200     a1      1       +
\end{Verbatim}


\paragraph{\texttt{-header} Print the header for the A file before reporting results.}
\label{content/tools/slop:header-print-the-header-for-the-a-file-before-reporting-results}
By default, if your A file has a header, it is ignored when reporting results.
This option will instead tell bedtools to first print the header for the
A file prior to reporting results.


\subsubsection{\emph{sort}}
\label{content/tools/sort:sort}\label{content/tools/sort::doc}
\textbf{sortBed} sorts a feature file by chromosome and other criteria.


\paragraph{Usage and option summary}
\label{content/tools/sort:usage-and-option-summary}
Usage:

\begin{Verbatim}[commandchars=\\\{\}]
sortBed [OPTIONS] -i \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-sizeA}
 & 
Sort by feature size in ascending order.
\\\hline

\textbf{-sizeD}
 & 
Sort by feature size in descending order.
\\\hline

\textbf{-chrThenSizeA}
 & 
Sort by chromosome, then by feature size (asc).
\\\hline

\textbf{-chrThenSizeD}
 & 
Sort by chromosome, then by feature size (desc).
\\\hline

\textbf{-chrThenScoreA}
 & 
Sort by chromosome, then by score (asc).
\\\hline

\textbf{-chrThenScoreD}
 & 
Sort by chromosome, then by score (desc).
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/sort:default-behavior}
By default, \textbf{sortBed} sorts a BED file by chromosome and then by start position in ascending order.

For example:

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1 800 1000
chr1 80  180
chr1 1   10
chr1 750 10000

sortBed -i A.bed
chr1 1   10
chr1 80  180
chr1 750 10000
chr1 800 1000
\end{Verbatim}


\paragraph{Optional sorting behavior}
\label{content/tools/sort:optional-sorting-behavior}
\textbf{sortBed} will also sorts a BED file by chromosome and then by other criteria.

For example, to sort by chromosome and then by feature size (in descending order):

\begin{Verbatim}[commandchars=\\\{\}]
cat A.bed
chr1 800 1000
chr1 80  180
chr1 1   10
chr1 750 10000

sortBed -i A.bed -sizeD
chr1 750 10000
chr1 800 1000
chr1 80  180
chr1 1   10
\end{Verbatim}

\textbf{Disclaimer:} it should be noted that \textbf{sortBed} is merely a convenience utility, as the UNIX sort utility
will sort BED files more quickly while using less memory. For example, UNIX sort will sort a BED file
by chromosome then by start position in the following manner:

\begin{Verbatim}[commandchars=\\\{\}]
sort -k 1,1 -k2,2 -n a.bed
chr1 1   10
chr1 80  180
chr1 750 10000
chr1 800 1000
\end{Verbatim}


\subsubsection{\emph{subtract}}
\label{content/tools/subtract:subtract}\label{content/tools/subtract::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{subtract-glyph.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\code{bedtools subtract} searches for features in B that overlap A. If an
overlapping feature is found in B, the overlapping portion is removed from A
and the remaining portion of A is reported. If a feature in B overlaps all of a
feature in A, the A feature will not be reported.


\paragraph{Usage and option summary}
\label{content/tools/subtract:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools subtract [OPTIONS] -a \textless{}BED/GFF/VCF\textgreater{} -b \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
subtractBed [OPTIONS] -a \textless{}BED/GFF/VCF\textgreater{} -b \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-f}
 & 
Minimum overlap required as a fraction of A. Default is 1E-9 (i.e. 1bp).
\\\hline

\textbf{-s}
 & 
Force ``strandedness''. That is, only report hits in B that overlap A on the same strand. By default, overlaps are reported without respect to strand.
\\\hline

\textbf{-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.
\\\hline

\textbf{-A}
 & 
Remove entire feature if any overlap.  That is, by default, only subtract the portion of A that overlaps B. Here, if any overlap is found (or \code{-f} amount), the entire feature is removed.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/subtract:default-behavior}
By default, \code{bedtools subtracts} removes each overlapping interval in B
from A.  If a feature in B \emph{completely} overlaps a feature in A, the A feature
is removed.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10   20
chr1  100  200

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  0    30
chr1  180  300

\PYG{n+nv}{\PYGZdl{} }bedtools subtract -a A.bed -b B.bed
chr1  100  180
\end{Verbatim}


\paragraph{\texttt{-f} Requiring a minimal overlap fraction before subtracting}
\label{content/tools/subtract:f-requiring-a-minimal-overlap-fraction-before-subtracting}
This option behaves the same as the \code{-f} option for \code{bedtools intersect}.
In this case, \code{subtract} will only subtract an overlap with B if it covers at
least the fraction of A defined by \code{-f}. If an overlap is found,
but it does not meet the overlap fraction, the original A feature is
reported without subtraction.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  180  300

\PYG{n+nv}{\PYGZdl{} }bedtools subtract -a A.bed -b B.bed -f 0.10
chr1  100  180

\PYG{n+nv}{\PYGZdl{} }bedtools subtract -a A.bed -b B.bed -f 0.80
chr1  100  200
\end{Verbatim}


\paragraph{\texttt{-s} Enforcing same ``strandedness''}
\label{content/tools/subtract:s-enforcing-same-strandedness}
This option behaves the same as the \code{-s} option for \code{bedtools intersect}
while scanning for features in B that should be subtracted from A.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200    a1  1   +

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  80   120    b1  1   +
chr1  180  300    b2  1   -

\PYG{n+nv}{\PYGZdl{} }bedtools subtract -a A.bed -b B.bed -s
chr1  120  120    a1  1   +
\end{Verbatim}


\paragraph{\texttt{-S} Enforcing opposite ``strandedness''}
\label{content/tools/subtract:s-enforcing-opposite-strandedness}
This option behaves the same as the \code{-s} option for \code{bedtools intersect}
while scanning for features in B that should be subtracted from A.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200    a1  1   +

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  80   120    b1  1   +
chr1  180  300    b2  1   -

\PYG{n+nv}{\PYGZdl{} }bedtools subtract -a A.bed -b B.bed -S
chr1  100  180    a1  1   +
\end{Verbatim}


\paragraph{\texttt{-A} Remove features with any overlap}
\label{content/tools/subtract:a-remove-features-with-any-overlap}
Unlike the default behavior, the \code{-A} option will completely remove
a feature from A if it has even 1bp of overlap with a feature in B.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  180  300

\PYG{n+nv}{\PYGZdl{} }bedtools subtract -a A.bed -b B.bed
chr1  100  180

\PYG{n+nv}{\PYGZdl{} }bedtools subtract -a A.bed -b B.bed -A
\end{Verbatim}


\subsubsection{\emph{tag}}
\label{content/tools/tag:tag}\label{content/tools/tag::doc}

\subsubsection{\emph{unionbedg}}
\label{content/tools/unionbedg:unionbedg}\label{content/tools/unionbedg::doc}
\textbf{unionBedGraphs} combines multiple BEDGRAPH files into a single file such that one can directly
compare coverage (and other text-values such as genotypes) across multiple sample


\paragraph{Usage and option summary}
\label{content/tools/unionbedg:usage-and-option-summary}
Usage:

\begin{Verbatim}[commandchars=\\\{\}]
unionBedGraphs [OPTIONS] -i FILE1 FILE2 FILE3 ... FILEn
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-header}
 & 
Print a header line, consisting of chrom, start, end followed by the names of each input BEDGRAPH file.
\\\hline

\textbf{-names}
 & 
A list of names (one per file) to describe each file in -i. These names will be printed in the header line.
\\\hline

\textbf{-empty}
 & 
Report empty regions (i.e., start/end intervals w/o values in all files). \emph{Requires the `-g FILE' parameter (see below)}.
\\\hline

\textbf{-g}
 & 
The genome file to be used to calculate empty regions.
\\\hline

\textbf{-filler TEXT}
 & 
Use TEXT when representing intervals having no value. Default is `0', but you can use `N/A' or any other text.
\\\hline

\textbf{-examples}
 & 
Show detailed usage examples.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/unionbedg:default-behavior}
Figure:

\begin{Verbatim}[commandchars=\\\{\}]
cat 1.bg
chr1 1000 1500 10
chr1 2000 2100 20

cat 2.bg
chr1 900 1600 60
chr1 1700 2050 50

cat 3.bg
chr1 1980 2070 80
chr1 2090 2100 20

cat sizes.txt
chr1 5000

unionBedGraphs -i 1.bg 2.bg 3.bg
chr1 900  1000 0  60 0
chr1 1000 1500 10 60 0
chr1 1500 1600 0  60 0
chr1 1700 1980 0  50 0
chr1 1980 2000 0  50 80
chr1 2000 2050 20 50 80
chr1 2050 2070 20 0  80
chr1 2070 2090 20 0  0
chr1 2090 2100 20 0  20
\end{Verbatim}


\paragraph{\texttt{-header} Add a header line to the output}
\label{content/tools/unionbedg:header-add-a-header-line-to-the-output}
Figure:

\begin{Verbatim}[commandchars=\\\{\}]
unionBedGraphs -i 1.bg 2.bg 3.bg -header
chrom  start  end  1  2  3
chr1   900    1000 0  60 0
chr1   1000   1500 10 60 0
chr1   1500   1600 0  60 0
chr1   1700   1980 0  50 0
chr1   1980   2000 0  50 80
chr1   2000   2050 20 50 80
chr1   2050   2070 20 0  80
chr1   2070   2090 20 0  0
chr1   2090   2100 20 0  20
\end{Verbatim}


\paragraph{\texttt{-names} Add a header line with custom file names to the output}
\label{content/tools/unionbedg:names-add-a-header-line-with-custom-file-names-to-the-output}
Figure:

\begin{Verbatim}[commandchars=\\\{\}]
unionBedGraphs -i 1.bg 2.bg 3.bg -header -names WT-1 WT-2 KO-1
chrom  start  end   WT-1  WT-2  KO-1
chr1   900    1000  0     60    0
chr1   1000   1500  10    60    0
chr1   1500   1600  0     60    0
chr1   1700   1980  0     50    0
chr1   1980   2000  0     50    80
chr1   2000   2050  20    50    80
chr1   2050   2070  20    0     80
chr1   2070   2090  20    0     0
chr1   2090   2100  20    0     20
\end{Verbatim}


\paragraph{\texttt{-empty} Include regions that have zero coverage in all BEDGRAPH files.}
\label{content/tools/unionbedg:empty-include-regions-that-have-zero-coverage-in-all-bedgraph-files}
Figure:

\begin{Verbatim}[commandchars=\\\{\}]
unionBedGraphs -i 1.bg 2.bg 3.bg -empty -g sizes.txt -header
chrom  start  end  WT-1  WT-2  KO-1
chrom  start  end  1     2     3
chr1   0      900  0     0     0
chr1   900    1000 0     60    0
chr1   1000   1500 10    60    0
chr1   1500   1600 0     60    0
chr1   1600   1700 0     0     0
chr1   1700   1980 0     50    0
chr1   1980   2000 0     50    80
chr1   2000   2050 20    50    80
chr1   2050   2070 20    0     80
chr1   2070   2090 20    0     0
chr1   2090   2100 20    0     20
chr1   2100   5000 0     0     0
\end{Verbatim}


\paragraph{\texttt{-filler} Use a custom value for missing values.}
\label{content/tools/unionbedg:filler-use-a-custom-value-for-missing-values}
Figure:

\begin{Verbatim}[commandchars=\\\{\}]
unionBedGraphs -i 1.bg 2.bg 3.bg -empty -g sizes.txt -header -filler N/A
chrom start end  WT-1  WT-2  KO-1
chrom start end  1     2     3
chr1  0     900  N/A   N/A   N/A
chr1  900   1000 N/A   60    N/A
chr1  1000  1500 10    60    N/A
chr1  1500  1600 N/A   60    N/A
chr1  1600  1700 N/A   N/A   N/A
chr1  1700  1980 N/A   50    N/A
chr1  1980  2000 N/A   50    80
chr1  2000  2050 20    50    80
chr1  2050  2070 20    N/A   80
chr1  2070  2090 20    N/A   N/A
chr1  2090  2100 20    N/A   20
chr1  2100  5000 N/A   N/A   N/A
\end{Verbatim}


\paragraph{Use BEDGRAPH files with non-numeric values.}
\label{content/tools/unionbedg:use-bedgraph-files-with-non-numeric-values}
Figure:

\begin{Verbatim}[commandchars=\\\{\}]
cat 1.snp.bg
chr1 0 1 A/G
chr1 5 6 C/T

cat 2.snp.bg
chr1 0 1 C/C
chr1 7 8 T/T

cat 3.snp.bg
chr1 0 1 A/G
chr1 5 6 C/T

unionBedGraphs -i 1.snp.bg 2.snp.bg 3.snp.bg -filler -/-
chr1 0 1 A/G C/C A/G
chr1 5 6 C/T -/- C/T
chr1 7 8 -/- T/T -/-
\end{Verbatim}


\subsubsection{\emph{window}}
\label{content/tools/window:window}\label{content/tools/window::doc}
\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

\includegraphics[width=600pt]{window-glyph.png}

\begin{DUlineblock}{0em}
\item[] 
\end{DUlineblock}

Similar to \code{bedtools intersect}, \code{window} searches for overlapping features
in A and B. However, \code{window} adds a specified number (1000, by default) of
base pairs upstream and downstream of each feature in A. In effect, this allows
features in B that are ``near'' features in A to be detected.


\paragraph{Usage and option summary}
\label{content/tools/window:usage-and-option-summary}
\textbf{Usage}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools window [OPTIONS] [-a\textbar{}-abam] -b \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\textbf{(or)}:

\begin{Verbatim}[commandchars=\\\{\}]
bedtools window [OPTIONS] [-a\textbar{}-abam] -b \textless{}BED/GFF/VCF\textgreater{}
\end{Verbatim}

\begin{tabulary}{\linewidth}{|L|L|}
\hline
\textbf{
Option
} & \textbf{
Description
}\\\hline

\textbf{-abam}
 & 
BAM file A. Each BAM alignment in A is compared to B in search of overlaps. Use ``stdin'' if passing A with a UNIX pipe: For example:  samtools view -b \textless{}BAM\textgreater{} \textbar{} bedtools window -abam stdin -b genes.bed
\\\hline

\textbf{-ubam}
 & 
Write uncompressed BAM output. The default is write compressed BAM output.
\\\hline

\textbf{-bed}
 & 
When using BAM input (-abam), write output as BED. The default is to write output in BAM when using -abam. For example:  bedtools window -abam reads.bam -b genes.bed -bed
\\\hline

\textbf{-w}
 & 
Base pairs added upstream and downstream of each entry in A when searching for overlaps in B. \emph{Default is 1000 bp}.
\\\hline

\textbf{-l}
 & 
Base pairs added upstream (left of) of each entry in A when searching for overlaps in B. \emph{Allows one to create assymetrical ``windows''. Default is 1000bp}.
\\\hline

\textbf{-r}
 & 
Base pairs added downstream (right of) of each entry in A when searching for overlaps in B. \emph{Allows one to create assymetrical ``windows''. Default is 1000bp}.
\\\hline

\textbf{-sw}
 & 
Define -l and -r based on strand. For example if used, -l 500 for a negative-stranded feature will add 500 bp downstream. \emph{By default, this is disabled}.
\\\hline

\textbf{-sm}
 & 
Only report hits in B that overlap A on the same strand. \emph{By default, overlaps are reported without respect to strand}.
\\\hline

\textbf{-Sm}
 & 
Only report hits in B that overlap A on the same strand. \emph{By default, overlaps are reported without respect to strand}.
\\\hline

\textbf{-u}
 & 
Write original A entry once if any overlaps found in B. In other words, just report the fact at least one overlap was found in B.
\\\hline

\textbf{-c}
 & 
For each entry in A, report the number of hits in B while restricting to -f. Reports 0 for A entries that have no overlap with B.
\\\hline

\textbf{-v}
 & 
Only report those entries in A that have \emph{no overlaps} with B.
\\\hline

\textbf{-header}
 & 
Print the header from the A file prior to results.
\\\hline
\end{tabulary}



\paragraph{Default behavior}
\label{content/tools/window:default-behavior}
By default, \code{bedtools window} adds 1000 bp upstream and downstream of each A
feature and searches for features in B that overlap this ``window''. If an overlap
is found in B, both the \emph{original} A feature and the \emph{original} B feature are
reported.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  500  1000
chr1  1300 2000

\PYG{n+nv}{\PYGZdl{} }bedtools window -a A.bed -b B.bed
chr1  100  200  chr1  500  1000
\end{Verbatim}


\paragraph{\texttt{-w} Defining a custom window size}
\label{content/tools/window:w-defining-a-custom-window-size}
Instead of using the default window size of 1000bp, one can define a custom,
\emph{symmetric} window around each feature in A using the \textbf{-w} option. One should
specify the window size in base pairs. For example, a window of 5kb should be
defined as \code{-w 5000}.

For example (note that in contrast to the default behavior,
the second B entry is reported):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  100  200

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  500  1000
chr1  1300 2000

\PYG{n+nv}{\PYGZdl{} }bedtools window -a A.bed -b B.bed -w 5000
chr1  100  200  chr1  500   1000
chr1  100  200  chr1  1300  2000
\end{Verbatim}


\paragraph{\texttt{-l and -r} Defining \emph{assymteric} windows}
\label{content/tools/window:l-and-r-defining-assymteric-windows}
One can also define asymmetric windows where a differing number of bases are
added upstream and downstream of each feature using the \code{-l} (upstream)
and \code{-r} (downstream)** options.

\begin{notice}{note}{Note:}
By default, the \code{-l} and \code{-r} options ignore.  If you want to define
\emph{upstream} and \emph{downstream} based on strand, use the \code{-sw} option (below)
with the \code{-l} and \code{-r} options.
\end{notice}

For example (note the difference between -l 200 and -l 300):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  1000  2000

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  500   800
chr1  10000 20000

\PYG{n+nv}{\PYGZdl{} }bedtools window -a A.bed -b B.bed -l 200 -r 20000
chr1  100   200  chr1  10000  20000

\PYG{n+nv}{\PYGZdl{} }bedtools window -a A.bed -b B.bed -l 300 -r 20000
chr1  100   200  chr1  500    800
chr1  100   200  chr1  10000  20000
\end{Verbatim}


\paragraph{\texttt{-sw} Defining assymteric windows based on strand}
\label{content/tools/window:sw-defining-assymteric-windows-based-on-strand}
Especially when dealing with gene annotations or RNA-seq experiments, you may
want to define asymmetric windows based on ``strand''. For example, you may want
to screen for overlaps that occur within 5000 bp upstream of a gene (e.g. a
promoter region) while screening only 1000 bp downstream of the gene.
By enabling the \code{-sw} (``stranded'' windows) option, the windows are added
upstream or downstream according to strand. For example, imagine one
specifies  \code{-l 5000}, \code{-r 1000} as well as the \code{-sw} option. In this case,
forward stranded (``+'') features will screen 5000 bp to the \emph{left} (that is,
\emph{lower} genomic coordinates) and 1000 bp to the \emph{right} (that is, \emph{higher}
genomic coordinates). By contrast, reverse stranded (``-'') features will screen
5000 bp to the \emph{right} (that is, \emph{higher} genomic coordinates) and 1000 bp to
the \emph{left} (that is, \emph{lower} genomic coordinates).

For example (note the difference between \code{-l 200} and \code{-l 300}):

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }cat A.bed
chr1  10000  20000  A.forward  1  +
chr1  10000  20000  A.reverse  1  -

\PYG{n+nv}{\PYGZdl{} }cat B.bed
chr1  1000   8000   B1
chr1  24000  32000  B2

\PYG{n+nv}{\PYGZdl{} }bedtools window -a A.bed -b B.bed -l 5000 -r 1000 -sw
chr1  10000  20000  A.forward  1  +  chr1  1000   8000   B1
chr1  10000  20000  A.reverse  1  -  chr1  24000  32000  B2
\end{Verbatim}


\paragraph{\texttt{-sm} Enforcing matches with the \emph{same} ``strandedness''}
\label{content/tools/window:sm-enforcing-matches-with-the-same-strandedness}
This option behaves the same as the \code{-s} option for \code{bedtools intersect}
while scanning for overlaps within the ``window'' surrounding A. That is, overlaps
in B will only be included if the B interval is on the \emph{same} strand as the A
interval.


\paragraph{\texttt{-Sm} Enforcing matches with the \emph{same} ``strandedness''}
\label{content/tools/window:id1}
This option behaves the same as the \code{-S} option for \code{bedtools intersect} while
scanning for overlaps within the ``window'' surrounding A. That is, overlaps in
B will only be included if the B interval is on the \emph{opposite} strand as the A
interval.


\paragraph{\texttt{-u} Reporting the presence/absence of at least one overlapping feature}
\label{content/tools/window:u-reporting-the-presence-absence-of-at-least-one-overlapping-feature}
This option behaves the same as for \code{bedtools intersect}.  That is, even if
multiple overlaps exist, each A interval will only be reported once.


\paragraph{\texttt{-c} Reporting the number of overlapping features}
\label{content/tools/window:c-reporting-the-number-of-overlapping-features}
This option behaves the same as for \code{bedtools intersect}.  That is, it will
report the \emph{count} of intervals in B that overlap each A interval.


\paragraph{\texttt{-v} Reporting the absence of any overlapping features}
\label{content/tools/window:v-reporting-the-absence-of-any-overlapping-features}
This option behaves the same as for \code{bedtools intersect}.  That is, it will
only report those intervals in A that have have \emph{zero} overlaps in B.


\paragraph{\texttt{-header} Print the header for the A file before reporting results.}
\label{content/tools/window:header-print-the-header-for-the-a-file-before-reporting-results}
By default, if your A file has a header, it is ignored when reporting results.
This option will instead tell bedtools to first print the header for the
A file prior to reporting results.


\section{Example usage}
\label{content/example-usage:example-usage}\label{content/example-usage::doc}
Below are several examples of basic bedtools usage. Example BED files are
provided in the /data directory of the bedtools distribution.


\subsection{bedtools intersect}
\label{content/example-usage:bedtools-intersect}
Report the base-pair overlap between sequence alignments and genes.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a reads.bed -b genes.bed
\end{Verbatim}

Report whether each alignment overlaps one or more genes. If not, the alignment is not reported.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a reads.bed -b genes.bed -u
\end{Verbatim}

Report those alignments that overlap NO genes. Like ``grep -v''

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a reads.bed -b genes.bed -v
\end{Verbatim}

Report the number of genes that each alignment overlaps.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a reads.bed -b genes.bed -c
\end{Verbatim}

Report the entire, original alignment entry for each overlap with a gene.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a reads.bed -b genes.bed -wa
\end{Verbatim}

Report the entire, original gene entry for each overlap with a gene.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a reads.bed -b genes.bed -wb
\end{Verbatim}

Report the entire, original alignment and gene entries for each overlap.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a reads.bed -b genes.bed -wa -wb
\end{Verbatim}

Only report an overlap with a repeat if it spans at least 50\% of the exon.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a exons.bed -b repeatMasker.bed -f 0.50
\end{Verbatim}

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.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a SV.bed -b segmentalDups.bed -f 0.50 -r
\end{Verbatim}

Read BED A from stdin. For example, find genes that overlap LINEs but not SINEs.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a genes.bed -b LINES.bed \textbar{} intersectBed -a stdin -b SINEs.bed -v
\end{Verbatim}

Retain only single-end BAM alignments that overlap exons.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -abam reads.bam -b exons.bed \PYGZgt{} reads.touchingExons.bam
\end{Verbatim}

Retain only single-end BAM alignments that do not overlap simple sequence
repeats.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -abam reads.bam -b SSRs.bed -v \PYGZgt{} reads.noSSRs.bam
\end{Verbatim}


\subsection{bedtools bamtobed}
\label{content/example-usage:bedtools-bamtobed}
Convert BAM alignments to BED format.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools bamtobed -i reads.bam \PYGZgt{} reads.bed
\end{Verbatim}

Convert BAM alignments to BED format using the BAM edit distance (NM) as the
BED ``score''.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools bamtobed -i reads.bam -ed \PYGZgt{} reads.bed
\end{Verbatim}

Convert BAM alignments to BEDPE format.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools bamtobed -i reads.bam -bedpe \PYGZgt{} reads.bedpe
\end{Verbatim}


\subsection{bedtools window}
\label{content/example-usage:bedtools-window}
Report all genes that are within 10000 bp upstream or downstream of CNVs.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools window -a CNVs.bed -b genes.bed -w 10000
\end{Verbatim}

Report all genes that are within 10000 bp upstream or 5000 bp downstream of
CNVs.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools window -a CNVs.bed -b genes.bed -l 10000 -r 5000
\end{Verbatim}

Report all SNPs that are within 5000 bp upstream or 1000 bp downstream of genes.
Define upstream and downstream based on strand.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools window -a genes.bed -b snps.bed -l 5000 -r 1000 -sw
\end{Verbatim}


\subsection{bedtools closest}
\label{content/example-usage:bedtools-closest}
Note: By default, if there is a tie for closest, all ties will be reported. \textbf{closestBed} allows overlapping
features to be the closest.

Find the closest ALU to each gene.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools closest -a genes.bed -b ALUs.bed
\end{Verbatim}

Find the closest ALU to each gene, choosing the first ALU in the file if there is a
tie.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools closest -a genes.bed -b ALUs.bed -t first
\end{Verbatim}

Find the closest ALU to each gene, choosing the last ALU in the file if there is a
tie.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools closest -a genes.bed -b ALUs.bed -t last
\end{Verbatim}


\subsection{bedtools subtract}
\label{content/example-usage:bedtools-subtract}
\begin{notice}{note}{Note:}
If a feature in A is entirely ``spanned'' by any feature in B, it will not be reported.
\end{notice}

Remove introns from gene features. Exons will (should) be reported.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools subtract -a genes.bed -b introns.bed
\end{Verbatim}


\subsection{bedtools merge}
\label{content/example-usage:bedtools-merge}
\begin{notice}{note}{Note:}
\code{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: \code{sort -k1,1 -k2,2n input.bed \textgreater{} input.sorted.bed}
\end{notice}

Merge overlapping repetitive elements into a single entry.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools merge -i repeatMasker.bed
\end{Verbatim}

Merge overlapping repetitive elements into a single entry, returning the number of
entries merged.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools merge -i repeatMasker.bed -n
\end{Verbatim}

Merge nearby (within 1000 bp) repetitive elements into a single entry.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools merge -i repeatMasker.bed -d 1000
\end{Verbatim}


\subsection{bedtools coverage}
\label{content/example-usage:bedtools-coverage}
Compute the coverage of aligned sequences on 10 kilobase ``windows'' spanning the
genome.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools coverage -a reads.bed -b windows10kb.bed \textbar{} 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
\end{Verbatim}

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.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools coverage -a reads.bed -b windows10kb.bed \textbar{} cut -f 1-4 \PYGZgt{} windows10kb.cov.bedg
\end{Verbatim}

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.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools coverage -a reads.bed -b windows10kb.bed \textbar{} \PYG{l+s+se}{\PYGZbs{}}
   awk \PYG{l+s+s1}{'\PYGZob{}OFS="\PYGZbs{}t"; print \PYGZdl{}1,\PYGZdl{}2,\PYGZdl{}3,\PYGZdl{}6\PYGZcb{}'} \PYG{l+s+se}{\PYGZbs{}}
   \PYGZgt{} windows10kb.pctcov.bedg
\end{Verbatim}


\subsection{bedtools complement}
\label{content/example-usage:bedtools-complement}
Report all intervals in the human genome that are not covered by repetitive
elements.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools complement -i repeatMasker.bed -g hg18.genome
\end{Verbatim}


\subsection{bedtools shuffle}
\label{content/example-usage:bedtools-shuffle}
Randomly place all discovered variants in the genome. However, prevent them
from being placed in know genome gaps.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools shuffle -i variants.bed -g hg18.genome -excl genome\PYGZus{}gaps.bed
\end{Verbatim}

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.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools shuffle -i variants.bed -g hg18.genome -excl genome\PYGZus{}gaps.bed -chrom
\end{Verbatim}


\section{Advanced usage}
\label{content/advanced-usage::doc}\label{content/advanced-usage:advanced-usage}

\subsection{Mask all regions in a genome except for targeted capture regions.}
\label{content/advanced-usage:mask-all-regions-in-a-genome-except-for-targeted-capture-regions}
Step 1. Add 500 bp up and downstream of each probe

\begin{Verbatim}[commandchars=\\\{\}]
bedtools slop -i probes.bed -b 500 \PYGZgt{} probes.500bp.bed
\end{Verbatim}

Step 2. Get a BED file of all regions not covered by the probes (+500 bp up/down)

\begin{Verbatim}[commandchars=\\\{\}]
bedtools complement -i probes.500bp.bed -g hg18.genome \PYGZgt{} probes.500bp.complement.bed
\end{Verbatim}

Step 3. Create a masked genome where all bases are masked except for the probes +500bp

\begin{Verbatim}[commandchars=\\\{\}]
bedtools maskfasta -in hg18.fa -bed probes.500bp.complement.bed -fo \PYG{l+s+se}{\PYGZbs{}}
\PYGZgt{} hg18.probecomplement.masked.fa
\end{Verbatim}


\subsection{Screening for novel SNPs.}
\label{content/advanced-usage:screening-for-novel-snps}
Find all SNPs that are not in dbSnp and not in the latest 1000 genomes calls

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a snp.calls.bed -b dbSnp.bed -v \textbar{} \PYG{l+s+se}{\PYGZbs{}}
bedtools intersect -a - -b 1KG.bed -v \textbar{} \PYG{l+s+se}{\PYGZbs{}}
\PYGZgt{} snp.calls.novel.bed
\end{Verbatim}


\subsection{Computing the coverage of features that align entirely within an interval.}
\label{content/advanced-usage:computing-the-coverage-of-features-that-align-entirely-within-an-interval}
By default, bedtools \code{coverage} counts any feature in A that overlaps B
by \textgreater{}= 1 bp. If you want to require that a feature align entirely within B for
it to be counted, you can first use intersectBed with the ``-f 1.0'' option.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools intersect -a features.bed -b windows.bed -f 1.0 \textbar{} \PYG{l+s+se}{\PYGZbs{}}
bedtools coverage -a - -b \PYG{l+s+se}{\PYGZbs{}}
\PYGZgt{} windows.bed.coverage
\end{Verbatim}


\subsection{Computing the coverage of BAM alignments on exons.}
\label{content/advanced-usage:computing-the-coverage-of-bam-alignments-on-exons}
One can combine \code{samtools} with \code{bedtools} to compute coverage directly
from the BAM data by using \code{bamtobed}.

\begin{Verbatim}[commandchars=\\\{\}]
bedtools bamtobed -i reads.bam \textbar{} \PYG{l+s+se}{\PYGZbs{}}
bedtools coverage -a - -b exons.bed \PYG{l+s+se}{\PYGZbs{}}
\PYGZgt{} exons.bed.coverage
\end{Verbatim}

Take it a step further and require that coverage be from properly-paired reads.

\begin{Verbatim}[commandchars=\\\{\}]
samtools view -uf 0x2 reads.bam \textbar{} \PYG{l+s+se}{\PYGZbs{}}
coverageBed -abam - -b exons.bed \PYG{l+s+se}{\PYGZbs{}}
\PYGZgt{} exons.bed.proper.coverage
\end{Verbatim}


\subsection{Computing coverage separately for each strand.}
\label{content/advanced-usage:computing-coverage-separately-for-each-strand}
Use grep to only look at forward strand features (i.e. those that end in ``+'').

\begin{Verbatim}[commandchars=\\\{\}]
bedtools bamtobed -i reads.bam \textbar{} \PYG{l+s+se}{\PYGZbs{}}
grep \PYG{l+s+se}{\PYGZbs{}+}\PYG{n+nv}{\PYGZdl{} } \textbar{} \PYG{l+s+se}{\PYGZbs{}}
bedtools coverage -a - -b genes.bed \PYG{l+s+se}{\PYGZbs{}}
\PYGZgt{} genes.bed.forward.coverage
\end{Verbatim}

Use grep to only look at reverse strand features (i.e. those that end in ``-'').

\begin{Verbatim}[commandchars=\\\{\}]
bedtools bamtobed -i reads.bam \textbar{} \PYG{l+s+se}{\PYGZbs{}}
grep \PYG{l+s+se}{\PYGZbs{}-}\PYG{n+nv}{\PYGZdl{} }\textbar{} \PYG{l+s+se}{\PYGZbs{}}
bedtools coverage -a - -b genes.bed \PYG{l+s+se}{\PYGZbs{}}
\PYGZgt{} genes.bed.reverse.coverage
\end{Verbatim}


\section{Tips and Tricks}
\label{content/tips-and-tricks:tips-and-tricks}\label{content/tips-and-tricks::doc}

\subsection{The \texttt{-sorted} option}
\label{content/tips-and-tricks:the-sorted-option}

\section{FAQ}
\label{content/faq:faq}\label{content/faq::doc}

\subsection{Installation issues}
\label{content/faq:installation-issues}

\subsubsection{Why am I getting all of these zlib errors?}
\label{content/faq:why-am-i-getting-all-of-these-zlib-errors}
On certain operating systems (especially free Linux distributions) the complete
zlib libraries are not installed.  Bedtools depends upon zlib in order to
decompress gzipped files.

\begin{Verbatim}[commandchars=\\\{\}]
- Building main bedtools binary.
obj/gzstream.o: In function gzstreambuf::open(char const*, int):
gzstream.C:(.text+0x2a5): undefined reference to gzopen64'
collect2: ld returned 1 exit status
make: *** [all] Error 1
\end{Verbatim}

If you see an error such as the above, it suggests you need to install the
\code{zlib} and \code{zlib1g-dev} libraries.  This is typically straightforward using
package managers.  For example, on Debian/Ubuntu this would be:

\begin{Verbatim}[commandchars=\\\{\}]
apt-get install zlib
apt-get install zlib1g-dev
\end{Verbatim}

and on Fedora/Centos this would be:

\begin{Verbatim}[commandchars=\\\{\}]
yum install zlib
yum install zlib1g-dev
\end{Verbatim}


\subsection{General questions}
\label{content/faq:general-questions}

\subsubsection{How do I know what version of bedtools I am using?}
\label{content/faq:how-do-i-know-what-version-of-bedtools-i-am-using}
Use the --version option.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools --version
bedtools v2.17.0
\end{Verbatim}


\subsubsection{How do I bring up the help/usage menu?}
\label{content/faq:how-do-i-bring-up-the-help-usage-menu}
To receive a high level list of available tools in bedtools, use \code{{}`-h}:

\begin{Verbatim}[commandchars=\\\{\}]
\$ bedtools -h
bedtools: flexible tools for genome arithmetic and DNA sequence analysis.
usage:    bedtools \textless{}subcommand\textgreater{} [options]

The bedtools sub-commands include:

[ Genome arithmetic ]
    intersect     Find overlapping intervals in various ways.
    window        Find overlapping intervals within a window around an interval.
    closest       Find the closest, potentially non-overlapping interval.
    coverage      Compute the coverage over defined intervals.
    map           Apply a function to a column for each overlapping interval.
    genomecov     Compute the coverage over an entire genome.
    merge         Combine overlapping/nearby intervals into a single interval.
    cluster       Cluster (but don't merge) overlapping/nearby intervals.
    complement    Extract intervals \_not\_ represented by an interval file.
...
\end{Verbatim}

To display the help for a specific tool (e.g., \code{bedtools shuffle}), use:

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{n+nv}{\PYGZdl{} }bedtools merge -h

Tool:    bedtools merge \PYG{o}{(}aka mergeBed\PYG{o}{)}
Version: v2.17.0
Summary: Merges overlapping BED/GFF/VCF entries into a single interval.

Usage:   bedtools merge \PYG{o}{[}OPTIONS\PYG{o}{]} -i \PYGZlt{}bed/gff/vcf\PYGZgt{}

Options:
    -s      Force strandedness.  That is, only merge features
            that are the same strand.
            - By default, merging is \PYG{k}{done }without respect to strand.

    -n      Report the number of BED entries that were merged.
            - Note: \PYG{l+s+s2}{"1"} is reported \PYG{k}{if }no merging occurred.
\end{Verbatim}


\section{Related software}
\label{content/related-tools:related-software}\label{content/related-tools::doc}
Bedtools has been used as an engine behind other genomics software and has been
integrated into widely used tools such as Galaxy and IGV.  Below is a likely
incomplete list.  If you know of others, please let us know, or better yet,
edit the document on GitHub and send us a pull request.  You can do this by
clicking on the ``Edit and improve this document'' link in the lower lefthand
corner.


\subsection{IGV}
\label{content/related-tools:igv}
Bedtools is now integrated into the IGV genome viewer as of IGV version 2.2.  We
are actively working withe IGV development team to improve and expand this
integration.  See
\href{http://www.broadinstitute.org/igv/IGV2.2.x}{here}
and
\href{https://www.broadinstitute.org/software/igv/bedtools}{here} for details.
\begin{quote}

\includegraphics{bedtoolsMenu.png}
\end{quote}


\subsection{Galaxy}
\label{content/related-tools:galaxy}
\href{https://main.g2.bx.psu.edu/}{Galaxy} has its own tools for working with
genomic intervals under the ``Operate on Genomic Intervals'' section.  A subset
of complementary Bedtools utilities have also been made available on Galaxy in
an effort to provide functionality that isn't available with the native Galaxy
tools.
\begin{quote}

\includegraphics{galaxy-bedtools.png}
\end{quote}


\subsection{Pybedtools}
\label{content/related-tools:pybedtools}
\href{http://pypi.python.org/pypi/pybedtools}{Pybedtools} is a really fantastic
Python library that wraps (and extends upon) the bedtools utilities and exposes
them for easy use and new tool development using Python.  Pybedtools is actively
maintained by Ryan Dale.


\subsection{MISO}
\label{content/related-tools:miso}
\href{http://genes.mit.edu/burgelab/miso/}{MISO} is ``a probabilistic framework
that quantitates the expression level of alternatively spliced genes from
RNA-Seq data, and identifies differentially regulated isoforms or exons across
samples.'' A subset of the functionality in MISO depends upon \code{bedtools}. MISO
is developed by Yarden Katz.


\subsection{RetroSeq}
\label{content/related-tools:retroseq}
\href{http://bioinformatics.oxfordjournals.org/content/early/2012/12/10/bioinformatics.bts697.abstract}{RetroSeq}
is ``a tool for discovery and genotyping of transposable element variants (TEVs)
(also known as mobile element insertions) from next-gen sequencing reads aligned
to a reference genome in BAM format''. RetroSeq is developed by Thomas Keane.
Source code can be obtained on \href{https://github.com/tk2/RetroSeq}{GitHub}.


\chapter{Brief example}
\label{index: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 \emph{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.

\begin{Verbatim}[commandchars=\\\{\}]
\PYG{c}{\PYGZsh{} intersect the peaks from both experiments.}
\PYG{c}{\PYGZsh{} -f 0.50 combined with -r requires 50\PYGZpc{} reciprocal overlap between the}
\PYG{c}{\PYGZsh{} peaks from each experiment.}
\PYG{n+nv}{\PYGZdl{} }bedtools intersect -a exp1.bed -b exp2.bed -f 0.50 -r \PYGZgt{} both.bed

\PYG{c}{\PYGZsh{} find the closest, non-overlapping gene for each interval where}
\PYG{c}{\PYGZsh{} both experiments had a peak}
\PYG{c}{\PYGZsh{} -io ignores overlapping intervals and returns only the closest,}
\PYG{c}{\PYGZsh{} non-overlapping interval (in this case, genes)}
\PYG{n+nv}{\PYGZdl{} }bedtools closest -a both.bed -b genes.bed -io \PYGZgt{} both.nearest.genes.txt
\end{Verbatim}


\chapter{License}
\label{index:license}
bedtools is freely available under a GNU Public License (Version 2).


\chapter{Acknowledgments}
\label{index:acknowledgments}
To do.


\chapter{Mailing list}
\label{index:mailing-list}
If you have questions, requests, or bugs to report, please email the
\href{https://groups.google.com/forum/?fromgroups\#!forum/bedtools-discuss}{bedtools mailing list}



\renewcommand{\indexname}{Index}
\printindex
\end{document}
