diff --git a/src/main/proto/ga4gh/coverage_service.proto b/src/main/proto/ga4gh/coverage_service.proto new file mode 100644 index 00000000..0c698a99 --- /dev/null +++ b/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; +} \ No newline at end of file