NAME¶
Bio::Tools::Run::BEDTools - Run wrapper for the BEDTools suite of programs
*BETA*
SYNOPSIS¶
# use a BEDTools program
$bedtools_fac = Bio::Tools::Run::BEDTools->new( -command => 'subtract' );
$result_file = $bedtools_fac->run( -bed1 => 'genes.bed', -bed2 => 'mask.bed' );
# if IO::Uncompress::Gunzip is available...
$result_file = $bedtools_fac->run( -bed1 => 'genes.bed.gz', -bed2 => 'mask.bed.gz' );
# be more strict
$bedtools_fac->set_parameters( -strandedness => 1 );
# and even more...
$bedtools_fac->set_parameters( -minimum_overlap => 1e-6 );
# create a Bio::SeqFeature::Collection object
$features = $bedtools_fac->result( -want => 'Bio::SeqFeature::Collection' );
DEPRECATION WARNING¶
Most executables from BEDTools v>=2.10.1 can read GFF and VCF formats in
addition to BED format. This requires the use of a new input file param, shown
in the following documentation, '-bgv', in place of '-bed' for the executables
that can do this.
This behaviour breaks existing scripts.
DESCRIPTION¶
This module provides a wrapper interface for Aaron R. Quinlan and Ira M. Hall's
utilities "BEDTools" that allow for (among other things):
- •
- Intersecting two BED files in search of overlapping
features.
- •
- Merging overlapping features.
- •
- Screening for paired-end (PE) overlaps between PE sequences
and existing genomic features.
- •
- Calculating the depth and breadth of sequence coverage
across defined "windows" in a genome.
(see <
http://code.google.com/p/bedtools/> for manuals and downloads).
OPTIONS¶
"BEDTools" is a suite of 17 commandline executable. This module
attempts to provide and options comprehensively. You can browse the choices
like so:
$bedtools_fac = Bio::Tools::Run::BEDTools->new;
# all bowtie commands
@all_commands = $bedtools_fac->available_parameters('commands');
@all_commands = $bedtools_fac->available_commands; # alias
# just for default command ('bam_to_bed')
@btb_params = $bedtools_fac->available_parameters('params');
@btb_switches = $bedtools_fac->available_parameters('switches');
@btb_all_options = $bedtools_fac->available_parameters();
Reasonably mnemonic names have been assigned to the single-letter command line
options. These are the names returned by "available_parameters", and
can be used in the factory constructor like typical BioPerl named parameters.
As a number of options are mutually exclusive, and the interpretation of intent
is based on last-pass option reaching bowtie with potentially unpredicted
results. This module will prevent inconsistent switches and parameters from
being passed.
See <
http://code.google.com/p/bedtools/> for details of BEDTools options.
FILES¶
When a command requires filenames, these are provided to the "run"
method, not the constructor ("new()"). To see the set of files
required by a command, use "available_parameters('filespec')" or the
alias "filespec()":
$bedtools_fac = Bio::Tools::Run::BEDTools->new( -command => 'pair_to_bed' );
@filespec = $bedtools_fac->filespec;
This example returns the following array:
#bedpe
#bam
bed
#out
This indicates that the bed ("BEDTools" BED format) file MUST be
specified, and that the out, bedpe ("BEDTools" BEDPE format) and bam
("SAM" binary format) file MAY be specified (Note that in this case
you MUST provide ONE of bedpe OR bam, the module at this stage does not allow
this information to be queried). Use these in the "run" call like
so:
$bedtools_fac->run( -bedpe => 'paired.bedpe',
-bgv => 'genes.bed',
-out => 'overlap' );
The object will store the programs STDERR output for you in the
"stderr()" attribute:
handle_bed_warning($bedtools_fac) if ($bedtools_fac->stderr =~ /Usage:/);
For the commands 'fasta_from_bed' and 'mask_fasta_from_bed' STDOUT will also be
captured in the "stdout()" attribute by default and all other
commands can be forced to capture program output in STDOUT by setting the -out
filespec parameter to '-'.
FEEDBACK¶
Mailing Lists¶
User feedback is an integral part of the evolution of this and other Bioperl
modules. Send your comments and suggestions preferably to the Bioperl mailing
list. Your participation is much appreciated.
bioperl-l@bioperl.org - General discussion
http://bioperl.org/wiki/Mailing_lists - About the mailing lists
Support¶
Please direct usage questions or support issues to the mailing list:
bioperl-l@bioperl.org
Rather than to the module maintainer directly. Many experienced and reponsive
experts will be able look at the problem and quickly address it. Please
include a thorough description of the problem with code and data examples if
at all possible.
Reporting Bugs¶
Report bugs to the Bioperl bug tracking system to help us keep track of the bugs
and their resolution. Bug reports can be submitted via the web:
http://redmine.open-bio.org/projects/bioperl/
AUTHOR - Dan Kortschak¶
Email dan.kortschak adelaide.edu.au
CONTRIBUTORS¶
Additional contributors names and emails here
APPENDIX¶
The rest of the documentation details each of the object methods. Internal
methods are usually preceded with a _
new()¶
Title : new
Usage : my $obj = new Bio::Tools::Run::BEDTools();
Function: Builds a new Bio::Tools::Run::BEDTools object
Returns : an instance of Bio::Tools::Run::BEDTools
Args :
run()¶
Title : run
Usage : $result = $bedtools_fac->run(%params);
Function: Run a BEDTools command.
Returns : Command results (file, IO object or Bio object)
Args : Dependent on filespec for command.
See $bedtools_fac->filespec and BEDTools Manual.
Also accepts -want => '(raw|format|<object_class>)' - see want().
Note : gzipped inputs are allowed if IO::Uncompress::Gunzip
is available
Command <in> <out>
annotate bgv ann(s) #out
graph_union bg_files #out
fasta_from_bed seq bgv #out
mask_fasta_from_bed seq bgv #out
bam_to_bed bam #out
bed_to_IGV bgv #out
merge bgv #out
sort bgv #out
links bgv #out
b12_to_b6 bed #out
overlap bed #out
group_by bed #out
bed_to_bam bgv #out
shuffle bgv genome #out
slop bgv genome #out
complement bgv genome #out
genome_coverage bed genome #out
window bgv1 bgv2 #out
closest bgv1 bgv2 #out
coverage bgv1 bgv2 #out
subtract bgv1 bgv2 #out
pair_to_pair bedpe1 bedpe2 #out
intersect bgv1|bam bgv2 #out
pair_to_bed bedpe|bam bgv #out
bgv* signifies any of BED, GFF or VCF. ann is a bgv.
NOTE: Replace 'bgv' with 'bed' unless $use_bgv is set.
want()¶
Title : want
Usage : $bowtiefac->want( $class )
Function: make factory return $class, or 'raw' results in file
or 'format' for result format
All commands can return Bio::Root::IO
commands returning: can return object:
- BED or BEDPE - Bio::SeqFeature::Collection
- sequence - Bio::SeqIO
Returns : return wanted type
Args : [optional] string indicating class or raw of wanted result
result()¶
Title : result
Usage : $bedtoolsfac->result( [-want => $type|$format] )
Function: return result in wanted format
Returns : results
Args : [optional] hashref of wanted type
Note : -want arg does not persist between result() call when
specified in result(), for persistence, use want()
Title : _determine_format( $has_run )
Usage : $bedtools-fac->_determine_format
Function: determine the format of output for current options
Returns : format of bowtie output
Args : [optional] boolean to indicate result exists
_read_bed()¶
Title : _read_bed()
Usage : $bedtools_fac->_read_bed
Function: return a Bio::SeqFeature::Collection object from a BED file
Returns : Bio::SeqFeature::Collection
Args :
_read_bedpe()¶
Title : _read_bedpe()
Usage : $bedtools_fac->_read_bedpe
Function: return a Bio::SeqFeature::Collection object from a BEDPE file
Returns : Bio::SeqFeature::Collection
Args :
Title : _validate_file_input
Usage : $bedtools_fac->_validate_file_input( -type => $file )
Function: validate file type for file spec
Returns : file type if valid type for file spec
Args : hash of filespec => file_name
version()¶
Title : version
Usage : $version = $bedtools_fac->version()
Function: Returns the program version (if available)
Returns : string representing location and version of the program