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 Reporting Bugs
  90
  91 Report bugs to the Bioperl bug tracking system to help us keep track
  92 the bugs and their resolution.  Bug reports can be submitted via the
  93 web:
  94
  95   http://bugzilla.open-bio.org/
  96
  97 =head1 AUTHOR - James Gilbert, Mark Johnson
  98
  99 Email - jgrg@sanger.ac.uk, mjohnson@watson.wustl.edu
 100
 101 =head1 APPENDIX
 102
 103 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
 104
 105 =cut
 106
 107
 108 # Let the code begin...
 109
 110
 111 package Bio::Index::Qual;
 112
 113 use strict;
 114
 115 use Bio::Seq;
 116
 117 use base qw(Bio::Index::AbstractSeq);
 118
 119 #
 120 # Suggested fix by Michael G Schwern <schwern@pobox.com> to
 121 # get around a clash with CPAN shell...
 122 #
 123
 124
 125 sub _version {
 126         return 0.2;
 127 }
 128
 129 =head2 _file_format
 130
 131  Title   : _file_format
 132  Function: The file format for this package, which is needed
 133            by the SeqIO system when reading the sequence.
 134  Returns : 'qual'
 135
 136 =cut
 137
 138 sub _file_format {
 139         return 'qual';
 140 }
 141
 142
 143
 144 =head2 _index_file
 145
 146   Title   : _index_file
 147   Usage   : $index->_index_file( $file_name, $i )
 148   Function: Specialist function to index QUAL format files.
 149             Is provided with a filename and an integer
 150             by make_index in its SUPER class.
 151   Example :
 152   Returns :
 153   Args    :
 154
 155 =cut
 156
 157 sub _index_file {
 158         my( $self,
 159                  $file, # File name
 160                  $i,    # Index-number of file being indexed
 161           ) = @_;
 162
 163         my( $begin,     # Offset from start of file of the start
 164                     # of the last found record.
 165           );
 166
 167         $begin = 0;
 168
 169         my $id_parser = $self->id_parser;
 170
 171         open my $QUAL, '<', $file or $self->throw("Can't open file for read : $file");
 172
 173         # Main indexing loop
 174         while (<$QUAL>) {
 175                 if (/^>/) {
 176                         # $begin is the position of the first character after the '>'
 177                         my $offset = ( $^O =~ /mswin/i ) ? 0 : 1;
 178                         my $begin = tell($QUAL) - length( $_ ) + $offset;
 179
 180                         foreach my $id (&$id_parser($_)) {
 181                                 $self->add_record($id, $i, $begin);
 182                         }
 183                 }
 184         }
 185
 186         close $QUAL;
 187         return 1;
 188 }
 189
 190 =head2 id_parser
 191
 192   Title   : id_parser
 193   Usage   : $index->id_parser( CODE )
 194   Function: Stores or returns the code used by record_id to
 195             parse the ID for record from a string.  Useful
 196             for (for instance) specifying a different
 197             parser for different flavours of Qual file.
 198             Returns \&default_id_parser (see below) if not
 199             set. If you supply your own id_parser
 200             subroutine, then it should expect a qual
 201             description line.  An entry will be added to
 202             the index for each string in the list returned.
 203   Example : $index->id_parser( \&my_id_parser )
 204   Returns : ref to CODE if called without arguments
 205   Args    : CODE
 206
 207 =cut
 208
 209 sub id_parser {
 210         my( $self, $code ) = @_;
 211
 212         if ($code) {
 213                 $self->{'_id_parser'} = $code;
 214         }
 215         return $self->{'_id_parser'} || \&default_id_parser;
 216 }
 217
 218
 219
 220 =head2 default_id_parser
 221
 222   Title   : default_id_parser
 223   Usage   : $id = default_id_parser( $header )
 224   Function: The default Qual ID parser for Qual.pm
 225             Returns $1 from applying the regexp /^>\s*(\S+)/
 226             to $header.
 227   Returns : ID string
 228   Args    : a qual header line string
 229
 230 =cut
 231
 232 sub default_id_parser {
 233         if ($_[0] =~ /^>\s*(\S+)/) {
 234                 return $1;
 235         } else {
 236                 return;
 237         }
 238 }
 239
 240 1;