Bio/Index/Qual.pm

   1 #
   2 # $Id$
   3 #
   4 # BioPerl module for Bio::Index::Qual
   5 #
   6 # Copied almost verbatim from James Gilbert's Bio::Index::Fasta
   7 #
   8 # You may distribute this module under the same terms as perl itself
   9
  10 # POD documentation - main docs before the code
  11
  12 =head1 NAME
  13
  14 Bio::Index::Qual - Interface for indexing (multiple) fasta qual files
  15
  16 =head1 SYNOPSIS
  17
  18     # Complete code for making an index for several
  19     # qual files
  20     use Bio::Index::Qual;
  21     use strict;
  22
  23     my $Index_File_Name = shift;
  24     my $inx = Bio::Index::Qual->new(
  25         '-filename' => $Index_File_Name,
  26         '-write_flag' => 1);
  27     $inx->make_index(@ARGV);
  28
  29     # Print out several sequences present in the index
  30     # in Qual format
  31     use Bio::Index::Qual;
  32     use strict;
  33
  34     my $Index_File_Name = shift;
  35     my $inx = Bio::Index::Qual->new('-filename' => $Index_File_Name);
  36     my $out = Bio::SeqIO->new('-format' => 'qual','-fh' => \*STDOUT);
  37
  38     foreach my $id (@ARGV) {
  39         my $seq = $inx->fetch($id); # Returns Bio::Seq object
  40         $out->write_seq($seq);
  41     }
  42
  43     # or, alternatively
  44     my $id;
  45     my $seq = $inx->get_Seq_by_id($id); #identical to fetch
  46
  47 =head1 DESCRIPTION
  48
  49 Inherits functions for managing dbm files from Bio::Index::Abstract.pm,
  50 and provides the basic funtionallity for indexing qual files, and
  51 retrieving the sequence from them. For best results 'use strict'.
  52
  53 Bio::Index::Qual supports the Bio::DB::BioSeqI interface, meaning
  54 it can be used as a Sequence database for other parts of bioperl
  55
  56 Additional example code is available in scripts/index/*PLS and in
  57 the Bioperl Tutorial (L<http://www.bioperl.org/wiki/Bptutorial.pl>).
  58
  59 Note that by default the key for the sequence will be the first continuous
  60 string after the 'E<gt>' in the qual header. If you want to use a specific
  61 substring of the qual header you must use the id_parser() method.
  62
  63 You can also set or customize the unique key used to retrieve by
  64 writing your own function and calling the id_parser() method.
  65 For example:
  66
  67    $inx->id_parser(\&get_id);
  68    # make the index
  69    $inx->make_index($file_name);
  70
  71    # here is where the retrieval key is specified
  72    sub get_id {
  73       my $line = shift;
  74       $line =~ /^(\d+)/;
  75       $1;
  76    }
  77
  78 =head1 FEED_BACK
  79
  80 =head2 Mailing Lists
  81
  82 User feedback is an integral part of the evolution of this and other
  83 Bioperl modules. Send your comments and suggestions preferably to one
  84 of the Bioperl mailing lists.  Your participation is much appreciated.
  85
  86   bioperl-l@bioperl.org                  - General discussion
  87   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  88
  89 =head2 Support
  90
  91 Please direct usage questions or support issues to the mailing list:
  92
  93 L<bioperl-l@bioperl.org>
  94
  95 rather than to the module maintainer directly. Many experienced and
  96 reponsive experts will be able look at the problem and quickly
  97 address it. Please include a thorough description of the problem
  98 with code and data examples if at all possible.
  99
 100 =head2 Reporting Bugs
 101
 102 Report bugs to the Bioperl bug tracking system to help us keep track
 103 the bugs and their resolution.  Bug reports can be submitted via the
 104 web:
 105
 106   http://bugzilla.open-bio.org/
 107
 108 =head1 AUTHOR - James Gilbert, Mark Johnson
 109
 110 Email - jgrg@sanger.ac.uk, mjohnson@watson.wustl.edu
 111
 112 =head1 APPENDIX
 113
 114 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
 115
 116 =cut
 117
 118
 119 # Let the code begin...
 120
 121
 122 package Bio::Index::Qual;
 123
 124 use strict;
 125
 126 use Bio::Seq;
 127
 128 use base qw(Bio::Index::AbstractSeq);
 129
 130 #
 131 # Suggested fix by Michael G Schwern <schwern@pobox.com> to
 132 # get around a clash with CPAN shell...
 133 #
 134
 135
 136 sub _version {
 137         return 0.2;
 138 }
 139
 140 =head2 _file_format
 141
 142  Title   : _file_format
 143  Function: The file format for this package, which is needed
 144            by the SeqIO system when reading the sequence.
 145  Returns : 'qual'
 146
 147 =cut
 148
 149 sub _file_format {
 150         return 'qual';
 151 }
 152
 153
 154
 155 =head2 _index_file
 156
 157   Title   : _index_file
 158   Usage   : $index->_index_file( $file_name, $i )
 159   Function: Specialist function to index QUAL format files.
 160             Is provided with a filename and an integer
 161             by make_index in its SUPER class.
 162   Example :
 163   Returns :
 164   Args    :
 165
 166 =cut
 167
 168 sub _index_file {
 169         my( $self,
 170                  $file, # File name
 171                  $i,    # Index-number of file being indexed
 172           ) = @_;
 173
 174         my( $begin,     # Offset from start of file of the start
 175                     # of the last found record.
 176           );
 177
 178         $begin = 0;
 179
 180         my $id_parser = $self->id_parser;
 181
 182         open my $QUAL, '<', $file or $self->throw("Can't open file for read : $file");
 183
 184         # Main indexing loop
 185         while (<$QUAL>) {
 186                 if (/^>/) {
 187                         # $begin is the position of the first character after the '>'
 188                         my $offset = ( $^O =~ /mswin/i ) ? 0 : 1;
 189                         my $begin = tell($QUAL) - length( $_ ) + $offset;
 190
 191                         foreach my $id (&$id_parser($_)) {
 192                                 $self->add_record($id, $i, $begin);
 193                         }
 194                 }
 195         }
 196
 197         close $QUAL;
 198         return 1;
 199 }
 200
 201 =head2 id_parser
 202
 203   Title   : id_parser
 204   Usage   : $index->id_parser( CODE )
 205   Function: Stores or returns the code used by record_id to
 206             parse the ID for record from a string.  Useful
 207             for (for instance) specifying a different
 208             parser for different flavours of Qual file.
 209             Returns \&default_id_parser (see below) if not
 210             set. If you supply your own id_parser
 211             subroutine, then it should expect a qual
 212             description line.  An entry will be added to
 213             the index for each string in the list returned.
 214   Example : $index->id_parser( \&my_id_parser )
 215   Returns : ref to CODE if called without arguments
 216   Args    : CODE
 217
 218 =cut
 219
 220 sub id_parser {
 221         my( $self, $code ) = @_;
 222
 223         if ($code) {
 224                 $self->{'_id_parser'} = $code;
 225         }
 226         return $self->{'_id_parser'} || \&default_id_parser;
 227 }
 228
 229
 230
 231 =head2 default_id_parser
 232
 233   Title   : default_id_parser
 234   Usage   : $id = default_id_parser( $header )
 235   Function: The default Qual ID parser for Qual.pm
 236             Returns $1 from applying the regexp /^>\s*(\S+)/
 237             to $header.
 238   Returns : ID string
 239   Args    : a qual header line string
 240
 241 =cut
 242
 243 sub default_id_parser {
 244         if ($_[0] =~ /^>\s*(\S+)/) {
 245                 return $1;
 246         } else {
 247                 return;
 248         }
 249 }
 250
 251 1;