Linux Certif

Toute la documentation sur la certification Linux LPI

Bio::DB::Qual.3pm

NAME

Bio::DB::Qual -- Fast indexed access to a directory of quality files

SYNOPSIS

   use Bio::DB::Qual;
 
   # create database from directory of qual files
   my $db      = Bio::DB::Qual->new('/path/to/qual/files');
   my @ids     = $db->ids;
 
   # simple access (for those without Bioperl)
   my @qual    = @{$db->qual('CHROMOSOME_I',4_000_000 => 4_100_000)};
   my @revqual = @{$db->qual('CHROMOSOME_I',4_100_000 => 4_000_000)};
   my $length  = $db->length('CHROMOSOME_I');
   my $header  = $db->header('CHROMOSOME_I');
 
   # Bioperl-style access
   my $obj     = $db->get_Qual_by_id('CHROMOSOME_I');
   my @qual    = @{$obj->qual};
   my @subqual = @{$obj->subqual(4_000_000 => 4_100_000)};
   my $length  = $obj->length;
   # (etc)
 
   # Bio::SeqIO-style access
   my $stream  = $db->get_PrimaryQual_stream;
   while (my $qual = $stream->next_seq) {
     # Bio::Seq::PrimaryQual operations
   }
 
   my $fh = Bio::DB::Qual->newFh('/path/to/qual/files');
   while (my $qual = <$fh>) {
     # Bio::Seq::PrimaryQual operations
   }
 
   # tied hash access
   tie %qualities,'Bio::DB::Qual','/path/to/qual/files';
   print $qualities{'CHROMOSOME_I:1,20000'};
 
 

DESCRIPTION

Bio::DB::Qual provides indexed access to one or more qual files. It provides random access to each quality score entry without having to read the file from the beginning. Access to subqualities (portions of a quality score) is provided, although contrary to Bio::DB::Fasta, the full quality score has to be brought in memory.

When you initialize the module, you point it at a single qual file or a directory of multiple such files. The first time it is run, the module generates an index of the contents of the file or directory using the AnyDBM module (Berkeley DB* preferred, followed by GDBM_File, NDBM_File, and SDBM_File). Thereafter it uses the index file to find the file and offset for any requested quality score. If one of the source qual files is updated, the module reindexes just that one file. (You can also force reindexing manually). For improved performance, the module keeps a cache of open filehandles, closing less-recently used ones when the cache is full.

The qual files may contain decimal quality scores. Entries may have any line length up to 65,536 characters, and different line lengths are allowed in the same file. However, within a quality score entry, all lines must be the same length except for the last. An error will be thrown if this is not the case.

The module uses /^>(\S+)/ to extract the primary ID of each quality score from the qual header. During indexing, you may pass a callback routine to modify this primary ID. For example, you may wish to extract a portion of the gi|gb|abc|xyz prefixes that are commonly used. The original header line can be recovered later.

*Berkeley DB can be obtained free from www.sleepycat.com. After it is installed you will need to install the BerkeleyDB Perl module.

DATABASE CREATION AND INDEXING

The two constructors for this class are new() and newFh(). The former creates a Bio::DB::Qual object which is accessed via method calls. The latter creates a tied filehandle which can be used Bio::SeqIO-style to fetch quality score objects in a data stream. There is also a tied hash interface.

$db = Bio::DB::Qual->new($qual_path [,%options])

Create a new Bio::DB::Qual object from the Qual file or files indicated by $qual_path. Indexing will be performed automatically if needed. If successful, new() will return the database accessor object. Otherwise it will return undef.

$qual_path may be an individual qual file, or may refer to a directory containing one or more of such files. Following the path, you may pass a series of name=>value options or a hash with these same name=>value pairs. Valid options are:

  Option Name   Description               Default
  -----------   -----------               -------
 
  -glob         Glob expression to use    *.{qa,QA,qual,QUAL}
                for searching for qual
                files in directories. 
 
  -makeid       A code subroutine for     None
                transforming qual IDs.
 
  -maxopen      Maximum size of           32
                filehandle cache.
 
  -debug        Turn on status            0
                messages.
 
  -reindex      Force the index to be     0
                rebuilt.
 
  -dbmargs      Additional arguments      none
                to pass to the DBM
                routines when tied
                (scalar or array ref).
 
 

-dbmargs can be used to control the format of the index. For example, you can pass $DB_BTREE to this argument so as to force the IDs to be sorted and retrieved alphabetically. Note that you must use the same arguments every time you open the index!

-reindex can be used to force the index to be recreated from scratch.

$fh = Bio::DB::Qual->newFh($qual_path [,%options])

Create a tied filehandle opened on a Bio::DB::Qual object. Reading from this filehandle with <> will return a stream of quality objects, Bio::SeqIO-style.

The -makeid option gives you a chance to modify quality score IDs during indexing. The option value should be a code reference that will take a scalar argument and return a scalar result, like this:

   $db = Bio::DB::Qual->new("file.qual",-makeid=>\&make_my_id);
 
   sub make_my_id {
     my $description_line = shift;
     # get a different id from the quality header, e.g.
     $description_line =~ /(\S+)$/;
     return $1;
   }
 
 

