Provided by: libbio-perl-run-perl_1.6.9-2_all bug

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()

   _determine_format()
        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    :

   _validate_file_input()
        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