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

💖 NAME 💖

Bio::DB::SeqFeature — a normalized feature for use with Bio::DB::SeqFeature::Store. Yes bestie, this whole page is about that one little object. She's the default girlie. ✨

---

🌸 SYNOPSIS 🌸

use Bio::DB::SeqFeature::Store;

# Open the sequence database
my $db      = Bio::DB::SeqFeature::Store->new( -adaptor => 'DBI::mysql',
                                               -dsn     => 'dbi:mysql:test');
my ($feature)   = $db->get_features_by_name('ZK909');
my @subfeatures = $feature->get_SeqFeatures();
my @exons_only  = $feature->get_SeqFeatures('exon');

# create a new object
my $new = $db->new_feature(-primary_tag=>'gene',
                           -seq_id     => 'chr3',
                           -start      => 10000,
                           -end        => 11000);

# add a new exon
$feature->add_SeqFeature($db->new_feature(-primary_tag=>'exon',
                                          -seq_id     => 'chr3',
                                          -start      => 5000,
                                          -end        => 5551));

---

🦋 DESCRIPTION 🦋

Okay so. The Bio::DB::SeqFeature object is the default SeqFeature class stored inside Bio::DB::SeqFeature databases. She implements both the Bio::DB::SeqFeature::NormalizedFeatureI interface and the Bio::DB::SeqFeature::NormalizedTableFeatureI interface — and the way that translates, bestie, is that her subfeatures (if she has any) get stored in the database in a normalized fashion, and the parent/child hierarchy of features and subfeatures is also stored in the database as a set of tuples. It's giving organized. It's giving efficient. Both storage and retrieval speed get the glow-up. 💅

Typically you will not create a Bio::DB::SeqFeature directly — you'll just ask the database to do it on your behalf, exactly like it's described in Bio::DB::SeqFeature::Store. Let the database do the work, that's her whole thing.

✨ new ✨

• Title: new
• Usage: $feature = Bio::DB::SeqFeature::NormalizedFeature->new(@args)
• Function: create a new feature
• Returns: the new seqfeature
• Args: see below
• Status: public

This method creates — and if it possibly can, stores into a database — a brand new Bio::DB::SeqFeature::NormalizedFeature object, using the specialized Bio::DB::SeqFeature class. She's built different.

The arguments are the same as Bio::SeqFeature::Generic->new() and Bio::Graphics::Feature->new(). The most important difference is the -store option, which — if present — creates the object in a Bio::DB::SeqFeature::Store database. And then there's the -index option, which controls whether the feature will be indexed for retrieval (default is true). Ordinarily you'd only want to turn indexing on when you're creating top level features, and off only when you're storing subfeatures. The default is on. Periodt.

Arguments are as follows:

• -seq_id — the reference sequence
• -start — the start position of the feature
• -end — the stop position of the feature
• -display_name — the feature name (returned by seqname)
• -primary_tag — the feature type (returned by primary_tag)
• -source — the source tag
• -score — the feature score (for GFF compatibility)
• -desc — a description of the feature
• -segments — a list of subfeatures (see Bio::Graphics::Feature)
• -subtype — the type to use when creating subfeatures
• -strand — the strand of the feature (one of -1, 0 or +1)
• -phase — the phase of the feature (0..2)
• -url — a URL to link to when rendered with Bio::Graphics
• -attributes — a hashref of tag value attributes, in which the key is the tag and the value is an array reference of values
• -store — a previously-opened Bio::DB::SeqFeature::Store object
• -index — index this feature if true

Aliases, because sometimes one name just isn't enough 💅:

• -id — an alias for -display_name
• -seqname — an alias for -display_name
• -display_id — an alias for -display_name
• -name — an alias for -display_name
• -stop — an alias for end
• -type — an alias for primary_tag

🌈 Bio::SeqFeatureI methods 🌈

The following Bio::SeqFeatureI methods are supported, no cap:

seq_id(), start(), end(), strand(), get_SeqFeatures(),
display_name(), primary_tag(), source_tag(), seq(),
location(), primary_id(), overlaps(), contains(), equals(),
intersection(), union(), has_tag(), remove_tag(),
add_tag_value(), get_tag_values(), get_all_tags()

Some methods that do not make sense in the context of a genome annotation database system — like attach_seq(), for example — are not supported. Sorry bestie, she simply doesn't do that.

Please see Bio::SeqFeatureI for more details.

🎀 add_SeqFeature 🎀

• Title: add_SeqFeature
• Usage: $flag = $feature->add_SeqFeature(@features)
• Function: Add subfeatures to the feature
• Returns: true if successful
• Args: list of Bio::SeqFeatureI objects
• Status: public

Add one or more subfeatures to the feature. For best results, subfeatures should be of the same class as the parent feature (i.e. do not try mixing Bio::DB::SeqFeature::NormalizedFeature with other feature types — that's a vibe clash, don't do it).

An alias for this method is add_segment().

🧚 update 🧚

• Title: update
• Usage: $flag = $feature->update()
• Function: Update feature in the database
• Returns: true if successful
• Args: none
• Status: public

