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

✨ NAME ✨

Bio::DB::GFF::RelSegment — a sequence segment that literally does relative coordinate support, bestie. That's the whole vibe. 💖

---

🦋 SYNOPSIS 🦋

okay so, plot twist, there's no synopsis here:

See Bio::DB::GFF.

go read that one, iykyk. 🫶

---

💖 DESCRIPTION 💖

Bio::DB::GFF::RelSegment is a stretch of sequence that can handle relative coordinate addressing. It inherits from Bio::DB::GFF::Segment, and it's the base class for Bio::DB::GFF::Feature. 👑

So here's the tea: on top of the source sequence, a relative segment has a "reference sequence", and that reference sequence is the basis for its whole coordinate system. And you can change that reference sequence whenever you want?? at will?? which means you get full freedom to change the "frame of reference" for the features inside the segment. iconic. For example, if you set a segment's reference sequence to the beginning of a gene, you can then view all the other features in gene-relative coordinates. slay. ✨

Now, the reference sequence and the source sequence have to be on the same physical stretch of DNA, naturally. But 💀 they do not have to be on the same strand. The strandedness of the reference sequence is what decides whether coordinates increase to the right or to the left.

Generally you will not create or manipulate Bio::DB::GFF::RelSeg0ment objects directly — you'll just use the ones that get handed back to you by the Bio::DB::GFF module. no cap. 🎀

🌸 An Example 🌸

To understand how relative coordinates work, consider the following example from the C. elegans database. First we create the appropriate GFF accessor object (the factory):

my $db = Bio::DB::GFF->new(-dsn => 'dbi:mysql:elegans',
                           -adaptor=>'dbi:mysqlopt');

Now we fetch out a segment based on cosmid clone ZK909:

my $seg = $db->segment('ZK909');

If we call the segment's refseq() method, we see that the base of the coordinate system is the sequence "ZK154", and that its start and stop positions are 1 and the length of the cosmid:

print $seg->refseq;
=> ZK909

print $seg->start,' - ',$seg->stop;
=> 1 - 33782

As a convenience, the "" operator is overloaded in this class, to give the reference sequence, and start and stop positions:

print $seg;
=> ZK909:1,33782

Internally, Bio::DB::GFF::RelSegment has looked up the absolute coordinates of this segment and maintains the source sequence and the absolute coordinates relative to the source sequence. We can see this information using sourceseq() (inherited from Bio::DB::GFF::Segment) and the abs_start() and abs_end() methods:

print $seg->sourceseq;
=> CHROMOSOME_I

print $seg->abs_start,' - ',$seg->abs_end;
=> 14839545 - 14873326

We can also put the segment into absolute mode, so that it behaves like Bio::DB::Segment, and always represents coordinates on the source sequence. This is done by passing a true value to the absolute() method:

$seq->absolute(1);
print $seg;
=> CHROMOSOME_I:14839545,14873326

We can change the reference sequence at any time. One way is to call the segment's ref() method, giving it the ID (and optionally the class) of another landmark on the genome. For example, if we know that cosmid ZK337 is adjacent to ZK909, then we can view ZK909 in ZK337-relative coordinates:

$seg->refseq('ZK337');
print $seg;
=> ZK337:-33670,111

We can call the segment's features() method in order to get the list of contigs that overlap this segment (in the C. elegans database, contigs have feature type "Sequence:Link"):

@links = $seg->features('Sequence:Link');

We can now set the reference sequence to the first of these contigs like so:

$seg->refseq($links[0]);
print $seg;
=> Sequence:Link(LINK_Y95D11A):3997326,4031107

---

👑 API 👑

The remainder of this document describes the API for Bio::DB::GFF::Segment.

---

💅 new

Title   : new
Usage   : $s = Bio::DB::GFF::RelSegment->new(@args)
Function: create a new relative segment
Returns : a new Bio::DB::GFF::RelSegment object
Args    : see below
Status  : Public

This method creates a new Bio::DB::GFF::RelSegment object. Generally this gets called automatically by the Bio::DB::GFF module and its derivatives, so like… you usually don't have to do it yourself. 🫶

This function uses a named-argument style:

-factory      a Bio::DB::GFF::Adaptor to use for database access
-seq          ID of the source sequence
-class        class of the source sequence
-start        start of the desired segment relative to source sequence
-stop         stop of the desired segment relative to source sequence
-ref          ID of the reference sequence
-refclass     class of the reference sequence
-offset       0-based offset from source sequence to start of segment
-length       length of desired segment
-absolute, -force_absolute
              use absolute coordinates, rather than coordinates relative
              to the start of self or the reference sequence

The -seq argument accepts the ID of any landmark in the database. The stored source sequence becomes whatever the GFF file says is the proper sequence for that landmark. A class of "Sequence" is assumed unless you say otherwise in the -class argument.

If the argument to -seq is a Bio::GFF::Featname object (such as the one returned by the group() method), then the class is taken from that. cute. 🎀

The optional -start and -stop arguments specify the end points for the retrieved segment. And for those of you who do not vibe with 1-based indexing, -offset and -length are provided. If you provide both -start/-stop and -offset/-length, the latter overrides the former.

