Bio::SeqFeatureI(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

✨ Bio::SeqFeatureI ✨

okay so bestie, welcome to Bio::SeqFeatureI 💖 — this is a User Contributed Perl Documentation page, and it's the whole ~vibe~ of a Sequence Feature. Grab a snack, this one's a two-parter 🍓

🌸 NAME 🌸

Bio::SeqFeatureI — the Abstract interface of a Sequence Feature. no cap, that's literally it 💅

🦋 SYNOPSIS 🦋

okay so imagine you got yourself a seqfeature somehow, like from a Sequence with Features attached:

# get a seqfeature somehow, eg, from a Sequence with Features attached

foreach $feat ( $seq->get_SeqFeatures() ) {
    print "Feature from ", $feat->start, "to ",
          $feat->end, " Primary tag  ", $feat->primary_tag,
          ", produced by ", $feat->source_tag(), "\n";

    if ( $feat->strand == 0 ) {
        print "Feature applicable to either strand\n";
    }
    else {
        print "Feature on strand ", $feat->strand,"\n"; # -1,1
    }

    print "feature location is ",$feat->start, "..",
          $feat->end, " on strand ", $feat->strand, "\n";
    print "easy utility to print locations in GenBank/EMBL way ",
          $feat->location->to_FTstring(), "\n";

    foreach $tag ( $feat->get_all_tags() ) {
        print "Feature has tag ", $tag, " with values, ",
              join(' ',$feat->get_tag_values($tag)), "\n";
    }
    print "new feature\n" if $feat->has_tag('new');
    # features can have sub features
    my @subfeat = $feat->get_SeqFeatures();
}

like, that's the whole tour right there, it's giving "everything you'd ever wanna ask a feature" 🫶

💜 DESCRIPTION 💜

So this interface is the set of functions you can expect for any Sequence Feature — no matter how it's implemented, and no matter whether it's a fancier more complex type (eg, a Gene). This object does not actually provide any implementation — it's just the definitions of what methods you can call, like a menu with no kitchen behind it 😭. If you want a real, solid, standard implementation of this object, go look at Bio::SeqFeature::Generic ✨

🎀 FEEDBACK 🎀

User feedback is an integral part of the evolution of this and other Bioperl modules, fr fr. 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 and 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. iykyk — the more context you give, the faster someone slays your bug 💅

💀 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:

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

🧚 APPENDIX 🧚

The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _ — that underscore is the "staff only" door, bestie 🙈

👑 Bio::SeqFeatureI specific methods 👑

New method interfaces. ✨

🦋 get_SeqFeatures 🦋

  • Title: get_SeqFeatures
  • Usage: @feats = $feat->get_SeqFeatures();
  • Function: Returns an array of sub Sequence Features
  • Returns: An array
  • Args: none

🌸 display_name 🌸

  • Title: display_name
  • Usage: $name = $feat->display_name()
  • Function: Returns the human-readable name of the feature for displays.
  • Returns: a string
  • Args: none

💖 primary_tag 💖

  • Title: primary_tag
  • Usage: $tag = $feat->primary_tag()
  • Function: Returns the primary tag for a feature, eg 'exon'
  • Returns: a string
  • Args: none

🎀 source_tag 🎀

  • Title: source_tag
  • Usage: $tag = $feat->source_tag()
  • Function: Returns the source tag for a feature, eg, 'genscan'
  • Returns: a string
  • Args: none

⭐ has_tag ⭐

  • Title: has_tag
  • Usage: $tag_exists = $self->has_tag('some_tag')
  • Function:
  • Returns: TRUE if the specified tag exists, and FALSE otherwise
  • Args:

💜 get_tag_values 💜

  • Title: get_tag_values
  • Usage: @values = $self->get_tag_values('some_tag')
  • Function:
  • Returns: An array comprising the values of the specified tag.
  • Args: a string
throws an exception if there is no such tag 😭

🍓 get_tagset_values 🍓

  • Title: get_tagset_values
  • Usage: @values = $self->get_tagset_values(qw(label transcript_id product))
  • Function:
  • Returns: An array comprising the values of the specified tags, in order of tags
  • Args: An array of strings
does NOT throw an exception if none of the tags are not present

this method is useful for getting a human-readable label for a SeqFeatureI; not all tags can be assumed to be present, so a list of possible tags in preferential order is provided 🫶

🌈 get_all_tags 🌈

  • Title: get_all_tags
  • Usage: @tags = $feat->get_all_tags()
  • Function: gives all tags for this feature
  • Returns: an array of strings
  • Args: none

🧚 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

Note that it is not guaranteed that if you obtain a feature from an object in bioperl, it will have a sequence attached. Also, implementors of this interface can choose to provide an empty implementation of this method. I.e., there is also no guarantee that if you do attach a sequence, seq() or entire_seq() will not return undef.

The reason that this method is here on the interface is to enable you to call it on every SeqFeatureI compliant object, and that it will be implemented in a useful way and set to a useful value for the great majority of use cases. Implementors who choose to ignore the call are encouraged to specifically state this in their documentation.

  • Example:
  • Returns: TRUE on success
  • Args: a Bio::PrimarySeqI compliant object

💅 seq 💅

  • Title: seq
  • Usage: $tseq = $sf->seq()
  • Function: returns the truncated sequence (if there is a sequence attached) for this feature
  • Example:
  • Returns: sub seq (a Bio::PrimarySeqI compliant object) on attached sequence bounded by start & end, or undef if there is no sequence attached. If the strand is defined and set to -1, the returned sequence is the reverse-complement of the region
  • 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:
  • Returns: a Bio::PrimarySeqI compliant object, or undef if there is no sequence attached
  • Args: none

💀 seq_id 💀

  • Title: seq_id
  • Usage: $obj->seq_id($newval)
  • Function: There are many cases when you make a feature that you do know the sequence name, but do not know its actual sequence. This is an attribute such that you can store the ID (e.g., display_id) of the sequence.

This attribute should not be used in GFF dumping, as that should come from the collection in which the seq feature was found.

  • Returns: value of seq_id
  • Args: newvalue (optional)

🎀 gff_string 🎀

  • Title: gff_string
  • Usage: $str = $feat->gff_string; $str = $feat->gff_string($gff_formatter);
  • Function: Provides the feature information in GFF format.

The implementation provided here returns GFF2 by default. If you want a different version, supply an object implementing a method gff_string() accepting a SeqFeatureI object as argument. E.g., to obtain GFF1 format, do the following:

my $gffio = Bio::Tools::GFF->new(-gff_version => 1);
$gff1str = $feat->gff_string($gff1io);
  • Returns: A string
  • Args: Optionally, an object implementing gff_string().

🙈 _static_gff_formatter 🙈

  • Title: _static_gff_formatter
  • Usage:
  • Function:
  • Example:
  • Returns:
  • Args:

okay so that's the whole first half and every single field is exactly where it should be — don't go anywhere, there's more 👑

🎀 Decorating methods 🎀

okay so these ones right here? Bio::SeqFeatureI already hands you a working implementation for every single one of them 💖 — but subclasses are totally validly allowed to overwrite them with their own version. no cap.

✨ spliced_seq ✨

  • Title: spliced_seq
  • Usage:
    • $seq = $feature->spliced_seq()
    • $seq = $feature_with_remote_locations->spliced_seq($db_for_seqs)
  • Function: bestie, this hands you the sequence of the feature that is the most semantically "relevant" one for this sequence. there's a default implementation, and for the simple cases it just returns the sequence, but for split cases it loops over the split location to get the sequence back out. now — split locations with remote locations, like
join(AB000123:5567-5589,80..1144)

when a database object gets passed in, it'll try to pull the sequence from that database object and "Do the right thing" 😌. but if no database object shows up? it'll generate the correct number of N's (DNA) or X's (protein, though this is unlikely 👀).

this function is deliberately "magical" — it's out here trying to second-guess what you want as "the" sequence for this feature. honestly iconic behaviour.

and implementing classes are free to override this method with their own magic if they've got a better idea what the user actually wants 🪄.

  • Args (all optional):
    • -db — a Bio::DB::RandomAccessI compliant object, for when you need to retrieve remote seqs.
    • -nosort — boolean, if the locations should not be sorted by start location. this can happen, for instance, in a circular sequence where a gene span starts before the end of the sequence and ends after the sequence start. Example: join(15685..16260,1..207) (default = if sequence is_circular(), 1, otherwise 0).
    • -phase — truncates the returned sequence based on the intron phase (0,1,2).
  • Returns: A Bio::PrimarySeqI object 🌸

📍 location 📍

  • Title: location
  • Usage: my $location = $seqfeature->location()
  • Function: returns a location object suitable for identifying the location of the feature on the sequence, or on the parent feature.
  • Returns: Bio::LocationI object
  • Args: none

🆔 primary_id 🆔

  • Title: primary_id
  • Usage: $obj->primary_id($newval)
  • Function: (the manpage just leaves this one blank, bestie 💀)
  • Example: (also blank, we move)
  • Returns: value of primary_id (a scalar)
  • Args: on set, new value (a scalar or undef, optional)

Primary ID is a synonym for the tag 'ID' — iykyk 💅

🔢 phase 🔢

  • Title: phase
  • Usage: $obj->phase($newval)
  • Function: get/set this feature's phase.
  • Example: (blank, nothing to see here)
  • Returns: undef if no phase is set, otherwise 0, 1, or 2 (the only valid values for phase)
  • Args: on set, the new value

Most features do not have or need a defined phase.

but for features representing a CDS, the phase tells you where the feature begins with reference to the reading frame 📖. the phase is one of the integers 0, 1, or 2, and it means the number of bases that should be removed from the beginning of this feature to reach the first base of the next codon. in other words:

  • a phase of "0" means the next codon begins at the first base of the region described by the current line
  • a phase of "1" means the next codon begins at the second base of this region
  • a phase of "2" means the codon begins at the third base of this region
🚨 do NOT confuse this with the frame, bestie. the frame is simply start modulo 3. two different things, do not mix them up, this is a vibe check you will fail if you mix them up 😭

for forward strand features, phase is counted from the start field. for reverse strand features, phase is counted from the end field. periodt. 💅

🌈 Bio::RangeI methods 🌈

these ones are inherited from RangeI and can be used directly straight off a SeqFeatureI interface 🫶. remember that a SeqFeature is-a RangeI, so wherever you see RangeI you can just drop a feature in there ($r in the documentation below, that's your feature).

start()

See Bio::RangeI ✨

end()

See Bio::RangeI ✨

strand()

See Bio::RangeI ✨

overlaps()

See Bio::RangeI ✨

contains()

See Bio::RangeI ✨

equals()

See Bio::RangeI ✨

intersection()

See Bio::RangeI ✨

union()

See Bio::RangeI ✨

and that's the whole page, bestie 🎀🦋 you made it to the end, main character energy fr fr. quick shoutout to the footer legends: this is from perl v5.32.1, dated 2021-08-15, and it's the Bio::SeqFeatureI(3pm) page. obsessed. bye 💖

📦 where this page comes from