Results in AnnData and Seurat

run() returns the annotated AnnData. It is the object you passed to CyteType(), except when label_na=True relabeled missing cluster labels: then it is a new object, and only that object carries the results. Always assign the return value.

adata = annotator.run(study_context="Healthy human PBMCs, 10x Genomics 3' scRNA-seq")

run() adds five categorical columns to adata.obs, named {results_prefix}_<field>_{group_key}:

The categories of the confidence column are listed as High, Moderate, Low, Unknown (only those that occur), so legends follow that order; the categorical is not ordered, so comparisons such as > do not apply. Cells in clusters without a result get Unknown (an empty value for the cell state).

If every label in the cluster column has at most three characters (for example Leiden numbers), CyteType uses the labels themselves as IDs. Otherwise it numbers the clusters 0, 1, 2, ... in natural sort order of the labels. With label_na=True, the added label Unknown is longer than three characters, so all clusters are then numbered. annotator.cluster_map maps each of your labels to its ID:

id_to_label = {cluster_id: label for label, cluster_id in annotator.cluster_map.items()}

get_results() returns a dictionary:

results = annotator.get_results()

Each entry in annotations has these keys:

Interpret and review results explains how to read the confidence and heterogeneity values.

adata.uns holds two entries:

Build a table of the annotation levels:

import pandas as pd

rows = []
for cluster_id, cluster in results["raw_annotations"].items():
    annotation = (cluster.get("latest") or {}).get("annotation") or {}
    cell_type = (annotation.get("fullOutput") or {}).get("cellType") or {}
    levels = cell_type.get("annotationLevels") or {}
    rows.append({
        "clusterId": cluster_id,
        **{name: (levels.get(name) or {}).get("label", "") for name in ["L1", "L2", "L3", "L4", "L5"]},
    })
levels_table = pd.DataFrame(rows)

The results live in adata.obs and adata.uns, so they are saved with the AnnData. Call annotator.cleanup() first if you want to remove the upload files and the temporary gene symbol column that CyteType added to adata.var.

import json
import anndata as ad

adata.write_h5ad("annotated.h5ad")

adata = ad.read_h5ad("annotated.h5ad")
results = json.loads(adata.uns["cytetype_results"]["result"])
report_url = adata.uns["cytetype_jobDetails"]["report_url"]

Parsing the JSON returns the results exactly as they were stored. Files written by 0.21.0 already contain reviewerConfidence, isHeterogeneous and heterogeneityType and the filled evidence fields. For files written by older versions, get_results() and marker_dotplot() in 0.21.0 normalize the stored results when they read them: they fill the evidence fields and add the three review keys (as None for files from version 0.7.0 and older, which have no raw results). The reviewerConfidence column is not added to adata.obs of older files. get_results() is a method of the CyteType object, so in a new session parsing the JSON is the simplest way to read the results.

Color the embedding by the label or by the reviewer’s confidence:

import scanpy as sc

sc.pl.umap(adata, color="cytetype_annotation_leiden")

confidence_colors = {"High": "#1a9850", "Moderate": "#fdae61", "Low": "#d73027", "Unknown": "#bdbdbd"}
sc.pl.umap(adata, color="cytetype_reviewerConfidence_leiden", palette=confidence_colors)

marker_dotplot() draws a Scanpy dot plot of the genes that support each label, with the labels ordered and the genes grouped by display group (the clusterCategories):

from cytetype import marker_dotplot

marker_dotplot(adata, group_key="leiden")
marker_dotplot(adata, group_key="leiden", n_top_markers=5, standard_scale="var")

Gene names are matched without regard to case, because CyteType reports upper-case symbols (for example CD8A for mouse Cd8a). Genes that are not found are skipped with a warning. Like Scanpy, the function uses adata.raw when it exists and you pass no layer. It needs Scanpy, and it raises an error when the results have no display groups (some older jobs) or no raw results (files from version 0.7.0 and older).

From get_results(), with your cluster labels added:

import pandas as pd

results = annotator.get_results()
table = pd.DataFrame(results["annotations"])
for column in ["supportingMarkers", "conflictingMarkers"]:
    table[column] = table[column].apply(lambda genes: ";".join(genes) if isinstance(genes, list) else "")

id_to_label = {cluster_id: label for label, cluster_id in annotator.cluster_map.items()}
table.insert(1, "leiden", table["clusterId"].map(id_to_label))
table.to_csv("cytetype_clusters.csv", index=False)

From the obs columns, which also works on a reloaded file without the CyteType object:

group_key = "leiden"
fields = ["annotation", "cellOntologyTerm", "cellOntologyTermID", "cellState", "reviewerConfidence"]
columns = [f"cytetype_{field}_{group_key}" for field in fields]

per_cluster = adata.obs.groupby(group_key, observed=True)[columns].first()
per_cluster["n_cells"] = adata.obs[group_key].value_counts()
per_cluster.to_csv("cytetype_clusters.csv")