singler 0.1.2

Python bindings to the singleR algorithm to annotate cell types from known references.

Tinder for single-cell data

Overview

This package provides Python bindings to the C++ implementation of the SingleR algorithm, originally developed by Aran et al. (2019). It is designed to annotate cell types by matching cells to known references based on their expression profiles. So kind of like Tinder, but for cells.

Quick start

Firstly, let's load in the famous PBMC 4k dataset from 10X Genomics:

import singlecellexperiment as sce
data = sce.read_tenx_h5("pbmc4k-tenx.h5")
mat = data.assay("counts")
features = [str(x) for x in data.row_data["name"]]

Now we use the Blueprint/ENCODE reference to annotate each cell in mat:

import singler
results = singler.annotate_single(
    mat,
    features,
    ref_data = "BlueprintEncode",
    ref_features = "symbol",
    ref_labels = "main",
    cache_dir = "_cache"
)

The results data frame contains all of the assignments and the scores for each label:

results.column("best")
## ['Monocytes',
##  'Monocytes',
##  'Monocytes',
##  'CD8+ T-cells',
##  'CD4+ T-cells',
##  'CD8+ T-cells',
##  'Monocytes',
##  'Monocytes',
##  'B-cells',
##  ...
## ]

results.column("scores").column("Macrophages")
## array([0.35935275, 0.40833545, 0.37430726, ..., 0.32135929, 0.29728435,
##        0.40208581])

Calling low-level functions

The annotate_single() function is a convenient wrapper around a number of lower-level functions in singler. Advanced users may prefer to build the reference and run the classification separately. This allows us to re-use the same reference for multiple datasets without repeating the build step.

We start by fetching the reference of interest from GitHub. Note the use of cache_dir to avoid repeated downloads from GitHub.

ref = singler.fetch_github_reference("BlueprintEncode", cache_dir="_cache")

We'll be using the gene symbols here with the markers for the main labels. We need to set restrict_to to the features in our test data, so as to avoid picking marker genes in the reference that won't be present in the test.

ref_features = ref.row_data.column("symbol")

markers = singler.realize_github_markers(
    ref.metadata["main"],
    ref_features,
    restrict_to=set(features),
)

Now we build the reference from the ranked expression values and the associated labels in the reference:

built = singler.build_single_reference(
    ref_data=ref.assay("ranks"),
    ref_labels=ref.col_data.column("main"),
    ref_features=ref_features,
    markers=markers,
)

And finally, we apply the pre-built reference to the test dataset to obtain our label assignments. This can be repeated with different datasets that have the same features or a superset of features.

output = singler.classify_single_reference(
    mat,
    test_features=features,
    ref_prebuilt=built,
)

## output
BiocFrame with 4340 rows and 3 columns
            best                                   scores                delta
        <list>                              <BiocFrame>   <ndarray[float64]>
[0] Monocytes 0.33265560369962943:0.407117403330602...  0.40706830113982534
[1] Monocytes 0.4078771641637374:0.4783396310685646...  0.07000418564184802
[2] Monocytes 0.3517036021728629:0.4076971245524348...  0.30997293412307647
            ...                                      ...                  ...
[4337]  NK cells 0.3472631136865701:0.3937898240670208...  0.09640242155786138
[4338]   B-cells 0.26974632191999887:0.334862058137758... 0.061215905058676856
[4339] Monocytes 0.39390119034537324:0.468867490667427...  0.06678168346812047

Integrating labels across references

We can use annotations from multiple references through the annotate_integrated() function:

import singler
single_results, integrated = singler.annotate_integrated(
    mat,
    features,
    ref_data_list = ("BlueprintEncode", "DatabaseImmuneCellExpression"),
    ref_features_list= "symbol",
    ref_labels_list = "main",
    build_integrated_args = { "ref_names": ("Blueprint", "DICE") },
    cache_dir = "_cache",
    num_threads = 6
)

This annotates the test dataset against each reference individually to obtain the best per-reference label, and then it compares across references to find the best label from all references. Both the single and integrated annotations are reported for diagnostics.

integrated.column("best_label")
## ['Monocytes', 
##  'Monocytes',
##  'Monocytes',
##  'CD8+ T-cells',
##  'CD4+ T-cells',
##  'CD8+ T-cells',
##  'Monocytes',
##  'Monocytes',
##  ...
## ]

integrated.column("best_reference")
## ['Blueprint',
## 'Blueprint',
## 'Blueprint',
## 'Blueprint',
## 'Blueprint',
## 'Blueprint',
## 'Blueprint',
## ...
##]

Developer notes

Build the shared object file:

python setup.py build_ext --inplace

For quick testing:

pytest

For more complex testing:

python setup.py build_ext --inplace && tox

To rebuild the ctypes bindings with cpptypes:

cpptypes src/singler/lib --py src/singler/_cpphelpers.py --cpp src/singler/lib/bindings.cpp --dll _core