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

💖 NAME 💖

Bio::DB::SeqFeature::Segment — location-based access to genome annotation data. bestie, that's the whole pitch. it's the lil' object that stands in for a chunk of the genome so you don't have to keep typing coordinates over and over. 💅

it comes to you courtesy of the User Contributed Perl Documentation, page Bio::DB::SeqFeature::Segment(3pm). 🎀

---

✨ 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 $segment  = $db->segment('Chr1',5000=>6000);
my @features = $segment->features('mRNA','match');

---

🦋 DESCRIPTION 🦋

okay so the segment object makes life with Bio::DB::SeqFeature store so much easier, because it acts as a placeholder for a region of the genome. like, a little bookmark. a vibe. 🫶

instead of writing this whole dramatic statement:

@features = $db->features(-seq_id=>'Chr1',
                          -start=>5000,
                          -end=>6000,
                          -types=>['mRNA','match','repeat_region']);

you get to write these instead:

$segment = $db->segment('Chr1',5000=>6000);
@features = $segment->features('mRNA','match','repeat_region');

same result, way less typing. slay. ✨

you can also spin up a segment from an existing SeqFeature object — the range gets picked up straight from the SeqFeature boundaries:

$segment = Bio::DB::SeqFeature::Segment->new($feature);        # for Bio::DB::SeqFeature
$segment = Bio::DB::SeqFeature::Segment->new($feature,$store); # for other Bio::SeqFeatureI objects

and the segment object implements the full Bio::SeqFeature::CollectionI interface, which means you can iterate over every single feature in the range. icon behavior, honestly. 👑

---

👑 PUBLIC METHODS 👑

these are the public methods, i.e. the ones that are meant for you to use from outside. come thru. 🌸

💫 new

• Title: new
• Usage: $segment = Bio::DB::SeqFeature::Segment->new(@options)
• Function: create a new Segment object
• Returns: A Bio::DB::SeqFeature::Segment object
• Args: several — see below
• Status: public

this class method creates a Bio::DB::SeqFeature::Segment object. you must provide a Bio::DB::SeqFeature::Store as well as the coordinates of the segment. these arguments can be handed over explicitly or indirectly — dealer's choice, bestie.

First form:

$segment = Bio::DB::SeqFeature::Segment->new($store,$seqid,$start,$end,$strand)

in this form a segment is defined by a Bio::DB::SeqFeature::Store, the sequence ID, the start, end and strand. this is the form that gets invoked internally by Bio::DB::SeqFeature::Store when you call its segment() method. lowkey the main character of the two forms. 🎀

Second form:

$segment = Bio::DB::SeqFeature::Segment->new($seqfeature [,$store]);

in this form, you pass new() a Bio::SeqFeatureI object. the segment is constructed from the seq_id, and the coordinates are taken from the object. if you pass a store-aware seqfeature object (e.g. Bio::DB::SeqFeature) then the store database is also derived from the feature. otherwise you will have to pass the store as a second argument. no store, no segment, that's the rule. 💅

🔍 features

• Title: features
• Usage: @features = $segment->features(@args)
• Function: fetch seqfeatures that overlap the segment
• Returns: list of features
• Args: see below
• Status: Public

this is the workhorse for feature query and retrieval. it takes a series of -name=>$value arguments as filter arguments, and features that match all the filters are returned. all of them. every filter. it's giving thorough. ✨

here's the full rundown of arguments:

Location filters:

• -strand — Strand
• -range_type — Type of range match ('overlaps','contains','contained_in')

Name filters:

• -name — Name of feature (may be a glob expression)
• -aliases — If true, match aliases as well as display names
• -class — Archaic argument for backward compatibility. (-class=>'Clone',-name=>'ABC123') is equivalent to (-name=>'Clone:ABC123')

Type filters:

• -types — List of feature types (array reference) or one type (scalar)
• -type — Synonym for the above
• -primary_tag — Synonym for the above
• -attributes — Hashref of attribute=>value pairs as per get_features_by_attribute(). Multiple alternative values can be matched by providing an array reference.
• -attribute — synonym for -attributes

this is identical to the Bio::DB::SeqFeature::Store->features() method, except that the -seq_id, -start, and -end arguments are provided by the segment object. if a simple list of arguments is provided, then the list is taken to be the set of feature types (primary tags) to filter on. easy. 🦋

