Skip to content
This repository has been archived by the owner on Jan 25, 2023. It is now read-only.

DUP,DEL and required positional parameters #94

Merged
merged 7 commits into from Jun 22, 2017
Merged

DUP,DEL and required positional parameters #94

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7fbe875
Structural DUP,DEL and range match requirements
May 3, 2017
ae14149
Merge remote-tracking branch 'origin/develop-proto' into develop-prot…
May 23, 2017
199adc9
implementing separate start end attributes
May 24, 2017
7aef4e7
reference_bases comment
mbaudis May 24, 2017
a025f89
removing "required" from start, add TODO
mbaudis Jun 1, 2017
a9d6a87
Merge branch 'develop-proto' into develop-proto-structural_and_ranges
mbaudis Jun 20, 2017
b8db290
TODO removal
mbaudis Jun 20, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
150 changes: 95 additions & 55 deletions src/main/proto/ga4gh/beacon.proto
View file
Open in desktop
Expand Up @@ -9,32 +9,72 @@ message BeaconAlleleRequest {
// Reference name (chromosome).
//
// Accepted values: 1-22, X, Y.
// Required.
string reference_name = 1;

// Position, allele locus (0-based).
// Position, genomic locus (0-based).
//
// start only:
// - for single positions, e.g. the start of a specified sequence alteration
// where the size is given through the specified alternate_bases
// - typical use are queries for SNV and small InDels
// - the use of "start" without an "end" parameter requires the use of
// "reference_bases"
//
// start and end:
// - special use case for exactly determined structural changes
//
// start_min + start_max + end_min + end_max
// - for querying imprecise positions (e.g. identifying all structural
// variants starting anywhere between start_min <-> start_max, and ending
// anywhere between end_min <-> end_max
// - single or douple sided precise matches can be achieved by setting
// start_min = start_max XOR end_min = end_max
//
// Accepted values: non-negative integers smaller than reference length.
int64 start = 2;

// Reference bases for this variant (starting from `start`). OPTIONAL.
//
int64 start_min = 3;

int64 start_max = 4;

int64 end = 5;

int64 end_min = 6;

int64 end_max = 7;

// Reference bases for this variant (starting from `start`).
//
// Accepted values: see the REF field in VCF 4.2 specification
// (https://samtools.github.io/hts-specs/VCFv4.2.pdf).
string reference_bases = 3;
// When querying for variants without specific base alterations (e.g.
// imprecise structural variants with separate variant_type as well as
// start_min & end_min ... parameters), the use of a single "N" value is
// recommended.
string reference_bases = 8;

// The bases that appear instead of the reference bases.
//
// Accepted values: see the ALT field in VCF 4.2 specification
// (https://samtools.github.io/hts-specs/VCFv4.2.pdf).
string alternate_bases = 4;
// Optional (either "alternate_bases" or "variant_type" is required)
string alternate_bases = 9;

// The "variant_type" is used to denote e.g. structural variants.
// Examples:
// DUP : duplication of sequence following "start"; not necessarily in situ
// DEL : deletion of sequence following "start"
// Optional (either "alternate_bases" or "variant_type" is required)
string variant_type = 10;

// Assembly identifier (GRC notation, e.g. `GRCh37`).
string assembly_id = 5;
string assembly_id = 11;

// Identifiers of datasets, as defined in `BeaconDataset`.
//
// If this field is null/not specified, all datasets should be queried.
repeated string dataset_ids = 6;
// Optional.
repeated string dataset_ids = 12;

enum FilterDatasetResponse {
ALL = 0; // All datasets
Expand All @@ -48,12 +88,12 @@ message BeaconAlleleRequest {
// (`BeaconAlleleResponse`) to this request or not.
//
// If null (not specified), the default value of NONE is assumed.
FilterDatasetResponse include_dataset_responses = 7;
FilterDatasetResponse include_dataset_responses = 13;
}

// Dataset of a beacon.
message BeaconDataset {
// Unique identifier of the dataset.
// Unique identifier of the dataset.
string id = 1;

// Name of the dataset.
Expand All @@ -62,51 +102,51 @@ message BeaconDataset {
// Description of the dataset.
string description = 3;

// Assembly identifier (GRC notation, e.g. `GRCh37`).
// Assembly identifier (GRC notation, e.g. `GRCh37`).
string assembly_id = 4;

// The time the dataset was created (ISO 8601 format).
// The time the dataset was created (ISO 8601 format).
string create_date_time = 5;

// The time the dataset was updated in (ISO 8601 format).
// The time the dataset was updated in (ISO 8601 format).
string update_date_time = 6;

// Version of the dataset.
// Version of the dataset.
string version = 7;

// Total number of variants in the dataset.
// Total number of variants in the dataset.
int64 variant_count = 8;

// Total number of calls in the dataset.
// Total number of calls in the dataset.
int64 call_count = 9;

// Total number of samples in the dataset.
// Total number of samples in the dataset.
int64 sample_count = 10;

// URL to an external system providing more dataset information (RFC 3986
// format).
// URL to an external system providing more dataset information (RFC 3986
// format).
string external_url = 11;

// A map of additional information.
map<string, string> info = 12;
}

// Organization owning a beacon.
// Organization owning a beacon.
message BeaconOrganization {
// Unique identifier of the organization. Use reverse domain name notation
// Unique identifier of the organization. Use reverse domain name notation
// (e.g. org.ga4gh)
string id = 1;

// Name of the organization.
// Name of the organization.
string name = 2;

// Description of the organization.
// Description of the organization.
string description = 3;

// Address of the organization.
// Address of the organization.
string address = 4;

// URL of the website of the organization (RFC 3986 format).
// URL of the website of the organization (RFC 3986 format).
string welcome_url = 5;

// URL with the contact for the beacon operator/maintainer, e.g. link to
Expand All @@ -120,86 +160,86 @@ message BeaconOrganization {
map<string, string> info = 12;
}

// Beacon.
// Beacon.
message Beacon {
// Unique identifier of the beacon. Use reverse domain name notation (e.g.
// Unique identifier of the beacon. Use reverse domain name notation (e.g.
// org.ga4gh.beacon)
string id = 1;

// Name of the beacon.
string name = 2;

// Version of the API provided by the beacon.
// Version of the API provided by the beacon.
string api_version = 3;

// Organization owning the beacon.
// Organization owning the beacon.
BeaconOrganization organization = 4;

// Description of the beacon.
// Description of the beacon.
string description = 5;

// Version of the beacon.
// Version of the beacon.
string version = 6;

// URL to the welcome page for this beacon (RFC 3986 format).
// URL to the welcome page for this beacon (RFC 3986 format).
string welcome_url = 7;

// Alternative URL to the API, e.g. a restricted version of this beacon
// (RFC 3986 format).
string alternative_url = 8;

// The time the beacon was created (ISO 8601 format).
// The time the beacon was created (ISO 8601 format).
string create_date_time = 9;

// The time the beacon was updated in (ISO 8601 format).
// The time the beacon was updated in (ISO 8601 format).
string update_date_time = 10;

// Datasets served by the beacon. Any beacon should specify at least one
// dataset.
repeated BeaconDataset datasets = 11;

// Examples of interesting queries, e.g. a few queries demonstrating
// Examples of interesting queries, e.g. a few queries demonstrating
// different responses.
repeated BeaconAlleleRequest sample_allele_requests = 12;

// A map of additional information.
map<string, string> info = 13;
}

// Beacon-specific error representing an unexpected problem.
// Beacon-specific error representing an unexpected problem.
message BeaconError {

enum ErrorCode {
// HTTP error code 400. To be used when the error is not among below.
GENERIC_ERROR = 0;
// HTTP error code 401
UNAUTHORIZED = 1;
// HTTP error code 401
UNAUTHORIZED = 1;
// HTTP error code 404
NOT_FOUND = 2;
}

// Error code.
// Error code.
ErrorCode error_code = 1;

// Error message.
// Accepted values:
// - HTTP error code 400: Generic error.
// - HTTP error code 401: Unauthenticated users cannot access this dataset
// - HTTP error code 404: Dataset not found
// - HTTP error code 400: Missing mandatory parameters: referenceName,
// - HTTP error code 400: Missing mandatory parameters: referenceName,
// position/start and/or assemblyId
// - HTTP error code 400: The reference genome of this dataset X does not
// - HTTP error code 400: The reference genome of this dataset X does not
// match the provided value
// - HTTP error code 400: Invalid alternateBases parameter, it can only be
// - HTTP error code 400: Invalid alternateBases parameter, it can only be
// [ACTG]+
// - HTTP error code 400: Invalid referenceBases parameter, it can only be
// - HTTP error code 400: Invalid referenceBases parameter, it can only be
// [ACTG]+
string message = 2;
}

// Dataset's response to a query for information about a specific allele.
// Dataset's response to a query for information about a specific allele.
message BeaconDatasetAlleleResponse {
// Identifier of the dataset, as defined in `BeaconDataset`.
// Identifier of the dataset, as defined in `BeaconDataset`.
string dataset_id = 1;

// Indicator of whether the given allele was observed in the dataset.
Expand All @@ -214,19 +254,19 @@ message BeaconDatasetAlleleResponse {
// `exists` has to be null.
BeaconError error = 3;

// Frequency of this allele in the dataset. Between 0 and 1, inclusive.
// Frequency of this allele in the dataset. Between 0 and 1, inclusive.
double frequency = 4;

// Number of variants matching the allele request in the dataset.
// Number of variants matching the allele request in the dataset.
int64 variant_count = 5;

// Number of calls matching the allele request in the dataset.
// Number of calls matching the allele request in the dataset.
int64 call_count = 6;

// Number of samples matching the allele request in the dataset.
// Number of samples matching the allele request in the dataset.
int64 sample_count = 7;

// Additional note or description of the response.
// Additional note or description of the response.
string note = 8;

// URL to an external system, such as a secured beacon or a system providing
Expand All @@ -237,9 +277,9 @@ message BeaconDatasetAlleleResponse {
map<string, string> info = 13;
}

// Beacon's response to a query for information about a specific allele.
// Beacon's response to a query for information about a specific allele.
message BeaconAlleleResponse {
// Identifier of the beacon, as defined in `Beacon`.
// Identifier of the beacon, as defined in `Beacon`.
string beacon_id = 1;

// Indicator of whether the given allele was observed in any of the datasets
Expand All @@ -254,11 +294,11 @@ message BeaconAlleleResponse {
// This should be non-null in exceptional situations only, in which case
// `exists` has to be null.
BeaconError error = 3;
// Allele request as interpreted by the beacon.

// Allele request as interpreted by the beacon.
BeaconAlleleRequest allele_request = 4;

// Version of the API provided by the beacon.
// Version of the API provided by the beacon.
string api_version = 6;

// Indicator of whether the given allele was observed in individual datasets.
Expand Down