Cell Atlas Approximations - API

Cell atlases such as Tabula Muris and Tabula Sapiens are multi-organ single cell omics data sets describing entire organisms. A cell atlas approximation is a lossy and lightweight compression of a cell atlas that can be streamed via the internet.

This project enables biologists, doctors, and data scientist to quickly find answers for questions such as:

• What types of cells populate the human heart?
• What is the expression of a specific gene across cell types in C elegans?
• What are the marker genes of a specific cell type in mouse pancreas?
• What fraction of cells (of a specific type) express a gene of interest?

These questions can be asked in Python or R using the provided packages (see below), or in a language agnostic manner using the REST API. We even made a shell script for Linux and Mac that calls the API from your terminal! - check out shell/atlasapprox!

Version

The latest API version is v1.

We support several organs and organisms: human, mouse, lemur (a type of monkey), zebrafish, C. elegans. More organisms and organs are planned for the near future.

Documentation

Tutorial and reference documentation is available at https://atlasapprox.readthedocs.io.

Usage

REST

REST

The REST interface is language-agnostic and can be queried using any HTTP request handler, e.g. in JavaScript:

(async () => {
  let response = await fetch("http://api.atlasapprox.org/v1/organisms");
  if (response.ok) {
    let data = await response.json();
    console.log(data);
  }  
})();

Similar results can be obtained via Python's requests, R's httr, etc. If you are using Python or R, however, please consider using the dedicated interfaces below, as they are more efficient and easier on our servers thanks to caching.

Python

Python

The Python interface uses a central API class. Its methods implement the REST endpoints:

import atlasapprox

api = atlasapprox.API()
print(api.organisms())
print(api.celltypes(organism="c_elegans", organ="whole"))

R

R

The R interface includes a number of GetXXX functions connected to the REST endpoints:

library("atlasapprox")

organisms <- GetOrganisms()
print(organisms)

JavaScript

JavaScript/nodejs

An object containing one function for each API endpoint is exported by the atlasapprox npm package:

let atlasapprox = require('atlasapprox');
(async () => {
  let data = await atlasapprox.organisms();
  console.log(data);
  }  
})();

Shell

Shell (bash, zsh, et similia)

A single script is provided in this repo under shell/atlasapprox. Usage instructions are included, but as a quick example:

atlasapprox average --organism=m_musculus --organ=Lung --features=Col1a1,Ptprc

Note that the output is a serialized JSON string: you'll probably need some kind of parser to interpret the results.

Repo contents

• data: files required for the compression of current cell atlases
• preprocess: scripts used for the approximations
• web: webserver code in Flask that implements the RESTful API
• Python: package code providing a Python interface for the RESTful API
• R: package code providing an R interface for the RESTful API
• docs: user documentation for the API

Authors

• Fabio Zanini @ fabilab