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

💖 Bio::Das::SegmentI — DAS-style access to a feature database 💖

hey bestie 🫶 so you found yourself in the Bio::Das::SegmentI manual (that's the User Contributed Perl Documentation section, in case you were wondering which little corner of the man pages you wandered into). Buckle up, because this one is a whole vibe — it's the interface that gives you DAS-style access to a feature database, and we're gonna go through it together, no skips, no skimming. ✨

---

🌸 NAME 🌸

Bio::Das::SegmentI — DAS-style access to a feature database. that's it, that's the name 💅

---

✨ SYNOPSIS ✨

okay so picture this: you already have a Bio::DasI database object, and you want a segment out of it. boom:

# Get a Bio::Das::SegmentI object from a Bio::DasI database...

$segment = $das->segment(-name=>'Landmark',
                         -start=>$start,
                         -end => $end);

@features = $segment->overlapping_features(-type=>['type1','type2']);
# each feature is a Bio::SeqFeatureI-compliant object

@features = $segment->contained_features(-type=>['type1','type2']);

@features = $segment->contained_in(-type=>['type1','type2']);

$stream = $segment->get_feature_stream(-type=>['type1','type2','type3'];
while (my $feature = $stream->next_seq) {
   # do something with feature
}

$count = $segment->features_callback(-type=>['type1','type2','type3'],
                                     -callback => sub { ... { }
                                     );

yes, that synopsis is doing a lot of heavy lifting and also being a little chaotic 😭 but it's giving "here's every way you can pull features out of a segment" and honestly? iconic. 🎀

---

🌈 DESCRIPTION 🌈

Bio::Das::SegmentI is a simplified alternative interface to sequence annotation databases, the kind used by the distributed annotation system. In this scheme, the genome is represented as a series of landmarks. 🗺️

Every single Bio::Das::SegmentI object — we call it a "segment" for short, iykyk — corresponds to a genomic region defined by a landmark plus a start and end position relative to that landmark. And how do you get one of these little guys? You make it with the Bio::DasI segment() method. periodt. 👑

---

💫 Filtering your features 💫

Features can be filtered by the following attributes, and yes you have options bestie:

1. their location relative to the segment — whether they're overlapping, contained within, or completely containing it 📍
2. their type 🏷️
3. other attributes, using tag/value semantics 🧚

---

🦋 The three APIs (a vibe check) 🦋

Access to the feature list uses three distinct APIs:

1. fetching the entire list of features at a time 📋
2. fetching an iterator across features 🔁
3. a callback 📞

three whole ways to get your features, pick your fighter 💜

---

💌 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 one of the Bioperl mailing lists. Your participation is much appreciated, fr fr. 🫶

bioperl-l@bio.perl.org

🛟 Support

Please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. real talk: there are so many experienced and reponsive experts who 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. 🙏

🐛 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

do it, the maintainers will literally love you for it 🍓

---

👑 AUTHOR - Lincoln Stein 👑

Email lstein@cshl.org

shoutout to Lincoln, absolute legend, main character energy ⭐

---

okay that's part 1 bestie, there's more coming so don't go anywhere 💖

✨ APPENDIX ✨

okay so the rest of this doc is literally every single object method, one by one 💅 internal methods usually get a lil underscore _ in front, that's the vibe check.

---

🌸 seq_id

• Title — seq_id
• Usage — $ref = $s->seq_id
• Function — return the ID of the landmark
• Returns — a string
• Args — none
• Status — Public

🌸 display_name

• Title — seq_name
• Usage — $ref = $s->seq_name
• Function — return the human-readable name for the landmark
• Returns — a string
• Args — none
• Status — Public

ngl, this one defaults to being the same as seq_id.

🌸 start

• Title — start
• Usage — $s->start
• Function — start of segment
• Returns — integer
• Args — none
• Status — Public

this is a read-only accessor for the start of the segment 🫶 and it's an alias to low() for Gadfly compatibility, periodt.

🌸 end

• Title — end
• Usage — $s->end
• Function — end of segment
• Returns — integer
• Args — none
• Status — Public

read-only accessor for the end of the segment 💖 alias to high() for Gadfly compatibility, no cap.

🌸 length

• Title — length
• Usage — $s->length
• Function — length of segment
• Returns — integer
• Args — none
• Status — Public

returns the length of the segment. always a positive number ✨ the way it refuses to be negative? iconic.

🌸 seq

• Title — seq
• Usage — $s->seq
• Function — get the sequence string for this segment
• Returns — a string
• Args — none
• Status — Public

gives you the sequence for this segment as a simple string 🌈

🌸 ref

• Title — ref
• Usage — $ref = $s->ref([$newlandmark])
• Function — get/set the reference landmark for addressing
• Returns — a string
• Args — none
• Status — Public

so this method lets you examine/change the reference landmark that establishes the coordinate system 👑 by default the landmark cannot be changed, so this ends up doing the same thing as seq_id(). the new landmark might be an ID, or it might be another Das::SegmentI object. your call bestie.

🌸 absolute

• Title — absolute
• Usage — $s->absolute([$new_value])
• Function — get/set absolute addressing mode
• Returns — flag
• Args — new flag (optional)
• Status — Public

turns absolute-addressing mode on and off 💅 in absolute addressing mode, coordinates are relative to some underlying "top level" coordinate system (like a chromosome). ref() returns the identity of the top level landmark, and start() and end() return locations relative to that landmark. in relative addressing mode, coordinates are relative to the landmark sequence specified when the segment was created — or later modified by the ref() method.

default behaviour: returns false, and does nothing when you try to set absolute addressing mode. it's giving "no thoughts, head empty" and honestly that's by design 🙈

🌸 features

• Title — features
• Usage — @features = $s->features(@args)
• Function — get features that overlap this segment
• Returns — a list of Bio::SeqFeatureI objects
• Args — see below
• Status — Public

this method finds all the features that intersect the segment in a whole buncha ways and returns a list of Bio::SeqFeatureI objects 🎀 the feature locations will use coordinates relative to the reference sequence in effect at the time that features() was called.

the returned list can be limited to certain types, attributes or range intersection modes. types of range intersection are one of:

"overlaps"      the default
"contains"      return features completely contained within the segment
"contained_in"  return features that completely contain the segment

two types of argument lists are accepted ✨ in the positional argument form, the arguments are treated as a list of feature types. in the named parameter form, the arguments are a series of -name=>value pairs.

  Argument    Description
  --------   ------------

  -types      An array reference to type names in the format
              "method:source"

  -attributes A hashref containing a set of attributes to match

  -rangetype  One of "overlaps", "contains", or "contained_in".

  -iterator   Return an iterator across the features.

  -callback   A callback to invoke on each feature

the -attributes argument is a hashref containing one or more attributes to match against 🦋 like this:

  -attributes => { Gene => 'abc-1',
                   Note => 'confirmed' }

attribute matching is simple string matching, and multiple attributes are ANDed together 💖 want something fancier? use the -callback option (see below).

if -iterator is true, then the method returns an object reference that implements the next_seq() method. each call to next_seq() returns a new Bio::SeqFeatureI object 👑

if -callback is passed a code reference, that code reference will be invoked on each feature returned. the code gets passed two arguments — the current feature and the segment object itself — and it must return a true value. if the code returns a false value, feature retrieval will be aborted. brutal but fair 💀

-callback and -iterator are mutually exclusive, bestie. if -iterator is defined, then -callback is ignored. pick a lane 🌸

NOTE: the following methods all build on top of features(), and do not need to be explicitly implemented.

    overlapping_features()
    contained_features()
    contained_in()
    get_feature_stream()

🌸 overlapping_features

• Title — overlapping_features
• Usage — @features = $s->overlapping_features(@args)
• Function — get features that overlap this segment
• Returns — a list of Bio::SeqFeatureI objects
• Args — see below
• Status — Public

identical to features() except it defaults to finding overlapping features. lowkey the same girl, different outfit 💅

🌸 contained_features

• Title — contained_features
• Usage — @features = $s->contained_features(@args)
• Function — get features that are contained in this segment
• Returns — a list of Bio::SeqFeatureI objects
• Args — see below
• Status — Public

identical to features() except it defaults to a range type of 'contained' ✨

🌸 contained_in

• Title — contained_in
• Usage — @features = $s->contained_in(@args)
• Function — get features that contain this segment
• Returns — a list of Bio::SeqFeatureI objects
• Args — see below
• Status — Public

identical to features() except it defaults to a range type of 'contained_in' 🌈

🌸 get_feature_stream

• Title — get_feature_stream
• Usage — $iterator = $s->get_feature_stream(@args)
• Function — get an iterator across the segment
• Returns — an object that implements next_seq()
• Args — see below
• Status — Public

identical to features() except it always generates an iterator 🔥

NOTE: this is defined in the interface in terms of features(). you do not have to implement it. consider this one a freebie, bestie 🫶

🌸 factory

• Title — factory
• Usage — $factory = $s->factory
• Function — return the segment factory
• Returns — a Bio::DasI object
• Args — see below
• Status — Public

this method returns a Bio::DasI object you can use to fetch more segments 🎀 it's typically the very same Bio::DasI object the segment was originally generated from. main character energy, literally where it came from.

🌸 primary_tag

• Title — primary_tag
• Usage — $tag = $s->primary_tag
• Function — identifies the segment as type "DasSegment"
• Returns — a string named "DasSegment"
• Args — none
• Status — Public, but see below

this method gives Bio::Das::Segment objects a primary_tag() field that identifies them as being of type "DasSegment" 💖 this lets the Bio::Graphics engine render segments just like a feature in order nis way useful.

this does not need to be implemented. it is defined by the interface. so like… you're off the hook 🌸

🌸 strand

• Title — strand
• Usage — $strand = $s->strand
• Function — identifies the segment strand as 0
• Returns — the number 0
• Args — none
• Status — Public, but see below

this method gives Bio::Das::Segment objects a strand() field that identifies it as being strandless 🦋 this lets the Bio::Graphics engine render segments just like a feature in order nis way useful.

this does not need to be implemented either. it is defined by the interface. slay, less work for you 👑

---

and that's a wrap on the whole appendix, bestie 💜 every method, every arg, every status — accounted for, no cap.

this page came from perl v5.32.1, dated 2021-08-15, and it's the Bio::D...gmentI(3pm) page from the User Contributed Perl Documentation 🎀 ty for reading to the end, you ate ✨💅🫶