Package: singler
Tinder for single-cell dataOverviewThis package provides Python bindings to theC++ implementationof theSingleR algorithm,
originally developed byAran 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 startFirstly, let's load in the famous PBMC 4k dataset from 10X Genomics:importsinglecellexperimentasscedata=sce.read_tenx_h5("pbmc4k-tenx.h5")mat=data.assay("counts")features=[str(x)forxindata.row_data["name"]]Now we use the Blueprint/ENCODE reference to annotate each cell inmat:importsinglerresults=singler.annotate_single(mat,features,ref_data="BlueprintEncode",ref_features="symbol",ref_labels="main",cache_dir="_cache")Theresultsdata 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 functionsTheannotate_single()function is a convenient wrapper around a number of lower-level functions insingler.
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 fromGitHub.
Note the use ofcache_dirto 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 setrestrict_toto 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 offeatures.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.06678168346812047Integrating labels across referencesWe can use annotations from multiple references through theannotate_integrated()function:importsinglersingle_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 notesBuild the shared object file:pythonsetup.pybuild_ext--inplaceFor quick testing:pytestFor more complex testing:pythonsetup.pybuild_ext--inplace&&toxTo rebuild thectypesbindings withcpptypes:cpptypessrc/singler/lib--pysrc/singler/_cpphelpers.py--cppsrc/singler/lib/bindings.cpp--dll_core