Bio::S...otated(3pm)

📦
version 1.6.905 · 2 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

🌸 Bio::SeqFeature::Annotated(3pm) 🌸

okay bestie, welcome to the manual page for Bio::SeqFeature::Annotated, straight outta the User Contributed Perl Documentation. It's giving ✨under construction✨ energy, but we're gonna read it together 💅

🎀 NAME 🎀

Bio::SeqFeature::Annotated — PLEASE PUT SOMETHING HERE 💀

(yes, that's literally what it says. iconic. no cap.)

📜 SYNOPSIS 📜

# none yet, complain to authors

💬 DESCRIPTION 💬

None yet, complain to authors. 🙈 fr fr, that's the whole thing.

🧬 Implemented Interfaces 🧬

This class implements the following interfaces, bestie:

  • Bio::SeqFeatureI — and note that this includes implementing Bio::RangeI.
  • Bio::AnnotatableI
  • Bio::FeatureHolderI — features held by a feature are essentially sub-features.

🫶 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 one of the Bioperl mailing lists. Your participation is much appreciated. 🥹

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. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible. 🙏

🐛 Reporting Bugs

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

http://bugzilla.open-bio.org/

👑 AUTHOR - Allen Day 👑

Allen Day <allenday at ucla.edu>

📖 APPENDIX 📖

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _.

🌈 PREAMBLE 🌈

Okay, where to start... 😅

The original idea for this class appears to lump all SeqFeatureI data (primary_tag, source_tag, etc) into AnnotationI objects into an Bio::Annotation::Collection. The type is then checked against SOFA.

There have been several requests to have type checking be optionally run.

and then it just... dumps this list of methods at us. here they all are, no skips, no cuts:

  • Bio::FeatureHolderI::create_hierarchy_from_ParentIDs
  • Bio::FeatureHolderI::feature_count
  • Bio::FeatureHolderI::get_all_SeqFeatures
  • Bio::FeatureHolderI::set_ParentIDs_from_hierarchy
  • Bio::RangeI::contains
  • Bio::RangeI::disconnected_ranges
  • Bio::RangeI::equals
  • Bio::RangeI::intersection
  • Bio::RangeI::offsetStranded
  • Bio::RangeI::overlap_extent
  • Bio::RangeI::overlaps
  • Bio::RangeI::subtract
  • Bio::RangeI::union
  • Bio::SeqFeature::Annotated::Dumper
  • Bio::SeqFeature::Annotated::MAX_TYPE_CACHE_MEMBERS
  • Bio::SeqFeature::Annotated::add_Annotation
  • Bio::SeqFeature::Annotated::add_SeqFeature
  • Bio::SeqFeature::Annotated::add_tag_value
  • Bio::SeqFeature::Annotated::add_target
  • Bio::SeqFeature::Annotated::annotation
  • Bio::SeqFeature::Annotated::attach_seq
  • Bio::SeqFeature::Annotated::display_name
  • Bio::SeqFeature::Annotated::each_target
  • Bio::SeqFeature::Annotated::end
  • Bio::SeqFeature::Annotated::entire_seq
  • Bio::SeqFeature::Annotated::frame
  • Bio::SeqFeature::Annotated::from_feature
  • Bio::SeqFeature::Annotated::get_Annotations
  • Bio::SeqFeature::Annotated::get_SeqFeatures
  • Bio::SeqFeature::Annotated::get_all_tags
  • Bio::SeqFeature::Annotated::get_tag_values
  • Bio::SeqFeature::Annotated::get_tagset_values
  • Bio::SeqFeature::Annotated::has_tag
  • Bio::SeqFeature::Annotated::length
  • Bio::SeqFeature::Annotated::location
  • Bio::SeqFeature::Annotated::name
  • Bio::SeqFeature::Annotated::new
  • Bio::SeqFeature::Annotated::phase
  • Bio::SeqFeature::Annotated::primary_tag
  • Bio::SeqFeature::Annotated::remove_Annotations
  • Bio::SeqFeature::Annotated::remove_SeqFeatures
  • Bio::SeqFeature::Annotated::remove_tag
  • Bio::SeqFeature::Annotated::score
  • Bio::SeqFeature::Annotated::seq
  • Bio::SeqFeature::Annotated::seq_id
  • Bio::SeqFeature::Annotated::source
  • Bio::SeqFeature::Annotated::source_tag
  • Bio::SeqFeature::Annotated::start
  • Bio::SeqFeature::Annotated::strand
  • Bio::SeqFeature::Annotated::type
  • Bio::SeqFeature::Annotated::uri_escape
  • Bio::SeqFeature::Annotated::uri_unescape
  • Bio::SeqFeature::TypedSeqFeatureI::croak
  • Bio::SeqFeature::TypedSeqFeatureI::ontology_term
  • Bio::SeqFeatureI::generate_unique_persistent_id
  • Bio::SeqFeatureI::gff_string
  • Bio::SeqFeatureI::primary_id
  • Bio::SeqFeatureI::spliced_seq

🎀 ATTRIBUTE ACCESSORS FOR Bio::SeqFeature::Annotated 🎀

🌟 from_feature

  • Usage: $obj->from_feature($myfeature);
  • Desc: initialize this object with the contents of another feature object. Useful for converting objects like L<Bio::SeqFeature::Generic> to this class.
  • Ret: nothing meaningful
  • Args: a single object of some other feature type,
  • Side Effects: throws error on failure
  • Example:

🌟 seq_id()

  • Usage: $obj->seq_id($newval)
  • Function: holds a string corresponding to the unique seq_id of the sequence underlying the feature (e.g. database accession or primary key).
  • Returns: string representing the seq_id.
  • Args: on set, some string or a Bio::Annotation::SimpleValue object.

🌟 name()

  • Usage: $obj->name($newval)
  • Function: human-readable name for the feature.
  • Returns: value of name (a scalar)
  • Args: on set, new value (a scalar or undef, optional)

🌟 type()

  • Usage: $obj->type($newval)
  • Function: a SOFA type for the feature.
  • Returns: Bio::Annotation::OntologyTerm object representing the type. NB: to get a string, use primary_tag().
  • Args: on set, Bio::Annotation::OntologyTerm object. NB: to set a string (SOFA name or identifier), use primary_tag()

🌟 source()

  • Usage: $obj->source($newval)
  • Function: holds the source of the feature.
  • Returns: a Bio::Annotation::SimpleValue representing the source. NB: to get a string, use source_tag()
  • Args: on set, a Bio::Annotation::SimpleValue object. NB: to set a string, use source_tag()

🌟 score()

  • Usage:
$score = $feat->score()
$feat->score($score)
  • Function: holds a value corresponding to the score of the feature.
  • Returns: a string representing the score.
  • Args: on set, a scalar or a Bio::Annotation::SimpleValue object.

🌟 phase()

  • Usage:
$phase = $feat->phase()
$feat->phase($phase)
  • Function: get/set on phase information
  • Returns: a string 0,1,2,'.'
  • Args: on set, one of 0,1,2,'.' or a Bio::Annotation::SimpleValue object holding one of 0,1,2,'.' as its value.

🌟 frame()

  • Usage:
$frame = $feat->frame()
$feat->frame($phase)
  • Function: get/set on phase information
  • Returns: a string 0,1,2,'.'
  • Args: on set, one of 0,1,2,'.' or a Bio::Annotation::SimpleValue object holding one of 0,1,2,'.' as its value.

🧚 SHORTCUT METHODS TO ACCESS Bio::AnnotatableI INTERFACE METHODS 🧚

💫 add_Annotation()

  • Usage:
  • Function: $obj->add_Annotation() is a shortcut to $obj->annotation->add_Annotation
  • Returns:
  • Args:

💫 remove_Annotations()

  • Usage:
  • Function: $obj->remove_Annotations() is a shortcut to $obj->annotation->remove_Annotations
  • Returns:
  • Args:

🔥 INTERFACE METHODS FOR Bio::SeqFeatureI 🔥

Note that no methods are deprecated. Any SeqFeatureI methods must return strings (no objects).

heads up bestie: strings only, no objects. that's the vibe check.
  • display_name()
  • primary_tag()
  • source_tag()

🦋 attach_seq()

  • Usage: $sf->attach_seq($seq)
  • Function: Attaches a Bio::Seq object to this feature. This Bio::Seq object is for the entire sequence: ie from 1 to 10000
  • Returns: TRUE on success
  • Args: a Bio::PrimarySeqI compliant object

🦋 seq()

  • Usage: $tseq = $sf->seq()
  • Function: returns a truncated version of seq() with bounds matching this feature
  • Returns: sub seq (a Bio::PrimarySeqI compliant object) on attached sequence bounded by start & end, or undef if there is no sequence attached
  • Args: none

🦋 entire_seq()

  • Usage: $whole_seq = $sf->entire_seq()
  • Function: gives the entire sequence that this seqfeature is attached to
  • Returns: a Bio::PrimarySeqI compliant object, or undef if there is no sequence attached
  • Args: none

💜 INTERFACE METHODS FOR Bio::RangeI 💜

as inherited via Bio::SeqFeatureI 🫶

🌸 length()

  • Usage: $feature->length()
  • Function: Get the feature length computed as $feat->end - $feat->start + 1
  • Returns: integer
  • Args: none

🌸 start()

  • Usage: $obj->start($newval)
  • Function: Get/set on the start coordinate of the feature
  • Returns: integer
  • Args: on set, new value (a scalar or undef, optional)

🌸 end()

  • Usage: $obj->end($newval)
  • Function: Get/set on the end coordinate of the feature
  • Returns: integer
  • Args: on set, new value (a scalar or undef, optional)

🌸 strand()

  • Usage: $strand = $feat->strand($newval)
  • Function: get/set on strand information, being 1,-1 or 0
  • Returns: -1,1 or 0
  • Args: on set, new value (a scalar or undef, optional)

🌈 INTERFACE METHODS FOR Bio::FeatureHolderI 🌈

This includes methods for retrieving, adding, and removing features. Since this is already a feature, features held by this feature holder are essentially sub-features.

🍓 get_SeqFeatures

  • Usage: @feats = $feat->get_SeqFeatures();
  • Function: Returns an array of Bio::SeqFeatureI objects
  • Returns: An array
  • Args: none

🍓 add_SeqFeature()

  • Usage:
$feat->add_SeqFeature($subfeat);
$feat->add_SeqFeature($subfeat,'EXPAND')
  • Function: adds a SeqFeature into the subSeqFeature array. with no 'EXPAND' qualifer, subfeat will be tested as to whether it lies inside the parent, and throw an exception if not.

If EXPAND is used, the parent''s start/end/strand will be adjusted so that it grows to accommodate the new subFeature

  • Example:
  • Returns: nothing
  • Args: a Bio::SeqFeatureI object

🍓 remove_SeqFeatures()

  • Usage: $obj->remove_SeqFeatures
  • Function: Removes all sub SeqFeatures. If you want to remove only a subset, remove that subset from the returned array, and add back the rest.
  • Returns: The array of Bio::SeqFeatureI implementing sub-features that was deleted from this feature.
  • Args: none

okay and that's only part 1, bestie — the rest of the methods are coming in part 2 🫶✨

🌈 INTERFACE METHODS FOR Bio::AnnotatableI 🌈

💖 annotation()

Usage   : $obj->annotation($annot_obj)
Function: Get/set the annotation collection object for annotating this
          feature.
Returns : A Bio::AnnotationCollectionI object
Args    : newvalue (optional)

okay so this is the get/set for the annotation collection object that does the annotating for this feature. hand it a newvalue if you want to set one, or don't, it's optional bestie. you get back a Bio::AnnotationCollectionI object. 💅

🦋 location()

Usage   : my $location = $seqfeature->location()
Function: returns a location object suitable for identifying location
          of feature on sequence or parent feature
Returns : Bio::LocationI object
Args    : [optional] Bio::LocationI object to set the value to.

gives u a location object, the kind that's good for pinning down where a feature lives on a sequence or on a parent feature. returns a Bio::LocationI object. and yes u can pass in a Bio::LocationI object to set the value, but it's optional, no pressure. ✨

🌸 add_target()

Usage   : $seqfeature->add_target(Bio::LocatableSeq->new(...));
Function: adds a target location on another reference sequence for this feature
Returns : true on success
Args    : a Bio::LocatableSeq object

drops a target location on a different reference sequence for this feature. pass it a Bio::LocatableSeq object, get back true when it works. slay. 🔥

🎀 each_target()

Usage   : @targets = $seqfeature->each_target();
Function: Returns a list of Bio::LocatableSeqs which are the locations of this object.
          To obtain the "primary" location, see L</location()>.
Returns : a list of 0..N Bio::LocatableSeq objects
Args    : none

hands u back a list of Bio::LocatableSeqs that are the locations of this object — could be anywhere from 0 to N of them, no cap. if u want the primary location instead, that's over at L</location()>. takes no args, it's that easy. 💜

🫶 _expand_region

Title   : _expand_region
Usage   : $self->_expand_region($feature);
Function: Expand the total region covered by this feature to
          accomodate for the given feature.

          May be called whenever any kind of subfeature is added to this
          feature. add_SeqFeature() already does this.
Returns :
Args    : A Bio::SeqFeatureI implementing object.

stretches the total region this feature covers so it can fit the given feature in. it's fine to call this whenever any kind of subfeature gets added to this feature — and btw add_SeqFeature() is already out here doing it for u. takes a Bio::SeqFeatureI-implementing object. no documented return value, so don't come looking for one. 🙈

⭐ get_Annotations

Usage   : my $parent   = $obj->get_Annotations('Parent');
          my @parents = $obj->get_Annotations('Parent');
Function: a wrapper around Bio::Annotation::Collection::get_Annotations().
Returns : returns annotations as
          Bio::Annotation::Collection::get_Annotations() does, but
          additionally returns a single scalar in scalar context
          instead of list context so that if an annotation tag
          contains only a single value, you can do:

          $parent = $feature->get_Annotations('Parent');

          instead of:

          ($parent) = ($feature->get_Annotations('Parent'))[0];

          if the 'Parent' tag has multiple values and is called in a
          scalar context, the number of annotations is returned.

Args    : an annotation tag name.

this one is a lil wrapper around Bio::Annotation::Collection::get_Annotations(). it gives u back annotations the same way that does, but — plot twist — in scalar context it returns a single scalar instead of doing the whole list-context thing. so if ur annotation tag only holds one value, u get to just write:

$parent = $feature->get_Annotations('Parent');

instead of the lowkey tragic:

($parent) = ($feature->get_Annotations('Parent'))[0];

but heads up 🫣 — if the 'Parent' tag has multiple values and u call it in scalar context, u get back the number of annotations. takes an annotation tag name. the way that's so convenient fr fr. 💖

👑 Bio::SeqFeatureI implemented methods 👑

these are specialized implementations of SeqFeatureI methods that call up the internal Bio::Annotation::AnnotationCollection object. story time: just before the 1.5 release, the methods below got moved from Bio::SeqFeatureI over to Bio::AnnotatableI, and Bio::SeqFeatureI was made to inherit from Bio::AnnotatableI. that move forced every single Bio::SeqFeatureI-implementing class to use Bio::AnnotationI objects for any data at all. and the core devs all agreed — consensus, bestie — that this should get rolled back in favor of a more flexible approach: roll back the changes above and make this class Bio::AnnotatableI. so the SeqFeatureI tag-related methods got reimplemented to approximate the same behavior as before. iconic recovery honestly. ✨

the methods below let u map the "get_tag_values()"-style annotation access onto Bio::AnnotationCollectionI. these do not need to be implemented in a Bio::AnnotationCollectionI-compliant class, because they're built on top of the methods. for usage, see Bio::SeqFeatureI. 🌈

has_tag

no usage block on this one bestie, the manpage just names it — go peek at Bio::SeqFeatureI for the deets. 💅

add_tag_value

same situation, no usage block here either — it's just chillin' in the list. 💜

🍓 get_tag_values

Usage   : @annotations = $obj->get_tag_values($tag)
Function: returns annotations corresponding to $tag
Returns : a list of scalars
Args    : tag name

returns the annotations that match $tag. u get a list of scalars back. hand it a tag name. simple as. 🌸

🧚 get_tagset_values

Usage   : @annotations = $obj->get_tagset_values($tag1,$tag2)
Function: returns annotations corresponding to a list of tags.
          this is a convenience method equivalent to multiple calls
          to get_tag_values with each tag in the list.
Returns : a list of Bio::AnnotationI objects.
Args    : a list of tag names

returns the annotations for a whole list of tags — it's a convenience method that's literally equivalent to calling get_tag_values once for each tag in the list. returns a list of Bio::AnnotationI objects. args are a list of tag names. obsessed. 🎀

💀 get_all_tags

Usage   : @tags = $obj->get_all_tags()
Function: returns a list of annotation tag names.
Returns : a list of tag names
Args    : none

gives u a list of all the annotation tag names. that's it. no args, no drama. 👑

🙈 remove_tag

Usage   : See remove_Annotations().
Function:
Returns :
Args    :
Note    : Contrary to what the name suggests, this method removes
          all annotations corresponding to $tag, not just a
          single anntoation.

usage is over at remove_Annotations(), and there's no function, returns or args spelled out here. but the note is important bestie, so listen up: contrary to what the name is giving, this method removes all annotations corresponding to $tag — not just a single annotation. do not let the singular name gaslight u. 😭

and that's a wrap on the whole page, bestie!! 💖✨ this was pulled straight from the perl v5.30.0 docs, dated 2020-01-13, and it's the Bio::S...otated(3pm) page — go annotate something gorgeous, u absolute main character. 🦋👑💅

📦 where this page comes from