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

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

💖 Bio::D...Feature(3pm) 💖

okay bestie, gather round, because we're doing the Bio::DB::GFF::Feature page (that's the Bio::D...Feature(3pm) man page, she's long so this is part 1 of 2, don't panic). user contributed perl documentation, iconic behavior, let's go 🫶

✨ NAME ✨

Bio::DB::GFF::Feature — a relative segment identified by a feature type 💅

✨ SYNOPSIS ✨

go look at Bio::DB::GFF. that's the whole synopsis. iykyk 🌸

✨ DESCRIPTION ✨

so Bio::DB::GFF::Feature is a stretch of sequence that corresponds to a single annotation in a GFF database. one annotation, one vibe. 🦋

she inherits from Bio::DB::GFF::RelSegment, which means she gets all the relative-addressing support that class and its ancestors have. and she also inherits from Bio::SeqFeatureI, so you get the familiar start(), stop(), primary_tag() and location() methods — and honestly? she implements Bio::LocationI too, if you need that. versatile queen 👑

Bio::DB::GFF::Feature adds new methods on top, so you can grab the annotation type, the group, and other GFF attributes. annotation types are represented by Bio::DB::GFF::Typename objects — a simple class with two methods, method() and source(). those map to the method and source fields of a GFF file. no cap.

annotation groups are doing double duty, and we love a multitasker: they give the annotation a human-readable name, and they provide higher-order groupings of subfeatures into features. the groups this module hands back are Bio::DB::GFF::Featname objects. periodt.

Bio::DB::GFF::Feature inherits from and implements the abstract methods of Bio::SeqFeatureI, which is what lets her interoperate with other Bioperl modules. friendship bracelet energy 🤝

generally though? you will not be creating or manipulating Bio::DB::GFF::Feature objects directly. you use the ones that come back from the Bio::DB::GFF::RelSegment->features() method. let the class do her thing.

⚠️ Important note about start() vs end() ⚠️

listen, this part matters. if features are derived from segments that use relative addressing (which is the default), then start() will be less than end() if the feature is on the opposite strand from the reference sequence. yes, really. 😭

this breaks Bio::SeqI compliance, but it's necessary to avoid having the real genomic locations designated by start() and end() swap places when you change reference points. it's giving "chaotic but on purpose."

to avoid this behavior, call $segment->absolute(1) before fetching features from it. that forces everything into absolute coordinates. clean, simple, slay. ✨

for example:

my $segment = $db->segment('CHROMOSOME_I');
$segment->absolute(1);
my @features = $segment->features('transcript');

🌈 API 🌈

the rest of this doc describes the public and private methods this module implements. buckle up, bestie.

🎀 new_from_parent

  • Title: new_from_parent
  • Usage: $f = Bio::DB::GFF::Feature->new_from_parent(@args);
  • Function: create a new feature object
  • Returns: new Bio::DB::GFF::Feature object
  • Args: see below
  • Status: Internal

this method gets called by Bio::DB::GFF to create a new feature using info it pulled from the GFF database. she's one of two similar constructors. this one gets called when the feature is generated from a RelSegment object, and she should inherit the coordinate system of that object. main character inherits the whole vibe 💅

the 13 arguments are positional (sorry):

$parent       a Bio::DB::GFF::RelSegment object (or descendent)
$start        start of this feature
$stop         stop of this feature
$method       this feature's GFF method
$source       this feature's GFF source
$score               this feature's score
$fstrand      this feature's strand (relative to the source
                    sequence, which has its own strandedness!)
$phase        this feature's phase
$group        this feature's group (a Bio::DB::GFF::Featname object)
$db_id        this feature's internal database ID
$group_id     this feature's internal group database ID
$tstart       this feature's target start
$tstop        this feature's target stop

tstart and tstop are not used for anything at the moment, since that info is embedded in the group object. they're just there. chilling. 🛋️

🎀 new

  • Title: new
  • Usage: $f = Bio::DB::GFF::Feature->new(@args);
  • Function: create a new feature object
  • Returns: new Bio::DB::GFF::Feature object
  • Args: see below
  • Status: Internal

also called by Bio::DB::GFF to build a new feature from GFF database info, and she's the other one of the two similar constructors. this one shows up when the feature is generated without reference to a RelSegment object, so she should use her default coordinate system (relative to herself). self-centered, and honestly? valid. ✨

the 11 arguments are positional:

$factory      a Bio::DB::GFF adaptor object (or descendent)
$srcseq       the source sequence
$start        start of this feature
$stop         stop of this feature
$method       this feature's GFF method
$source       this feature's GFF source
$score               this feature's score
$fstrand      this feature's strand (relative to the source
                    sequence, which has its own strandedness!)
