Skip to content

API: Beacon Services

The bycon environment provides a number of data services beyond typical Beacon functionality. These services can be loosely grouped into two major types:

  • services which extend Beacon formats, i.e. use Beacon concepts and query parameters but provide non-standard output
    • plotting functions
    • tabular and text output
    • aggregated data such as CNV frequencies (see intervalFrequencies)
  • services which make use of utility function and data existing primarily for the support of Beacon functionality
    • ontology term cross mapping
    • geneId to location lookup
    • geographic location mapping and map projections (see geolocations)
    • ISCN cytogenetic band mapping
    • publication data for cancer genome screening publications

API Parameters

A complete list of parameters accepted by the API is provided on the Web and Command Line Parameters page.

Response formats

Standard responses are provided as Content-Type: application/json. The wrapper format is based on the Beacon v2 response format, with the data returned in the results array: 

meta:
  api_version: ...
  returned_schemas: [ ]
response:
  exists: true | false
  info: { }
  resultSets: [ ]

This (incomplete) example response may help with understanding the general format. Here, the data is a dictionary/object with a single key (genes):

Request Example

Plotting

The byconServices package inside bycon provides a number of plotting functions which can be used to visualize the data in the database. Generally plot functionality is focussed on generating CNV visualizations for per-sample and aggregated CNV data (e.g. frequencyplots). Additionally some geographic map projectins are provided e.g. for samples and metadata.

More information can be found in the plot documentation on this page.

List of Services

/byconschemas

This helper service reads and serves local schema definition files. The name of the schema (corresponding to the file name minus extension) is provided either as an id query parameter or as the first part of the path after schemas/.

/cnvstats

TBD

/collationplots

The collationplots function is a service to provide plots for CNV data aggregated for samples matching individual filter values such as diagnostic codes or experimental series id values. The default response is an SVG histogram ("histoplot"). Please refer to the plot parameters documentation and the ByconPlot class for other options.

For a single plot one can provide the entity id as path id value.

Examples (using the Progenetix resource as endpoint):

/collations

The collations service provides access to information about data "subsets" in the project databases. Collations typically are aggregations of samples sharing an ontology code (e.g. NCIT) or external identifier (e.g. PMID). Therefore, in the context of Beacon the collations in bycon provide the filtering_terms available through Beacon queries, but also additional information e.g. about child terms and statistics related to the terms.

In the case of the web projects the main purpose of the `services/collations/ endpoin is in providing the child terms and path relations for generating ontology trees in the UI.

Parameters

  • collationTypes=...
  • includeDescendantTerms=false
  • only delivers data about codes with direct matches, i.e. excluding such where only a child term had a direct match
  • this is especially useful for e.g. getting a fast overview about mappings of deeply nested coding systems like NCIT
  • deliveryKeys=...

Examples

/cytomapper

The cytomapper function provides a JSON response with cytoband information such as matched cytobands and the genome coordinates of their extend.

There is currently only support for GRCh38.

Response Schema

Parameters

  • cytoBands (path default)
    • a properly formatted cytoband annotation
    • "8", "9p11q21", "8q", "1p12qter"
  • or chroBases
    • 7:23028447-45000000
    • X:99202660

Examples (using the Progenetix resource as endpoint):

/dbstats

This service endpoint provides statistic information about the resource's datasets.

Examples

/endpoints

The service provides the schemas for the BeaconMap OpenAPI endpoints.

Examples (using the Progenetix resource as endpoint):

/genespans

The genespans function provides a JSON response with the coordinates of matching gene IDs.

Examples (using the Progenetix resource as endpoint):

/geolocations

TBD

Examples

/ids

The ids service forwards compatible, prefixed ids (see config/ids.yaml) to specific website endpoints. There is no check if the id exists; this is left to the web page handling itself.

Stacking with the "pgx:" prefix is allowed.

Examples (using the Progenetix resource as endpoint):

/intervalFrequencies

None

/ontologymaps

Examples

/pgxsegvariants

None

/publications

The publications service provides API functionality for accessing the Progenetix publications collection, which represents curated information about several thousand articles reporting genome-wide screening experiments in cancer.

Examples

/samplemap

TBD

/samplematrix

The service uses the standard bycon data retrieval pipeline with analysis as entity type. Therefore, all standard Beacon query parameters work and also the path is interpreted for an biosample id value if there is an entry at .../biosamples/{id}

/sampleplots

The plot service uses the standard bycon data retrieval pipeline with biosample as entity type. Therefore, all standard Beacon query parameters work and also the path is interpreted for an biosample id value if there is an entry at .../sampleplots/{id}

The plot type can be set with plotType=samplesplot (or histoplot but that is the fallback). Plot options are available as usual.

Examples (using the Progenetix resource as endpoint):

/sampletable

The service uses the standard bycon data retrieval pipeline with biosample as entity type. Therefore, all standard Beacon query parameters work and also the path is interpreted for an biosample id value if there is an entry at .../sampletable/{id}

The table type can be changed with tableType=individuals (or analyses).

Examples

/services

The services application deparses a request URI and calls the respective script. The functionality is combined with the correct configuration of a rewrite in the server configuration for creation of canonical URLs.

/uploader

This service is used by UI implementations to upload user provided .pgxseg files for visualization of the variants using the packages plotting functions.

As exception to the general rule the uploader service does not make use of standard argument parsing but directly uses cgi.FieldStorage() and ....file.read().

/variantsbedfile

The variantsbedfile function provides a BED file with the matched genomic variants from a Beacon query or a sample id.

Examples

/vcfvariants

The VCF service uses the standard bycon data retrieval pipeline with biosample as entity type. Therefore, all standard Beacon query parameters work and also the path is interpreted for an biosample id value if there is an entry at .../vcfvariants/{id}

Examples