view release on metacpan or  search on metacpan

lib/BioX/Seq/Fetch.pm  view on Meta::CPAN

    my $parser = BioX::Seq::Fetch->new(
        $filename,
        with_description => 1,
    );

Create a new C<BioX::Seq::Fetch> parser. Requires an input filename (STDIN or
open filehandles are not supported, as a filename is needed to find the
corresponding index file and to ensure than C<seek()>-ing is supported). Takes
one optional boolean argument ('with_description') indicating whether to
enable backtracking to find and include any sequence description present
(normally this is absent as the FASTA index includes the offset to the
sequence itself and not the defline). This option is currently experimental
and may slow down sequence fetches, so it is turned off by default.

=head1 METHODS

=head2 fetch_seq

    my $seq = $parser->fetch_seq(
        $name,
        $start, 
        $end,
    );

Returns the requested sequence as a C<BioX::Seq> object, or undef if no
matching sequence is found.  Requires a valid sequence identifier and
optionally 1-based start and end coordinates to retrieve a substring (the
entire sequence is returned by default). A fatal error is thrown if the
provided coordinates are outside the range of [1-length(sequence)].

=head2 write_index

    $parser->write_index();
    $parser->write_index( 'path/to/file.fa.fai' );

Writes a samtools-compatible index file for the underlying sequence file.
Accepts one optional argument specifying the path of the file to create (the
default, which should usually not be changed, is the same as the underlying
sequence file with a '.fai' extension added).

This method is now called automatically if a FASTA file is opened with no
index file present.

=head2 ids

    my @seq_ids = $parser->ids;

Returns an array of sequence IDs, ordered by their occurence in the underlying
file.

=head2 length

    my $len = $parser->length( $seq_id );

Returns the length of the sequence given by C<$seq_id>. May be marginally
faster than fetching the sequence object and then finding the length.

=head1 COMPRESSION

C<BioX::Seq::Fetch> supports files compressed with blocked gzip (BGZIP),
typically using the C<bgzip> utility. This allows for pseudo-random access
without the need for full file decompression. The C<Compress::BGZIP> module is
required for this functionality.


=head1 CAVEATS AND BUGS

Please report any bugs or feature requests to the issue tracker
at L<https://github.com/jvolkening/p5-BioX-Seq>.

=head1 AUTHOR

Jeremy Volkening <jeremy *at* base2bio.com>

=head1 COPYRIGHT AND LICENSE

Copyright 2014-2017 Jeremy Volkening

This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
this program.  If not, see <http://www.gnu.org/licenses/>.

=cut