$phase        this feature's phase
$group        this feature's group
$db_id        this feature's internal database ID

🎀 type

  • Title: type
  • Usage: $type = $f->type([$newtype])
  • Function: get or set the feature type
  • Returns: a Bio::DB::GFF::Typename object
  • Args: a new Typename object (optional)
  • Status: Public

gets or sets the type of the feature. the type is a Bio::DB::GFF::Typename object, which encapsulates the feature method and source. two-for-one, obsessed. 💖

the method() and source() methods described right below are the shortcuts to the individual fields of the type. 👑

🎀 method

  • Title: method
  • Usage: $method = $f->method([$newmethod])
  • Function: get or set the feature method
  • Returns: a string
  • Args: a new method (optional)
  • Status: Public

gets or sets the feature method. it's a convenience feature that delegates the whole task to the feature's type object. she's not doing the work herself, she's managing. 💅

🎀 source

  • Title: source
  • Usage: $source = $f->source([$newsource])
  • Function: get or set the feature source
  • Returns: a string
  • Args: a new source (optional)
  • Status: Public

gets or sets the feature source. again, pure delegation to the feature's type object. iconic, low effort, high reward. 🦋

🎀 score

  • Title: score
  • Usage: $score = $f->score([$newscore])
  • Function: get or set the feature score
  • Returns: a string
  • Args: a new score (optional)
  • Status: Public

gets or sets the feature score. that's it, that's the method. 🍓

🎀 phase

  • Title: phase
  • Usage: $phase = $f->phase([$phase])
  • Function: get or set the feature phase
  • Returns: a string
  • Args: a new phase (optional)
  • Status: Public

gets or sets the feature phase. yes the arg and the method have the same name, we don't make the rules. 🙈

🎀 strand

  • Title: strand
  • Usage: $strand = $f->strand
  • Function: get the feature strand
  • Returns: +1, 0 -1
  • Args: none
  • Status: Public

returns the strand of the feature. but unlike the other methods, the strand cannot be changed once the object is created — and that's due to coordinate considerations. she's set in her ways. no editing her after the fact. 💀

🎀 group

  • Title: group
  • Usage: $group = $f->group([$new_group])
  • Function: get or set the feature group
  • Returns: a Bio::DB::GFF::Featname object
  • Args: a new group (optional)
  • Status: Public

gets or sets the feature group. the group is a Bio::DB::GFF::Featname object, which has an ID and a class. two little fields, so much power. 👑

🎀 display_id

  • Title: display_id
  • Usage: $display_id = $f->display_id([$display_id])
  • Function: get or set the feature display id
  • Returns: a Bio::DB::GFF::Featname object
  • Args: a new display_id (optional)
  • Status: Public

this method is just an alias for group(). it exists for Bio::SeqFeatureI compatibility. same girl, different name tag. 🎀

🎀 info

  • Title: info
  • Usage: $info = $f->info([$new_info])
  • Function: get or set the feature group
  • Returns: a Bio::DB::GFF::Featname object
  • Args: a new group (optional)
  • Status: Public

another alias for group(), this time for AcePerl compatibility. she contains multitudes. 🌸

🎀 target

  • Title: target
  • Usage: $target = $f->target([$new_target])
  • Function: get or set the feature target
  • Returns: a Bio::DB::GFF::Homol object
  • Args: a new group (optional)
  • Status: Public

works like group(), but she only returns the group if it implements the start() method. that's typical for similarity/assembly features, where the target encodes the start and stop location of the alignment. 📍

the returned object is of type Bio::DB::GFF::Homol, which is a subclass of Bio::DB::GFF::Segment. family tree, but make it biology. 🌈

🎀 flatten_target

  • Title: flatten_target
  • Usage: $target = $f->flatten_target($f->target)
  • Function: flatten a target object
  • Returns: a string (GFF2), an array [GFF2.5] or an array ref [GFF3]
  • Args: a target object (required), GFF version (optional)
  • Status: Public

this flattens a target object into text so you can dump GFF. if you pass a second argument, version-specific vocabulary gets used for the flattened target. speak her language, bestie. 💅

🎀 hit

  • Title: hit
  • Usage: $hit = $f->hit([$new_hit])
  • Function: get or set the feature hit
  • Returns: a Bio::DB::GFF::Featname object
  • Args: a new group (optional)
  • Status: Public

this is the same as target(), for compatibility with Bio::SeqFeature::SimilarityPair. twin behavior, we love to see it. 👯

🎀 id

  • Title: id
  • Usage: $id = $f->id
  • Function: get the feature ID
  • Returns: a database identifier
  • Args: none
  • Status: Public

