From 256e260d934fbcecf503a7a053054850bed3f57b Mon Sep 17 00:00:00 2001 From: Michael Baudis <675030+mbaudis@users.noreply.github.com> Date: Tue, 19 Mar 2024 10:21:30 +0100 Subject: [PATCH] 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 --- docs/.DS_Store | Bin 6148 -> 6148 bytes docs/genomic-coordinates-mappings.md | 15 ++++ docs/index.html | 8 ++ docs/query-solutions.md | 72 ++++++++++++++++++ docs/terms-and-values.md | 15 ++++ docs/use-case-examples.md | 57 -------------- .../index.md => variant-types.md} | 9 ++- mkdocs.yml | 8 +- 8 files changed, 123 insertions(+), 61 deletions(-) create mode 100644 docs/genomic-coordinates-mappings.md create mode 100644 docs/index.html create mode 100644 docs/query-solutions.md create mode 100644 docs/terms-and-values.md delete mode 100644 docs/use-case-examples.md rename docs/{variant-types/index.md => variant-types.md} (86%) diff --git a/docs/.DS_Store b/docs/.DS_Store index 5008ddfcf53c02e82d7eee2e57c38e5672ef89f6..9a43e85e0593344a26bd51aa7b5ceae908e8a765 100644 GIT binary patch delta 351 zcmZoMXfc=|#>B)qF;Q%yo}wrd0|Nsi1A_nqLn1>SLkWW}5La$YT+UbzlHp}21Bw?h zWFpHl6fmSR6epDz7bNB6CjnJ$Pb$dCEG{uHxW>rD%)-jX&d$ls%^n+^kzXEMl2}q& z?37p(4dR95=jSBB*ojGDnW^RR0wT`&c_oRNd8tKU4VfvaKqWEZ^_h7o`Q=XerFkjE zV9mi08BR_P&UgXw>S_yf9R*V(i&`CpYD*&n9R(9JliFHN4pC)&>!A4ToZP(pPN3U> zfD!0FFyMvKFscj4!0AIihT^i|qP(2^ymX*4#*K*|SSA~Yux#e$;N}1Z-^Rr6%#-;= T6j?#Rq%he~M0#_8$QEV*S7%lY delta 70 zcmZoMXfc=|#>AjHu~2NHo+1YW5HK<@2y9kle#WxdfcX^DW_AvK4xj>{$am(+{342+ UKzW7)kiy9(Jj$D6L{=~Z02rPQkN^Mx diff --git a/docs/genomic-coordinates-mappings.md b/docs/genomic-coordinates-mappings.md new file mode 100644 index 0000000..b1d77cd --- /dev/null +++ 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 new file mode 100644 index 0000000..2e53cc8 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/query-solutions.md b/docs/query-solutions.md new file mode 100644 index 0000000..f944285 --- /dev/null +++ b/docs/query-solutions.md @@ -0,0 +1,72 @@ +# Use Case 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== \ No newline at end of file diff --git a/docs/terms-and-values.md b/docs/terms-and-values.md new file mode 100644 index 0000000..cd9deff --- /dev/null +++ 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== \ No newline at end of file diff --git a/docs/use-case-examples.md b/docs/use-case-examples.md deleted file mode 100644 index 7feefd6..0000000 --- a/docs/use-case-examples.md +++ /dev/null @@ -1,57 +0,0 @@ -# Use Case Examples - - - -## Any deletion(s) involving the TP53 gene locus - -### `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 -``` - -### `GeneRequest` - -For the interpretation of the "deletion" parameter see above. - -``` -?geneId=TP53&variantType=EFO:0030067 -``` - --------------------------------------------------------------------------------- - -## Copy number gains involving the whole locus (chr2:54,700,000-63,900,000) - -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. - -Besides the positions, this requires knowledge about the maximum value of the -reference base (or use of a very large one exceeding chromosome size; this example -here uses an "2nd end position equal to chr2 + 1" value). - -While the example uses `SO:0001742` for `copy_number_gain` the EFO term use -(`EFO:0030070`: `copy number gain`) should be 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== \ No newline at end of file diff --git a/docs/variant-types/index.md b/docs/variant-types.md similarity index 86% rename from docs/variant-types/index.md rename to docs/variant-types.md index 460c0a4..ad96436 100644 --- a/docs/variant-types/index.md +++ b/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 index e07fefc..4a2a2a8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,17 +4,19 @@ site_author: Michael Baudis copyright: '© 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 ----------------------------------->#