⚠️ Generally it is not a good idea to mix metaphors. fr fr.

-ref and -refclass together indicate a sequence to be used for relative coordinates. If you don't provide them, the source sequence indicated by -seq is used as the reference sequence. And if the argument to -ref is a Bio::GFF::Featname object (such as returned by the group() method), then the class is taken from that.

-force_absolute should be used if you wish to skip the lookup of the absolute position of the source sequence that ordinarily occurs when you create a relative segment. In this case, the source sequence must be a sequence that has been specified as the "source" in the GFF file.

---

🧚 refseq

Title   : refseq
Usage   : $ref = $s->refseq([$newseq] [,$newseqclass])
Function: get/set reference sequence
Returns : current reference sequence
Args    : new reference sequence and class (optional)
Status  : Public

This method will get or set the reference sequence. Call it with no arguments and it returns the current reference sequence. Call it with either a sequence ID and class, a Bio::DB::GFF::Segment object (or subclass), or a Bio::DB::GFF::Featname object, and it will set the current reference sequence and hand you back the previous one. two-for-one, we love to see it. ✨

💀 The method will generate an exception if you try to set the reference sequence to a sequence that isn't contained in the database, or one that has a different source sequence from the segment. so like, don't.

---

🍓 abs_low

Title   : abs_low
Usage   : $s->abs_low
Function: the absolute lowest coordinate of the segment
Returns : an integer
Args    : none
Status  : Public

This is for GadFly compatibility, and returns the low coordinate in absolute coordinates;

---

🌈 abs_high

Title   : abs_high
Usage   : $s->abs_high
Function: the absolute highest coordinate of the segment
Returns : an integer
Args    : none
Status  : Public

This is for GadFly compatibility, and returns the high coordinate in absolute coordinates;

---

🦋 asString

Title   : asString
Usage   : $s->asString
Function: human-readable representation of the segment
Returns : a string
Args    : none
Status  : Public

This method will return a human-readable representation of the segment. It's the overloaded method call for the "" operator. ✨

Currently the format is:

refseq:start,stop

---

🎀 name

Title   : name
Usage   : Alias for asString()

that's it, that's the method. an alias. 💅

---

💜 absolute

Title   : absolute
Usage   : $abs = $s->absolute([$abs])
Function: get/set absolute coordinates
Returns : a boolean flag
Args    : new setting for flag (optional)
Status  : Public

Call this with a boolean flag and it controls whether to display relative coordinates (relative to the reference sequence) or absolute coordinates (relative to the source sequence). It will return the previous value of the setting. so you can always undo, no stress. 🫶

---

🔥 features

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

This method will find all features that overlap the segment and return a list of Bio::DB::GFF::Feature objects. The features will use coordinates relative to the reference sequence that was in effect at the time features() was called. timing matters bestie. ⏰

The returned list can be limited to certain types of feature by filtering on their method and/or source. In addition, it's possible to obtain an iterator that will step through a large number of features sequentially.

Arguments can be provided positionally or using the named arguments format. In the former case, the arguments are a list of feature types in the format "method:source". Either method or source can be omitted, in which case the missing component is treated as a wildcard. If no colon is present, then the type is treated as a method name. Multiple arguments are ORed together.

Examples:

@f = $s->features('exon:curated');           # all curated exons
@f = $s->features('exon:curated','intron');  # curated exons and all introns
@f = $s->features('similarity:.*EST.*');     # all similarities
                                             # having something to do
                                             # with ESTs

The named parameter form gives you control over a few options:

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

-merge     Whether to apply aggregators to the generated features (default yes)

-rare      Turn on an optimization suitable for a relatively rare feature type,
           where it will be faster to filter by feature type first
           and then by position, rather than vice versa.

-attributes a hashref containing a set of attributes to match

-range_type One of 'overlapping', 'contains', or 'contained_in'

-iterator  Whether to return an iterator across the features.

okay and that's where part 1 wraps… but hold on, there's more coming, don't go anywhere 💖

• -binsize — bestie, a true value will create a set of artificial features whose start and stop positions indicate bins of the given size, and whose scores are the number of features in the bin. The class and method of the feature will be set to "bin", its source to "method:source", and its group to "bin:method:source". This is a handy way of generating histograms of feature density. 💅
• -merge is a boolean flag that controls whether the adaptor's aggregators will be applied to the features returned by this method. yes, it's giving merge energy

If -iterator is true, then the method returns a single scalar value consisting of a Bio::SeqIO object. You can call next_seq() repeatedly on this object to fetch each of the features in turn. If iterator is false or absent, then all the features are returned as a list. iconic behavior tbh

The -attributes argument is a hashref containing one or more attributes to match against:

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

Attribute matching is simple string matching, and multiple attributes are ANDed together. no cap

get_SeqFeatures