retrieves the database identifier for the feature. it cannot be changed. read-only, no notes. 🚫✏️

🎀 group_id

  • Title: group_id
  • Usage: $id = $f->group_id
  • Function: get the feature ID
  • Returns: a database identifier
  • Args: none
  • Status: Public

retrieves the database group identifier for the feature, and nope, she cannot be changed either. often the group identifier is more useful than the feature identifier, since it's used to refer to a complex object containing subparts. the group id is the one with the lore. 🔥

🎀 clone

  • Title: clone
  • Usage: $feature = $f->clone
  • Function: make a copy of the feature
  • Returns: a new Bio::DB::GFF::Feature object
  • Args: none
  • Status: Public

returns a copy of the feature. dupe her, she doesn't mind. 💖

🎀 compound

  • Title: compound
  • Usage: $flag = $f->compound([$newflag])
  • Function: get or set the compound flag
  • Returns: a boolean
  • Args: a new flag (optional)
  • Status: Public

gets or sets a flag indicating that the feature is not a primary one from the database, but rather the result of aggregation. she's built different — literally, she was assembled. 🧚

🎀 sub_SeqFeature

  • Title: sub_SeqFeature
  • Usage: @feat = $feature->sub_SeqFeature([$method])
  • Function: get subfeatures
  • Returns: a list of Bio::DB::GFF::Feature objects
  • Args: a feature method (optional)
  • Status: Public

...and that's where part 1 leaves you, bestie. part 2 is coming, don't go anywhere 🫶

Okay so this method is giving you a list of every subfeature that belongs to the main feature. Iconic. And if your feature has a whole mix of different subfeatures, you can filter by passing a method name. Also, you can call this method as segments() or get_SeqFeatures() — same vibe, different name. 💅

add_subfeature 💖

  • Title: add_subfeature
  • Usage: $feature->add_subfeature($feature)
  • Function: add a subfeature to the feature
  • Returns: nothing
  • Args: a Bio::DB::GFF::Feature object
  • Status: Public

This method adds a new subfeature to the object. It's used internally by aggregators, but it's available for public use as well. So go off, bestie. ✨

attach_seq 🎀

  • Title: 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
  • Example: (none provided)
  • Returns: TRUE on success
  • Args: a Bio::PrimarySeqI compliant object

location 🗺️

  • Title: 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: none

entire_seq 🧬

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

merged_segments 🔥

  • Title: merged_segments
  • Usage: @segs = $feature->merged_segments([$method])
  • Function: get merged subfeatures
  • Returns: a list of Bio::DB::GFF::Feature objects
  • Args: a feature method (optional)
  • Status: Public

This method acts like sub_SeqFeature, except that it merges overlapping segments of the same time into contiguous features. Not a typo, bestie — it says "same time". For those features that contain heterogeneous subfeatures, you can retrieve a subset of the subfeatures by providing a method name to filter on.

A side-effect of this method is that the features are returned in sorted order by their start tposition. (Yes, "tposition". We keep it exactly as it is.)

sub_types 🧚

  • Title: sub_types
  • Usage: @methods = $feature->sub_types
  • Function: get methods of all sub-seqfeatures
  • Returns: a list of method names
  • Args: none
  • Status: Public

For those features that contain subfeatures, this method will return a unique list of method names of those subfeatures, suitable for use with sub_SeqFeature().

attributes 💅

  • Title: attributes
  • Usage: @attributes = $feature->attributes($name)
  • Function: get the "attributes" on a particular feature
  • Returns: an array of string
  • Args: feature ID
  • Status: public

Some GFF version 2 files use the groups column to store a series of attribute/value pairs. In this interpretation of GFF, the first such pair is treated as the primary group for the feature; subsequent pairs are treated as attributes. Two attributes have special meaning: "Note" is for backward compatibility and is used for unstructured text remarks. "Alias" is considered as a synonym for the feature name.

@gene_names = $feature->attributes('Gene');
@aliases    = $feature->attributes('Alias');

If no name is provided, then attributes() returns a flattened hash, of attribute=>value pairs. This lets you do:

%attributes = $db->attributes;

notes 📝

  • Title: notes
  • Usage: @notes = $feature->notes
  • Function: get the "notes" on a particular feature
  • Returns: an array of string
  • Args: feature ID
  • Status: public

Some GFF version 2 files use the groups column to store various notes and remarks. Adaptors can elect to store the notes in the database, or just ignore them. For those adaptors that store the notes, the notes() method will return them as a list.

aliases 🏷️

  • Title: aliases
  • Usage: @aliases = $feature->aliases
  • Function: get the "aliases" on a particular feature
  • Returns: an array of string
  • Args: feature ID
  • Status: public

