lib/Bio/Tools/Run/Samtools.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tools::Run::Samtools
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Mark A. Jensen <maj -at- fortinbras -dot- us>
   8 #
   9 # Copyright Mark A. Jensen
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::Tools::Run::Samtools - a run wrapper for the samtools suite *BETA*
  18
  19 =head1 SYNOPSIS
  20
  21  # convert a sam to a bam
  22  $samt = Bio::Tools::Run::Samtools( -command => 'view',
  23                                     -sam_input => 1,
  24                                     -bam_output => 1 );
  25  $samt->run( -bam => "mysam.sam", -out => "mysam.bam" );
  26  # sort it
  27  $samt = Bio::Tools::Run::Samtools( -command => 'sort' );
  28  $samt->run( -bam => "mysam.bam", -pfx => "mysam.srt" );
  29  # now create an assembly
  30  $assy = Bio::IO::Assembly->new( -file => "mysam.srt.bam",
  31                                  -refdb => "myref.fas" );
  32
  33 =head1 DESCRIPTION
  34
  35 This is a wrapper for running samtools, a suite of large-alignment
  36 reading and manipulation programs available at
  37 L<http://samtools.sourceforge.net/>.
  38
  39 =head1 RUNNING COMMANDS
  40
  41 To run a C<samtools>
  42 command, construct a run factory, specifying the desired command using
  43 the C<-command> argument in the factory constructor, along with
  44 options specific to that command (see L</OPTIONS>):
  45
  46  $samt = Bio::Tools::Run::Samtools->new( -command => 'view',
  47                                          -sam_input => 1,
  48                                          -bam_output => 1);
  49
  50 To execute, use the C<run()> method. Input and output files are
  51 specified in the arguments of C<run()> (see L</FILES>):
  52
  53  $samt->run( -bam => "mysam.sam", -out => "mysam.bam" );
  54
  55 =head1 OPTIONS
  56
  57 C<samtools> is complex, with many subprograms (commands) and command-line
  58 options and file specs for each. This module attempts to provide
  59 commands and options comprehensively. You can browse the choices like so:
  60
  61  $samt = Bio::Tools::Run::Samtools->new( -command => 'pileup' );
  62  # all samtools commands
  63  @all_commands = $samt->available_parameters('commands');
  64  @all_commands = $samt->available_commands; # alias
  65  # just for pileup
  66  @pup_params = $samt->available_parameters('params');
  67  @pup_switches = $samt->available_parameters('switches');
  68  @pup_all_options = $samt->available_parameters();
  69
  70 Reasonably mnemonic names have been assigned to the single-letter
  71 command line options. These are the names returned by
  72 C<available_parameters>, and can be used in the factory constructor
  73 like typical BioPerl named parameters.
  74
  75 See L<http://samtools.sourceforge.net/samtools.shtml> for the gory details.
  76
  77 =head1 FILES
  78
  79 When a command requires filenames, these are provided to the
  80 C<run()> method, not the constructor (C<new()>). To see the set of
  81 files required by a command, use C<available_parameters('filespec')>
  82 or the alias C<filespec()>:
  83
  84   $samt = Bio::Tools::Run::Samtools->new( -command => 'view' );
  85   @filespec = $samt->filespec;
  86
  87 This example returns the following array:
  88
  89  bam
  90  >out
  91
  92 This indicates that the bam/sam file (bam) and the output file (out)
  93 MUST be specified in the C<run()> argument list:
  94
  95  $samt->run( -bam => 'mysam.sam', -out => 'mysam.cvt' );
  96
  97 If files are not specified per the filespec, text sent to STDOUT and
  98 STDERR is saved and is accessible with C<$bwafac->stdout()> and
  99 C<$bwafac->stderr()>.
 100
 101 =head1 FEEDBACK
 102
 103 =head2 Mailing Lists
 104
 105 User feedback is an integral part of the evolution of this and other
 106 Bioperl modules. Send your comments and suggestions preferably to
 107 the Bioperl mailing list.  Your participation is much appreciated.
 108
 109   bioperl-l@bioperl.org                  - General discussion
 110 http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
 111
 112 =head2 Support
 113
 114 Please direct usage questions or support issues to the mailing list:
 115
 116 L<bioperl-l@bioperl.org>
 117
 118 rather than to the module maintainer directly. Many experienced and
 119 reponsive experts will be able look at the problem and quickly
 120 address it. Please include a thorough description of the problem
 121 with code and data examples if at all possible.
 122
 123 =head2 Reporting Bugs
 124
 125 Report bugs to the Bioperl bug tracking system to help us keep track
 126 of the bugs and their resolution. Bug reports can be submitted via
 127 the web:
 128
 129   http://redmine.open-bio.org/projects/bioperl/
 130
 131 =head1 AUTHOR - Mark A. Jensen
 132
 133 Email maj -at- fortinbras -dot- us
 134
 135 =head1 APPENDIX
 136
 137 The rest of the documentation details each of the object methods.
 138 Internal methods are usually preceded with a _
 139
 140 =cut
 141
 142 # Let the code begin...
 143 package Bio::Tools::Run::Samtools;
 144 use strict;
 145 use warnings;
 146 use Bio::Root::Root;
 147 use Bio::Tools::Run::Samtools::Config;
 148
 149 # currently an AssemblerBase object, but the methods we need from
 150 # there should really go in an updated WrapperBase.../maj
 151
 152 use base qw(Bio::Tools::Run::WrapperBase Bio::Root::Root);
 153 use Bio::Tools::Run::WrapperBase::CommandExts;
 154
 155 our $program_name = 'samtools';
 156 our $use_dash = 1;
 157 our $join = ' ';
 158
 159 =head2 new
 160
 161  Title   : new
 162  Usage   : my $obj = new Bio::Tools::Run::Samtools();
 163  Function: Builds a new Bio::Tools::Run::Samtools object
 164  Returns : an instance of Bio::Tools::Run::Samtools
 165  Args    :
 166
 167 =cut
 168
 169 sub new {
 170     my ($class, @args) = @_;
 171     $program_dir ||= $ENV{SAMTOOLSDIR};
 172     my $self = $class->SUPER::new(@args);
 173     return $self;
 174 }
 175
 176 sub run { shift->_run(@_) }
 177 1;