additional parameters and updated examples

Update mkdocs.yaml formatting; page cleanup vrsType added and example updates
ga4gh-beacon · Feb 7, 2025 · 519c1d6 · 519c1d6
1 parent ec6a011
commit 519c1d6
Show file tree

Hide file tree

Showing 11 changed files with 175 additions and 69 deletions.
diff --git a/docs/generated/requestParameterComponents.md b/docs/generated/requestParameterComponents.md
@@ -284,6 +284,24 @@ Origin: Beacon v2.0
 
 * `minimum`: `1`    
 
+## `VRStype` 
+
+#### Description
+Type of the variation according to the VRS model. Examples are here e.g. `Adjacency` or `Allele`. Origin: VRS v2    
+
+#### Definitions
+
+* `type`: `string`    
+
+* `enum`:     
+    - `Adjacency`    
+    - `Allele`    
+    - `CisPhasedBlock`    
+    - `CopyNumberChange`    
+    - `CopyNumberCount`    
+    - `DerivativeMolecule`    
+    - `Terminus`        
+
 ## `Assembly` 
 
 #### Description

diff --git a/docs/generated/requestProfiles.md b/docs/generated/requestProfiles.md
@@ -49,7 +49,8 @@ This represents the generic collection of variant parameters supported in Beacon
     - `genomicAlleleShortForm`: `'$ref': './requestParameterComponents.yaml#/$defs/GenomicAlleleShortForm'`      
     - `sequenceLength`: `'$ref': './requestParameterComponents.yaml#/$defs/SequenceLength'`      
     - `variantMinLength`: `'$ref': './requestParameterComponents.yaml#/$defs/VariantMinLength'`      
-    - `variantMaxLength`: `'$ref': './requestParameterComponents.yaml#/$defs/VariantMaxLength'`    
+    - `variantMaxLength`: `'$ref': './requestParameterComponents.yaml#/$defs/VariantMaxLength'`      
+    - `vrsType`: `'$ref': './requestParameterComponents.yaml#/$defs/VRStype'`    
 
 ## `BV2alleleRequest` 
 
@@ -167,7 +168,7 @@ A typical Beacon v2.n request for gene queries, e.g. for the retrieval of all va
 * `required`:     
     - `geneId`        
 
-## `VQSsequenceRequest` 
+## `VQSalleleRequest` 
 
 #### Description
 A Beacon v2+ sequence query. It is in its scope similar to the Beacon v1/v2 allele requests but replaces the original parameters with VRS v2 concepts.    
@@ -176,11 +177,12 @@ A Beacon v2+ sequence query. It is in its scope similar to the Beacon v1/v2 alle
 
 * `type`: `object`    
 * `properties`:    
-    - `requestProfileId`: `'const': 'VQSsequenceRequest'`      
+    - `requestProfileId`: `'const': 'VQSalleleRequest'`      
     - `referenceAccession`: `'$ref': './requestParameterComponents.yaml#/$defs/RefgetAccession'`      
     - `start`: `'$ref': './requestParameterComponents.yaml#/$defs/SequenceStart'`      
     - `end`: `'$ref': './requestParameterComponents.yaml#/$defs/SequenceEnd'`      
-    - `sequence`: `'$ref': './requestParameterComponents.yaml#/$defs/Sequence'`    
+    - `sequence`: `'$ref': './requestParameterComponents.yaml#/$defs/Sequence'`      
+    - `vrsType`: `'const': 'Allele'`    
 
 * `required`:     
     - `referenceAccession`    
@@ -202,7 +204,8 @@ A typical Beacon v2.n request for copy number variations (CNVs) queries approxim
     - `end`: `'$ref': './requestParameterComponents.yaml#/$defs/SequenceEnd'`      
     - `copyChange`: `'$ref': './requestParameterComponents.yaml#/$defs/CopyChange'`      
     - `variantMinLength`: `'$ref': './requestParameterComponents.yaml#/$defs/VariantMinLength'`      
