Provided by: libbio-perl-perl_1.6.923-1_all bug

NAME

       Bio::DB::GFF::Feature -- A relative segment identified by a feature type

SYNOPSIS

       See Bio::DB::GFF.

DESCRIPTION

       Bio::DB::GFF::Feature is a stretch of sequence that corresponding to a single annotation
       in a GFF database.  It inherits from Bio::DB::GFF::RelSegment, and so has all the support
       for relative addressing of this class and its ancestors.  It also inherits from
       Bio::SeqFeatureI and so has the familiar start(), stop(), primary_tag() and location()
       methods (it implements Bio::LocationI too, if needed).

       Bio::DB::GFF::Feature adds new methods to retrieve the annotation type, group, and other
       GFF attributes.  Annotation types are represented by Bio::DB::GFF::Typename objects, a
       simple class that has two methods called method() and source().  These correspond to the
       method and source fields of a GFF file.

       Annotation groups serve the dual purpose of giving the annotation a human-readable name,
       and providing higher-order groupings of subfeatures into features.  The groups returned by
       this module are objects of the Bio::DB::GFF::Featname class.

       Bio::DB::GFF::Feature inherits from and implements the abstract methods of
       Bio::SeqFeatureI, allowing it to interoperate with other Bioperl modules.

       Generally, you will not create or manipulate Bio::DB::GFF::Feature objects directly, but
       use those that are returned by the Bio::DB::GFF::RelSegment->features() method.

   Important note about start() vs end()
       If features are derived from segments that use relative addressing (which is the default),
       then start() will be less than end() if the feature is on the opposite strand from the
       reference sequence.  This breaks Bio::SeqI compliance, but is necessary to avoid having
       the real genomic locations designated by start() and end() swap places when changing
       reference points.

       To avoid this behavior, call $segment->absolute(1) before fetching features from it.  This
       will force everything into absolute coordinates.

       For example:

        my $segment = $db->segment('CHROMOSOME_I');
        $segment->absolute(1);
        my @features = $segment->features('transcript');

