Bio::Species(3pm)

💖 NAME 💖

Bio::Species — it's a generic species object, bestie. That's the whole vibe. It's a 3pm page (a perl module manpage, iykyk) and it's here to hold your phylogenetic info. 🦋

---

✨ SYNOPSIS ✨

okay so here's how you actually use it:

    $species = Bio::Species->new(-classification => [@classification]);
                                    # Can also pass classification
                                    # array to new as below

    $species->classification(qw( sapiens Homo Hominidae
                                 Catarrhini Primates Eutheria
                                 Mammalia Vertebrata Chordata
                                 Metazoa Eukaryota ));

    $genus = $species->genus();

    $bi = $species->binomial();     # $bi is now "Homo sapiens"

    # For storing common name
    $species->common_name("human");

    # For storing subspecies
    $species->sub_species("accountant");

like… $bi is literally "Homo sapiens" after that call. iconic. 💅

---

🌸 DESCRIPTION 🌸

NOTE: this class is planned for deprecation in favor of the simpler Bio::Taxon. Please use that class instead. fr fr, it's the glow-up. 😭

So what is it? It provides a very simple object for storing phylogenetic information. The classification is stored in an array — and that array is a list of nodes in a phylogenetic tree. 🌳

You get access to getting and setting species and genus, but not to any of the other node types (eg: "phylum", "class", "order", "family"). There's plenty of scope for making the model more sophisticated, if this is ever needed. (not me saying "scope" like it's a personality trait 🙈)

A methods are also provided for storing common names, and subspecies. periodt.

---

🫶 FEEDBACK 🫶

💌 Mailing Lists

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to the Bioperl mailing list. Your participation is much appreciated. (we love a supportive community, no cap 💖)

 bioperl-l@bioperl.org                  - General discussion
 http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

🎀 Support

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

bioperl-l@bioperl.org

rather than to the module maintainer directly. The way that there are so many experienced and responsive experts who will be able look at the problem and quickly address it… chef's kiss. 👑

Please include a thorough description of the problem with code and data examples if at all possible. (give them the receipts, bestie 🧾)

🐛 Reporting Bugs

Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their resolution. Bug reports can be submitted via the web:

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

---

🌈 AUTHOR 🌈

James Gilbert email jgrg@sanger.ac.uk

---

⭐ CONTRIBUTORS ⭐

Sendu Bala, bix@sendu.me.uk Chris Fields, cjfields at bioperl dot org

---

👑 APPENDIX 👑

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _ (the little secret ones, iykyk 🙈).

🧚 new

• Title: new
• Usage: my $obj = Bio::Species->new(-classification => \@class)
• Function: Build a new Species object
• Returns: Bio::Species object
• Args:
  • -ncbi_taxid => NCBI taxonomic ID (optional)
  • -classification => arrayref of classification

🧚 classification

• Title: classification
• Usage:

$self->classification(@class_array);
@classification = $self->classification();

• Function: Get/set the lineage of this species. The array provided must be in the order ... ---> SPECIES, GENUS ---> KINGDOM ---> etc.
• Example: $obj->classification(qw( 'Homo sapiens' Homo Hominidae Catarrhini Primates Eutheria Mammalia Vertebrata Chordata Metazoa Eukaryota));
• Returns: Classification array
• Args: Classification array
  • OR
  • A reference to the classification array. In the latter case if there is a second argument and it evaluates to true, names will not be validated. NB: in any case, names are never validated anyway. (so… the validation is giving "vibes only" 💀)

🧚 ncbi_taxid

• Title: ncbi_taxid
• Usage: $obj->ncbi_taxid($newval)
• Function: Get/set the NCBI Taxon ID
• Returns: the NCBI Taxon ID as a string
• Args: newvalue to set or undef to unset (optional)

🧚 common_name

• Title: common_name
• Usage:

$self->common_name( $common_name );
$common_name = $self->common_name();

• Function: Get or set the common name of the species
• Example: $self->common_name('human')
• Returns: The common name in a string
• Args: String, which is the common name (optional)

🧚 division

• Title: division
• Usage: $obj->division($newval)
• Function: Genbank Division for a species
• Returns: value of division (a scalar)
• Args: value of division (a scalar)

🧚 species

• Title: species
• Usage:

$self->species( $species );
$species = $self->species();

• Function: Get or set the species name. Note that this is NOT genus and species -- use $self->binomial() for that. (read that twice bestie, it's the classic mix-up 😭)
• Example: $self->species('sapiens');
• Returns: species name as string (NOT genus and species)
• Args: species name as string (NOT genus and species)

🧚 genus

• Title: genus
• Usage:

$self->genus( $genus );
$genus = $self->genus();

• Function: Get or set the scientific genus name.
• Example: $self->genus('Homo');
• Returns: Scientific genus name as string
• Args: Scientific genus name as string

🧚 sub_species

• Title: sub_species
• Usage: $obj->sub_species($newval)
• Function: Get or set the scientific subspecies name.
• Returns: value of sub_species
• Args: newvalue (optional)

🧚 variant

• Title: variant
• Usage: $obj->variant($newval)
• Function: Get/set variant information for this species object (strain, isolate, etc).
• Example:
• Returns: value of variant (a scalar)
• Args: new value (a scalar or undef, optional)

🧚 binomial

• Title: binomial
• Usage:

$binomial = $self->binomial();
$binomial = $self->binomial('FULL');

• Function: Returns a string "Genus species", or "Genus species subspecies", if the first argument is 'FULL' (and the species has a subspecies).
• Args: Optionally the string 'FULL' to get the full name including the subspecies.
• Note: This is just munged from the taxon() name. (munged. that's the word. 🍓)

🧚 validate_species_name

• Title: validate_species_name
• Usage: $result = $self->validate_species_name($string);
• Function: Validate the species portion of the binomial
• Args: string
• Notes: The string following the "genus name" in the NCBI binomial is so variable that it's not clear that this is a useful function. Consider the binomials "Simian 11 rotavirus (serotype 3 / strain SA11-Patton)", or "St. Thomas 3 rotavirus", straight from GenBank. This is particularly problematic in microbes and viruses. As such, this isn't actually used automatically by any Bio::Species method. (so it's just… sitting there. main character energy, no plot 💀)

🧚 organelle

• Title: organelle
• Usage:

$self->organelle( $organelle );
$organelle = $self->organelle();

• Function: Get or set the organelle name
• Example: $self->organelle('Chloroplast')
• Returns: The organelle name in a string
• Args: String, which is the organelle name
• Note: TODO: We currently do not know where the organelle definition will eventually go. This is stored in the source seqfeature, though, so the information isn't lost. (okay at least it's safe 🫶)

💜 Delegation 💜

The following methods delegate to the internal Bio::Taxon instance. This is mainly to allow code continue using older methods, with the mind to migrate to using Bio::Taxon and related methods when this class is deprecated. (bridging era, we love to see it ✨)

🦋 taxon

• Title: taxon
• Usage: $obj->taxon
• Function: retrieve the internal Bio::Taxon instance
• Returns: A Bio::Taxon. If one is not previously set, an instance is created lazily
• Args: Bio::Taxon (optional)

🦋 tree

• Title: tree
• Usage: $obj->tree
• Function: Returns a Bio::Tree::Tree object
• Returns: A Bio::Tree::Tree. If one is not previously set, an instance is created lazily
• Args: Bio::Tree::Tree (optional)

---

and that's the whole page, bestie!! 🌈💖 This one's living its life as perl v5.32.1, dated 2021-08-15, under the name Bio::Species(3pm) — slay, go store some phylogeny, and remember: Bio::Taxon is the future. periodt. 💅🎀