HumanBase API
HumanBase API is a RESTful API that allows programmatic access to HB data and computational services.
datasets
read
Return the given dataset
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
slug required | Slugified dataset identifier |
datatypes
read
Return a given dataset data type
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
slug required | Slugified edge type title |
deepsea
read
Returns details of the chosen model
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
name required |
feature_predictions
Returns all feature scores for submitted variants of chosen model
-
URL parameters:
chr_variant
: string representation of specific chromosome & variant position, may be specified multiple times (eg.Y:102
)chr_and_variant_range
: string representation of chromosome and range of start and ending variant indices (eg.X:100:2000
)
-
Returns:
[
{
"chromosome": "1",
"position": 123456,
"rsid": null,
"ref_allele": "A",
"alt_allele": "G",
"feature_predictions": [ .56, .89, 1.5, ...]
},
{ ... },
]
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
name required |
features
Returns the DeepSEA model's associated features
-
URL parameters:
expecto
: if this parameter is present, addexpecto_features
to response.
-
Returns:
{
'model_features': [
{
"cell_type":
{
"name": "brain",
"description": "something",
},
"chromatin_feature_type":
{
"name": "DNAse",
"description": "something"
},
"treatment":
{
"name": "A treatment",
"description": "something",
},
"idx": 0,
},
...
],
'expecto_features': [
{
"title": "title_1",
"idx": 0,
},
...
]
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
name required |
jobs > create
- Returns:
{
"job_id": "018e13bf-4ad0-4fb3-8f41-951bcfbe8e57",
"title": "User Title",
"input_type": "vcf",
"created": "",
"status": "queued",
"ds_model": "beluga",
"files": {},
"insilico": false,
"expecto": false,
"genome_assembly": "hg19"
}
Request Body
The request body should be a "application/json"
encoded object, containing the following items.
Parameter | Description |
---|---|
ds_model required | |
input_type required | Input file type. Options are: vcf, fasta, bed |
title | Job title |
email | Email address for sending DeepSEA results |
expecto | Run user submitted ExPecto |
insilico | Run in silico mutagenesis on a sequence |
output_format | Optional output file format. Currently this is only supported for in-silico mutagenesis and user submitted ExPecto submissions. Possible choices are: tsv, hdf5 |
genome_assembly required |
jobs > read
- Returns:
{
"job_id": "018e13bf-4ad0-4fb3-8f41-951bcfbe8e57",
"created": "",
"status": "running",
"ds_model": "beluga",
"files": {
"uploaded_query": "http://some/path/example.vcf",
"variant_dis": {
"url": "http://some/path/dis.bw",
"name": "Disease impact score"
}
"feature_evalue": {
"url": "http://some/path/evalue.tsv.gz",
"name": "e-value"
},
"feature_evalue_index": {
"url": "http://some/path/evalue.tsv.gz.tbi"
"name": "e-value index"
},
}
}
- Raises:
Http404
: if job_id does not exist
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
job_id required | Unique DeepSEA job identifier |
jobs > feature_predictions
Returns all feature predictions for submitted variants of a job
-
URL parameters:
chr_variant
: string representation of specific chromosome & variant position, may be specified multiple times (eg.Y:102
)chr_and_variant_range
: string representation of chromosome and range of start and ending variant indices (eg.X:100:2000
)score_type
: the preferred score type relating to the deepsea job <diffs
|evalue
|zscore
|expecto
>
-
Returns:
[
{
"chromosome": "1",
"position": 123456,
"rsid": null,
"ref_allele": "A",
"alt_allele": "G",
"feature_predictions": [ .56, .89, 1.5, ...]
},
{ ... },
]
- Raises:
Http400
: ifjob.expecto
false whenscore_type
isexpecto
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
job_id required | Unique DeepSEA job identifier |
jobs > in_silico_mutagenesis
Returns feature predictions from a run of in silico mutagenseis
-
URL parameters:
sequence_name
: String name of the submitted sequencefeature_name
: String name of the desired feature valuefeature_only
: If set, does not return position, ref, or alt columns
-
Returns:
positions
: List of string representations for each positionpecentiles
: List of values for every percentile from 0 to 100%
{
"positions": [
"0,N,A,0.00e+00",
"0,N,G,0.00e+00",
"0,N,C,0.00e+00",
"0,N,T,0.00e+00",
"1,N,A,-8.53e-03",
"1,N,G,-8.27e-03",
"1,N,C,-3.05e-03",
"1,N,T,-2.69e-03",
"2,N,A,0.00e+00",
...
]
"percentiles": [ -5.4, ... ],
}
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
job_id required | Unique DeepSEA job identifier |
jobs > queue_position
Get the queue position of the DeepSEA job
- Returns:
{
"queue_size": "Total jobs queued",
"position": "Position of job in queue (1-indexed)",
}
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
job_id required | Unique DeepSEA job identifier |
jobs > score_types
Retrieve a list of available score types for a specific DeepSEA job
- Returns:
[
{
"name": "Disease impact score",
"level": "VARIANT",
"short_name": "dis"
}
...
]
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
job_id required | Unique DeepSEA job identifier |
jobs > sequence_scores
Returns a list of sequence/variant scores
-
URL parameters:
score_type
: the preferred score type relating to the deepsea job <mean-evalue
|dis
>
-
Returns:
{
"ds_model": "beluga",
"score_type": "mean-evalue",
"scores": [
{
"sequence": {
"chromosome": "chrX",
"position": 1000006,
"ref_allele": "T",
"alt_allele": "G",
"submitted_name": "[yada_yada_123]",
},
"value": 1.5
},
{ ... },
],
}
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
job_id required | Unique DeepSEA job identifier |
jobs > variant_scores
Returns a list of variant scores
-
URL parameters:
score_type
: the preferred score type relating to the deepsea job <mean-evalue
|dis
|expecto
>
-
Returns:
{
"ds_model": "beluga",
"score_type": "mean-evalue",
"scores": [
{
"variant": {
"chromosome": "chrX",
"position": 1000006,
"ref_allele": "T",
"alt_allele": "G",
"submitted_name": "[yada_yada_123]",
},
"value": 1.5
},
{ ... },
],
}
* Raises:
* `Http400`: if `score_type` not compatible with ds model
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
job_id required | Unique DeepSEA job identifier |
genes
read
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
entrez required | Unique NCBI Entrez ID |
annotations
Returns a list of terms a gene is annotated to
- URL parameters:
database
(optional): database of terms to filter predictionsmax_term_size
(optional): filter terms that have more thanmax_term_size
gene annotations (default 300)
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
entrez required | Unique NCBI Entrez ID |
predictions
Returns a list of terms a gene is predicted to be associated with
- URL parameters:
version
(optional): verison identifier of predictionsdatabase
(optional): database of terms to filter predictionsscore_cutoff
(optional): minimum score of predictions to return
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
entrez required | Unique NCBI Entrez ID |
tissue_variants
Returns a matrix (variants by tissues) of predicted variant effects on tissue expression for a gene
- URL parameters:
collapse
(optional): boolean for collapsing redundant tissues
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
entrez required | Unique NCBI Entrez ID |
integrations
community
Retrieve community predictions from a submitted list of genes.
-
URL parameters:
body_tag
: body tag to use for caching the requestintegration
: integration used to make a new request, required if the result is not already in cache viabody_tag
neighbour_count
(optional): for each submitted gene, the maximum number of neighbours to count starting with top weighted (default 50)top_sknn
(optional): Filter for the top % of edges in sknn (default 5 percent)iterations
(optional): The number of partitions to predict (default 10)comembership
(optional): Return / partition only the edges with comembership scores above the specified membership percentage (default 90 percent)false_dscv_rate
(optional): Sets the minimum Q value for Benjamini-Hochberg p-value correction of multiple hypothesis test.
-
Request body parameters:
entrez
(required): genes to query the integration/network, minimum 50 genes required.
-
Returns:
{
'nodes': [
{'cluster': '1', 'id': 'node_0', 'entrez': '2313'}, {...}
],
'edges': [
{
'id': 'edge_0',
'source': 'node_1',
'target': 'node_2',
'weight': 100
},
{...}
],
'enrichment': [
{
'cluster': 1,
'term': GO:23343,
'genes': [1, 2, ..., n]
'name': 'Some title',
'p_value': 0.001,
'q_value': 0.08
},
{...}
]
}
Request Body
The request body should be a "application/json"
encoded object, containing the following items.
Parameter | Description |
---|---|
slug required | Context slug of the integration |
connectivity
Retrieve the connectivity scores of a gene set across all functional networks
-
URL parameters:
entrez
(required): entrez gene ids
-
Returns:
- list of connectivity scores
-
Raises:
Http404
: if either gene is not a number nor gene id
edges
Retrieve the edges across all functional networks corresponding to a gene pair
-
URL parameters:
source
(required): entrez gene idtarget
(required): entrez gene id
-
Returns:
- list of edges across all networks where
source
andtarget
are incident nodes
- list of edges across all networks where
- Raises:
Http404
: if either gene is not a number nor gene id
relevant
Retrieve a list of network integrations with a relevance score for a provided gene set
-
Request body parameters:
entrez
(required): entrez gene ids
-
Returns:
- list of integrations, with
score
field
- list of integrations, with
-
Raises:
Http404
: if either gene is not a number nor gene id
Request Body
The request body should be a "application/json"
encoded object, containing the following items.
Parameter | Description |
---|---|
slug required | Context slug of the integration |
read
Returns a network integration
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
slug required | Context slug of the integration |
evidence
Retrieve the evidence (list of datasets and their contributions) for a gene pair
- URL parameters:
source
(required): entrez gene idtarget
(required): entrez gene idlimit
(optional): max datasets to return (default no limit)
- Returns:
datatypes
: list of dataset type dictsdatasets
: list of dataset dicts
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
slug required | Context slug of the integration |
network
Query a functional network and return the relevant gene subnetwork
-
URL parameters:
entrez
(required): genes to query the integration/networknode_size
(optional): size of (additional genes) the subnetwork to return (default 50)prior
(optional): prior probability of a functional relationship (default 0.1)datatypes
(optional): list of data types to be used in the integration
-
Returns:
genes
: list of genes as dictsedges
: list of edges where the incident genes are stored the indices in the above genes listmincut
: a suggested cutoff for edges in the network such that the query genes are minimally connected to other genes
- Raises:
Http404
: if entrez is not a number nor gene id
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
slug required | Context slug of the integration |
netwas
create
Creates a new NetWAS job on HumanBase server. Job parameters are passed via POST fields.
Valid tissue names can be any of the tissues covered by HB
(see integrations), or api-demo
, which will simulate a short NetWAS job
for testing purposes.
If a new job has been successfully submitted, this function will return a response echoing back the input parameters specified by the user, plus some additional information including a unique job ID, which can be used to track its progress and view its results.
Request Body
The request body should be a "application/json"
encoded object, containing the following items.
Parameter | Description |
---|---|
title | Optional job title |
email | Optional email address for sending NetWAS results |
gwas_file required | GWAS file of gene p-values |
gwas_format required | Format of the GWAS file: 'vegas', 'forge', or 'pseq' |
tissue required | Tissue network name (e.g. brain) |
p_value required | P-value cutoff for NetWAS analysis |
read
Retrieve the NetWAS job for the given id
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
id required | Unique NetWAS job identifier |
terms
annotated
Returns a list of terms that a provided set of genes are annotated to. Term annotations are filtered to only include the input genes
- URL parameters:
entrez
(required): gene entrez idmax_term_size
(optional): cutoff for term size (default 300)
read
Return a given term
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
slug required | Slugified database name and term identifier |
annotations
Returns a list of genes annotated to the term
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
slug required | Slugified database name and term identifier |
predictions
Returns a list of gene predictions for the term
- URL parameters:
version
(optional): version identifier of predictions
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
slug required | Slugified database name and term identifier |
variants
list
Returns a paginated list of all variants in HB. The query parameters apply filters to the variant search.
Query Parameters
The following parameters should be included as part of a URL query string.
Parameter | Description |
---|---|
page | A page number within the paginated result set. |
page_size | Number of results to return per page. |
rsid | |
rsid__startswith | |
chromosome | |
position__startswith | |
position__lte | |
position__gte | |
gene__standard_name__istartswith | |
variantfeature__value | |
variantfeature__value__istartswith | |
labels__name | |
rsid__isempty |
read
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
id required | A unique integer value identifying this variant. |
Query Parameters
The following parameters should be included as part of a URL query string.
Parameter | Description |
---|---|
rsid | |
rsid__startswith | |
chromosome | |
position__startswith | |
position__lte | |
position__gte | |
gene__standard_name__istartswith | |
variantfeature__value | |
variantfeature__value__istartswith | |
labels__name | |
rsid__isempty |
genes
Path Parameters
The following parameters should be included in the URL path.
Parameter | Description |
---|---|
id required | A unique integer value identifying this variant. |