API

       The remainder of this document describes the public and private methods implemented by
       this module.

   new_from_parent
        Title   : new_from_parent
        Usage   : $f = Bio::DB::GFF::Feature->new_from_parent(@args);
        Function: create a new feature object
        Returns : new Bio::DB::GFF::Feature object
        Args    : see below
        Status  : Internal

       This method is called by Bio::DB::GFF to create a new feature using information obtained
       from the GFF database.  It is one of two similar constructors.  This one is called when
       the feature is generated from a RelSegment object, and should inherit the coordinate
       system of that object.

       The 13 arguments are positional (sorry):

         $parent       a Bio::DB::GFF::RelSegment object (or descendent)
         $start        start of this feature
         $stop         stop of this feature
         $method       this feature's GFF method
         $source       this feature's GFF source
         $score               this feature's score
         $fstrand      this feature's strand (relative to the source
                             sequence, which has its own strandedness!)
         $phase        this feature's phase
         $group        this feature's group (a Bio::DB::GFF::Featname object)
         $db_id        this feature's internal database ID
         $group_id     this feature's internal group database ID
         $tstart       this feature's target start
         $tstop        this feature's target stop

       tstart and tstop are not used for anything at the moment, since the information is
       embedded in the group object.

   new
        Title   : new
        Usage   : $f = Bio::DB::GFF::Feature->new(@args);
        Function: create a new feature object
        Returns : new Bio::DB::GFF::Feature object
        Args    : see below
        Status  : Internal

       This method is called by Bio::DB::GFF to create a new feature using information obtained
       from the GFF database.  It is one of two similar constructors.  This one is called when
       the feature is generated without reference to a RelSegment object, and should therefore
       use its default coordinate system (relative to itself).

       The 11 arguments are positional:

         $factory      a Bio::DB::GFF adaptor object (or descendent)
         $srcseq       the source sequence
         $start        start of this feature
         $stop         stop of this feature
         $method       this feature's GFF method
         $source       this feature's GFF source
         $score               this feature's score
         $fstrand      this feature's strand (relative to the source
                             sequence, which has its own strandedness!)
         $phase        this feature's phase
         $group        this feature's group
         $db_id        this feature's internal database ID

   type
        Title   : type
        Usage   : $type = $f->type([$newtype])
        Function: get or set the feature type
        Returns : a Bio::DB::GFF::Typename object
        Args    : a new Typename object (optional)
        Status  : Public

       This method gets or sets the type of the feature.  The type is a Bio::DB::GFF::Typename
       object, which encapsulates the feature method and source.

       The method() and source() methods described next provide shortcuts to the individual
       fields of the type.

   method
        Title   : method
        Usage   : $method = $f->method([$newmethod])
        Function: get or set the feature method
        Returns : a string
        Args    : a new method (optional)
        Status  : Public

       This method gets or sets the feature method.  It is a convenience feature that delegates
       the task to the feature's type object.

   source
        Title   : source
        Usage   : $source = $f->source([$newsource])
        Function: get or set the feature source
        Returns : a string
        Args    : a new source (optional)
        Status  : Public

       This method gets or sets the feature source.  It is a convenience feature that delegates
       the task to the feature's type object.

   score
        Title   : score
        Usage   : $score = $f->score([$newscore])
        Function: get or set the feature score
        Returns : a string
        Args    : a new score (optional)
        Status  : Public

       This method gets or sets the feature score.

   phase
        Title   : phase
        Usage   : $phase = $f->phase([$phase])
        Function: get or set the feature phase
        Returns : a string
        Args    : a new phase (optional)
        Status  : Public

       This method gets or sets the feature phase.

   strand
        Title   : strand
        Usage   : $strand = $f->strand
        Function: get the feature strand
        Returns : +1, 0 -1
        Args    : none
        Status  : Public

       Returns the strand of the feature.  Unlike the other methods, the strand cannot be changed
       once the object is created (due to coordinate considerations).

   group
        Title   : group
        Usage   : $group = $f->group([$new_group])
        Function: get or set the feature group
        Returns : a Bio::DB::GFF::Featname object
        Args    : a new group (optional)
        Status  : Public

       This method gets or sets the feature group.  The group is a Bio::DB::GFF::Featname object,
       which has an ID and a class.

   display_id
        Title   : display_id
        Usage   : $display_id = $f->display_id([$display_id])
        Function: get or set the feature display id
        Returns : a Bio::DB::GFF::Featname object
        Args    : a new display_id (optional)
        Status  : Public

       This method is an alias for group().  It is provided for Bio::SeqFeatureI compatibility.

   info
        Title   : info
        Usage   : $info = $f->info([$new_info])
        Function: get or set the feature group
        Returns : a Bio::DB::GFF::Featname object
        Args    : a new group (optional)
        Status  : Public

       This method is an alias for group().  It is provided for AcePerl compatibility.

   target
        Title   : target
        Usage   : $target = $f->target([$new_target])
        Function: get or set the feature target
        Returns : a Bio::DB::GFF::Homol object
        Args    : a new group (optional)
        Status  : Public

       This method works like group(), but only returns the group if it implements the start()
       method.  This is typical for similarity/assembly features, where the target encodes the
       start and stop location of the alignment.

       The returned object is of type Bio::DB::GFF::Homol, which is a subclass of
       Bio::DB::GFF::Segment.

   flatten_target
        Title   : flatten_target
        Usage   : $target = $f->flatten_target($f->target)
        Function: flatten a target object
        Returns : a string (GFF2), an array [GFF2.5] or an array ref [GFF3]
        Args    : a target object (required), GFF version (optional)
        Status  : Public

       This method flattens a target object into text for GFF dumping.  If a second argument is
       provided, version-specific vocabulary is used for the flattened target.

   hit
        Title   : hit
        Usage   : $hit = $f->hit([$new_hit])
        Function: get or set the feature hit
        Returns : a Bio::DB::GFF::Featname object
        Args    : a new group (optional)
        Status  : Public

       This is the same as target(), for compatibility with Bio::SeqFeature::SimilarityPair.

   id
        Title   : id
        Usage   : $id = $f->id
        Function: get the feature ID
        Returns : a database identifier
        Args    : none
        Status  : Public

       This method retrieves the database identifier for the feature.  It cannot be changed.

   group_id
        Title   : group_id
        Usage   : $id = $f->group_id
        Function: get the feature ID
        Returns : a database identifier
        Args    : none
        Status  : Public

       This method retrieves the database group identifier for the feature.  It cannot be
       changed.  Often the group identifier is more useful than the feature identifier, since it
       is used to refer to a complex object containing subparts.

   clone
        Title   : clone
        Usage   : $feature = $f->clone
        Function: make a copy of the feature
        Returns : a new Bio::DB::GFF::Feature object
        Args    : none
        Status  : Public

       This method returns a copy of the feature.

   compound
        Title   : compound
        Usage   : $flag = $f->compound([$newflag])
        Function: get or set the compound flag
        Returns : a boolean
        Args    : a new flag (optional)
        Status  : Public

       This method gets or sets a flag indicated that the feature is not a primary one from the
       database, but the result of aggregation.

   sub_SeqFeature
        Title   : sub_SeqFeature
        Usage   : @feat = $feature->sub_SeqFeature([$method])
        Function: get subfeatures
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : a feature method (optional)
        Status  : Public

       This method returns a list of any subfeatures that belong to the main feature.  For those
       features that contain heterogeneous subfeatures, you can retrieve a subset of the
       subfeatures by providing a method name to filter on.

       This method may also be called as segments() or get_SeqFeatures().

   add_subfeature
        Title   : add_subfeature
        Usage   : $feature->add_subfeature($feature)
        Function: add a subfeature to the feature
        Returns : nothing
        Args    : a Bio::DB::GFF::Feature object
        Status  : Public

       This method adds a new subfeature to the object.  It is used internally by aggregators,
       but is available for public use as well.

   attach_seq
        Title   : attach_seq
        Usage   : $sf->attach_seq($seq)
        Function: Attaches a Bio::Seq object to this feature. This
                  Bio::Seq object is for the *entire* sequence: ie
                  from 1 to 10000
        Example :
        Returns : TRUE on success
        Args    : a Bio::PrimarySeqI compliant object

   location
        Title   : location
        Usage   : my $location = $seqfeature->location()
        Function: returns a location object suitable for identifying location
                  of feature on sequence or parent feature
        Returns : Bio::LocationI object
        Args    : none

   entire_seq
        Title   : entire_seq
        Usage   : $whole_seq = $sf->entire_seq()
        Function: gives the entire sequence that this seqfeature is attached to
        Example :
        Returns : a Bio::PrimarySeqI compliant object, or undef if there is no
                  sequence attached
        Args    : none

   merged_segments
        Title   : merged_segments
        Usage   : @segs = $feature->merged_segments([$method])
        Function: get merged subfeatures
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : a feature method (optional)
        Status  : Public

       This method acts like sub_SeqFeature, except that it merges overlapping segments of the
       same time into contiguous features.  For those features that contain heterogeneous
       subfeatures, you can retrieve a subset of the subfeatures by providing a method name to
       filter on.

       A side-effect of this method is that the features are returned in sorted order by their
       start tposition.

   sub_types
        Title   : sub_types
        Usage   : @methods = $feature->sub_types
        Function: get methods of all sub-seqfeatures
        Returns : a list of method names
        Args    : none
        Status  : Public

       For those features that contain subfeatures, this method will return a unique list of
       method names of those subfeatures, suitable for use with sub_SeqFeature().

   attributes
        Title   : attributes
        Usage   : @attributes = $feature->attributes($name)
        Function: get the "attributes" on a particular feature
        Returns : an array of string
        Args    : feature ID
        Status  : public

       Some GFF version 2 files use the groups column to store a series of attribute/value pairs.
       In this interpretation of GFF, the first such pair is treated as the primary group for the
       feature; subsequent pairs are treated as attributes.  Two attributes have special meaning:
       "Note" is for backward compatibility and is used for unstructured text remarks.  "Alias"
       is considered as a synonym for the feature name.

        @gene_names = $feature->attributes('Gene');
        @aliases    = $feature->attributes('Alias');

       If no name is provided, then attributes() returns a flattened hash, of attribute=>value
       pairs.  This lets you do:

         %attributes = $db->attributes;

   notes
        Title   : notes
        Usage   : @notes = $feature->notes
        Function: get the "notes" on a particular feature
        Returns : an array of string
        Args    : feature ID
        Status  : public

       Some GFF version 2 files use the groups column to store various notes and remarks.
       Adaptors can elect to store the notes in the database, or just ignore them.  For those
       adaptors that store the notes, the notes() method will return them as a list.

   aliases
        Title   : aliases
        Usage   : @aliases = $feature->aliases
        Function: get the "aliases" on a particular feature
        Returns : an array of string
        Args    : feature ID
        Status  : public

       This method will return a list of attributes of type 'Alias'.

   Autogenerated Methods
        Title   : AUTOLOAD
        Usage   : @subfeat = $feature->Method
        Function: Return subfeatures using autogenerated methods
        Returns : a list of Bio::DB::GFF::Feature objects
        Args    : none
        Status  : Public

       Any method that begins with an initial capital letter will be passed to AUTOLOAD and
       treated as a call to sub_SeqFeature with the method name used as the method argument.  For
       instance, this call:

         @exons = $feature->Exon;

       is equivalent to this call:

         @exons = $feature->sub_SeqFeature('exon');

   SeqFeatureI methods
       The following Bio::SeqFeatureI methods are implemented:

       primary_tag(), source_tag(), all_tags(), has_tag(), each_tag_value() [renamed
       get_tag_values()].

   adjust_bounds
        Title   : adjust_bounds
        Usage   : $feature->adjust_bounds
        Function: adjust the bounds of a feature
        Returns : ($start,$stop,$strand)
        Args    : none
        Status  : Public

       This method adjusts the boundaries of the feature to enclose all its subfeatures.  It
       returns the new start, stop and strand of the enclosing feature.

   sort_features
        Title   : sort_features
        Usage   : $feature->sort_features
        Function: sort features
        Returns : nothing
        Args    : none
        Status  : Public

       This method sorts subfeatures in ascending order by their start position.  For reverse
       strand features, it sorts subfeatures in descending order.  After this is called
       sub_SeqFeature will return the features in order.

       This method is called internally by merged_segments().

   asString
        Title   : asString
        Usage   : $string = $feature->asString
        Function: return human-readabled representation of feature
        Returns : a string
        Args    : none
        Status  : Public

       This method returns a human-readable representation of the feature and is called by the
       overloaded "" operator.

   gff_string
        Title   : gff_string
        Usage   : $string = $feature->gff_string
        Function: return GFF2 of GFF2.5 representation of feature
        Returns : a string
        Args    : none
        Status  : Public

   gff3_string
        Title   : gff3_string
        Usage   : $string = $feature->gff3_string([$recurse])
        Function: return GFF3 representation of feature
        Returns : a string
        Args    : An optional flag, which if true, will cause the feature to recurse over
                  subfeatures.
        Status  : Public

   version
        Title   : version
        Usage   : $feature->version()
        Function: get/set the GFF version to be returned by gff_string
        Returns : the GFF version (default is 2)
        Args    : the GFF version (2, 2.5 of 3)
        Status  : Public

   cmap_link()
        Title   : cmap_link
        Usage   : $link = $feature->cmap_link
        Function: returns a URL link to the corresponding feature in cmap
        Returns : a string
        Args    : none
        Status  : Public

       If integrated cmap/gbrowse installation, it returns a link to the map otherwise it returns
       a link to a feature search on the feature name.  See the cmap documentation for more
       information.

       This function is intended primarily to be used in gbrowse conf files.  For example:

         link       = sub {my $self = shift; return $self->cmap_viewer_link(data_source);}

