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

🌸 Bio::DB::SeqFeature::NormalizedFeature 🌸

User Contributed Perl Documentation · section 3pm

okay bestie, sit DOWN, grab a strawberry 🍓, because this is the manual page for Bio::DB::SeqFeature::NormalizedFeature and it's actually kind of a serve. it's a normalized feature for use with Bio::DB::SeqFeature::Store, and yes, we're doing the whole thing, no skimming, no "you get the gist" energy. periodt. 💅

---

✨ NAME ✨

Bio::DB::SeqFeature::NormalizedFeature — Normalized feature for use with Bio::DB::SeqFeature::Store

---

📜 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
$db->seqfeature_class('Bio::DB::SeqFeature::NormalizedFeature');
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 💖

so the Bio::DB::SeqFeature::NormalizedFeature object is basically an alt representation of SeqFeatures, made to vibe with the Bio::DB::SeqFeature::Store database system. it's identical to Bio::DB::SeqFeature, with one tiny lil plot twist: instead of storing the feature/subfeature relationships in a database table, all that info lives inside the object itself. iconic behavior honestly. the tradeoff? these objects are lowkey inconvenient to work with straight from SQL, but it does speed up access somewhat. slay for speed, awkward for SQL. 🦋

to use this class, you just pass its name to the Bio::DB::SeqFeature::Store object's seqfeature_class() method. after that, $db->new_feature() will create objects of type Bio::DB::SeqFeature::NormalizedFeature. and if you're using the GFF3 loader, pass Bio::DB::SeqFeature::Store::GFF3Loader->new() the -seqfeature_class argument:

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

my $store  = connect_to_db_somehow();
my $loader = Bio::DB::SeqFeature::Store::GFF3Loader->new(
              -store=>$db,
              -seqfeature_class => 'Bio::DB::SeqFeature::NormalizedFeature'
             );

---

🎀 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 can, also stores into a database — a brand new Bio::DB::SeqFeature::NormalizedFeature object, using the specialized Bio::DB::SeqFeature class. main character creation moment fr fr. 👑

the arguments are the same as Bio::SeqFeature::Generic->new() and Bio::Graphics::Feature->new(). the biggest difference is the -store option, which — if it's present — creates the object in a Bio::DB::SeqFeature::Store database, plus the -index option, which controls whether the feature gets indexed for retrieval (default is true). ordinarily you'd only wanna turn indexing on when you're creating top level features, and off only when you're storing subfeatures. the default is on. ✨

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, aka the nicknames bestie goes by:

-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 🧬

these are the Bio::SeqFeatureI methods that are supported:

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 just don't make sense in the context of a genome annotation database system — like attach_seq() — are not supported. don't come for them, they're simply not invited to the function. 🙈

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 — so like, do not try mixing Bio::DB::SeqFeature::NormalizedFeature with other feature types, that's a chaos vibe nobody asked for. 😭

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 you change 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. it's giving self-sufficient. 💅

---

🦋 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 — in which case only subfeatures whose primary_tag is contained on that list get returned. and if you pass no types at all? all subfeatures come back. no filter, full send. ✨

---

🍓 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 gets or sets the Bio::DB::SeqFeature::Store object that's associated with the feature. after changing the store, you should probably unset the feature's primary_id() and call update() to make sure the object gets written into the database as a new feature. lowkey important, don't skip it.

---

⭐ 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 get stringified, they're represented in the form "primary_tag(display_name)". to turn this feature off, call overloaded_names() with a false value. you can invoke it on an individual feature object or on the class:

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. it's giving glow-up into a whole new form. 🧚

---

👑 AUTOLOADED methods 👑

@subfeatures = $feature->Exon;

if you use an unknown method that begins with a capital letter, 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')

if you use an unknown method that begins with Tag_(tagname), Att_(tagname), Is_(tagname), then it'll be the same as calling the each_tag_value() method with the tagname. in a list context, these autogenerated procedures return the list of results. in scalar context, they return the first item in the list!! (not the whole thing, just the first one, ok bestie, don't get caught out 💀)

---

🎀 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. heads up though — this method may not be supported in future versions of the module. so like, don't build your whole personality around it. 😭

---

🌈 notes 🌈

Title   : notes
Usage   : @notes = $feature->notes
Function: get contents of the GFF3 Note tag
Returns : List of GFF3 Note tags
Args    : none
Status  : public

for features that were originally loaded by the GFF3 loader, this method returns the contents of the Note tag as a list. it's a convenience for Bio::Graphics, which looks for notes() when it constructs a default description line. cute lil helper. 🫶

---

💜 primary_id 💜

Title   : primary_id
Usage   : $id = $feature->primary_id([$new_id])
Function: get/set the feature's database ID
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. and here's the tea: if you change this field and then call update(), it'll have the effect of making a copy of the feature in the database under a new ID. not a rename — a whole new copy. mind the plot twist. 💅

---

🦋 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. someday, bestie. someday. 🙈

---

🧚 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 feature's primary_tag 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. no gatekeeping the bug reports, we all grow together. 🫶

---

👀 SEE ALSO 👀

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

👑 AUTHOR 👑

Okay bestie, credit where credit is due, because we do NOT plagiarize in this house 💅

• Lincoln Stein — the actual legend, reachable at lstein@cshl.org ✨
• Copyright (c) 2006 Cold Spring Harbor Laboratory. 🧬

---

And now the legal bit, but make it cute:

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

fr fr, that's the whole license. Same terms as Perl, no cap. Go wild, remix it, ship it, just keep it free like that 🫶

---

perl v5.40.0 · 2024-10-11 · Bio::D...eature(3pm)

That's the whole page, bestie — this doc was generated straight from perl v5.40.0 back on 2024-10-11, and it lives under the name Bio::D...eature(3pm). Take care of her, she's iconic 💖✨🎀