Stargeo API¶
Stargeo provides API to access our data, make annotations, run analyses and more. It will be presented here in the form of copy-pastable examples. Continue reading or jump to series and samples, platforms and probes, tags, analyses or annotations.
We will start with importing requests and pandas.
import requests
import pandas as pd
Series and their samples¶
# Fetch first 10 series, defaults to 100
r = requests.get('http://stargeo.org/api/v2/series/?limit=10')
assert r.ok
data = r.json()
data['count'], len(data['results'])
data['results'][0]
# Fetch next 10 series
r = requests.get(data['next'])
You can also fetch single serie data and its samples by gse name.
# Fetch GSE1 serie data
requests.get('http://stargeo.org/api/v2/series/GSE1/').text
# Fetch GSE1 samples
samples_json = requests.get('http://stargeo.org/api/v2/series/GSE1/samples/').json()
# or
samples = pd.read_json('http://stargeo.org/api/v2/series/GSE1/samples/')
samples.head()
Platforms¶
# Fetch first 100 platforms, fetching the rest same way as with series above
r = requests.get('http://stargeo.org/api/v2/platforms/').json()
platforms = r['results']
platforms[:2]
# Fetch single platform by gpl name
requests.get('http://stargeo.org/api/v2/platforms/GPL7/').json()
Platform probes¶
probes = pd.read_json('http://stargeo.org/api/v2/platforms/GPL7/probes/', orient='split')
len(probes)
probes.head()
Tags¶
# Fetch all samples
tags = requests.get('http://stargeo.org/api/v2/tags/').json()
# or
tags = pd.read_json('http://stargeo.org/api/v2/tags/')
tags[tags.concept_name != ''].head()
Fetch single tag info:
# Fetch tag with id 7 data
requests.get('http://stargeo.org/api/v2/tags/7/').json()
Analyses¶
Stargeo API provides a way to list and load existing analyses and load their results as well as source data and fold changes. Additionally an authorized user can perform new analyses.
data = requests.get('http://stargeo.org/api/v2/analysis/').json()
data['count'], len(data['results'])
analysis = data['results'][0]
# or
analysis = requests.get('http://stargeo.org/api/v2/analysis/243/').json()
analysis
Source and fold changes dataframes are accessible via links in corresponding analysis fields.
# Fetch source dataframe
analysis_df = pd.read_json(analysis['df'], orient='split')
analysis_df.head()
# Fetch fold changes. WARNING: this could be big
r = requests.get(analysis['fold_changes'])
# It is also compressed with zlib
import zlib
fold_changes = pd.read_json(zlib.decompress(r.content), orient='split')
fold_changes.head()
results = pd.read_json('http://stargeo.org/api/v2/analysis/243/results/', orient='split')
results.head()
To create and start an analysis you need to provide an auth token. You can get see yours in the example below once you are logged in.
# This is your auth token, don't share it with anybody
headers = {'Authorization': 'Token your-token-here'}
# Create new analysis
r = requests.post('http://stargeo.org/api/v2/analysis/', headers=headers, data={
'analysis_name': 'Young Severe Dengue',
'description': 'Dengue cases in patients under 9',
'specie': 'human',
'case_query': "DHF=='DHF' or DSS=='DSS'",
'control_query': "DF=='DF'",
'modifier_query': "Age < 9",
})
r.json()
Annotations¶
Allows listing, fetching and adding annotations. Note that at each point in time you see best available annotations, along with their reliability characteristics. Pay attention at best_cohens_kappa attribute, we consider annotation validated when it equals 1, meaning there are two annotation authors that blindly did it the same way.
annotations = requests.get('http://stargeo.org/api/v2/annotations/').json()
annotations['count'], len(annotations['results'])
annotations['results'][0]
print(requests.get('http://stargeo.org/api/v2/annotations/1607/samples/').text)
To post annotations you need to authorize as a competent user. To authorize you need to send Authorization token same as when creating analysis.
# This is your auth token, don't share it with anybody
headers = {'Authorization': 'Token your-token-here'}
# Create new analysis
r = requests.post('http://localhost:5000/api/v2/annotations/', headers=headers, json={
'tag': 'melanoma',
'series': 'GSE1',
'platform': 'GPL7',
# Need to provide full set of samples
'annotations': {'GSM11': 'melanoma', 'GSM12': '', ...},
# Optional text note
'note': '...',
})
assert r.ok