Coverage Service

src/main/proto/ga4gh/coverage_service.proto

@@ -0,0 +1,93 @@
+syntax = "proto3";
+
+package ga4gh;
+
+import "google/api/annotations.proto";
+
+// The coverage service returns binned counts for on requested containers.
+// It is designed to provide intermediate scale views of the data for genome
+// browsers.
+service CoverageService {
+  // Gets a list of `Dataset` matching the search criteria.
+  //
+  // `POST /datasets/search` must accept a JSON version of
+  // `SearchDatasetsRequest` as the post body and will return a JSON
+  // version of `SearchDatasetsResponse`.
+  rpc Coverage(CoverageRequest)
+    returns (CoverageResponse) {
+      option (google.api.http) = {
+        post: "/v0.6.0a8/coverage"
+        body: "*"
+      };
+    };
+}
+
+// A Bin message provides a count of elements. The width of a bin is defined
+// by the CoverageRequest made to the service.
+message Bin {
+  // The number of features in this bin.
+  uint64 count = 1;
+
+  // Optional. In the case where the bin width returned is different than what
+  // was requested a client may use this information to calculate average 
+  // coverage.
+  uint64 width = 2;
+}
+
+// A CoverageRequest specifies the container to be binned, the
+// bin width, a page size, and page token. Only one container
+// identifier should be provided. If more than one container
+// identifier is provided this is considered a malformed request.
+message CoverageRequest {
+  // The ID of the Read Group Set to be binned. One container ID is required.
+  string read_group_set_id = 1;
+
+  // The ID of the Variant Set to be binned. One container ID is required.
+  string variant_set_id = 2;
+
+  // The ID of the Feature Set to be binned. One container ID is required.
+  string feature_set_id = 3;
+
+  // Provides the reference sequence that the coverage request is performed on.
+  string reference_name = 4;
+
+  // Required. The beginning of the window (0-based, inclusive) to perform binning.
+  int64 start = 5;
+
+  // Required. The end of the window (0-based, exclusive) on which to perform binning.
+  int64 end = 6;
+
+  // Required. The width of each bin, where it is expected that if the region does not
+  // bin evenly, the last bin will count the number of elements in the remaining region.
+  // This may cause the last bin to appear to represent lower than actual coverage.
+  uint64 bin_width = 7;
+
+  // Specifies the maximum number of results to return in a single page.
+  // If unspecified, a system default will be used.
+  int32 page_size = 8;
+
+  // The continuation token, which is used to page through large result sets.
+  // To get the next page of results, set this parameter to the value of
+  // `next_page_token` from the previous response.
+  string page_token = 9;
+}
+
+// The CoverageResponse counts of binned elements in a requested genomic region. The
+// requested number of bins may exceed what can reasonably fit in a page, and so
+// the coverage response returns a `next_page_token`.
+message CoverageResponse {
+  // The list of bins matching the request.
+  repeated Bin bins = 1;
+
+  // Optional. Some servers may precalculate some bin widths. In that case they may
+  // choose to find the nearest bin width to the requested width. This field allows
+  // clients to negotiate and verify the bin width returned from a server. If a bin
+  // has its width field specified, that value takes precedence over this field
+  // for that bin message.
+  uint64 bin_width = 2;
+
+  // The continuation token, which is used to page through large result sets.
+  // Provide this value in a subsequent request to return the next page of
+  // results. This field will be empty if there aren't any additional results.
+  string next_page_token = 3;
+}