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

💖 Bio::SeqFeature::Collection 💖

okay bestie, welcome to the manual page for Bio::SeqFeature::Collection from the User Contributed Perl Documentation collection. she's a container class for SeqFeatures, and she is so good at what she does — finding features within a range, matching a certain feature type, all that. let's get into it 🎀

---

✨ NAME ✨

Bio::SeqFeature::Collection — a container class for SeqFeatures, suitable for performing operations such as finding features within a range, that match a certain feature type, etc. she's giving organized queen energy fr fr 💅

---

🌸 SYNOPSIS 🌸

use Bio::SeqFeature::Collection;
use Bio::Location::Simple;
use Bio::Tools::GFF;
use Bio::Root::IO;
use File::Spec;
# let's first input some features
my $gffio = Bio::Tools::GFF->new(-file => File::Spec->catfile
                               ("t","data","myco_sites.gff"),
                               -gff_version => 2);
my @features = ();
# loop over the input stream
while(my $feature = $gffio->next_feature()) {
    # do something with feature
    push @features, $feature;
}
$gffio->close();
# build the Collection object
my $col = Bio::SeqFeature::Collection->new();
# add these features to the object
my $totaladded = $col->add_features(\@features);

my @subset = $col->features_in_range(-start => 1,
                                   -end => 25000,
                                   -strand => 1,
                                   -contain => 0);
# subset should have 18 entries for this dataset
print "size is ", scalar @subset, "\n";
@subset = $col->features_in_range(-range => Bio::Location::Simple->new
                                (-start => 70000,
                                 -end => 150000,
                                 -strand => -1),
                                -contain => 1,
                                -strandmatch => 'strong');

# subset should have 22 entries for this dataset
print "size is ", scalar @subset, "\n";
print "total number of features in collection is ",
       $col->feature_count(),"\n";

like, look at her go 🦋 she literally reads a GFF file, hoovers up all the features, and then pulls out exactly the ones you want. 18 entries in the first subset, 22 in the second, no cap.

---

🌈 DESCRIPTION 🌈

so here's the tea ☕ this object will efficiently allow one to query subsets of ranges within a large collection of sequence features — and honestly, the objects just have to be Bio::RangeI compliant, that's the whole bar, she's not picky bestie 💜

how does she do it? by the creation of bins which are stored in order in a B-Tree data structure, as provided by the DB_File interface to the Berkeley DB. it's giving data structures degree, and she ate 🔥

this is based on work done by Lincoln for storage in a mysql instance — but this version is intended to be an embedded in-memory implementation for easily querying for subsets of a large range set. so like, no server, no drama, just vibes 🌸

and guess what — collections can be made persistent by keeping the indexfile and passing in the -keep flag, like this:

my $collection = Bio::SeqFeature::Collection->new(-keep => 1,
                                                 -file => 'col.idx');
$collaction->add_features(\@features);
undef $collection;

# To reuse this collection, next time you initialize a Collection object
# specify the filename and the index will be reused.
$collection = Bio::SeqFeature::Collection->new(-keep => 1,
                                              -file => 'col.idx');

yes the variable in that snippet is spelled $collaction. that's what's written, that's what we're keeping, don't @ me 😭 (she's perfect even with a typo, ok?)

---

🫶 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 the Bioperl mailing list. your participation is much appreciated — genuinely, we love to hear from you 🥹

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. give them the full context bestie, they can't debug a vibe check alone 🙈

🐛 Reporting Bugs

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

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

---

👑 AUTHOR - Jason Stajich

Email jason@bioperl.org — thank you king, the icon, the blueprint 💖

---

⭐ CONTRIBUTORS

using code and strategy developed by Lincoln Stein (lstein@cshl.org) in the Bio::DB::GFF implementation. credit also to Lincoln for suggesting using Storable to serialize features rather than my previous implementation which kept the features in memory. the glow up was real 🌈✨

---

🎀 APPENDIX 🎀

the rest of the documentation details each of the object methods. internal methods are usually preceded with a _ — so if you see an underscore, mind your business, that's private 💅

---

🧚 new

• Title — new
• Usage — my $obj = Bio::SeqFeature::Collection->new();
• Function — builds a brand new Bio::SeqFeature::Collection object ✨
• Returns — Bio::SeqFeature::Collection
• Args —
  • -minbin — minimum value to use for binning (default is 100,000,000)
  • -maxbin — maximum value to use for binning (default is 1,000)
  • -file — filename to store/read the BTREE from rather than an in-memory structure (default is false and in-memory).
  • -keep — boolean, will not remove index file on object destruction.
  • -features — Array ref of features to add initially

yes bestie, that's what the defaults say — -minbin defaults to 100,000,000 and -maxbin defaults to 1,000. we do not question the ancestors 😭

---

🦋 add_features

• Title — add_features
• Usage — $collection->add_features(\@features);
• Function —
• Returns — number of features added
• Args — arrayref of Bio::SeqFeatureI objects to index

(the Function line is literally empty in the original, she's mysterious like that 🙈)

---

🌸 features_in_range

• Title — features_in_range
• Usage — my @features = $collection->features_in_range($range)
• Function — retrieves a list of features which were contained or overlap the the requested range (see Args for way to specify overlap or only those containe)d)
• Returns — List of Bio::SeqFeatureI objects
• Args —
  • -range => Bio::RangeI object defining range to search,
  • OR
  • -start => start,
  • -end => end,
  • -strand => strand
  • -contain => boolean — true if feature must be completely contained with range, OR false if should include features that simply overlap the range. Default: true.
  • -strandmatch =>
    • 'strong' — ranges must have the same strand
    • 'weak' — ranges must have the same strand or no strand
    • 'ignore' — ignore strand information
    • Default. 'ignore'.

---

💜 remove_features

• Title — remove_features
• Usage — $collection->remove_features(\@array)
• Function — removes the requested sequence features (based on features which have the same location)
• Returns — Number of features removed
• Args — Arrayref of Bio::RangeI objects

---

✨ get_all_features

• Title — get_all_features
• Usage — my @f = $col->get_all_features()
• Function — return all the features stored in this collection (Could be large)
• Returns — Array of Bio::RangeI objects
• Args — None

she said could be large in parentheses, so like, heed the warning bestie 😭 hydrate and maybe grab a snack before you call this one

---

🎀 min_bin

• Title — min_bin
• Usage — my $minbin= $self->min_bin;
• Function — get/set the minimum value to use for binning
• Returns — integer
• Args — [optional] minimum bin value

---

💖 max_bin

• Title — max_bin
• Usage — my $maxbin= $self->max_bin;
• Function — get/set the maximum value to use for binning
• Returns — integer
• Args — [optional] maximum bin value

---

🌈 feature_count

• Title — feature_count
• Usage — my $c = $col->feature_count()
• Function — retrieve the total number of features in the collection
• Returns — integer
• Args — none

---

🍓 indexfile

• Title — indexfile
• Usage — $obj->indexfile($newval)
• Function — get/set the filename where index is kept
• Returns — value of indexfile (a filename string)
• Args — on set, new value (a filename string )

---

🌟 keep

• Title — keep
• Usage — $obj->keep($newval)
• Function — get/set boolean flag to keep the indexfile after exiting program
• Example —
• Returns — value of keep (boolean)
• Args — on set, new value (boolean)

---

and that's the whole page, bestie, we made it 🫶 this beauty ships as part of perl v5.32.1, dated 2021-08-15 — so like, she's vintage, she's classic, she's still serving 💅✨ no cap, go index something iconic 👑🌈