Optional Features

The Beacon specification contains some optional features that may be utilised or not.

Handover Protocol

The handover protocol is a feature comparable to HATEOAS and HAL. It can be used to convey extra information regarding the Beacon service, or the dataset response. More information about the handover protocol can be read from the Beacon Project page and Beacon Specification’s handover issue at Github.

The handover protocol can be configured in config.ini as follows:

[handover_info]
# The base url for all handovers
# if this url is empty or commented, handover feature is disabled
#drs=https://examplebrowser.org

# Make the handovers 1- or 0-based
handover_base = 1

# Handovers for datasets
dataset_paths=
  Variants,browse the variants matched by the query,dataset/{dataset}/browser/variant/{chr}-{start}-{ref}-{alt}
  Region,browse data of the region matched by the query,dataset/{dataset}/browser/region/{chr}-{start}-{end}
  Data,retrieve information of the datasets,dataset/{dataset}/browser

# Handovers for general beacon
beacon_paths=
  Project,retrieve information about the datasets,dataset/{dataset}

Note

Handover protocol is disabled by default, as shown by the commented out drs variable. This variable should point to the server, which serves the additional data. To enable the handover protocol, uncomment the drs variable.

The handover protocol will generate new objects to the beacon root object according to information given in the beacon_paths variable and to the includeDatasetResponses object according to information in dataset_paths. The line is spliced, so that the first CSV element becomes the label key in the handover, the second element becomes the description key and the third element becomes the url key.

Taking the first line from dataset_paths as an example, produces an object in the includeDatasetResponses object as follows:

{
    "datasetHandover": [
        {
            "handoverType": {
                "id": "CUSTOM",
                "label": "Variants"
            },
            "description": "browse the variants matched by the query",
            "url": "https://examplebrowser.org/dataset/{dataset}/browser/variant/{chr}-{start}-{ref}-{alt}"
        }
    ]
}

MateName Fusions

This extension deals with processing SVTYPE=BND where each adjacency ties together 2 breakends. Refer to Page 20 of the VCF documentation for more information.

REF	ALT	Meaning
s	t[p[	piece extending to the right of p is joined after t
s	t]p]	reverse comp piece extending left of p is joined after t
s	]p]t	piece extending to the left of p is joined before t
s	[p[t	reverse comp piece extending right of p is joined before t

Note

Where p is chr:pos.

Example queries:

localhost:5050/query?referenceName=1&\
                    referenceBases=N&\
                    start=108796059&\
                    assemblyId=GRCh38&\
                    variantType=BND&\
                    end=121482216&\
                    datasetIds=urn:hg:1000genome&\
                    includeDatasetResponses=HIT

localhost:5050/query?referenceName=1&\
                     referenceBases=N&\
                     start=108796059&\
                     assemblyId=GRCh38&\
                     mateName=10&\
                     end=121482216&\
                     datasetIds=urn:hg:1000genome&\
                     includeDatasetResponses=HIT

localhost:5050/query?referenceName=1&\
                     referenceBases=N&\
                     startMin=108796058&\
                     startMax=108796059&\
                     assemblyId=GRCh38&\
                     mateName=10&\
                     endMin=121482215&\
                     endMax=121482216&\
                     datasetIds=urn:hg:1000genome&\
                     includeDatasetResponses=HIT

Currently querying for a BND using startMin, startMax and endMin, endMax with variantType=BND has the response illustrated below. Fixed start and end can be utilised, as well as mateName as depicted above.

Note

By default when using mateName, variantType is implicit BND, but it can also be set in an explicit manner using both mateName and variantType=BND in a query.

{
"beaconId": "localhost:5050",
"apiVersion": "1.1.0",
"exists": true,
"alleleRequest": {
    "referenceName": "1",
    "referenceBases": "N",
    "assemblyId": "GRCh38",
    "includeDatasetResponses": "HIT",
    "datasetIds": [
        "urn:hg:1000genome"
    ],
    "startMin": 108796058,
    "startMax": 108796059,
    "endMin": 121482215,
    "endMax": 121482216
},
"datasetAlleleResponses": [
    {
        "datasetId": "urn:hg:1000genome",
        "referenceName": "1",
        "mateName": "10",
        "referenceID": "137_1",
        "mateID": "137_2",
        "mateStart": 121482216,
        "externalUrl": "ftp://example",
        "note": "Data",
        "variantCount": 0,
        "callCount": 0,
        "sampleCount": 1,
        "frequency": 0,
        "exists": true,
        "referenceBases": "N",
        "alternateBases": "N[CHR10:121482216[",
        "variantType": "BND",
        "start": 108796058,
        "end": 108796059,
        "info": {
            "accessType": "PUBLIC"
        }
    },
    {
        "datasetId": "urn:hg:1000genome",
        "referenceName": "10",
        "mateName": "1",
        "referenceID": "137_2",
        "mateID": "137_1",
        "mateStart": 108796059,
        "externalUrl": "ftp://example",
        "note": "Data",
        "variantCount": 0,
        "callCount": 0,
        "sampleCount": 1,
        "frequency": 0,
        "exists": true,
        "referenceBases": "N",
        "alternateBases": "]CHR1:108796059]N",
        "variantType": "BND",
        "start": 121482215,
        "end": 121482216,
        "info": {
            "accessType": "PUBLIC"
        }
    }
]
}