-    - `variantMaxLength`: `'$ref': './requestParameterComponents.yaml#/$defs/VariantMaxLength'`    
+    - `variantMaxLength`: `'$ref': './requestParameterComponents.yaml#/$defs/VariantMaxLength'`      
+    - `vrsType`: `'const': 'CopyNumberChange'`    
 
 * `required`:     
     - `referenceAccession`    
@@ -225,7 +228,8 @@ A typical Beacon v2.n request for sequence adjacency queries, e.g. for the retri
     - `end`: `'$ref': './requestParameterComponents.yaml#/$defs/SequenceEnd'`      
     - `adjacencyAccession`: `'$ref': './requestParameterComponents.yaml#/$defs/AdjacencyAccession'`      
     - `adjacencyStart`: `'$ref': './requestParameterComponents.yaml#/$defs/AdjacencyStart'`      
-    - `adjacencyEnd`: `'$ref': './requestParameterComponents.yaml#/$defs/AdjacencyEnd'`    
+    - `adjacencyEnd`: `'$ref': './requestParameterComponents.yaml#/$defs/AdjacencyEnd'`      
+    - `vrsType`: `'const': 'Adjacency'`    
 
 ## `VQSsequenceRepeatRequest` 
 
@@ -288,4 +292,4 @@ This multi variant query is a collection of individual variant queries based on
 * `properties`:    
     - `requestProfileId`: `'const': 'VQSmultivarRequest'`      
     - `variantLogic`: `'type': 'string', 'enum': ['AND', 'OR'], 'default': 'AND'`      
-    - `queries`: `'type': 'array', 'items': 'anyOf': ['$ref': '#/$defs/VQSsequenceRequest', '$ref': '#/$defs/VQScopyChangeRequest', '$ref': '#/$defs/VQSadjacencyRequest', '$ref': '#/$defs/VQSgeneIdRequest', '$ref': '#/$defs/BV2variantIdRequest', '$ref': '#/$defs/BV2aminoacidChangeRequest', '$ref': '#/$defs/BV2genomicAlleleShortFormRequest']`    
+    - `queries`: `'type': 'array', 'items': 'anyOf': ['$ref': '#/$defs/VQSalleleRequest', '$ref': '#/$defs/VQScopyChangeRequest', '$ref': '#/$defs/VQSadjacencyRequest', '$ref': '#/$defs/VQSgeneIdRequest', '$ref': '#/$defs/BV2variantIdRequest', '$ref': '#/$defs/BV2aminoacidChangeRequest', '$ref': '#/$defs/BV2genomicAlleleShortFormRequest']`    
diff --git a/docs/generated/requestProfiles_VQSadjacencyRequest.md b/docs/generated/requestProfiles_VQSadjacencyRequest.md
@@ -1,3 +1,46 @@
 # Request Profile: `VQSadjacencyRequest`
 