This method will return a list of attributes of type 'Alias'.

Autogenerated Methods ✨

  • Title: AUTOLOAD
  • Usage: @subfeat = $feature->Method
  • Function: Return subfeatures using autogenerated methods
  • Returns: a list of Bio::DB::GFF::Feature objects
  • Args: none
  • Status: Public

Any method that begins with an initial capital letter will be passed to AUTOLOAD and treated as a call to sub_SeqFeature with the method name used as the method argument. For instance, this call:

@exons = $feature->Exon;

is equivalent to this call:

@exons = $feature->sub_SeqFeature('exon');

SeqFeatureI methods 🦋

The following Bio::SeqFeatureI methods are implemented:

primary_tag(), source_tag(), all_tags(), has_tag(), each_tag_value() [renamed get_tag_values()].

adjust_bounds 📏

  • Title: adjust_bounds
  • Usage: $feature->adjust_bounds
  • Function: adjust the bounds of a feature
  • Returns: ($start,$stop,$strand)
  • Args: none
  • Status: Public

This method adjusts the boundaries of the feature to enclose all its subfeatures. It returns the new start, stop and strand of the enclosing feature.

sort_features 🔀

  • Title: sort_features
  • Usage: $feature->sort_features
  • Function: sort features
  • Returns: nothing
  • Args: none
  • Status: Public

This method sorts subfeatures in ascending order by their start position. For reverse strand features, it sorts subfeatures in descending order. After this is called sub_SeqFeature will return the features in order.

This method is called internally by merged_segments().

asString 🧾

  • Title: asString
  • Usage: $string = $feature->asString
  • Function: return human-readabled representation of feature
  • Returns: a string
  • Args: none
  • Status: Public

This method returns a human-readable representation of the feature and is called by the overloaded "" operator.

gff_string 📜

  • Title: gff_string
  • Usage: $string = $feature->gff_string
  • Function: return GFF2 of GFF2.5 representation of feature
  • Returns: a string
  • Args: none
  • Status: Public

gff3_string 🧬

  • Title: gff3_string
  • Usage: $string = $feature->gff3_string([$recurse])
  • Function: return GFF3 representation of feature
  • Returns: a string
  • Args: An optional flag, which if true, will cause the feature to recurse over subfeatures.
  • Status: Public

version 🏷️

  • Title: version
  • Usage: $feature->version()
  • Function: get/set the GFF version to be returned by gff_string
  • Returns: the GFF version (default is 2)
  • Args: the GFF version (2, 2.5 of 3)
  • Status: Public
  • Title: cmap_link
  • Usage: $link = $feature->cmap_link
  • Function: returns a URL link to the corresponding feature in cmap
  • Returns: a string
  • Args: none
  • Status: Public

If integrated cmap/gbrowse installation, it returns a link to the map otherwise it returns a link to a feature search on the feature name. See the cmap documentation for more information.

This function is intended primarily to be used in gbrowse conf files. For example:

link       = sub {my $self = shift; return $self->cmap_viewer_link(data_source);}

A Note About Similarities 🌈

The current default aggregator for GFF "similarity" features creates a composite Bio::DB::GFF::Feature object of type "gapped_alignment". The target() method for the feature as a whole will return a RelSegment object that is as long as the extremes of the similarity hit target, but will not necessarily be the same length as the query sequence. The length of each "similarity" subfeature will be exactly the same length as its target(). These subfeatures are essentially the HSPs of the match.

The following illustrates this:

@similarities = $segment->feature('similarity:BLASTN');
$sim          = $similarities[0];

print $sim->type;        # yields "gapped_similarity:BLASTN"

$query_length  = $sim->length;
$target_length = $sim->target->length;  # $query_length != $target_length

@matches = $sim->Similarity;   # use autogenerated method
$query1_length  = $matches[0]->length;
$target1_length = $matches[0]->target->length; # $query1_length == $target1_length

If you merge segments by calling merged_segments(), then the length of the query sequence segments will no longer necessarily equal the length of the targets, because the alignment information will have been lost. Nevertheless, the targets are adjusted so that the first and last base pairs of the query match the first and last base pairs of the target.

BUGS 💀

This module is still under development.

SEE ALSO 👀

bioperl, Bio::DB::GFF, Bio::DB::RelSegment

AUTHOR 💜

Lincoln Stein <lstein@cshl.org>.

Copyright (c) 2001 Cold Spring Harbor Laboratory.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

And that's a wrap, bestie! 💖 This page came from perl v5.30.0, dated 2020-01-13, for Bio::D...Feature(3pm). Stay iconic, keep slaying those features, and remember: the vibe changes, the facts do not. 💅✨

📦 where this page comes from