Skip to content

Progenetix API Services /services/

The bycon environment provides a number of data services which make use of resources in the Progenetix environment.

Services are not part of the standard bycon distribution but installed from the byconaut package.

Progenetix Beacon API

For the main Beacon data API please see the separate documentation page.

Formats

services.py and URL Mapping

The service URL format is progenetix.org/services/{serviceName}/?parameter=value.

API Response formats

Standard responses are provided as Content-Type: application/json. The wrapper format for JSON encoded data follows the standard Beacon response format where the main data is usually contained in the response.results list.

Services

Cancer Genomics Publications publications

The publications service serves as backend API for the display of genome screening publications through the Progenetix Publications DB.

It provides articles describing whole genome screening (WGS, WES, aCGH, cCGH) experiments in cancer, including some information about e.g. the numbers of samples analysed with a given technology and if sample profiles are available in Progenetix.

Please contact us to alert us about additional articles you are aware of. The inclusion criteria are described in the documentation.

Since 2021 you can now directly submit suggestions for matching publications to the oncopubs repository on Github.

Cytoband Mapping cytomapper

This services parses either:

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

While the return object is JSON by default, specifying text=1, together with the cytoBands or chroBases parameter will return the text version.

There is a fallback to GRCh38 if no assembly is being provided.

The cytoBands and chroBases parameters can be used for running the script on the command line (see examples below).

Examples

Response

As in other bycon services, API responses are in JSON format with the main content being contained in the response.results field.

Gene Coordinates genespans

  • genomic mappings of gene coordinats
  • initially limited to GRCh38 and overall CDS extension
  • responds to (start-anchored) text input of HUGO gene symbols using the geneId parameter or path value
  • returns a list of matching gene objects (see below under Response Formats)
  • the filterPrecision=exact query parameter restricts the response to a single exact gene symbol match

Examples

Ontology Cross-Mapping (ontologymappings)

The ontologymappings service provides equivalency mapping between ICD-O and other classification systems, notably NCIt. The mappings are represented in the ICDOntologies project and accessible trough a front-end in the Progenetix Services area.

ICD-O Representation

Our resources use an internal representation of ICD-O 3 codes since no official CURIES are provided by the IARC. The syntax is:

  • ICD-O 3 morphologies
    • "pgx:icdom-"s/\///; i.e. number only code
    • "8500/3" => pgx:icdom-85003
  • ICD-O 3 Topographies
    • "icdot-" + code
    • "C53.9" => pgx:icdot-C53.9

Parameters

filters
  • required
  • comma-concatenated complete codes and/or prefixes
  • partial codes (see above for ICD-O syntax) will not be matched unless a relaxed filter precision is indicated
filterPrecision
  • optional
  • to allow partial code matches (see examples below)

Examples

NCIt and ICD-O 3
UBERON and ICD-O 3 Topography

More Information

Public and Local Identifiers 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.

The pgx prefix has been registered with identifiers.org and the service can also be used to access identifiers at Progenetix.

Geographic Locations / Cities geolocations

This service provides geographic location mapping for cities above 25'000 inhabitants (~22750 cities), through either:

  • matching of the (start-anchored) name
    • optional use of one of
      • ISO3166alpha3
      • ISO3166alpha2
      • (start-anchored, partial...) country
  • providing GeoJSON compatible parameters:
    • geoLongitude
    • geoLatitude
    • geoDistance
      • optional, in meters; a default of 10'000m (10km) is provided
      • can be used for e.g. retrieving all places (or data from places if used with publication or sample searches) in an approximate region (e.g. for Europe using 2500000 around Heidelberg...)
      • optional use of a single ISO3166alpha3 or ISO3166alpha2 country code; e.g. ?geoLatitude=42.36&geoLongitude=-71.06&geoDistance=500000&ISO3166alpha3=USA&map_h_px=800 will show cities in the NE U.S. (500km around Boston, MA) w/o matching Canadian ones

Query Types

  • by city
    • start-anchored, case insensitive match ?city=heide
    • optional e.g. ?city=heidelberg&ISO3166alpha2=ZA
  • by id
    • this uses the city::country "id" value, e.g. lecce::italy
  • by geoLatitude & geoLongitude & geoDistance
    • geoDistance is to be given in meters

Response options

  • &output=text
  • &output=map
    • see below...
Examples

Geographic Maps

The new (2022) service utilizes the geolocations service to

  • display of matched cities on a map using the &output=map option
  • load arbitrary data from a hosted data table (e.g. on Github)

Map Projections of Query results

The option output=map activates a Leaflet-based map projection of the geomapping data (either from search results or provided as an external, web hosted file).

Parameters
  • output=map is required for the map display
  • help=true will show map configuration parameters
  • file=http://........tsv can be used to load a (tab-delimited) table of data w/ latitude + loniitude parameters for displaying it on a map

Map with markers from a hosted file

file properties

The current setup allows to have multiple items per "group", where a group corresponds to a single location (i.e. all items have the same latitude & longitude parameters).

group_label : Label text, required

group_lat : Latitude, required

group_lon : Longitude, required

item_size : size parameter, e.g. count for this item; will be summed up for all members of the same group (e.g. for a marker size corresponding to the group size); defaults to 1

item_label : Label for this item

item_link : Link for this item; optional

markerType : One of marker or circle; defaults to marker if no size is given

group_label group_lat   group_lon   item_size   item_label  item_link   markerType
Swiss   47  8   50  Progenetix  http://progenetix.org
Swiss   47  8   60  LSZGS 2 http://lifescienceszurich.ch
Swiss   47  8   100 UZH http://uzh.ch
Swiss   47  8   97  SIB http://sib.swiss
German  51  10  217     
Italian 44  11  75      
Austrian    48  15  41
Examples

  1. Before 2022-02-11 there where 3102 (or 6204) intervals. After this, a changed algorithm lead to avoidance of centromere-spanning intervals, i.e. shortened last intervals assigned to the chromosomal p-arm and downstream shifts of interval positions. ↩