make_my_id() will be called with the full qual id line (including the ``>'' symbol!). For example:

   >A12345.3 Predicted C. elegans protein egl-2
 
 

By default, this module will use the regular expression /^>(\S+)/ to extract ``A12345.3'' for use as the ID.If you pass a -makeid callback, you can extract any portion of this, such as the ``egl-2'' symbol.

The -makeid option is ignored after the index is constructed.

OBJECT METHODS

The following object methods are provided.

$raw_qual = $db->qual($id [,$start, $stop])

Return a quality score array reference given an ID and optionally a start and stop position (the quality value number) in the quality score. If $stop is less than $start, then the reverse complement of the quality score is returned (this violates Bio::Seq conventions).

For your convenience, subqualities can be indicated with any of the following compound IDs:

    $db->qual("$id:$start,$stop")
 
    $db->qual("$id:$start..$stop")
 
    $db->qual("$id:$start-$stop")
 
 

$length = $db->length($id)

Return the length of the indicated quality score, i.e. the number of quality values.

$header = $db->header($id)

Return the header line for the ID, including the initial ``>''.

$filename = $db->file($id)

Return the name of the file in which the indicated quality score can be found.

$offset = $db->offset($id)

Return the offset of the indicated quality score from the beginning of the file in which it is located. The offset points to the beginning of the quality score, not the beginning of the header line.

$header_length = $db->headerlen($id)

Return the length of the header line for the indicated quality score.

$header_offset = $db->header_offset($id)

Return the offset of the header line for the indicated quality score from the beginning of the file in which it is located.

$index_name = $db->index_name

Return the path to the index file.

$path = $db->path

Return the path to the Qual file(s).

For BioPerl-style access, the following methods are provided:

$qual = $db->get_Qual_by_id($id)

Return a Bio::Seq::PrimaryQual object, which obeys the Bio::PrimarySeqI conventions. To recover the quality score, call $qual->qual().

Note that get_Qual_by_id() does not bring the entire quality score into memory until requested. Internally, the returned object uses the accessor to generate subqualities as needed.

$qual = $db->get_Qual_by_acc($id)

$qual = $db->get_Qual_by_primary_id($id)

These methods all do the same thing as get_Qual_by_id().

$stream = $db->get_PrimaryQual_stream()

Return a Bio::DB::Qual::Stream object, which supports a single method next_seq(). Each call to next_seq() returns a new Bio::Seq::PrimaryQual object, until no more quality scores remain.

See Bio::Seq::PrimaryQual and Bio::PrimarySeqI for methods provided by the quality objects returned from get_Qual_by_id() and get_PrimaryQual_stream().

TIED INTERFACES

This module provides two tied interfaces, one which allows you to treat the quality score database as a hash, and the other which allows you to treat the database as an I/O stream.

Creating a Tied Hash

The tied hash interface is very straightforward.

$obj = tie %db,'Bio::DB::Qual','/path/to/qual/files' [,@args]

Tie %db to Bio::DB::Qual using the indicated path to the Qual files. The optional @args list is the same set of named argument/value pairs used by Bio::DB::Qual->new().

If successful, tie() will return the tied object. Otherwise it will return undef.

Once tied, you can use the hash to retrieve an individual quality score by its ID, like this:

   my $qual = $db{CHROMOSOME_I};
 
 

You may select a subquality by appending the comma-separated range to the quality score ID in the format ``$id:$start,$stop''. For example, here is the first 1000 quality values of the quality score with ID ``CHROMOSOME_I'':

   my $qual = $db{'CHROMOSOME_I:1,1000'};
 
 

(The regular expression used to parse this format allows quality score IDs to contain colons.)

When selecting subqualities, if $start > stop, then the reverse complement will be returned.

The keys() and values() functions will return the IDs and their quality scores, respectively. In addition, each() can be used to iterate over the entire data set:

  while (my ($id,$quality) = each %db) {
     print "$id => $quality\n";
  }
 
 

When dealing with very large quality scores, you can avoid bringing them into memory by calling each() in a scalar context. This returns the key only. You can then use tied(%db) to recover the Bio::DB::Qual object and call its methods.

  while (my $id = each %db) {
     print "$id => $db{$quality:1,100}\n";
     print "$id => ",tied(%db)->length($id),"\n";
  }
 
 

You may, in addition invoke Bio::DB::Qual the FIRSTKEY and NEXTKEY tied hash methods directly.

$id = $db->FIRSTKEY

Return the first ID in the database.

$id = $db->NEXTKEY($id)

Given an ID, return the next quality score ID.

This allows you to write the following iterative loop using just the object- oriented interface:

  my $db = Bio::DB::Qual->new('/path/to/qual/files');
  for (my $id=$db->FIRSTKEY; $id; $id=$db->NEXTKEY($id)) {
     # do something with quality
  }
 
 

Creating a Tied Filehandle