• Title: get_SeqFeatures
• Usage: (nothing here, bestie — it's blank)
• Function: returns the top level sequence features
• Returns: L<Bio::SeqFeatureI> objects
• Args: none

Segments do not ordinarily return any subfeatures. so don't expect extra drama

feature_count

• Title: feature_count
• Usage: $seq->feature_count()
• Function: Return the number of SeqFeatures attached to a sequence
• Returns: integer representing the number of SeqFeatures
• Args: none

This method comes through extension of Bio::FeatureHolderI. See Bio::FeatureHolderI for more information. iykyk

get_feature_stream

• Title: features
• Usage: $stream = $s->get_feature_stream(@args)
• Function: get a stream of features that overlap this segment
• Returns: a Bio::SeqIO::Stream-compliant stream
• Args: see below
• Status: Public

This is the same as features(), but returns a stream. Use like this:

        $stream = $s->get_feature_stream('exon');
        while (my $exon = $stream->next_seq) {
           print $exon->start,"\n";
        }

get_seq_stream

• Title: get_seq_stream
• Usage: $stream = $s->get_seq_stream(@args)
• Function: get a stream of features that overlap this segment
• Returns: a Bio::SeqIO::Stream-compliant stream
• Args: see below
• Status: Public

This is the same as feature_stream(), and is provided for Bioperl compatibility. Use like this:

        $stream = $s->get_seq_stream('exon');
        while (my $exon = $stream->next_seq) {
           print $exon->start,"\n";
        }

overlapping_features

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

This is an alias for the features() method, and takes the same arguments. slay

contained_features

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

This is identical in behavior to features() except that it returns only those features that are completely contained within the segment, rather than any that overlap. no overlap allowed, periodt

contained_in

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

This is identical in behavior to features() except that it returns only those features that completely contain the segment. main character energy

delete

• Title: delete
• Usage: $db->delete(@args)
• Function: delete features
• Returns: count of features deleted -- if available
• Args: numerous, see below
• Status: public

This method deletes all features that overlap the specified region or are of a particular type. If no arguments are provided and the -force argument is true, then deletes ALL features. ALL FEATURES. be careful bestie 😭

Arguments:

• -type, -types — Either a single scalar type to be deleted, or a reference to an array of types.
• -range_type — Control the range type of the deletion. One of "overlaps" (default), "contains" or "contained_in".

Examples:

         $segment->delete(-type=>['intron','repeat:repeatMasker']);  # remove all introns & repeats
         $segment->delete(-type=>['intron','repeat:repeatMasker']
                          -range_type => 'contains');                # remove all introns & repeats
                                                                     # strictly contained in segment

IMPORTANT NOTE: This method only deletes features. It does NOT delete the names of groups that contain the deleted features. Group IDs will be reused if you later load a feature with the same group name as one that was previously deleted. this is important, bestie

NOTE ON FEATURE COUNTS: The DBI-based versions of this call return the result code from the SQL DELETE operation. Some dbd drivers return the count of rows deleted, while others return 0E0. Caveat emptor. caveat emptor fr fr

_process_feature_args

• Title: _process_feature_args
• Usage: @args = $s->_process_feature_args(@args)
• Function: preprocess arguments passed to features, contained_features, and overlapping_features
• Returns: a list of parsed arguments
• Args: see feature()
• Status: Internal

This is an internal method that is used to check and format the arguments to features() before passing them on to the adaptor. internal business, don't touch

types

• Title: types
• Usage: @types = $s->types([-enumerate=>1])
• Function: list feature types that overlap this segment
• Returns: a list of Bio::DB::GFF::Typename objects or a hash
• Args: see below
• Status: Public

The types() method will return a list of Bio::DB::GFF::Typename objects, each corresponding to a feature that overlaps the segment. If the optional -enumerate parameter is set to a true value, then the method will return a hash in which the keys are the type names and the values are the number of times a feature of that type is present on the segment. For example:

         %count = $s->types(-enumerate=>1);

🧚 Internal Methods 🧚

The following are internal methods and should not be called directly. do not call them directly, bestie, I'm serious

new_from_segment

• Title: new_from_segment
• Usage: $s = $segment->new_from_segment(@args)
• Function: create a new relative segment
• Returns: a new Bio::DB::GFF::RelSegment object
• Args: see below
• Status: Internal

This constructor is used internally by the subseq() method. It forces the new segment into the Bio::DB::GFF::RelSegment package, regardless of the package that it is called from. This causes subclass-specific information, such as feature types, to be dropped when a subsequence is created. subclass info? dropped. periodt.

_abs2rel

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

This is used internally to map from absolute to relative coordinates. It does not take the offset of the reference sequence into account, so please use abs2rel() instead. use abs2rel() instead, okay?

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. math but make it slay

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. coordinates but relative, cute

💖 Bio::RangeI Methods 💖

The following Bio::RangeI methods are supported:

• overlaps()
• contains()
• equals()
• intersection()
• union()
• overlap_extent()

🐛 BUGS 🐛

Schemas need some work. yeah, they do 💀

👀 SEE ALSO 👀

bioperl go read that too bestie

✨ AUTHOR ✨

Lincoln Stein <lstein@cshl.org>.

Copyright (c) 2001 Cold Spring Harbor Laboratory.

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

---

This page is from perl v5.30.0, dated 2020-01-13, for Bio::D...egment(3pm). byeeee bestie, go slay some genomics 🧬✨