.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::DB::Qual 3pm"
.TH Bio::DB::Qual 3pm "2020-10-28" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::DB::Qual \- Fast indexed access to quality files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Bio::DB::Qual;
\&
\&  # create database from directory of qual files
\&  my $db      = Bio::DB::Qual\->new(\*(Aq/path/to/qual/files/\*(Aq);
\&  my @ids     = $db\->get_all_primary_ids;
\&
\&  # Simple access
\&  my @qualarr = @{$db\->qual(\*(AqCHROMOSOME_I\*(Aq,4_000_000 => 4_100_000)};
\&  my @revqual = @{$db\->qual(\*(AqCHROMOSOME_I\*(Aq,4_100_000 => 4_000_000)};
\&  my $length  = $db\->length(\*(AqCHROMOSOME_I\*(Aq);
\&  my $header  = $db\->header(\*(AqCHROMOSOME_I\*(Aq);
\&
\&  # Access to sequence objects. See Bio::PrimarySeqI.
\&  my $obj     = $db\->get_Qual_by_id(\*(AqCHROMOSOME_I\*(Aq);
\&  my @qual    = @{$obj\->qual};
\&  my @subqual = @{$obj\->subqual(4_000_000 => 4_100_000)};
\&  my $length  = $obj\->length;
\&
\&  # Loop through sequence objects
\&  my $stream  = $db\->get_PrimarySeq_stream;
\&  while (my $qual = $stream\->next_seq) {
\&    # Bio::Seq::PrimaryQual operations
\&  }
\&
\&  # Filehandle access
\&  my $fh = Bio::DB::Qual\->newFh(\*(Aq/path/to/qual/files/\*(Aq);
\&  while (my $qual = <$fh>) {
\&    # Bio::Seq::PrimaryQual operations
\&  }
\&
\&  # Tied hash access
\&  tie %qualities,\*(AqBio::DB::Qual\*(Aq,\*(Aq/path/to/qual/files/\*(Aq;
\&  print $qualities{\*(AqCHROMOSOME_I:1,20000\*(Aq};
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Bio::DB::Qual provides indexed access to a single Fasta file, several files,
or a directory of 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. Bio::DB::Qual is based on
Bio::DB::IndexedBase. See this module's documentation for details.
.PP
The qual files should 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.
.PP
The module uses /^>(\eS+)/ to extract the primary \s-1ID\s0 of each quality score
from the qual header. See \-makeid in Bio::DB::IndexedBase to pass a callback
routine to reversibly modify this primary \s-1ID,\s0 e.g. if you wish to extract a
specific portion of the gi|gb|abc|xyz GenBank IDs.
.SH "DATABASE CREATION AND INDEXING"
.IX Header "DATABASE CREATION AND INDEXING"
The object-oriented constructor is \fBnew()\fR, the filehandle constructor is \fBnewFh()\fR
and the tied hash constructor is \fBtie()\fR. They all allow one to index a single Fasta
file, several files, or a directory of files. See Bio::DB::IndexedBase.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Bio::DB::IndexedBase
.PP
Bio::DB::Fasta
.PP
Bio::Seq::PrimaryQual
.SH "LIMITATIONS"
.IX Header "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 \*(L"ghost\*(R" entry
will remain in the index and will return garbage results if accessed. Currently,
the only way to accommodate deletions is to rebuild the entire index, either by
deleting it manually, or by passing \-reindex=>1 to \fBnew()\fR when
initializing the module.
.PP
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 that 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?).
.SH "AUTHOR"
.IX Header "AUTHOR"
Florent E Angly <florent . angly @ gmail\-dot\-com>.
.PP
Module largely based on and adapted from Bio::DB::Fasta by Lincoln Stein.
.PP
Copyright (c) 2007 Florent E Angly.
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
.PP
For BioPerl-style access, the following methods are provided:
.SS "get_Seq_by_id"
.IX Subsection "get_Seq_by_id"
.Vb 10
\& Title   : get_Seq_by_id,  get_Seq_by_acc, get_Seq_by_version, get_Seq_by_primary_id,
\&           get_Qual_by_id, get_qual_by_acc, get_qual_by_version, get_qual_by_primary_id,
\& Usage   : my $seq = $db\->get_Seq_by_id($id);
\& Function: Given an ID, fetch the corresponding sequence from the database.
\& Returns : A Bio::PrimarySeq::Fasta object (Bio::PrimarySeqI compliant)
\&           Note that to save resource, Bio::PrimarySeq::Fasta sequence objects
\&           only load the sequence string into memory when requested using seq().
\&           See L<Bio::PrimarySeqI> for methods provided by the sequence objects
\&           returned from get_Seq_by_id() and get_PrimarySeq_stream().
\& Args    : ID
.Ve
.SS "get_PrimarySeq_stream"
.IX Subsection "get_PrimarySeq_stream"
.Vb 7
\& Title   : get_Seq_stream, get_PrimarySeq_stream
\& Usage   : my $stream = $db\->get_Seq_stream();
\& Function: Get a stream of Bio::PrimarySeq::Fasta objects. The stream supports a
\&           single method, next_seq(). Each call to next_seq() returns a new
\&           Bio::PrimarySeq::Fasta sequence object, until no more sequences remain.
\& Returns : A Bio::DB::Indexed::Stream object
\& Args    : None
.Ve
.SH ""
.IX Header ""
For simple access, the following methods are provided:
.SS "new"
.IX Subsection "new"
.Vb 7
\& Title   : new
\& Usage   : my $db = Bio::DB::Qual\->new( $path, %options);
\& Function: Initialize a new database object. When indexing a directory, files
\&           ending in .qual,qa are indexed by default.
\& Returns : A new Bio::DB::Qual object
\& Args    : A single file, or path to dir, or arrayref of files
\&           Optional arguments: see Bio::DB::IndexedBase
.Ve
.SS "qual"
.IX Subsection "qual"
.Vb 10
\& Title   : qual, quality, subqual
\& Usage   : # All quality scores
\&           my @qualarr = @{$qualdb\->subqual($id)};
\&           # Subset of the quality scores
\&           my @subqualarr = @{$qualdb\->subqual($id, $start, $stop, $strand)};
\&           # or...
\&           my @subqualarr = @{$qualdb\->subqual($compound_id)};
\& Function: Get a subqual of an entry in the database. For your convenience,
\&           the sequence to extract can be specified with any of the following
\&           compound IDs:
\&              $db\->qual("$id:$start,$stop")
\&              $db\->qual("$id:$start..$stop")
\&              $db\->qual("$id:$start\-$stop")
\&              $db\->qual("$id:$start,$stop/$strand")
\&              $db\->qual("$id:$start..$stop/$strand")
\&              $db\->qual("$id:$start\-$stop/$strand")
\&              $db\->qual("$id/$strand")
\&           If $stop is less than $start, then the reverse complement of the
\&           sequence is returned. Avoid using it if possible since this goes
\&           against Bio::Seq conventions.
\& Returns : Reference to an array of quality scores
\& Args    : Compound ID of entry to retrieve
\&             or
\&           ID, optional start (defaults to 1), optional end (defaults to the
\&           number of quality scores for this sequence), and strand (defaults to
\&           1).
.Ve
.SS "header"
.IX Subsection "header"
.Vb 5
\& Title   : header
\& Usage   : my $header = $db\->header($id);
\& Function: Get the header line (ID and description fields) of the specified entry.
\& Returns : String
\& Args    : ID of entry
.Ve