The Bio::DB::Qual->newFh() method creates a tied filehandle from which you can read Bio::Seq::PrimaryQual quality score objects sequentially. The following bit of code will iterate sequentially over all quality scores in the database:

  my $fh = Bio::DB::Qual->newFh('/path/to/qual/files');
  while (my $qual = <$fh>) {
    print $qual->id,' => ',$qual->length,"\n";
  }
 
 

When no more quality scores remain to be retrieved, the stream will return undef.

LIMITATIONS

When a quality score is deleted from one of the qual files, this deletion is not detected by the module and removed from the index. As a result, a ``ghost'' entry will remain in the index and will return garbage results if accessed. Currently, the only way to accomodate deletions is to rebuild the entire index, either by deleting it manually, or by passing -reindex=>1 to new() when initializing the module.

All quality score lines for a given quality score must have the same length except for the last (not sure why there is this limitation). This is not problematic for sequences but could be annoying for quality scores. A workaround is to make sure the your quality scores fit on no more than 2 lines. Another solution could be to padd them with blank spaces so that each line has the same number of characters (maybe this padding should be implemented in Bio::SeqIO::qual?).

AUTHOR

Florent E Angly <florent . angly @ gmail-dot-com>.

Module largely based on and adapted from Bio::DB::Fasta by Lincoln Stein.

Copyright (c) 2007 Florent E Angly.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

new

  Title   : new
  Usage   : my $db = Bio::DB::Qual->new( $path, @options);
  Function: initialize a new Bio::DB::Qual object
  Returns : new Bio::DB::Qual object
  Args    : path to dir of qual files or a single qual filename
 
 

These are optional arguments to pass in as well.

  -glob         Glob expression to use    *.{qual,QUAL,qa,QA}
                for searching for qual
                files in directories. 
 
  -makeid       A code subroutine for     none
                transforming qual IDs.
 
  -maxopen      Maximum size of           32
                filehandle cache.
 
  -debug        Turn on status            0
                messages.
 
  -reindex      Force the index to be     0
                rebuilt.
 
  -dbmargs      Additional arguments      none
                to pass to the DBM
                routines when tied
                (scalar or array ref).
 
 

newFh

  Title   : newFh
  Usage   : my $fh = Bio::DB::Qual->newFh('/path/to/qual/files');
  Function: gets a new Fh for a file or directory containing several files
  Returns : filehandle object
  Args    : none
 
 

index_dir

  Title   : index_dir
  Usage   : $db->index_dir($dir)
  Function: set the index dir and load all files in the dir
  Returns : hashref of qual offsets in each file
  Args    : dirname, boolean to force a reload of all files
 
 

get_Qual_by_id

  Title   : get_Qual_by_id
  Usage   : my $qual = $db->get_Qual_by_id($id)
  Function: Bio::DB::RandomAccessI method implemented
  Returns : Bio::PrimarySeqI object
  Args    : id
 
 

set_pack_method

  Title   : set_pack_method
  Usage   : $db->set_pack_method( @files )
  Function: Determines whether data packing uses 32 or 64 bit integers
  Returns : 1 for success
  Args    : one or more file paths
 
 

index_file

  Title   : index_file
  Usage   : $db->index_file($filename)
  Function: (re)loads a quality score file and indexes quality score offsets in
            the file
  Returns : qual offsets in the file
  Args    : filename, boolean to force reloading a file
 
 

dbmargs

  Title   : dbmargs
  Usage   : my @args = $db->dbmargs;
  Function: gets stored dbm arguments
  Returns : array
  Args    : none
 
 

index_name

  Title   : index_name
  Usage   : my $indexname = $db->index_name($path,$isdir);
  Function: returns the name of the index for a specific path 
  Returns : string
  Args    : path to check, boolean if it is a dir
 
 

calculate_offsets

  Title   : calculate_offsets
  Usage   : $db->calculate_offsets($filename,$offsets);
  Function: calculates the quality score offsets in a file based on ID
  Returns : offset hash for each file
  Args    : file to process, $offsets - hashref of id to offset storage
 
 

get_all_ids

  Title   : get_all_ids
  Usage   : my @ids = $db->get_all_ids
  Function: gets all the stored ids in all indexes
  Returns : list of ids
  Args    : none
 
 

length

  Title   : length
  Usage   : $qualdb->length($seqid);
  Function: gets the number of quality values in a quality score
  Returns : scalar
  Args    : ID of a quality score
 
 

subqual

  Title   : subqual
  Usage   : my @qualarr = @{$qualdb->subqual($id,$start,$stop)};
  Function: returns a subqual of a quality score in the database
  Returns : subquality array reference
  Args    : id of quality score, starting quality value number, ending quality
            value number
 
 

header

  Title   : header
  Usage   : $qualdb->header($id);
  Function: returns the header of a quality score in the database
  Returns : header string
  Args    : id of quality score
 
 

get_PrimaryQual_stream

  Title   : get_PrimaryQual_stream
  Usage   : $qualdb->get_PrimaryQual_stream
  Function: get a SeqIO-like stream of quality scores 
  Returns : stream object
  Args    : none