AdjacentFeatures
Sequence viewers--particularly genome browser--frequently wish to offer user interface or navigation elements that require knowledge of the next-adjacent feature to an arbitrary location. Typical use cases include:
-
User has loaded up a small set if interesting objects (e.g. regions which show epigenetic differences between samples) and wishes to rapidly scan through the set without having to hunt through large amounts of sequence or manually enter locations.
-
Current view location is set to a region containing no features (e.g. a large gene desert). Experience shows that in this case, users can wonder if there are really no annotations, or if the DAS system has failed. A good solution would be to show user interace elements indicating distance to the next feature in each direction and/or clickable elements to jump to an annotated region.
Such use cases could theoretically be accommodated using DAS as currently specified, for instance by issuing a series of requests for exponentially larger segments until some features are retrieved. However, this may require many requests, and could easily end up returning an unnecessarily large number of features, particularly in a dataset with a very heterogenous feature density (i.e. partial-genome tiling arrays or certain types of capture based high-throughput sequencing experiments).
I'm therefore proposing the feature-adjacent extension to DAS, which adds one extra filter operation to the existing feature capability. This extension will allow clients to efficiently navigate between features, regardless of their density or disposition. Sources implementing this extension MUST report it via the sources document(s) as:
<CAPABILITY type="das1:feature-adjacent" />
Clients may make to a datasource implementing this capability using the form:
SERVER/das/DSN/features?adjacent=ID:OFFSET[:direction]
[;type=TYPE]
The server responds with an entirely standard DASGFF document (or any other supported format, given appropriate negotiation between client server).
If the direction parameter is omitted, the server should attempt to return an adjacent feature in both directions relative to the query point, unless there are no more features. Thus, such a request would typically be expected to return two features.
If the requested position lies within a feature, that feature should be returned.
If the adjacent filter is combined with one or more type filters, then the nearest feature matching one of the type filters should be returned, even if a feature of a different type is closer.
The next adjacent feature may occur on a different reference object from that named in the request. This implies that servers will need to determine some ordering of segments. This ordering MUST be complete and consistent (e.g. if the first feature on a reference object named "chr22" is adjacent to the last feature on "chr21", the converse must also be true). Where a natural or conventional ordering of reference objects exists (e.g. chromosomes in numerical order for most species), servers SHOULD make every effort to follow this ordering. If a source implements both feature-adjacent and entry-points, it SHOULD use the same ordering for both.
Clients MAY combine the adjacent filter with one or more segment filters. If so, a server MUST find the union of features overlapping the requested segment(s) and features adjacent to the requested point(s), and return them in the normal manner. If the position identified by the adjacent filter lies within one of the requested segments, it is possible that no extra features, above and beyond those required to comply with the segment filter, will be returned. This means that a client can issue a single request to find visible features, if they exist, but discover the locations of features outside the visible range in the case where the visible range is empty.
>>> /das/DSN/features?adjacent=chr21:30000000
<DASGFF>
<GFF href="still_don't_get_why_this_was_included...">
<SEGMENT id="chr21" start="29000000" stop="31000499" version="NCBI36">
<FEATURE id="dmr567">
<TYPE id="dmr">Differentially-methylated region</TYPE>
<METHOD id="wtd201103">WTDStats</METHOD>
<START>29000000</START>
<STOP>29000499</STOP>
<SCORE>4.7</SCORE>
</FEATURE>
<FEATURE id="dmr568">
<TYPE id="dmr">Differentially-methylated region</TYPE>
<METHOD id="wtd201103">WTDStats</METHOD>
<START>31000000</START>
<STOP>31000499</STOP>
<SCORE>4.7</SCORE>
</FEATURE>
</SEGMENT>
</GFF>
</DASGFF>
>>> /das/DSN/features?adjacent=chr21:30000000:+
<DASGFF>
<GFF href="still_don't_get_why_this_was_included...">
<SEGMENT id="chr21" start="31000000" stop="31000499" version="NCBI36">
<FEATURE id="dmr568">
<TYPE id="dmr">Differentially-methylated region</TYPE>
<METHOD id="wtd201103">WTDStats</METHOD>
<START>31000000</START>
<STOP>31000499</STOP>
<SCORE>4.7</SCORE>
</FEATURE>
</SEGMENT>
</GFF>
</DASGFF>
>>> /das/DSN/features?adjacent=chr21:32000000
<DASGFF>
<GFF href="still_don't_get_why_this_was_included...">
<SEGMENT id="chr21" start="31000000" stop="31000499" version="NCBI36">
<FEATURE id="dmr568">
<TYPE id="dmr">Differentially-methylated region</TYPE>
<METHOD id="wtd201103">WTDStats</METHOD>
<START>31000000</START>
<STOP>31000499</STOP>
<SCORE>5.2</SCORE>
</FEATURE>
</SEGMENT>
<SEGMENT id="chr22" start="15120500" stop="15120999" version="NCBI36">
<FEATURE id="dmr569">
<TYPE id="dmr">Differentially-methylated region</TYPE>
<METHOD id="wtd201103">WTDStats</METHOD>
<START>15120500</START>
<STOP>15120999</STOP>
<SCORE>4.3</SCORE>
</FEATURE>
</SEGMENT>
</GFF>
</DASGFF>