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

Bio::DB::UpdateableSeqI 💾✨

the manual page you're reading is literally titled Bio::D...bleSeqI(3pm) (yes bestie, the terminal squished the name, it's giving truncation 💅) — and it lives in the User Contributed Perl Documentation section. okay so. sit down. hydrate. we're learning how to write back to a sequence database. 🫶

---

🌸 NAME 🌸

Bio::DB::UpdateableSeqI — an interface for writing to a database of sequences. like, the writing one. the one that changes things. no cap. 🔥

---

🦋 SYNOPSIS 🦋

# get a Bio::DB::UpdateableSeqI somehow
eval {
    my ( @updatedseqs, @newseqs, @deadseqs);
    my $seq = $db->get_Seq_by_id('ROA1_HUMAN');
    $seq->desc('a new description');

    push @updatedseqs, $seq;

    $db->write_seq(\@updatedseqs, \@newseqs, \@deadseqs);
};
if( $@ ) {
    print STDERR "an error when trying to write seq : $@\n";
}

notice how it's all wrapped in an eval block, bestie? that's not decoration, that's self-care. the error check at the bottom catches $@ and prints it. always wrap your writes. always. 😭

---

💖 DESCRIPTION 💖

So this module? it seeks to provide a simple method for pushing sequence changes back to a Sequence Database. And when we say "a Sequence Database" we mean it in the broadest possible sense, because that database can be:

• an SQL compliant database
• a file based database
• AceDB
• literally etc. 🎀

the whole point is you don't have to care which one it is, you just push your changes and vibe. main character energy for database abstraction. periodt. 👑

---

🎀 AUTHOR 🎀

Jason Stajich <jason@bioperl.org> — icon. legend. wrote the whole thing. 💜

✨ Support ✨

Okay so if you have a usage question or a support issue, please direct it to the mailing list:

bioperl-l@bioperl.org

and not to the module maintainer directly. i know, i know, sliding into the maintainer's DMs feels faster, but the mailing list is where the experienced and responsive experts are, and they will look at your problem and quickly address it. it's giving group chat but the group chat actually knows things.

Please include a thorough description of the problem with code and data examples if at all possible. fr fr. no "it doesn't work" with zero context, we are NOT doing that. 🙈

🐛 Reporting Bugs 🐛

Report bugs to the Bioperl bug tracking system, because that's how we keep track of the bugs and their resolution. 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. Heads up bestie: internal methods are usually preceded with a _ — that underscore is the little "staff only" rope, iykyk. 🧚

💅 write_seq

• Title : write_seq
• Usage : write_seq(\@updatedseqs, \@addedseqs, \@deadseqs)
• Function: updates sequences in first array, adds sequences in the second array, and removes sequences in the third array.
• Example :
• Returns :
• Args : arrays of sequence objects that must be obtained from Bio::DB::UpdateableSeqI.

three arrays, three jobs: update, add, delete. she's efficient. she's organized. she's booked and busy. 🌸

💜 _add_seq

• Title : _add_seq
• Usage : _add_seq($seq)
• Function: Adds a new sequence
• Example :
• Returns : will throw an exception if sequences accession number already exists
• Args : a new seq object - should have an accession number

careful bestie: if that accession number is already in there, she throws. duplicate accessions are NOT allowed on this campus. 🚫

🦋 _remove_seq

• Title : _remove_seq
• Usage : _remove_seq($seq)
• Function: Removes an existing sequence
• Example :
• Returns : will throw an exception if sequence does not exists for the primary_id
• Args : a seq object that was retrieved from Bio::DB::UpdateableSeqI

and yes, if there's no sequence for that primary_id, exception. you can't delete what was never there, babe. 💀

🌈 _update_seq

• Title : _update_seq
• Usage : _update_seq($seq)
• Function: Updates a sequence
• Example :
• Returns : will throw an exception if sequence is out of sync from expected val.
• Args : a seq object that was retrieved from Bio::DB::UpdateableSeqI

out of sync = exception. the database is checking you. the database always checks you. 😭

---

👑 Methods inherieted from Bio::DB::RandomAccessI 👑

🍓 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

---

💖 Methods inheirited from Bio::DB::SeqI 💖

✨ get_PrimarySeq_stream

• Title : get_PrimarySeq_stream
• Usage : $stream = get_PrimarySeq_stream
• Function: Makes a Bio::DB::SeqStreamI compliant object which provides a single method, next_primary_seq
• Returns : Bio::DB::SeqStreamI
• Args : none

one method. that's it. next_primary_seq. minimalism is the vibe. 🧚

🌸 get_all_primary_ids

• Title : get_all_ids
• Usage : @ids = $seqdb->get_all_primary_ids()
• Function: gives an array of all the primary_ids of the sequence objects in the database. These maybe ids (display style) or accession numbers or something else completely different - they are not meaningful outside of this database implementation.
• Example :
• Returns : an array of strings
• Args : none

important bestie: those ids might be ids, might be accessions, might be something else completely different. they are not meaningful outside of this database implementation. do not carry them around like they're universal. they are local. they are house keys, not passports. 🗝️

🦋 get_Seq_by_primary_id

• Title : get_Seq_by_primary_id
• Usage : $seq = $db->get_Seq_by_primary_id($primary_id_string);
• Function: Gets a Bio::Seq object by the primary id. The primary id in these cases has to come from $db->get_all_primary_ids. There is no other way to get (or guess) the primary_ids in a database.

The other possibility is to get Bio::PrimarySeqI objects via the get_PrimarySeq_stream and the primary_id field on these objects are specified as the ids to use here.

• Returns : A Bio::Seq object
• Args : accession number (as a string)
• Throws : "acc does not exist" exception

no guessing. there is literally no other way to get (or guess) the primary_ids in a database. they have to come from get_all_primary_ids, or from the primary_id field on the Bio::PrimarySeqI objects you pulled off the get_PrimarySeq_stream. those are the two doors. that's it. 🚪🚪

---

and that's the whole page, bestie!! 🌈⭐

this one was shipped with perl v5.32.1 and dated 2021-08-15 — so if you're reading it way later, just know she's vintage and she still ate. 💅

mwah. go write some sequences. responsibly. 🫶💖