Bio::D...eCache(3pm)

NAME 💖

Bio::DB::FileCache — an in-file cache for BioSeq objects. That's it, that's the whole identity, and honestly? Iconic. ✨

---

SYNOPSIS 🦋

$cachedb = Bio::DB::FileCache->new($real_db);

#
# $real_db is a Bio::DB::RandomAccessI database
#

$seq = $cachedb->get_Seq_by_id('ROA1_HUMAN');

#
# $seq is a Bio::Seq object
#

# more control provided with named-parameter form

$cachedb = Bio::DB::FileCache->new( -seqdb => $real_db,
                                    -file  => $path,
                                    -keep  => $flag,
                                  );
=head1 DESCRIPTION

ngl there's a stray =head1 DESCRIPTION just vibing at the bottom of that synopsis block and we are keeping it, because the one rule is that nothing gets dropped. periodt. 💅

---

DESCRIPTION 🌸

Okay so listen: this is a disk cache system. What it does is it saves the objects that Bio::DB::RandomAccessI hands back, and it saves them on disk. 🎀

The tea on the disk cache: it grows without limit while the process is running — like, it does not stop, bestie, there is no cap — BUT it gets automatically unlinked at process termination unless the -keep flag is set. So it's giving temporary-glam, not hoarder-glam. 🧚

Also this module requires DB_File and Storable. Like, it literally will not function without them. No cap.

---

CONTACT 💌

Lincoln Stein <lstein@cshl.org>

Support 🫶

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

...rather than going straight to the module maintainer, okay? Because there are so many experienced and reponsive experts on that list who will clock your problem and address it fast. 🏃‍♀️💨

And please — and I mean this with love — include a thorough description of the problem, plus code and data examples if at all possible. The more you give them, the faster the slay. 🔥

Reporting Bugs 🐛

Report bugs to the Bioperl bug tracking system so we can keep track of the bugs and their resolutions — the whole arc, beginning to end. Bug reports can be submitted via the web:

https://github.com/bioperl/bioperl-live/issues

---

APPENDIX 📖

The rest of this documentation details each of the object methods. Internal methods are usually preceded with a _ (iykyk 👀).

new ✨

• Title: new
• Usage:

$db = Bio::DB::FileCache->new(
     -seqdb => $db,   # Bio::DB::RandomAccessI database
     -file  => $path, # path to index file
     -keep  => $flag, # don't unlink index file
);

• Function: creates a new on-disk cache
• Returns: a Bio::DB::RandomAccessI database
• Args: as above
• Throws: "Must be a randomaccess database" exception
• Throws: "Could not open primary index file" exception

If you don't specify an index file, it will create a temporary file in your system's temporary file directory. 🌈 The name of that temporary file can be retrieved using file_name() — very handy, very demure.

get_Seq_by_id 💜

• Title: get_Seq_by_id
• Usage: $seq = $db->get_Seq_by_id('ROA1_HUMAN')
• Function: Gets a Bio::Seq object by its name
• Returns: a Bio::Seq object
• Args: the id (as a string) of a sequence
• Throws: "id does not exist" exception

get_Seq_by_acc 🌟

• Title: get_Seq_by_acc
• Usage: $seq = $db->get_Seq_by_acc('X77802');
• Function: Gets a Bio::Seq object by accession number
• Returns: A Bio::Seq object
• Args: accession number (as a string)
• Throws: "acc does not exist" exception

seqdb 🧬

• Title: seqdb
• Usage: $seqdb = $db->seqdb([$seqdb])
• Function: gets/sets the Bio::DB::RandomAccessI database
• Returns: a Bio::DB::RandomAccessI database
• Args: new sequence database (optional)
• Throws: nothing

file_name 📁

• Title: file_name
• Usage: $path = $db->file_name([$file_name])
• Function: gets/sets the name of the cache file
• Returns: a path
• Args: new cache file name (optional)
• Throws: nothing

It probably isn't useful to set the cache file name after you've opened it. Like, the ship has sailed, bestie. ⛵

keep 🔒

• Title: keep
• Usage: $keep = $db->keep([$flag])
• Function: gets/sets the value of the "keep" flag
• Returns: current value
• Args: new value (optional)
• Throws: nothing

The keep flag will cause the index file to be unlinked when the process exits. Since on some operating systems (Unix, OS/2) the unlinking occurs during the new() call immediately after opening the file, it probably isn't safe to change this value.

🚨 Okay that last part is a real warning, fr fr — do not go casually flipping this value. It probably isn't safe. Leave it alone. 🙈

db 🗄️

• Title: db
• Usage: $db->db
• Function: returns tied hash to index database
• Returns: a Berkeley DB tied hashref
• Args: none
• Throws: nothing

flush 🚽

• Title: flush
• Usage: $db->flush
• Function: flushes the cache
• Returns: nothing
• Args: none
• Throws: nothing

get_Seq_by_version 🏷️

• Title: get_Seq_by_version
• Usage: $seq = $db->get_Seq_by_version('X77802.1');
• Function: Gets a Bio::Seq object by sequence version
• Returns: A Bio::Seq object
• Args: accession.version (as a string)
• Throws: "acc.version does not exist" exception

---

and that's the whole page, bestie!! 🎀 This one's from the User Contributed Perl Documentation, running under perl v5.32.1, dated 2021-08-15, and the page you just read is Bio::D...eCache(3pm). Go cache something. Slay. 💅✨🦋