Bio::DB::Das::Chado::Segment is a simplified alternative interface to sequence annotation databases used by the distributed annotation system. In this scheme, the genome is represented as a series of landmarks. Each Bio::DB::Das::Chado::Segment object ("segment") corresponds to a genomic region defined by a landmark and a start and end position relative to that landmark. A segment is created using the Bio::DasI segment() method.

Features can be filtered by the following attributes:

1) their location relative to the segment (whether overlapping,
contained within, or completely containing)
2) their type
3) other attributes using tag/value semantics

Access to the feature list uses three distinct APIs:

1) fetching entire list of features at a time
2) fetching an iterator across features
3) a callback

User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated.

Title : strand
Usage : $obj->strand()
Function: Returns the strand of the feature. Unlike the other
methods, the strand cannot be changed once the object is
created (due to coordinate considerations).
corresponds to featureloc.strand
Returns : -1, 0, or 1
Args : on set, new value (a scalar or undef, optional)

Title : type
Usage : $obj->type($newval)
Function: used to be alias of class() for backward compatibility,
now behaves the same as Bio::DB::Das::Chado::Segment::Feature->type
Returns : A Bio::DB::GFF::Typename object
Args : on set, new value: Bio::DB::GFF::Typename object

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

This method will find all features that intersect the segment in a variety of ways and return a list of Bio::SeqFeatureI objects. The feature locations 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, attributes or range intersection modes. Types of range intersection are one of:

"overlaps" the default
"contains" return features completely contained within the segment
"contained_in" return features that completely contain the segment

Two types of argument lists are accepted. In the positional argument form, the arguments are treated as a list of feature types. In the named parameter form, the arguments are a series of -name=>value pairs.

Argument Description
-------- ------------
-types An array reference to type names in the format
"method:source"
-attributes A hashref containing a set of attributes to match
-rangetype One of "overlaps", "contains", or "contained_in".
-iterator Return an iterator across the features.
-callback A callback to invoke on each feature

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. More complex filtering can be performed using the -callback option (see below).

If -iterator is true, then the method returns an object reference that implements the next_seq() method. Each call to next_seq() returns a new Bio::SeqFeatureI object.

If -callback is passed a code reference, the code reference will be invoked on each feature returned. The code will be passed two arguments consisting of the current feature and the segment object itself, and must return a true value. If the code returns a false value, feature retrieval will be aborted.

-callback and -iterator are mutually exclusive options. If -iterator is defined, then -callback is ignored.

Its a crude copy past from feature + additionnal code to handle prefetching of 2 levels features. The generated query is ~ as performant as the one generated by features, and the calls to Bio::DB::Das::Chado::Segment->sub_SeqFeatures are avoided, but this doesn't lead to a huge performace boost.

If a further development increases the performances provided by this 2 level prefetch, we will need to refactor features and _features2level to avoid code duplication