After changing any fields in the feature, call update() to write it to the database. This is not needed for add_SeqFeature() — because update() gets invoked automatically there. She's proactive like that. ✨

💜 get_SeqFeatures 💜

• Title: get_SeqFeature
• Usage: @subfeatures = $feature->get_SeqFeatures([@types])
• Function: return subfeatures of this feature
• Returns: list of subfeatures
• Args: list of subfeature primary_tags (optional)
• Status: public

This method extends the Bio::SeqFeatureI get_SeqFeatures() slightly by letting you pass a list of primary_tags — and in that case, only subfeatures whose primary_tag is contained on the list will be returned. Without any types passed, all subfeatures are returned. Filtering is self-care. 🫶

🍓 object_store 🍓

• Title: object_store
• Usage: $store = $feature->object_store([$new_store])
• Function: get or set the database handle
• Returns: current database handle
• Args: new database handle (optional)
• Status: public

This method will get or set the Bio::DB::SeqFeature::Store object that's associated with the feature. After changing the store, you should probably unset the primary_id() of the feature and call update() — that way you can be sure the object is written into the database as a new feature. Main character energy, brand new ID.

👑 overloaded_names 👑

• Title: overloaded_names
• Usage: $overload = $feature->overloaded_names([$new_overload])
• Function: get or set overloading of object strings
• Returns: current flag
• Args: new flag (optional)
• Status: public

For convenience, when objects of this class are stringified, they get represented in the form "primary_tag(display_name)". To turn this feature off, call overloaded_names() with a false value. You can invoke this on an individual feature object or on the class itself:

Bio::DB::SeqFeature::NormalizedFeature->overloaded_names(0);

🌸 segment 🌸

• Title: segment
• Usage: $segment = $feature->segment
• Function: return a Segment object corresponding to feature
• Returns: a Bio::DB::SeqFeature::Segment
• Args: none
• Status: public

This turns the feature into a Bio::DB::SeqFeature::Segment object, which you can then use to query for overlapping features. See Bio::DB::SeqFeature::Segment. Glow-up complete. 💖

⭐ AUTOLOADED methods ⭐

@subfeatures = $feature->Exon;

If you use an unknown method that begins with a capital letter, then the feature autogenerates a call to get_SeqFeatures() using the lower-cased method name as the primary_tag. In other words $feature->Exon is equivalent to:

@subfeature s= $feature->get_SeqFeatures('exon')

😭 okay yes, that line is literally how it's written in the source doc — the space in @subfeature s and all. Not me fixing it, I'm just the messenger, bestie. The meaning is clear: it's $feature->get_SeqFeatures('exon') with the array named @subfeatures.

🦋 load_id 🦋

• Title: load_id
• Usage: $id = $feature->load_id
• Function: get the GFF3 load ID
• Returns: the GFF3 load ID (string)
• Args: none
• Status: public

For features that were originally loaded by the GFF3 loader, this method returns the GFF3 load ID. This method may not be supported in future versions of the module. So like… enjoy her while she's here. 💀

🌈 primary_id 🌈

• Title: primary_id
• Usage: $id = $feature->primary_id([$new_id])
• Function: get/set the database ID of the feature
• Returns: the current primary ID
• Args: none
• Status: public

This method gets or sets the primary ID of the feature in the underlying Bio::DB::SeqFeature::Store database. If you change this field and then call update(), it will have the effect of making a copy of the feature in the database under a new ID. Two of her. Clone era. 🙈

💅 target 💅

• Title: target
• Usage: $segment = $feature->target
• Function: return the segment correspondent to the "Target" attribute
• Returns: a Bio::DB::SeqFeature::Segment object
• Args: none
• Status: public

For features that are aligned with others via the GFF3 Target attribute, this returns a segment corresponding to the aligned region. The CIGAR gap string is not yet supported. She's working on it, okay?

🧚 Internal methods 🧚

• $feature->as_string() — Internal method used to implement overloaded stringification.
• $boolean = $feature->type_match(@list_of_types) — Internal method that will return true if the primary_tag of the feature and source_tag match any of the list of types (in primary_tag:source_tag format) provided.

---

💀 BUGS 💀

This is an early version, so there are certainly some bugs. Please use the BioPerl bug tracking system to report bugs. Be nice about it, she's growing. 🫶

---

🎀 SEE ALSO 🎀

bioperl, Bio::DB::SeqFeature::Store, Bio::DB::SeqFeature::Segment, Bio::DB::SeqFeature::NormalizedFeature, Bio::DB::SeqFeature::GFF3Loader, Bio::DB::SeqFeature::Store::DBI::mysql, Bio::DB::SeqFeature::Store::bdb

---

🌟 AUTHOR 🌟

Lincoln Stein <lstein@cshl.org>.

Copyright (c) 2006 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 the whole page, bestie — documented by the Perl crew, perl v5.40.0, dated 2024-10-11, and rewritten with love by your girl. slay, go annotate some genomes 💖✨🎀