Home Install User Guide Python Notebook API FAQ

API Examples

apiExample
In [2]:
import requests
from pprint import pprint
import pandas as pd
import numpy as np
The URL and port number is needed to use http API from Single Cell Explorer.
In [3]:
# use the url with port number of single cell explorer application you want to access
appUrl="http://54.159.6.229:8002/"

getAllNormalizedGeneExpr

We use above method to get all normalized gene counts data from specific cell types in specific map

1) mapid: Each map has a unique mapid (map identification) that will be automatically generated after loading into database. To find mapid, you can open the map, for an instance, the url of human liver map in our demo webste is: http://54.159.6.229:8002/map/5c8bf53ea05a37a5c7d707ce/; the last index number followed by "/map" will be mapid. In our examples, we use map from E-MTAB-6678 fetal-maternal interface, http://54.159.6.229:8002/map/5bfe36bdbef42b0d23956527/, the mapid=5bfe36bdbef42b0d23956527.
2) clstrType means cluster type including cellType (annotated by single cell explorer users, please visit our tutorial section from our website), phase, tissue, and any other cluster annotation deposited in the database. Not all the map has the same annotation information. clstrName means list itemd in the selected clstrype, you can choose "NK" cells as cluster name if you use "CellType" as cluster type
In [4]:
# download all normalized gene expression data from NK cells from "E-MTAB-6678 fetal-maternal interface" data 
url=appUrl+"api/getAllNormalizedGeneExpr";
data={
    "mapid":"5bfe36bdbef42b0d23956527",
    "clstrType":"cellType",
    "clstrName":"NK", 
}
#if clstrType and clstrName is None. will return all gene expressions
res = requests.post(url, data=data)
res=res.json();
df = pd.DataFrame(np.array(res["data"]),  columns=res["head"],index=res["index"]) 
df.head()
Out[4]:
24087_1#148 24087_7#201 24088_7#296 24087_7#213 24087_6#270 24088_7#262 24087_7#244 23728_3#242 24087_6#196 24087_7#269 ... 24087_2#191 23728_7#217 24087_8#238 23728_6#214 24088_7#199 23728_8#198 24087_6#191 24087_4#221 23728_3#270 24087_8#213
TNMD 0.0000 0.0 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 ... 0.0 0.000 0.0000 0.0000 0.0000 0.0000 0.0 0.0 0.0000 0.0000
DPM1 30.7298 0.0 0.0000 0.0000 0.0000 81.6965 0.0000 0.0000 0.0000 0.0000 ... 0.0 0.000 0.0000 0.0000 184.8351 0.0000 0.0 0.0 0.0000 0.0000
SCYL3 0.0000 0.0 0.0000 0.0000 0.0000 0.0000 0.0000 14.1999 0.0000 0.0000 ... 0.0 0.000 0.0000 0.0000 0.0000 0.0000 0.0 0.0 0.0000 0.0000
C1ORF112 0.0000 0.0 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 ... 0.0 0.000 0.0000 0.0000 0.0000 0.0000 0.0 0.0 0.0000 0.0000
FGR 1172.8553 0.0 42.1842 714.6705 248.9304 114.7228 255.3413 61.1688 2.7427 321.0956 ... 0.0 14.136 279.3446 25.6352 338.1643 16.0101 0.0 0.0 47.2006 73.0036

5 rows × 655 columns

getNormalizedGeneExpr

We use above method to get normalized counts data for the gene of interest from specific cell types in specific map