A Note About Similarities

       The current default aggregator for GFF "similarity" features creates a composite
       Bio::DB::GFF::Feature object of type "gapped_alignment".  The target() method for the
       feature as a whole will return a RelSegment object that is as long as the extremes of the
       similarity hit target, but will not necessarily be the same length as the query sequence.
       The length of each "similarity" subfeature will be exactly the same length as its
       target().  These subfeatures are essentially the HSPs of the match.

       The following illustrates this:

         @similarities = $segment->feature('similarity:BLASTN');
         $sim          = $similarities[0];

         print $sim->type;        # yields "gapped_similarity:BLASTN"

         $query_length  = $sim->length;
         $target_length = $sim->target->length;  # $query_length != $target_length

         @matches = $sim->Similarity;   # use autogenerated method
         $query1_length  = $matches[0]->length;
         $target1_length = $matches[0]->target->length; # $query1_length == $target1_length

       If you merge segments by calling merged_segments(), then the length of the query sequence
       segments will no longer necessarily equal the length of the targets, because the alignment
       information will have been lost.  Nevertheless, the targets are adjusted so that the first
       and last base pairs of the query match the first and last base pairs of the target.

BUGS

       This module is still under development.

SEE ALSO

       bioperl, Bio::DB::GFF, Bio::DB::RelSegment

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.