Bio::Tools::Run::BWA(3pm)

NAME

Bio::Tools::Run::BWA - Run wrapper for the BWA short-read assembler *BETA*

SYNOPSIS

 # create an assembly
 # run BWA commands separately

DESCRIPTION

This module provides a wrapper interface for Heng Li's reference-directed short read assembly suite "bwa" (see <http://bio-bwa.sourceforge.net/bwa.shtml> for manuals and downloads).

Manipulating the alignments requires "samtools" (<http://sourceforge.net/projects/samtools/>) and Lincoln Stein's package "Bio-SamTools" (<http://search.cpan.org/perldoc?Bio::DB::Sam>).

There are two modes of action.

•

Easy assembly

The first is a simple pipeline through the "maq" commands, taking your read data in and squirting out an assembly object of type Bio::Assembly::IO::maq. The pipeline is based on the one performed by "maq.pl easyrun":

 Action                  maq commands
 ------                  ------------
 data conversion to      fasta2bfa, fastq2bfq
 maq binary formats
 map sequence reads      map
 to reference seq
 assemble, creating      assemble
 consensus
 convert map & cns       mapview, cns2fq
 files to plaintext
 (for B:A:IO:maq)

Command-line options can be directed to the "map", "assemble", and "cns2fq" steps. See "OPTIONS" below.

•

BWA command mode

The second mode is direct access to "bwa" commands. To run a "bwa" command, construct a run factory, specifying the desired command using the "-command" argument in the factory constructor, along with options specific to that command (see "OPTIONS"):

 $bwafac = Bio::Tools::Run::BWA->new( -command => 'fasta2bfa' );

To execute, use the "run_bwa" methods. Input and output files are specified in the arguments of "run_bwa" (see "FILES"):

 $bwafac->run_bwa( -fas => "myref.fas", -bfa => "myref.bfa" );

OPTIONS

"bwa" is complex, with many subprograms (commands) and command-line options and file specs for each. This module attempts to provide commands and options comprehensively. You can browse the choices like so:

 $bwafac = Bio::Tools::Run::BWA->new( -command => 'aln' );
 # all maq commands
 @all_commands = $bwafac->available_parameters('commands'); 
 @all_commands = $bwafac->available_commands; # alias
 # just for aln
 @aln_params = $bwafac->available_parameters('params');
 @aln_switches = $bwafac->available_parameters('switches');
 @aln_all_options = $bwafac->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.

See <http://bio-bwa.sourceforge.net/bwa.shtml> for the gory details.

FILES

When a command requires filenames, these are provided to the "run_bwa" method, not the constructor ("new()"). To see the set of files required by a command, use "available_parameters('filespec')" or the alias "filespec()":

  $bwafac = Bio::Tools::Run::BWA->new( -command => 'aln' );
  @filespec = $bwafac->filespec;

This example returns the following array:

 fas
 faq 
 >sai

This indicates that the FASTA database (faq) and the FASTQ reads (faq) MUST be specified, and the STDOUT of this program (SA coordinates) MAY be slurped into a file specified in the "run_bwa" argument list:

 $bwafac->run_bwa( -fas => 'my.db.fas', -faq => 'reads.faq',
                   -sai => 'out.sai' );

If files are not specified per the filespec, text sent to STDOUT and STDERR is saved and is accessible with "$bwafac-"stdout()> and "$bwafac-"stderr()>.

FEEDBACK

  [email protected]                  - General discussion
http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

  http://redmine.open-bio.org/projects/bioperl/

AUTHOR - Mark A. Jensen

 Email maj -at- fortinbras -dot- us

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

 Title   : new
 Usage   : my $obj = new Bio::Tools::Run::BWA();
 Function: Builds a new Bio::Tools::Run::BWA object
 Returns : an instance of Bio::Tools::Run::BWA
 Args    :

 Title   : run
 Usage   : $assembly = $bwafac->run( @args );
 Function: Run the bwa assembly pipeline. 
 Returns : Assembly results (file, IO object or Assembly object)
 Args    : - fastq file containing single-end reads
           - fasta file containing the reference sequence
           - [optional] fastq file containing paired-end reads

 Title   : run_bwa
 Usage   : $obj->run_bwa( @file_args )
 Function: Run a bwa command as specified during object contruction
 Returns : 
 Args    : a specification of the files to operate on:

 Title   : stdout
 Usage   : $fac->stdout()
 Function: store the output from STDOUT for the run, 
           if no file specified in run_maq()
 Example : 
 Returns : scalar string
 Args    : on set, new value (a scalar or undef, optional)

 Title   : stderr
 Usage   : $fac->stderr()
 Function: store the output from STDERR for the run, 
           if no file is specified in run_maq()
 Example : 
 Returns : scalar string
 Args    : on set, new value (a scalar or undef, optional)

Bio::Tools::Run::AssemblerBase overrides

 No-op.

 No-op.

 Convert input fastq and fasta to maq format.

 Title   : _collate_subcmd_args
 Usage   : $args_hash = $self->_collate_subcmd_args
 Function: collate parameters and switches into command-specific
           arg lists for passing to new()
 Returns : hash of named argument lists
 Args    : [optional] composite cmd prefix (scalar string) 
           [default is 'run']

 Title   :   _run
 Usage   :   $factory->_run()
 Function:   Run a bwa assembly pipeline
 Returns :   a text-formatted sam alignment
 Args    :   - single end read file in maq bfq format
             - reference seq file in maq bfa format
             - [optional] paired end read file in maq bfq format

 Title   : available_parameters
 Usage   : @cmds = $fac->available_commands('commands');
 Function: Use to browse available commands, params, or switches
 Returns : array of scalar strings
 Args    : 'commands' : all bwa commands
           'params'   : parameters for this object's command
           'switches' : boolean switches for this object's command
           'filespec' : the filename spec for this object's command
 4Geeks  : Overrides Bio::ParameterBaseI via 
           Bio::Tools::Run::AssemblerBase