-A typical Beacon v2.n request for sequence adjacency queries, e.g. for the retrieval of chromosomal translocation events or sequence fusions. TODO: In VRS v2 there is an implicit sequence directionality from the use of either start or end parameters for either side of the adjacency. This might be problematic on the query side where in many instances just the approximate position of the (fused) breakpoints maight be of interest. This needs additional clarification (e.g. use of integer `start` and `end`, `adjacencyStart` and  `adjecencyEnd` parameters to indicate direction independent matching).
+A typical Beacon v2.n request for sequence adjacency queries, e.g. for the retrieval of chromosomal translocation events or sequence fusions. TODO: In VRS v2 there is an implicit sequence directionality from the use of either start or end parameters for either side of the adjacency. This might be problematic on the query side where in many instances just the approximate position of the (fused) breakpoints maight be of interest. This needs additional clarification (e.g. use of integer `start` and `end`, `adjacencyStart` and  `adjecencyEnd` parameters to indicate direction independent matching).
+
+### Find  t(8;14)(q24;q32) translocations
+#### Solution for `VQSrequest` using genomic ranges (`VQSadjacencyRequest`)
+This is a query for translocations between the MYC and IgH loci, where the breakpoints are loosely defined through there well known cytogenetic bands. The query here follows the VRS adjacency model. In contrast to the VRS representational model, here:    
+
+- VRS uses an array of 2 genomic locations while Beacon names the location
+  parameters individually (using "adjacency..." for the second partner)    
+- VRS explicitely encodes directionality by using either `start` or `end`
+  position parameters (integers or ranges) while this query example creates
+  non-directional ranges on both sides since directionality might not be known,
+  the storage system might not encode this or all options could be of interest    
+#### Request 
+
+* `requestProfileId`: `VQSadjacencyRequest`    
+
+* `referenceAccession`: `refseq:NC_000008.11`    
+
+* `start`: `116700000`    
+
+* `end`: `145138636`    
+
+* `adjacencyAccession`: `refseq:NC_000014.9`    
+
+* `adjacencyStart`: `89300000`    
+
+* `adjacencyEnd`: `107043718`    
+
+* `vrsType`: `Adjacency`    
+
+##### GET query string
+```requestProfileId=VQSadjacencyRequest&referenceAccession=refseq:NC_000008.11&start=116700000&end=145138636&adjacencyAccession=refseq:NC_000014.9&adjacencyStart=89300000&adjacencyEnd=107043718&vrsType=Adjacency```
+
+##### POST query component 
+```{
+    "adjacencyAccession": "refseq:NC_000014.9",
+    "adjacencyEnd": 107043718,
+    "adjacencyStart": 89300000,
+    "end": 145138636,
+    "referenceAccession": "refseq:NC_000008.11",
+    "requestProfileId": "VQSadjacencyRequest",
+    "start": 116700000,
+    "vrsType": "Adjacency"
+}```
diff --git a/docs/generated/requestProfiles_VQSalleleRequest.md b/docs/generated/requestProfiles_VQSalleleRequest.md
@@ -0,0 +1,3 @@
+# Request Profile: `VQSalleleRequest`
+
+A Beacon v2+ sequence query. It is in its scope similar to the Beacon v1/v2 allele requests but replaces the original parameters with VRS v2 concepts.
diff --git a/docs/generated/requestProfiles_VQScopyChangeRequest.md b/docs/generated/requestProfiles_VQScopyChangeRequest.md
@@ -21,9 +21,11 @@ The example uses `"copyChange": "EFO:0030070"` for `copy number gain` as specifi
     - `242193529`        
 
 * `copyChange`: `EFO:0030070`    
+
+* `vrsType`: `copyChange`    
 
 ##### GET query string
-```requestProfileId=VQScopyChangeRequest&referenceAccession=refseq:NC_000002.12&start=0,54700000&end=63900000,242193529&copyChange=EFO:0030070```
+```requestProfileId=VQScopyChangeRequest&referenceAccession=refseq:NC_000002.12&start=0,54700000&end=63900000,242193529&copyChange=EFO:0030070&vrsType=copyChange```
 
 ##### POST query component 
 ```{
@@ -37,7 +39,8 @@ The example uses `"copyChange": "EFO:0030070"` for `copy number gain` as specifi
     "start": [
         0,
         54700000
-    ]
+    ],
+    "vrsType": "copyChange"
 }```
 
 
@@ -60,9 +63,11 @@ The query uses `"copyChange": "EFO:0020073"` for `high-level copy number loss` a
     - `23000000`        
     
 * `copyChange`: `EFO:0020073`    
+    
+* `vrsType`: `copyChange`    
 
 ##### GET query string
-```requestProfileId=VQScopyChangeRequest&referenceAccession=refseq:NC_000002.12&start=21000001,21975098&end=21967753,23000000&copyChange=EFO:0020073```
+```requestProfileId=VQScopyChangeRequest&referenceAccession=refseq:NC_000002.12&start=21000001,21975098&end=21967753,23000000&copyChange=EFO:0020073&vrsType=copyChange```
 
 ##### POST query component 
 ```{
@@ -76,5 +81,6 @@ The query uses `"copyChange": "EFO:0020073"` for `high-level copy number loss` a
     "start": [
         21000001,
         21975098
-    ]
+    ],
+    "vrsType": "copyChange"
 }```
