Provided by: libbio-db-gff-perl_1.7.4-1_all bug

NAME

       Bio::DB::GFF::RelSegment -- Sequence segment with relative coordinate support

SYNOPSIS

       See Bio::DB::GFF.

DESCRIPTION

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

       In addition to the source sequence, a relative segment has a "reference sequence", which
       is used as the basis for its coordinate system.  The reference sequence can be changed at
       will, allowing you freedom to change the "frame of reference" for features contained
       within the segment.  For example, by setting a segment's reference sequence to the
       beginning of a gene, you can view all other features in gene-relative coordinates.

       The reference sequence and the source sequence must be on the same physical stretch of
       DNA, naturally.  However, they do not have to be on the same strand.  The strandedness of
       the reference sequence determines whether coordinates increase to the right or the left.

       Generally, you will not create or manipulate Bio::DB::GFF::RelSeg0ment objects directly,
       but use those that are returned by the Bio::DB::GFF module.

   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 is called
       automatically by the Bio::DB::GFF module and derivatives.

       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 indicates is the proper sequence for this landmark.
       A class of "Sequence" is assumed unless otherwise specified in the -class argument.

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

       The optional -start and -stop arguments specify the end points for the retrieved segment.
       For those who do not like 1-based indexing, -offset and -length are provided.  If both
       -start/-stop and -offset/-length are provided, the latter overrides the former.  Generally
       it is not a good idea to mix metaphors.

       -ref and -refclass together indicate a sequence to be used for relative coordinates.  If
       not provided, the source sequence indicated by -seq is used as the reference sequence.  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.  Called with no arguments, it returns
       the current reference sequence.  Called with either a sequence ID and class, a
       Bio::DB::GFF::Segment object (or subclass) or a Bio::DB::GFF::Featname object, it will set
       the current reference sequence and return the previous one.

       The method will generate an exception if you attempt 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.

   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 is the
       overloaded method call for the "" operator.

       Currently the format is:

         refseq:start,stop

   name
        Title   : name
        Usage   : Alias for asString()

   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

       Called with a boolean flag, this method 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.

   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 in effect at the time that features() was called.

       The returned list can be limited to certain types of feature by filtering on their method
       and/or source.  In addition, it is 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.

         -binsize   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 wll be applied to
       the features returned by this method.

       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.

       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.

   get_SeqFeatures
        Title   : get_SeqFeatures
        Usage   :
        Function: returns the top level sequence features
        Returns : L<Bio::SeqFeatureI> objects
        Args    : none

       Segments do not ordinarily return any subfeatures.

   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.

   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.

   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.

   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.

   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.

       Arguments:

        -type,-types  Either a single scalar type to be deleted, or an
                      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.

       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.

   _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 arguents
        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.

   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.

   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-specfic information, such as feature types, to be dropped when
       a subsequence is created.

   _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.

   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::RangeI Methods
       The following Bio::RangeI methods are supported:

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

BUGS

       Schemas need some work.

SEE ALSO

       bioperl

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.