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