more site structure & content

* added genomic coordinates placeholder page * added terminologies placeholder page * added another solution example from the old scouts doc * reformatted solution examples to use collapsed admonitions
ga4gh-beacon · Mar 19, 2024 · 256e260 · 256e260
1 parent 35633ce
commit 256e260
Show file tree

Hide file tree

Showing 8 changed files with 123 additions and 61 deletions.
diff --git a/docs/.DS_Store b/docs/.DS_Store
diff --git a/docs/genomic-coordinates-mappings.md b/docs/genomic-coordinates-mappings.md
@@ -0,0 +1,15 @@
+# Genomic Coordinates and Mappings
+
+!!! Attention "GA4GH Beacon Genome Coordinate Use Recommendation[^1]"
+
+    * Beacon recommends the use of a __"0-start, half-open"__ (interbase) coordinate
+      system
+    * __"1-start, fully-closed"__ should be used when displaying coordinates through
+      a Beacon GUI
+
+## Variant normalization
+
+==TBD==
+
+
+[^1]: Source: [@andrewyatz](https://github.com/@andrewyatz/) at [GenomeStandards](https://genomestandards.org/standards/genome-coordinates/)
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,8 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta http-equiv="refresh" content="0; url='./variant-scouts-home/'" />
+  </head>
+  <body>
+  </body>
+</html>
diff --git a/docs/query-solutions.md b/docs/query-solutions.md
@@ -0,0 +1,72 @@
+# Use Case Examples
+
+<!--
+TODO:
+* more examples
+* GET vs. POST examples
+-->
+
+## Any deletion(s) involving the TP53 gene locus
+
+??? tip "Using `VariantRangeRequest`"
+
+	The query can be created by using the maximum extent of the TP53 coding region
+	(optionally extended for functionally relevent elements, e.g. promotor), and a
+	`variantType` parameter supported by the implementation. The interpretation of
+	"any deletion" is not straightforward; this would potentially include small
+	INDELS specified as sequence alterations as well as copy number deletions.
+
+	*Recommendation* Implementers should provide a mechanism to match any "deletion" `variantType`
+	(`EFO:0030067`, `DEL`, `SO:0001743`) independent of size since operational definitions
+	of `CNV` vs. `INDEL` vary, and use explicit `variantMinLength`, `variantMaxLength`
+	parameters if needed.
+
+	```
+	?referenceName=NC_0000017.11&start=7669608&end=7676593&variantType=EFO:0030067
+	```
+
+??? tip "Using `GeneRequest`"
+
+	For the interpretation of the "deletion" parameter see above.
+
+	```
+	?geneId=TP53&variantType=EFO:0030067
+	```
+
+
+## Insertion event in gene TP53 (17:7669607-7676593) or in close proximity (±~5000bp)
+
+??? tip "Using `VariantRangeRequest`"
+
+	For this query the mapping position of TP53 (17:7669607-7676593) has to be
+	known. Usually this knowledge would be provided by a front end helper and
+	the aditional padding added manually or w/ a helper field (if frequent scenario)
+	and the beacon itself would just receive the positional range request.
+
+	The "insertion" type is here provided through the Sequence Ontology term
+	`SO:0000667` and for the chromosome the full, prefixed RefSeq term is being used.
+
+	```
+	?referenceName=refseq:NC_000017.11&start=7664000&end=7682000&variantType=SO:0000667
+	```
+
+## Copy number gains involving the _whole_ locus _chr2:54,700,000-63,900,000_
+
+??? tip "Using `VariantBracketRequest`"
+
+	The query has to indicate the involved genomic region by positions as well as the
+	type of change. Here, matched duplication events start 5\` of the region and end 3\`
+	of it. For capturing any event upt to the complete chromosome duplication this
+	requires knowledge about the maximum value (_i.e._ chromosome base length; using a
+	random very large number might fail depending on the implementation).
+
+	The example uses `EFO:0030070` for `copy number gain` instead of the alternative
+	`SO:0001742` `copy_number_gain` as the preferred since the EFO terms
+	provide a more granular expressivity and are referenced in the
+	[VRS definitions](https://vrs.ga4gh.org/en/latest/terms_and_model.html#systemic-variation).
+
+	```
+	?referenceName=refseq:NC_000002.12&start=0,54700000&end=63900000,242193529&variantType=SO:0001742
+	```
+
+==TBD==
diff --git a/docs/terms-and-values.md b/docs/terms-and-values.md
@@ -0,0 +1,15 @@
+# Recommended Ternminologies and Example Values
+
+Beyond single beacons or managed beacon networks the use of common, widely supported and standardized query values is of special importance to empower federated queries.
+The main examples relevant to variation queries here are `referenceName` and
+`variantType`. 
+
+!!! info "Value Definitions in the Beacon Schemas"
+
+	In most of its schemas the Beacon v2 specification is not prescriptive in the
+	specific values permitted for individual parameters and provides a number of
+	legacy values as examples in its inline documentation. This was thought
+	to promote flexibility (e.g. non-human use cases) and simple adoption (e.g. reusing
+	VCF terms).
+
+==TBD==
diff --git a/docs/use-case-examples.md b/docs/use-case-examples.md
diff --git a/docs/variant-types/index.md → docs/variant-types.md b/docs/variant-types/index.md → docs/variant-types.md
@@ -45,4 +45,11 @@ manifestations.
 
 ### Cytogenetic fusions and translocations
 
-==TBD==
+### Variants by effect or annotation
+
+### Quantitative parameters related to regions and elements
+
+* expression
+* methylation
+
+... ==TBD==
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -4,17 +4,19 @@ site_author: Michael Baudis
 copyright: '&copy; Copyright 2024 GA4GH and Beacon Contributors'
 repo-name: variant-query-types
 repo_url: https://github.com/ga4gh-beacon/variant-query-types
-edit_uri: edit/main/docs/
+edit_uri: blob/main/docs/
 schemas_path: /blob/main/schemas/
 
 ###############################################################################
 
 nav:
-  - 'Home': variant-scouts-home
+  - Introduction: variant-scouts-home
   - Variation Types: variant-types
   - Request Parameters: query-types/variantRequestParameters
   - Query Types: query-types
-  - Use Cases: use-case-examples
+  - Genomic Coordinates: genomic-coordinates-mappings
+  - Recommended Terms: terms-and-values
+  - Query Solutions: query-solutions
   - Query Schema Source Files: https://github.com/ga4gh-beacon/variant-query-types/tree/main/schemas
 
 #<--------------------------- / Navigation ----------------------------------->#