In [5]:
# query a set of genes from all cell types from "E-MTAB-6678 fetal-maternal interface" data 
url=appUrl+"api/getNormalizedGeneExpr";
data={
    "mapid":"5bfe36bdbef42b0d23956527",
    "clstrType":None,
    "clstrName":None,
    "genes":",".join(["CD3E","CD14","CD1C","CIITA","TPSB2",])
}
res = requests.post(url, data=data)
res=res.json();
df = pd.DataFrame(np.array(res["data"]),  columns=res["head"],index=res["index"]) 
df
Out[5]:
24087_4#281 24087_6#46 24088_4#352 24088_6#289 24088_5#107 23728_3#106 23728_7#76 23728_7#33 24087_1#148 24088_5#231 ... 24087_1#347 24088_5#103 24087_3#111 24088_6#283 23728_3#47 24087_8#36 24088_3#246 24087_4#68 23728_8#64 24087_7#141
CD14 0.0 0.0000 0.0 0.0000 0.0000 2086.1244 1119.7418 1050.3315 0.0000 0.000 ... 0.0 0.0000 0.000 1021.5589 1258.4898 0.0000 0.0000 0.0 0.000 0.0000
CD1C 0.0 0.0000 0.0 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.000 ... 0.0 0.0000 0.000 0.0000 0.0000 0.0000 0.0000 0.0 0.000 0.0000
CD3E 0.0 77.2383 0.0 8.6147 85.4933 0.0000 0.0000 0.0000 419.9744 126.935 ... 0.0 337.4397 117.082 0.0000 0.0000 12.4941 99.7082 0.0 10.118 118.3252
CIITA 0.0 0.0000 0.0 0.0000 0.0000 0.9569 0.0000 0.0000 0.0000 0.000 ... 0.0 0.0000 0.000 0.0000 0.0000 0.0000 0.0000 0.0 0.000 0.0000
TPSB2 0.0 0.0000 0.0 0.0000 0.0000 0.0000 0.0000 0.0000 0.0000 0.000 ... 0.0 0.0000 0.000 0.0000 0.0000 0.0000 0.0000 0.0 0.000 0.0000

5 rows × 5510 columns

getClstrsByMapidAndClstrType

We use above method to retrieve table of cell barcodes and annotated cell type in a specific map

In [6]:
# full API path 
url=appUrl+"api/getClstrsByMapidAndClstrType";
# use mapid and cell type to call barcode and celltype information 
data={
    "mapid":"5bfe36bdbef42b0d23956527",
    "clstrType":"cellType"
}
res = requests.post(url, data=data)
res=res.json();
df = pd.DataFrame( list(res.values()),  columns= [data["clstrType"]],index=list(res.keys()) ) 
df.head()
Out[6]:
cellType
24087_6#46 Tcells
24088_6#289 Tcells
24088_5#107 Tcells
23728_3#106 dM2
24087_1#148 NK

getMarkGenesByMapidAndClusterType

We use above method to get annotated marker genes

In [7]:
url=appUrl+"api/getMarkGenesByMapidAndClstrType";
data={
    "mapid":"5bfe36bdbef42b0d23956527",
    "clstrType":"cellType"
}
res = requests.post(url, data=data)
# API return result in a json object.
pprint(res.json())
{'DC1': {'marks': ['IRF8', 'HLA-DPA1', 'HLA-DPB1', 'CLEC9A'], 'negmarks': ['']},
 'DC2': {'marks': ['CD1C',
                   'HLA-DQA2',
                   'HLA-DPB1',
                   'CIITA',
                   'HLA-DRA',
                   'FCER1A'],
         'negmarks': ['']},
 'Mast': {'marks': ['MS4A2', 'TPSB2', 'TPSAB1', 'HDC'], 'negmarks': ['']},
 'Monocyte': {'marks': ['LYZ', 'S100A9', 'CSF3R', 'CFP', 'FGR', 'S100A8'],
              'negmarks': ['']},
 'NK': {'marks': ['KLRC1', 'GNLY', 'NCAM1', 'KIR2DL4'], 'negmarks': ['']},
 'Tcells': {'marks': ['CD3G', 'IL7R', 'CD3E', 'LTB', 'CD3D'], 'negmarks': ['']},
 'Treg': {'marks': ['FOXP3', 'TIGIT', 'CTLA4'], 'negmarks': ['']},
 'dEndothelium': {'marks': ['TIE1', 'CDH5', 'VWF', 'CD34'], 'negmarks': ['']},
 'dM1': {'marks': ['IL1B', 'CXCL8', 'OLR1', 'OSM'], 'negmarks': ['']},
 'dM2': {'marks': ['VSIG4', 'C1QC', 'FOLR2', 'C1QA', 'CSF1R'],
         'negmarks': ['']}}

getMaps

We use above method to get map meta information

In [8]:
url=appUrl+"api/getMaps";
#query can set any search condition
query={
     'disease': 'Healthy',
}

