VariantDB

Documentation : API access to VariantDB

The API is designed to provide remote access to the filtering functions of VariantDB. Results are provided in JSON format. There is currently no functionality to change anything using the API.

Preparation: Obtaining an API key

API access requires a valid api key. To obtain this key, go to the "My Details" page (Accessible by clicking on your username in the top right corner). Check the box to create an API key and press 'Submit'. The presented API-key is a random string of 32-characters, and is valid for 1 week by default. Optionally, an API-key can be made valid indefinitely and can be disabled on demand.

The API-key must be provided on all API calls as follows:

NOTE: Do not share your api key, as it represents your login credentials. Once the API will support editing of data, sharing the key can have serious consequences.

API Command 'SavedFilters'

If no filter-id is provided, this method gets all stored filters. The result contains the following items for each stored filter:

• fid: Numeric Filter-ID.
• FilterName: The name associated to the filterset
• Comments: Optional extra information provided when saving the filterset
• nrRules: The number of filtering criteria included in the filterset

API Command 'SavedFilters/<filter_id>'

Retrieve full details on the specified filter. Returned items are:

• FilterName: The name associated to the filterset
• Comments: Optional extra information provided when saving the filterset
• Created: Date that filterset was saved in the system
• FilterSettings: String representation of filter details. Elements are delimited by '@@@', key-value pairs by '|||'. A filter rule consists of :
  1. Category: First level section (family, ANNOvAR, ClinVar, ...)
  2. Negate: Include or exclude matching variants
  3. Param: Second level section (RefSeq_Variant_Type, RefSeq_Gene_Location, ...)
  4. Argument: Selected items in option-lists (exonic, intronic, 5'UTR, ...). These values are typically encoded to integers. See API 'GetValueCodes' for decoding options
  5. Value: Value provided by the user in a free text field (e.g. Minimal depth value)
• FilterTree: JSON encoded representation of the filtering logic. Note that this item is double-encoded, escaping all regular JSON characters.

API Command 'LoadFilter'

Import a JSON representation of a saved filter set. This method requires POST submission to the API. Posted variables are:

• json_file: Text file with json representation of the filter set. It's a dump of api-call SavedFilters/<filter_id>
• apiKey: Your api-userkey.

The method returns the ID of the newly created filter set (field: 'id'). See example scripts for more details.

API Command 'SavedAnnotations'

If no annotationset-id is provided, this method gets all stored annotation sets. The result contains the following items for each stored set:

• aid: Numeric Annotation-ID.
• AnnotationName: The name associated to the annotation set
• Comments: Optional extra information provided when saving the set
• nrItems: The number of items selected in the set

API Command 'SavedAnnotations/<annotation_id>'

Retrieve full details on the specified annotation set. Returned items are:

• AnnotationName: The name associated to the annotation set
• Comments: Optional extra information provided when saving the set
• Created: Date that annotation set was saved in the system
• AnnotationSettings: List of selected annotations. Items are delimeted by '@@@'. Each item consists of a <Category>;<Annotation_Name> combination.

API Command 'LoadAnnotations'

Import a JSON representation of a saved annotation set. This method requires POST submission to the API. Posted variables are:

• json_file: Text file with json representation of the annation set. It's a dump of api-call SavedAnnotations/<annotation_id>
• apiKey: Your api-userkey.

The method returns the ID of the newly created annotation set (field: 'id'). See example scripts for more details.

API Command 'Samples'

Retrieve a list of all samples you have access to. Basic provided sample details include:

• id: Database identifier of the sample
• sample_name: Provided sample name
• gender: Either 'Male', 'Female', or 'Undef'
• project_name: The name of the project in which the sample is stored.
• project_id: Database identifier of the listed project.

API Command 'Samples/<sample_id>'

Retrieve full details on the specified sample. Returned items are:

• id: Database identifier of the sample
• sample_name: Provided sample name
• gender: Either 'Male', 'Female', or 'Undef'
• project_name: The name of the project in which the sample is stored.
• project_id: Database identifier of the listed project.
• project_created: Date when project was initially created. This does not neccessarily reflect the creation date of the sample.
• clinical_freetext: Provided free-text clinical information of the sample.
• clinical_hpo: Structured clinical information according to HPO. Included information per associated HPO term:
  • hpo_id: HPO identifier (e.g. HP:0001263)
  • hpo_term: Short HPO name of the phenotype
  • hpo_definition: Definition of the phenotype according to HPO
  • hpo_comment: Further information regarding the term.
  • hpo_xref: External identifiers corresponding to the HPO-id
• pedigree: Sample relation to rebuild the pedigree. Contains a node (by sample_id) for each sample in the pedigree holding the following information
  • Replicates: The same sample, under additional ids
  • Siblings: Brothers and/or sisters
  • Parents: Father and/or Mother
  • Children: If any, the children of the sample
  • Each of the above is a list with sample_id, sample_name and sample_gender
• nr_variants: The number of variants for the current sample, without any applied filters.
• marked_as_finished: 0/1. Samples can be marked as finished in VariantDB.
• control_sample: 0/1. Indicates if sample is a control sample.

API Command 'SubmitQuery/Sample/<sample_id>'

Run Query on a specific sample. Available parameters are:

• <sample_id>: Mandatory. Numeric sample_id of the sample under study.
• fid=<filter_id>: Optional. Filter setting to use. Only single filters are possible. Create and store filters using the web-interface to apply them here.
• aid=<annotation_id>: Optional. Annotation sets to add to the variants. Multiple sets can be provided as a comma seperated list.
• slicestart=<integer>: Optional. If provided, retrieve 100 variants (chromosome/position sorted), starting from the provided value. If absent, retrieve all variants.

The returned structure contains:

• query_key: Key to retrieve the results of the query
• queue_position: Position on the processing queue
• hpc_job_id: If queries are executed on a HPC-system, this value contains the internal hpc_job_id returned from the scheduler.

API Command 'SubmitQuery/Region/<region_description>'

Run Query on a specific region. Available parameters are:

• <region_description>: Mandatory. This can be either a RefSeq gene sybmol (e.g. ANK3, or a UCSC region description (e.g. chr5:1545000-1546000).
• fid=<filter_id>: Optional. Filter setting to use. Only single filters are possible. Create and store filters using the web-interface to apply them here.
• aid=<annotation_id>: Optional. Annotation sets to add to the variants. Multiple sets can be provided as a comma seperated list.
• slicestart=<integer>: Optional. If provided, retrieve 100 variants (chromosome/position sorted), starting from the provided value. If absent, retrieve all variants.

The returned structure contains:

• query_key: Key to retrieve the results of the query
• queue_position: Position on the processing queue
• hpc_job_id: If queries are executed on a HPC-system, this value contains the internal hpc_job_id returned from the scheduler.

API Command 'GetStatus/Query/<query_id>'

Get status of a query specified by its ID. The returned structure contains:

• status: Current status. Is one of queued/finished/running/error
• queue_position: Provided if still queued
• message: Provided if status is 'error', contains information on the problem
• stderr: Further error messages, if available in case of 'error'
• ERROR: Error message in case of failure to check query status

API Command 'GetStatus/Queue'

Get status of the queue for api-submitted queries. The returned structure contains the number of queued queries:

API Command 'GetStatus/Annotation'

Get the annotation status of VariantDB. Reports on pending and/or running annotation jobs for variants and modified gene panels

API Command 'GetStatus/Annotation/<sample_id>'

Get the annotation status of a specified sample. Reports timestamp when annotation was finished.

API Command 'GetStatus/Revision'

Get current version of VariantDB. Specified as the mercurial revision. The returned structure contains the output from "hg tip" for both the web-interface and the database backend.

API Command 'GetStatus/VariantDB'

Get the status of VariantDB itself. Status can be:

• Operative: System is fully operational.
• Construction: System is down for maintenance. All queries are delayed (paused), access to the website is blocked.
• LiftOver: A conversion to a new genome-build is performed. All queries are delayed, but (read-only) access to the website is possible.

API Command 'GetStatus/Stats'

ADMIN only: Get database and server statistics. Output includes:

• size_database: Total size of VariantDB databases, according to mysql.
• size_datafiles: Total size of BAM/VCF files stored on VariantDB by its users.
• system_df: Full output "df -h", performed on the VariantDB web-server.

API Command 'GetQueryResults/<Query_ID>'

Get results of a query, specified by its query_id. Output on success includes, for sample based queries, a 'Variants' element, which is an array of all retained variants and the annotations, and a 'Comments' element, which holds encountered problems and/or summary information.

For region based queries, the result contains a 'Variants' and 'Comments' element. The Variants element holds two child elements:

• general_annotations: Annotations that are not sample specific (e.g. Gene effect, population frequencies, ClinVar associations etc.)
• sample_specific_annotations: One entry per sample harbouring the variant, identified by the sample_id. These entries hold:
  • sample_details: sample_name, sample_gender
  • variant_details: All specified, sample specific annotations (e.g. Depth, Strand Bias, mapping quality, etc)