diff --git a/docs/generated/requestProfiles_VQSgeneIdRequest.md b/docs/generated/requestProfiles_VQSgeneIdRequest.md
@@ -17,15 +17,18 @@ Query for a deletion involving TP53 by using the HUGO name to specify the gene.
 * `variantMinLength`: `1000`    
 
 * `variantMaxLength`: `3000000`    
+
+* `vrsType`: `copyChange`    
 
 ##### GET query string
-```requestType=VQSgeneIdRequest&geneId=TP53&copyChange=EFO:0030067&variantMinLength=1000&variantMaxLength=3000000```
+```requestType=VQSgeneIdRequest&geneId=TP53&copyChange=EFO:0030067&variantMinLength=1000&variantMaxLength=3000000&vrsType=copyChange```
 
 ##### POST query component 
 ```{
     "copyChange": "EFO:0030067",
     "geneId": "TP53",
     "requestType": "VQSgeneIdRequest",
     "variantMaxLength": 3000000,
-    "variantMinLength": 1000
+    "variantMinLength": 1000,
+    "vrsType": "copyChange"
 }```
diff --git a/docs/generated/requestProfiles_VQSrequest.md b/docs/generated/requestProfiles_VQSrequest.md
@@ -41,6 +41,8 @@ For the parameter definitions please see the [`requestParameterComponents` page.
     - `$ref`: `./requestParameterComponents.yaml#/$defs/VariantMinLength`    
 * `variantMaxLength`:    
     - `$ref`: `./requestParameterComponents.yaml#/$defs/VariantMaxLength`    
+* `vrsType`:    
+    - `$ref`: `./requestParameterComponents.yaml#/$defs/VRStype`    
 
 
 ## Beacon v2+/VQS "VRSified" Request Examples
@@ -66,9 +68,11 @@ The example uses `"copyChange": "EFO:0030070"` for `copy number gain` as specifi
     - `242193529`        
 
 * `copyChange`: `EFO:0030070`    
+
+* `vrsType`: `copyChange`    
 
 ##### GET query string
-```requestProfileId=VQScopyChangeRequest&referenceAccession=refseq:NC_000002.12&start=0,54700000&end=63900000,242193529&copyChange=EFO:0030070```
+```requestProfileId=VQScopyChangeRequest&referenceAccession=refseq:NC_000002.12&start=0,54700000&end=63900000,242193529&copyChange=EFO:0030070&vrsType=copyChange```
 
 ##### POST query component 
 ```{
@@ -82,7 +86,8 @@ The example uses `"copyChange": "EFO:0030070"` for `copy number gain` as specifi
     "start": [
         0,
         54700000
-    ]
+    ],
+    "vrsType": "copyChange"
 }```
 
 
@@ -105,9 +110,11 @@ The query uses `"copyChange": "EFO:0020073"` for `high-level copy number loss` a
     - `23000000`        
     
 * `copyChange`: `EFO:0020073`    
+    
+* `vrsType`: `copyChange`    
 
 ##### GET query string
-```requestProfileId=VQScopyChangeRequest&referenceAccession=refseq:NC_000002.12&start=21000001,21975098&end=21967753,23000000&copyChange=EFO:0020073```
+```requestProfileId=VQScopyChangeRequest&referenceAccession=refseq:NC_000002.12&start=21000001,21975098&end=21967753,23000000&copyChange=EFO:0020073&vrsType=copyChange```
 
 ##### POST query component 
 ```{
@@ -121,7 +128,52 @@ The query uses `"copyChange": "EFO:0020073"` for `high-level copy number loss` a
     "start": [
         21000001,
         21975098
-    ]
+    ],
+    "vrsType": "copyChange"
+}```
+
+
+### Find  t(8;14)(q24;q32) translocations
+#### Solution for `VQSrequest` using genomic ranges (`VQSadjacencyRequest`)
+This is a query for translocations between the MYC and IgH loci, where the breakpoints are loosely defined through there well known cytogenetic bands. The query here follows the VRS adjacency model. In contrast to the VRS representational model, here:    
+
+- VRS uses an array of 2 genomic locations while Beacon names the location
+  parameters individually (using "adjacency..." for the second partner)    
+- VRS explicitely encodes directionality by using either `start` or `end`
+  position parameters (integers or ranges) while this query example creates
+  non-directional ranges on both sides since directionality might not be known,
+  the storage system might not encode this or all options could be of interest    
+#### Request 
+    
+* `requestProfileId`: `VQSadjacencyRequest`    
+    
+* `referenceAccession`: `refseq:NC_000008.11`    
+    
+* `start`: `116700000`    
+    
+* `end`: `145138636`    
+    
+* `adjacencyAccession`: `refseq:NC_000014.9`    
+    
+* `adjacencyStart`: `89300000`    
+    
+* `adjacencyEnd`: `107043718`    
+    
+* `vrsType`: `Adjacency`    
+
+##### GET query string
+```requestProfileId=VQSadjacencyRequest&referenceAccession=refseq:NC_000008.11&start=116700000&end=145138636&adjacencyAccession=refseq:NC_000014.9&adjacencyStart=89300000&adjacencyEnd=107043718&vrsType=Adjacency```
+
+##### POST query component 
+```{
+    "adjacencyAccession": "refseq:NC_000014.9",
+    "adjacencyEnd": 107043718,
+    "adjacencyStart": 89300000,
+    "end": 145138636,
+    "referenceAccession": "refseq:NC_000008.11",
+    "requestProfileId": "VQSadjacencyRequest",
+    "start": 116700000,
+    "vrsType": "Adjacency"
 }```
 
 
@@ -139,15 +191,18 @@ Query for a deletion involving TP53 by using the HUGO name to specify the gene.
 * `variantMinLength`: `1000`    
     
 * `variantMaxLength`: `3000000`    
+    
+* `vrsType`: `copyChange`    
 
 ##### GET query string
-```requestType=VQSgeneIdRequest&geneId=TP53&copyChange=EFO:0030067&variantMinLength=1000&variantMaxLength=3000000```
+```requestType=VQSgeneIdRequest&geneId=TP53&copyChange=EFO:0030067&variantMinLength=1000&variantMaxLength=3000000&vrsType=copyChange```
 
 ##### POST query component 
 ```{
     "copyChange": "EFO:0030067",
     "geneId": "TP53",
     "requestType": "VQSgeneIdRequest",
     "variantMaxLength": 3000000,
-    "variantMinLength": 1000
+    "variantMinLength": 1000,
+    "vrsType": "copyChange"
 }```
diff --git a/docs/generated/requestProfiles_VQSsequenceRequest.md b/docs/generated/requestProfiles_VQSsequenceRequest.md
@@ -1,3 +1,3 @@
-# Request Profile: `VQSsequenceRequest`
+# Request Profile: `VQSalleleRequest`
 
 A Beacon v2+ sequence query. It is in its scope similar to the Beacon v1/v2 allele requests but replaces the original parameters with VRS v2 concepts.
diff --git a/docs/terms-and-values.md b/docs/terms-and-values.md
@@ -64,6 +64,15 @@ as well as a dedicated vocabulary derived from EFO terminology.
 
 * for CNV queries use the EFO terms for relative copy number changes for either
   `copyChange` or `variantType` parameters, depending on the Beacon version
+* in Beacon v2+ the `copyChange` parameter MUST use a primaryCode representing one of:
+    - EFO:0030069: complete genomic loss    
+    - EFO:0020073: high-level loss    
+    - EFO:0030068: low-level loss    
+    - EFO:0030067: loss    
+    - EFO:0030064: regional base ploidy    
+    - EFO:0030070: gain    
+    - EFO:0030071: low-level gain    
+    - EFO:0030072: high-level gain    
 * for other types of variations `variantType` according to query documentation and
   emerging examples
 * `variantType` might be replaced during future development
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Request Profile: `VQSalleleRequest`

		A Beacon v2+ sequence query. It is in its scope similar to the Beacon v1/v2 allele requests but replaces the original parameters with VRS v2 concepts.