Examples:

all features that overlap the current segment:

@features = $segment->features;

all features of type mRNA that overlap the current segment:

@features = $segment->features('mRNA');

all features that are completely contained within the current segment:

@features = $segment->features(-range_type=>'contains');

all "confirmed" mRNAs that overlap the current segment:

@features = $segment->features(-attributes=>{confirmed=>1},-type=>'mRNA');

🔁 get_seq_stream

• Title: get_seq_stream
• Usage: $iterator = $segment->get_seq_stream(@args)
• Function: return an iterator across all features in the database
• Returns: a Bio::DB::SeqFeature::Store::Iterator object
• Args: (optional) the feature() method
• Status: public

this is identical to Bio::DB::SeqFeature::Store->get_seq_stream() except that the location filter is always automatically applied, so the iterator you receive returns features that overlap the segment's region. automatic. iconic. 💫

when called without any arguments this method will return an iterator object that will traverse all indexed features in the database that overlap the segment's region. call the iterator's next_seq() method to step through them (in no particular order):

my $iterator = $db->get_seq_stream;
while (my $feature = $iterator->next_seq) {
  print $feature->primary_tag,' ',$feature->display_name,"\n";
}

you can select a subset of features by passing a series of filter arguments. the arguments are identical to those accepted by $segment->features().

get_feature_stream() ican be used as a synonym for this method.

🗄️ store

• Title: store
• Usage: $store = $segment->store
• Function: return the Bio::DB::SeqFeature::Store object associated with the segment
• Returns: a Bio::DB::SeqFeature::Store: object
• Args: none
• Status: public

🏷️ primary_tag, type,

• Title: primary_tag,type
• Usage: $primary_tag = $segment->primary_tag
• Function: returns the string "region"
• Returns: "region"
• Args: none
• Status: public

the primary_tag method returns the constant tag "region". type() is a synonym for this method.

💬 as_string

• Title: as_string
• Usage: $name = $segment->as_string
• Function: expands the object into a human-readable string
• Returns: "seq_id:start..end"
• Args: none
• Status: public

the as_string() method is overloaded into the "" operator so that the object is represented as a human readable string in the form "seq_id:start..end" when used in a string context. so it just prints pretty. obsessed. 🥰

📐 rel2abs

• Title: rel2abs
• Usage: @coords = $s->rel2abs(@coords)
• Function: convert relative coordinates into absolute coordinates
• Returns: a list of absolute coordinates
• Args: a list of relative coordinates
• Status: Public

this function takes a list of positions in relative coordinates to the segment, and converts them into absolute coordinates.

📏 abs2rel

• Title: abs2rel
• Usage: @rel_coords = $s->abs2rel(@abs_coords)
• Function: convert absolute coordinates into relative coordinates
• Returns: a list of relative coordinates
• Args: a list of absolute coordinates
• Status: Public

this function takes a list of positions in absolute coordinates and returns a list expressed in relative coordinates.

🧬 Bio::SeqFeatureI compatibility methods

for convenience, segments are interchangeable with Bio::SeqFeature objects in many cases. this means that segments can be passed to BioPerl modules that expect Bio::SeqFeature objects and they should work as expected. the primary tag of segment objects is "region" (SO:0000001 "Continous sequence >=1 base pair"). ✨

all these methods are read-only except for the primary_id, which can be get or set. don't forget that part, bestie. ⚠️

the following Bio::SeqFeatureI methods are supported:

• start
• end
• seq_id
• strand
• length
• display_name
• primary_id
• primary_tag (always returns "region")
• source_tag (always returns "Bio::DB::SeqFeature::Segment")
• get_SeqFeatures (always returns an empty list)
• seq
• entire_seq
• location
• All Bio::RangeI methods

---

💀 BUGS 💀

this is an early version, so there are certainly some bugs. 😭 please use the BioPerl bug tracking system to report bugs. do not suffer in silence, we're fixing it together. 🫶

---

🌈 SEE ALSO 🌈

• bioperl
• Bio::DB::SeqFeature::Store
• 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 💖 this one's perl v5.40.0, dated 2024-10-11, straight from the User Contributed Perl Documentation. go forth and segment. 🦋✨👑