From 936383e5dc4582f2c53b8586369011eab0bb9262 Mon Sep 17 00:00:00 2001 From: Michael Baudis Date: Mon, 30 Sep 2024 15:39:56 +0200 Subject: [PATCH] genomebeacons.org migration entry --- docs/FAQ.md | 164 ----------------------------------- docs/changes-todo.md | 17 ++++ docs/css/theme_overrides.css | 2 +- docs/index.md | 2 +- mkdocs.yaml | 4 +- 5 files changed, 21 insertions(+), 168 deletions(-) delete mode 100644 docs/FAQ.md diff --git a/docs/FAQ.md b/docs/FAQ.md deleted file mode 100644 index 11758f132..000000000 --- a/docs/FAQ.md +++ /dev/null @@ -1,164 +0,0 @@ -# Frequently Asked Questions - -!!! Note "Citation" - - **Beacon v2 and Beacon Networks: a "lingua franca" for federated data discovery in biomedical genomics, and beyond.** - Jordi Rambla, Michael Baudis, Tim Beck, Lauren A. Fromont, Arcadi Navarro, Manuel Rueda, Gary Saunders, Babita Singh, J.Dylan Spalding, Juha Tornroos, Claudia Vasallo, Colin D.Veal, Anthony J.Brookes. _Human Mutation_ (2022) [DOI](https://doi.org/10.1002/humu.24369). - -??? faq "How do I emulate Beacon v1 while supporting the v2 protocol? " - - The [Beacon Framework](/framework) describes the overall structure of the API - requests, responses, parameters etc. One can implement e.g. a Boolean beacon (_cf._ the - original protocol) without any use of the model, just by providing a well-formed - JSON response upon a request [very similar to the (pre-)v1 allele request](/variant-queries/#beacon-sequence-queries). - - - ##### Minimal Example Request - - This example is for a minimal SNV-type variant query. - - ``` - /beacon/g_variants/?referenceName=refseq:NC_000017.11&start=7577120&referenceBases=G&alternateBases=A - ``` - - ##### Example Boolean Response - - In this minimal response to the query above the beacon indicates that its default - response is Boolean and that it could interpreted it against the `genomicVariant` entity and in the context of the same Beacon version. - - In principle one could launch a Beacon instance using the example response document as a template - in whatever server environment one has at hand. However, a proper Beacon v2 - installation also has to provide informational endpoints (`/info`, `/map` ...) - to allow it's integration through [aggregators](/networks/). - - ```json - { - "meta": { - "apiVersion": "v2.0.0", - "beaconId": "org.progenetix.beacon", - "receivedRequestSummary": { - "apiVersion": "v2.0.0", - "pagination": { - "limit": 2000, - "skip": 0 - }, - "requestedGranularity": "boolean", - "requestedSchemas": [ - { - "entityType": "genomicVariant", - "schema": "https://progenetix.org/services/schemas/genomicVariant/" - } - ], - "requestParameters": { - "alternateBases": "A", - "referenceBases": "G", - "referenceName": "refseq:NC_000017.11", - "start": [ - 7577120 - ] - } - }, - "returnedGranularity": "boolean", - "returnedSchemas": [ - { - "entityType": "genomicVariant", - "schema": "https://progenetix.org/services/schemas/genomicVariant/" - } - ] - }, - "responseSummary": { - "exists": true - } - } - ``` - - ###### last change 2023-02-17 @mbaudis - -??? faq "Is it `Beacon` or `beacon`?" - - The uppercase `Beacon` is used to label API, framework or protocol and their - components - while lower case `beacons` are instances of these, _i.e._ individual - resources using the protocol. - - ###### last change 2022-10-01 by @mbaudis - -??? faq "What types of genomic variants are supported in Beacon queries?" - - Beacon v2.0 does not provide a mechanism to detect what types of genomic variant - queries are supported by a given instance. - - Beacon had been originally designed to handle the "simplest" type of genomic - variant queries in which a `position`, `alternateBases` (_i.e._ one or more base - sequence of the variant at the position) and - sometimes optional - the reference - sequence at this position (necessary e.g. for small deletions). - - Beacon v1.1 in principle supported "bracketed" queries and a `variantType` parameter - (pointing to the VCF use) - see the [current documentation](https://docs.genomebeacons.org/variant-queries/#beacon-bracket-queries) for details. However, the support & interpretation was - and still is (2022-12-13) - - left to implementers. Similar for [Beacon Range Queries](https://docs.genomebeacons.org/variant-queries/#beacon-range-queries). - - However, the [Beacon documentation](https://docs.genomebeacons.org/variant-queries/#varianttype-parameter-interpretation) - provides information about use and expected interpretation of `variantType` values, specifically - for copy number variations. - - ###### last change 2022-12-14 @mbaudis - - -??? faq "How can I add e.g. an age limit to a query for a disease?" - - Ages are queried as [ISO8601 durations](https://genomestandards.org/standards/dates-times/#durations) - such as `P65Y` (_i.e._ 65 years) with a comparator (`=`, `<=`, `>` ...). However, - the value needs an indication of _what_ the duration refers to and resources - may provide different ways to indicate this (as then shown in their `/filtering_terms`) - endpoint). - - We recommend that all Beacon instances that support age queries support at - minimum the syntax of `age:<=P65Y` and map such values to the internal datapoint - most relevant for the resource's context (in most cases probably corresponding - to "age at diagniosis"). - - However, different scenarios may be supported (e.g. `EFO_0005056:<=P1Y6M` for - an "age at death" scenario). - - ###### last change 2023-05-31 by @mbaudis - -??? faq "How can I handle haplotype queries & representation in Beacon v2? " - - #### Queries - - The Beacon framework currently (_v2.0_ and earlier) considers genomic - variants to be _allelic_ and does not support the query for multiple alleles - or "haplotype shorthand expressions" (e.g. `C,T`). - - **Workarounds** In case of a specific need for haplotype queries implementers - of a given beacon with control of its data content in principle can extend their - query model to support shorthand haploype expressions, as long as they support - the standard format, too. However, such an approach may be superseeded or in conflict - with future direct protocol support. - - An approach in line with the current protocol would be to query for one allelic - variant with a record-level `genomicVariation` response, and then query the - retrieved variants individually by their `id` in combination with the second - allele. - - #### Variant representation - - As with queries the Beacon "legacy" format does not support haplotype representation - but would represent each allelic variation separately. The same is true for the - VRSified variant representation which for v2.0 corresponds to VRS v1.2. - However, draft versions of the VRS standard (will) address haplotype and genotype - representations and will be adopted by Beacon v2.n after reaching a release state. - - -??? faq "Does the Beacon protocol support Boolean expressions? " - - No (...but). Beacon queries as of v2 always assume a logical **AND** between query parameters - and individual filters, _i.e._ all conditions have to be met. There is currently - no support for Boolean expressions. - However, a logical exception is the use of multiple filters for the same parameter which - a Beacon implementation should treat as a logical **OR** since they otherwise - would fail in most instances. E.g. the query using `NCIT:C3493` and `NCIT:C2926` - (mapped against `biosample.histological_diagnosis.id`) would match both - _Lung Non-Small Cell Carcinoma_ (NCIT:C2926) and _Lung Squamous Cell Carcinoma_ - (NCIT:C3493) which are exclusive diagnoses. - - diff --git a/docs/changes-todo.md b/docs/changes-todo.md index 463115d70..8424ff380 100644 --- a/docs/changes-todo.md +++ b/docs/changes-todo.md @@ -5,6 +5,23 @@ of the Beacon project site(s) as well as with overarching repository organizatio ## Changes +### 2024-08-08: [genomebeacons.org](https://genomebeacons.org) now default Beacon domain + +We have now migrated towards general use fo the `genomebeacons.org` domain for +Beacon-related services and documentation. The main addresses are: + +* [genomebeacons.org](https://genomebeacons.org) - main site for information, news ... +* [docs.genomebeacons.org](https://docs.genomebeacons.org) - documentation site for API development and implementations + +In due course we will disentangle the current pages and purge the more general Beacon +information from [docs.genomebeacons.org](https://docs.genomebeacons.org). A start +has been made with the **F**requently **A**sked **Q**uestions section which is now under +[genomebeacons.org/FAQ](https://genomebeacons.org/FAQ). + +The old domain [beacon-project.io](https://beacon-project.io) still exists but +is only used for forwarding. + + ### 2023-06-12: Restructured and extended documentation * new separation of navigation areas into "Introducing Beacon", "Using Beacons", diff --git a/docs/css/theme_overrides.css b/docs/css/theme_overrides.css index 9dccbd298..a31b89747 100644 --- a/docs/css/theme_overrides.css +++ b/docs/css/theme_overrides.css @@ -3,7 +3,7 @@ } .md-grid { - max-width: 1024px; + max-width: 1200px; } .md-header__source { diff --git a/docs/index.md b/docs/index.md index ed5eaa63f..0088a867f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,7 +38,7 @@ considered important by the community such as: With the release of Beacon v2 implementations of v1 and earlier are not longer supported. Deployers of Beacon instances or networks are advised to migrate to v2 of the - standard. The functionality of Beacon v1 [can be easily implemented in v2](/FAQ/#v1-emulation). + standard. The functionality of Beacon v1 [can be easily implemented in v2](https://genomebeacons.org/FAQ/#v1-emulation). This website represents information about the Beacon protocol, its use for **data discovery** and **data delivery** but also about ways towards diff --git a/mkdocs.yaml b/mkdocs.yaml index 0a047961e..2c21e333a 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -1,7 +1,7 @@ site_name: Beacon v2 Documentation site_description: 'Documentation for Beacon v2' site_author: 'Michael Baudis, Manuel Rueda, Laureen Fromont & Beacon Developers' -copyright: '© Copyright 2021-2023, Beacon v2 Documentation Contributors' +copyright: '© Copyright 2021-2024, Beacon v2 Documentation Contributors' repo_name: 'beacon-v2' repo_url: https://github.com/ga4gh-beacon/beacon-v2 edit_uri: edit/main/docs/ @@ -18,8 +18,8 @@ nav: - Beacon Types: beacon-flavours - Security: security - Beacon Networks: networks - - FAQ: FAQ - Changes: changes-todo + - FAQ ↗: https://genomebeacons.org/FAQ/ - Beacon News ↗: https://genomebeacons.org/news/ - Using Beacons: - Genomic Queries: variant-queries