res = requests.post(url, data=query)
res=res.json();
pprint(res)
{'5bfe36bdbef42b0d23956527': {'_id': '5bfe36bdbef42b0d23956527',
                              'author': '',
                              'comment': '',
                              'disease': 'Healthy',
                              'name': 'E-MTAB-6678_SS2',
                              'source': 'Welcome Trust Sarah\xa0Teichmann',
                              'study': 'E-MTAB-6678 fetal-maternal interface',
                              'subjectid': 'E-MTAB-6678',
                              'tissue': 'tsne3'},
 '5c8bf53ea05a37a5c7d707ce': {'_id': '5c8bf53ea05a37a5c7d707ce',
                              'author': '',
                              'comment': 'Single cell RNA sequencing of human '
                                         'liver reveals distinct intrahepatic '
                                         'macrophage populations',
                              'disease': 'Healthy',
                              'name': 'HuLiver',
                              'source': 'University of Toronto Gary Bader',
                              'study': 'BaderLabHumanLiver',
                              'subjectid': 'None',
                              'tissue': 'Liver'},
 '5ccfb3c066adac0c7e7924c9': {'_id': '5ccfb3c066adac0c7e7924c9',
                              'author': 'demo',
                              'comment': '',
                              'disease': 'Healthy',
                              'name': 'pmbc10k_health_umap',
                              'source': '10XGenomic',
                              'study': 'Demo',
                              'subjectid': '',
                              'tissue': 'Blood'},
 '5ccfb94266adac0c7e7924e3': {'_id': '5ccfb94266adac0c7e7924e3',
                              'author': 'demo',
                              'comment': '',
                              'disease': 'Healthy',
                              'name': 'pmbc10k_health_tSNE',
                              'source': '10XGenomic',
                              'study': 'Demo',
                              'subjectid': '',
                              'tissue': 'Blood'},
 '5d1f5834b67cc25c6f480e47': {'_id': '5d1f5834b67cc25c6f480e47',
                              'author': 'demo',
                              'comment': 'from loom',
                              'disease': 'Healthy',
                              'mapType': 'tsne',
                              'mapname': 'Waddell_CentralBrain_10k_tSNE',
                              'name': 'Waddell_CentralBrain_10k_tSNE',
                              'sample': 'midbrain',
                              'source': 'Waddell2018',
                              'species': 'drosophila',
                              'study': 'flyBrain',
                              'subjectid': '',
                              'tissue': ''}}

getNormalizedGeneExprByTwoClstrs

We use above method to retrieve normalized gene expression matrices from two cell types;can be used for identifying differentially expressed genes

In [9]:
url=appUrl+"api/getNormalizedGeneExprByTwoClstrs";
data={
    "mapid":"5c8bf53ea05a37a5c7d707ce",
    "clstrType1":"cellType",
    "clstrName1":"Tcells",
    "clstrType2":"cellType",
    "clstrName2":"Bcells",
    #"zscoreFilter": 0.15,#if set "" , skip
    #"log2fc":4,#if set "" , skip
}

res = requests.post(url, data=data)
res=res.json();
pprint(len(res.keys()))
16477
In [ ]:
# follow is an example for running t-test
import diffxpy.api as de
In [11]:
%matplotlib inline
import matplotlib.pyplot as plt
import seaborn as sns
import scipy.stats
import numpy as np
import time
import scanpy.api as sc
In [ ]:
#make adata
data=[];
genes=[];
key=list(res.keys())[0]
g1len= len(res[key][0]);
g2len= len(res[key][1]);
condition = [0]*g1len+[1]*g2len;
for i in res:
    genes.append(i);
    data.append(res[i][0]+res[i][1])
    
data=np.array(data,dtype="float32");
adata=sc.AnnData(X=data);
adata.obs.index=genes;
adata=adata.T;
adata.obs["condition"]=condition
test_wilcox = de.test.wilcoxon(
    data=adata,
    grouping="condition",    
);
In [13]:
## B cells specific genes
test_wilcox.summary().sort_values(by=["qval","log2fc"],ascending=True).head()
Out[13]:
gene pval qval log2fc mean
15391 CD79A 5.249853e-213 8.650182e-209 8.654743 0.235708
5301 HLA-DRA 8.563910e-128 7.055377e-124 3.976070 0.670985
8650 MS4A1 6.066316e-117 3.331823e-113 5.346273 0.196800
13704 CD79B 1.361846e-114 5.609786e-111 4.084745 0.312431
11817 LINC00926 4.393352e-107 1.447785e-103 7.681458 0.100990
In [ ]: