Bio::DB::Fasta(3pm)

💖 Bio::DB::Fasta 💖

okay bestie, welcome to the User Contributed Perl Documentation for Bio::DB::Fasta — it's the module that gives you fast indexed access to fasta files, and it is genuinely iconic, no cap. ✨

---

🌸 NAME 🌸

Bio::DB::Fasta — fast indexed access to fasta files. she does exactly what it says on the tin and she does it fast. 💅

---

🦋 SYNOPSIS 🦋

use Bio::DB::Fasta;

# Create database from a directory of Fasta files
my $db       = Bio::DB::Fasta->new('/path/to/fasta/files/');
my @ids      = $db->get_all_primary_ids;

# Simple access
my $seqstr   = $db->seq('CHROMOSOME_I', 4_000_000 => 4_100_000);
my $revseq   = $db->seq('CHROMOSOME_I', 4_100_000 => 4_000_000);
my $length   = $db->length('CHROMOSOME_I');
my $header   = $db->header('CHROMOSOME_I');
my $alphabet = $db->alphabet('CHROMOSOME_I');

# Access to sequence objects. See Bio::PrimarySeqI.
my $seq     = $db->get_Seq_by_id('CHROMOSOME_I');
my $seqstr  = $seq->seq;
my $subseq  = $seq->subseq(4_000_000 => 4_100_000);
my $trunc   = $seq->trunc(4_000_000 => 4_100_000);
my $length  = $seq->length;

# Loop through sequence objects
my $stream  = $db->get_PrimarySeq_stream;
while (my $seq = $stream->next_seq) {
  # Bio::PrimarySeqI stuff
}

# Filehandle access
my $fh = Bio::DB::Fasta->newFh('/path/to/fasta/files/');
while (my $seq = <$fh>) {
  # Bio::PrimarySeqI stuff
}

# Tied hash access
tie %sequences,'Bio::DB::Fasta','/path/to/fasta/files/';
print $sequences{'CHROMOSOME_I:1,20000'};

---

🧚 DESCRIPTION 🧚

okay so Bio::DB::Fasta gives you indexed access to a single Fasta file, several files, or a whole directory of files. she provides persistent random access to every sequence entry — either as a Bio::PrimarySeqI-compliant object or as a plain string — and to subsequences inside each entry, which means you can grab lil portions of absolutely enormous sequences without dragging the entire sequence into memory. it's giving efficiency. it's giving main character energy. 🫶

and fr fr, Bio::DB::Fasta is based on Bio::DB::IndexedBase. go read that module's documentation for the details, bestie. 📖

your Fasta files can contain literally any combination of nucleotide and protein sequences — during indexing the module guesses the molecular type, which is honestly so brave of it. entries may have any line length up to 65,536 characters, and different line lengths are totally allowed in the same file. BUT. 🚨

within a sequence entry, all lines must be the same length except for the last one. if that's not the case, an error will be thrown. periodt. 💀

the module uses /^>(\S+)/ to extract the primary ID of each sequence from the Fasta header. check out -makeid in Bio::DB::IndexedBase if you wanna pass a callback routine to reversibly modify that primary ID — like, say, when you want to pull a specific portion out of those gi|gb|abc|xyz GenBank IDs. iykyk. 🎀

---

👑 DATABASE CREATION AND INDEXING 👑

the object-oriented constructor is new(), the filehandle constructor is newFh(), and the tied hash constructor is tie(). all three of them let you index a single Fasta file, several files, or a directory of files. see Bio::DB::IndexedBase. slay. ✨

---

🌈 SEE ALSO 🌈

• Bio::DB::IndexedBase
• Bio::DB::Qual
• Bio::PrimarySeqI

---

💜 AUTHOR 💜

Lincoln Stein <lstein@cshl.org>.

Copyright (c) 2001 Cold Spring Harbor Laboratory.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.

---

⭐ APPENDIX ⭐

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _. 🙈

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

🍓 get_Seq_by_id

• Title : get_Seq_by_id, get_Seq_by_acc, get_Seq_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

🍓 get_PrimarySeq_stream

• Title : get_PrimarySeq_stream
• Usage : my $stream = $db->get_PrimarySeq_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

For simple access, the following methods are provided:

🍓 new

• Title : new
• Usage : my $db = Bio::DB::Fasta->new( $path, %options);
• Function: initialize a new database object. when indexing a directory, files ending in .fa,fasta,fast,dna,fna,faa,fsa are indexed by default.
• Returns : a new Bio::DB::Fasta object.
• Args : a single file, or path to dir, or arrayref of files. optional arguments: see Bio::DB::IndexedBase

🍓 seq

• Title : seq, sequence, subseq
• Usage :

# Entire sequence string
my $seqstr    = $db->seq($id);
# Subsequence
my $subseqstr = $db->seq($id, $start, $stop, $strand);
# or...
my $subseqstr = $db->seq($compound_id);

• Function: get a subseq of a sequence from the database. for your convenience, the sequence to extract can be specified with any of the following compound IDs:

$db->seq("$id:$start,$stop")
$db->seq("$id:$start..$stop")
$db->seq("$id:$start-$stop")
$db->seq("$id:$start,$stop/$strand")
$db->seq("$id:$start..$stop/$strand")
$db->seq("$id:$start-$stop/$strand")
$db->seq("$id/$strand")

in the case of DNA or RNA sequence, 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 : a string
• Args : ID of sequence to retrieve, or compound ID of subsequence to fetch, or ID, optional start (defaults to 1), optional end (defaults to length of sequence) and optional strand (defaults to 1).

🍓 length

• Title : length
• Usage : my $length = $qualdb->length($id);
• Function: get the number of residues in the indicated sequence.
• Returns : Number
• Args : ID of entry

🍓 header

• Title : header
• Usage : my $header = $db->header($id);
• Function: get the header line (ID and description fields) of the specified sequence.
• Returns : String
• Args : ID of sequence

🍓 alphabet

• Title : alphabet
• Usage : my $alphabet = $db->alphabet($id);
• Function: get the molecular type of the indicated sequence: dna, rna or protein
• Returns : String
• Args : ID of sequence

---

and that's the whole page bestie!! 💖 this one's from perl v5.32.1, dated 2021-08-15, and it's the Bio::DB::Fasta(3pm) page — go index something huge and remember: never load the whole sequence into memory when you don't have to. 🦋✨ mwah. 💅