Bio::A...:DBLink(3pm)

💖 Bio::Annotation::DBLink — untyped links between databases 💖

okay bestie, gather round, because we're talking about Bio::A...:DBLink(3pm) — yes that's the manual name, she's from the User Contributed Perl Documentation collection and she is lowkey iconic. this page is your group chat briefing on Bio::Annotation::DBLink, a lil object that points at stuff in other databases without ever being nosy about what's in there. no cap.

---

✨ NAME ✨

Bio::Annotation::DBLink — untyped links between databases 🦋

---

🌸 SYNOPSIS 🌸

   $link1 = Bio::Annotation::DBLink->new(-database => 'TSC',
                                        -primary_id => 'TSC0000030'
                                        );

   #or

   $link2 = Bio::Annotation::DBLink->new();
   $link2->database('dbSNP');
   $link2->primary_id('2367');

   # DBLink is-a Bio::AnnotationI object, can be added to annotation
   # collections, e.g. the one on features or seqs
   $feat->annotation->add_Annotation('dblink', $link2);

see how easy that was?? two whole ways to make one. pick your fighter 💅

---

👑 DESCRIPTION 👑

so what is this thing. it provides an object which represents a link from one object to something in another database — and it does not prescribe what is in the other database. it's giving "i know a guy" energy. no assumptions, just vibes.

aside from Bio::AnnotationI, this class also implements Bio::IdentifiableI. double interface, double slay. ✨

---

🎀 AUTHOR - Ewan Birney 🎀

Ewan Birney — birney@ebi.ac.uk

---

📖 APPENDIX 📖

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ (iykyk, that underscore means stay out of the kitchen unless you're cooking).

🌈 new 🌈

• Title — new
• Usage — $dblink = Bio::Annotation::DBLink->new(-database =>"GenBank", -primary_id => "M123456");
• Function — Creates a new instance of this class.
• Example — (none given, bestie)
• Returns — A new instance of Bio::Annotation::DBLink.
• Args — Named parameters. At present, the following parameters are recognized.
  • -database — the name of the database referenced by the xref
  • -primary_id — the primary (main) id of the referenced entry (usually this will be an accession number)
  • -optional_id — a secondary ID under which the referenced entry is known in the same database
  • -comment — comment text for the dbxref
  • -tagname — the name of the tag under which to add this instance to an annotation bundle (usually 'dblink')
  • -type — the type of information in the referenced entry (e.g. protein, mRNA, structure)
  • -namespace — synonymous with -database (also overrides)
  • -version — version of the referenced entry
  • -authority — attribute of the Bio::IdentifiableI interface
  • -url — attribute of the Bio::IdentifiableI interface

---

🧚 AnnotationI implementing functions 🧚

💜 as_text

• Title — as_text
• Usage — (blank)
• Function — (blank)
• Example — (blank)
• Returns — (blank)
• Args — (blank)

not me leaving the whole thing blank but that's literally what the docs say 🙈

💜 display_text

• Title — display_text
• Usage — my $str = $ann->display_text();
• Function — returns a string. Unlike as_text(), this method returns a string formatted as would be expected for te specific implementation.

One can pass a callback as an argument which allows custom text generation; the callback is passed the current instance and any text returned

• Example — (blank)
• Returns — a string
• Args — [optional] callback

💜 hash_tree

• Title — hash_tree
• Usage — (blank)
• Function — (blank)
• Example — (blank)
• Returns — (blank)
• Args — (blank)

💜 tagname

• Title — tagname
• Usage — $obj->tagname($newval)
• Function — Get/set the tagname for this annotation value.

Setting this is optional. If set, it obviates the need to provide a tag to Bio::AnnotationCollectionI when adding this object. When obtaining an AnnotationI object from the collection, the collection will set the value to the tag under which it was stored unless the object has a tag stored already.

• Example — (blank)
• Returns — value of tagname (a scalar)
• Args — new value (a scalar, optional)

---

🍓 Specific accessors for DBLinks 🍓

💅 database

• Title — database
• Usage — $self->database($newval)
• Function — set/get on the database string. Databases are just a string here which can then be interpreted elsewhere
• Example — (blank)
• Returns — value of database
• Args — newvalue (optional)

💅 primary_id

• Title — primary_id
• Usage — $self->primary_id($newval)
• Function — set/get on the primary id (a string). The primary id is the main identifier used for this object in the database. Good examples would be accession numbers. The id is meant to be the main, stable identifier for this object
• Example — (blank)
• Returns — value of primary_id
• Args — newvalue (optional)

💅 optional_id

• Title — optional_id
• Usage — $self->optional_id($newval)
• Function — get/set for the optional_id (a string)

optional id is a slot for people to use as they wish. The main issue is that some databases do not have a clean single string identifier scheme. It is hoped that the primary_id can behave like a reasonably sane "single string identifier" of objects, and people can use/abuse optional ids to their heart's content to provide precise mappings.

• Example — (blank)
• Returns — value of optional_id
• Args — newvalue (optional)

💅 comment

• Title — comment
• Usage — $self->comment($newval)
• Function — get/set of comments (comment object). Sets or gets comments of this dblink, which is sometimes relevant
• Example — (blank)
• Returns — value of comment (Bio::Annotation::Comment)
• Args — newvalue (optional)

💅 type

• Title — type
• Usage — $self->type($newval)
• Function — get/set of type. Sets or gets the type of this dblink.
• Example — $self->type('protein')
• Returns — value of type
• Args — newvalue (optional)

---

⭐ Methods for Bio::IdentifiableI compliance ⭐

🌟 object_id

• Title — object_id
• Usage — $string = $obj->object_id()
• Function — a string which represents the stable primary identifier in this namespace of this object. For DNA sequences this is its accession_number, similarly for protein sequences

This is aliased to primary_id().

• Returns — A scalar

🌟 version

• Title — version
• Usage — $version = $obj->version()
• Function — a number which differentiates between versions of the same object. Higher numbers are considered to be later and more relevant, but a single object described the same identifier should represent the same concept
• Returns — A number

🌟 url

• Title — url
• Usage — $url = $obj->url()
• Function — URL which is associated with this DB link
• Returns — string, full URL descriptor

🌟 authority

• Title — authority
• Usage — $authority = $obj->authority()
• Function — a string which represents the organisation which granted the namespace, written as the DNS name for organisation (eg, wormbase.org)
• Returns — A scalar

🌟 namespace

• Title — namespace
• Usage — $string = $obj->namespace()
• Function — A string representing the name space this identifier is valid in, often the database name or the name describing the collection

For DBLink this is the same as database().

• Returns — A scalar

---

and that's the whole page, bestie!! 💖 this was written by Ewan Birney, it's part of perl v5.32.1, dated 2021-08-15, and it ships with the User Contributed Perl Documentation. go forth and link your databases, untyped and unbothered 🦋✨👑