Linux Certif

Toute la documentation sur la certification Linux LPI

Bio::DB::GFF::Feature.3pm

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.