sbeacon-exploration

Serverless Beacon v2 exploration for UMCCR use cases.

Demo instance

Our demo instance is available at https://beacon.demo.umccr.org

Please note that this is for testing only. We may change the service without notice.

Test dataset

CINECA_synthetic_cohort_EUROPE_UK1

sBeacon

For the implementation, we test drive the serverless beacon implementation from Transformational Bioinformatics team at CSIRO AEHRC.

Setting up sBeacon

CSIRO sBeacon team has added support to the recent GA4GH Beacon v2 specification.
We (UMCCR team) are working closely with CSIRO sBeacon team on test-driving this pilot deployment effort.
This development activity is happening in dev branch of sBeacon GitHub repo.
Deploy the serverless beacon following the instructions on the sBeacon GitHub repo
- https://github.com/aehrc/terraform-aws-serverless-beacon/tree/dev
- The Postman collection is provided in utils can be used for testing the API.
Create submission JSON for the dataset as specified for the sBeacon ingestion API
- We use the Jupyter Notebook in scripts to transform (ETL) the metadata from the Excel file into the sBeacon submission JSON.

Example queries

The following is an example for scenario-driven Beacon query.

Example1

Get service info

curl -s -X GET 'https://beacon.demo.umccr.org/info' | jq

Get service map

curl -s -X GET 'https://beacon.demo.umccr.org/map' | jq

Get service configuration

curl -s -X GET 'https://beacon.demo.umccr.org/configuration' | jq

Example2

Get all individuals

curl -s -X GET 'https://beacon.demo.umccr.org/individuals?requestedGranularity=record&limit=10' | jq

Example3

Get all available filtering terms for individuals endpoint

curl -s -X GET 'https://beacon.demo.umccr.org/individuals/filtering_terms' | jq

Example4

Get all individuals from the British Isles (i.e. EBI/OLS - GAZ:00001505). This makes use of ontology expansion to fetch individuals with geographic origins in England, Wales, Scotland, Ireland, etc.

curl -s -X POST 'https://beacon.demo.umccr.org/individuals?requestedGranularity=record' \
--header 'Content-Type: application/json' \
--data-raw '{
    "meta": {
        "apiVersion": "v2.0"
    },
    "query": {
        "requestedGranularity": "record",
        "filters": [
            {
                "id": "GAZ:00001505"
            }
        ],
        "pagination": {
            "limit": 100,
            "skip": 0
        }
    }
}' | jq

Example5

Search, if there exists any Genomic Variant C > G SNP at specified Chromosome 5 region.

curl -s -X POST 'https://beacon.demo.umccr.org/g_variants' \
--header 'Content-Type: application/json' \
--data-raw '{
    "meta": {
        "apiVersion": "v2.0"
    },
    "query": {
        "includeResultsetResponses": "HIT",
        "requestedGranularity": "record",
        "requestParameters": {
            "assemblyId": "GRCh38",
            "start": [
                10000000,
                10001000
            ],
            "end": [
                10000000,
                10001000
            ],
            "referenceBases": "C",
            "referenceName": "5",
            "alternateBases": "G"
        }
    }
}' | jq

NOTE: Please take note of the Beacon response Variant Internal ID i.e. "R1JDaDM3CTUJMTAwMDAxMjQJQwlH"

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "info": {},
  "meta": {
    "beaconId": "sbeacon.umccr.org",
    "apiVersion": "v2.0.0",
    "returnedSchemas": [
      {
        "entityType": "info",
        "schema": "beacon-map-v2.0.0"
      }
    ],
    "returnedGranularity": "record",
    "receivedRequestSummary": {
      "apiVersion": "v2.0.0",
      "requestedSchemas": [],
      "pagination": {
        "limit": 100,
        "skip": 0
      },
      "requestedGranularity": "record"
    }
  },
  "response": {
    "resultSets": [
      {
        "exists": true,
        "id": "redacted",
        "results": [
          {
            "variantInternalId": "R1JDaDM3CTUJMTAwMDAxMjQJQwlH",
            "variation": {
              "referenceBases": "C",
              "alternateBases": "G",
              "location": {
                "interval": {
                  "start": {
                    "type": "Number",
                    "value": 10000124
                  },
                  "end": {
                    "type": "Number",
                    "value": 10000125
                  },
                  "type": "SequenceInterval"
                },
                "sequence_id": "GRCh37",
                "type": "SequenceLocation"
              },
              "variantType": "SNP"
            }
          }
        ],
        "resultsCount": 1,
        "resultsHandovers": [],
        "setType": "genomicVariant"
      }
    ]
  },
  "responseSummary": {
    "exists": true,
    "numTotalResults": 1
  }
}

Example6

From Example5 query, there exists SNP at specified location.
Find all individuals that correspond to this SNP variant.

curl -s -X POST 'https://beacon.demo.umccr.org/g_variants/R1JDaDM3CTUJMTAwMDAxMjQJQwlH/individuals' \
--header 'Content-Type: application/json' \
--data-raw '{
    "meta": {
        "apiVersion": "v2.0"
    },
    "query": {
        "requestedGranularity": "record",
        "pagination": {
            "limit": 100,
            "skip": 0
        },
        "filters": []
    }
}' | jq

Example6.1

Consider further filter this SNP variant with individuals from the British Isles background (ref: Example4, GAZ ontology term ID)

curl -s -X POST 'https://beacon.demo.umccr.org/g_variants/R1JDaDM3CTUJMTAwMDAxMjQJQwlH/individuals' \
--header 'Content-Type: application/json' \
--data-raw '{
    "meta": {
        "apiVersion": "v2.0"
    },
    "query": {
        "requestedGranularity": "record",
        "pagination": {
            "limit": 100,
            "skip": 0
        },
        "filters": [
            {
                "id": "GAZ:00001505"
            }            
        ]        
    }
}
' | jq

Example6.2

Or consider filter this SNP variant with individuals related to Asthma; ICD disease code ICD10:J45

curl -s -X POST 'https://beacon.demo.umccr.org/g_variants/R1JDaDM3CTUJMTAwMDAxMjQJQwlH/individuals' \
--header 'Content-Type: application/json' \
--data-raw '{
    "meta": {
        "apiVersion": "v2.0"
    },
    "query": {
        "requestedGranularity": "record",
        "pagination": {
            "limit": 100,
            "skip": 0
        },
        "filters": [
            {
                "id": "ICD10:J45"
            }
        ]
    }
}
' | jq

anuradhawick/sbeacon-exploration