CyteType Documentation

The CyteType Dashboard is a web interface for managing API tokens and annotation reports. Navigate to /dashboard on your CyteType server.

Workspaces

The dashboard supports two workspaces, selectable from the switcher at the top of the sidebar.

Personal — Your free individual account. Tokens and reports here are private by default and subject to the free-tier daily limit (three annotation runs per day).

Organization — Available if your account is linked to an organization license. Switching to this workspace shows tokens and reports scoped to your organization, with shared quota, org-wide visibility options, and team administration features.

API Tokens

API tokens authenticate your requests to the CyteType API. Open the API Tokens section from the sidebar navigation.

Creating a token:

1. Click Create New Token.
2. Enter a descriptive name for the token (e.g. Production Server or Local notebook).
3. Optionally set a Quota Limit — the maximum number of clusters this token is allowed to annotate. Leave empty for no limit.
4. Click Create Token.

The token value is displayed in the table immediately. Copy it and store it securely — it is used as the auth_token parameter in the Python and R clients:

annotator = CyteType(adata, group_key="leiden", auth_token="your-token-here")

result <- CyteTypeR(
  obj = seurat_obj,
  prepped_data = prepped_data,
  study_context = "...",
  auth_token = "your-token-here"
)

Managing existing tokens:

The token table shows each token's status, total jobs run, clusters annotated, quota, and creation date.

• To disable a token permanently, click Disable. Disabled tokens cannot be re-enabled.
• To copy a token value, click the copy button beside it.
• To rename a token or update its quota, click the edit icon next to the name or quota field.

Use the Sort dropdown to order tokens by date created, name, usage, quota, or status. The filter pills toggle between showing only active tokens and all tokens including disabled ones.

Organization admins:

In the organization workspace, admins see all tokens created across the organization. Admins can create tokens on behalf of other members by entering a member's email address in the User Email field when creating a token.

Members who are not admins cannot create tokens in the organization workspace. Contact your organization admin to request one.

Reports

The Reports section lists annotation jobs submitted under your account. Two tabs are available:

• Reports shared with me — Jobs from other organization members made visible to you (organization workspace only).
• My Reports — Jobs you own.

Controlling visibility:

Each report has a visibility setting. Click the edit icon in the Visibility column to change it.

Sharing a report with specific users (organization workspace):

1. Select one or more reports using their checkboxes.
2. Click Share in the action bar.
3. Enter each person's email address and click Add.
4. Click Save Changes.

You can also click the value in the Shared With column of a single report to open the share dialog for that report directly.

When sharing multiple reports at once, new users are added to each report's existing share list without removing anyone already shared. When editing a single report's shares, the list is replaced entirely — remove users by deleting them from the list before saving.

Archiving reports:

Archiving hides reports from the default view without deleting them. To archive one or more reports, select them and click Archive. To view archived reports, enable Show archived above the table. Select an archived report and click Unarchive to restore it.

Transferring ownership (organization workspace):

To transfer one or more reports to another organization member:

1. Select the reports.
2. Click Transfer in the action bar.
3. Enter the new owner's email address.
4. Click Transfer All.

Transfer is permanent. The receiving user must be a member of the same organization.

Preprocessing your data

CyteType requires differential expression results computed per cluster before submission.

import scanpy as sc

# Assumes adata already has normalized counts in adata.X
# and cluster labels in adata.obs["leiden"]

sc.tl.rank_genes_groups(
    adata,
    groupby="leiden",
    method="wilcoxon",
    key_added="rank_genes_leiden",
    n_genes=100,
)

# If gene symbols are stored separately from var_names:
# adata.var["gene_symbols"] = adata.var_names  # or set during load

library(Seurat)
library(dplyr)

pbmc <- NormalizeData(pbmc)
pbmc <- FindVariableFeatures(pbmc, nfeatures = 2000)
pbmc <- ScaleData(pbmc)
pbmc <- RunPCA(pbmc)
pbmc <- FindNeighbors(pbmc, dims = 1:10)
pbmc <- FindClusters(pbmc, resolution = 0.5)
pbmc <- RunUMAP(pbmc, dims = 1:10)

pbmc.markers <- FindAllMarkers(pbmc, only.pos = TRUE) %>%
  dplyr::filter(avg_log2FC > 1)

Initializing the annotator

The initialization step validates your data and precomputes expression percentages. This can take a few minutes on large datasets but only needs to run once per object.

from cytetype import CyteType

annotator = CyteType(
    adata,
    group_key="leiden",             # column in adata.obs with cluster labels
    rank_key="rank_genes_leiden",   # key in adata.uns with DE results
    gene_symbols_column="gene_symbols",  # column in adata.var with gene symbols
    n_top_genes=50,                 # top marker genes per cluster
    aggregate_metadata=True,        # include obs metadata in context
    min_percentage=10,              # min % threshold for metadata
    coordinates_key="X_umap",      # key in adata.obsm for UMAP coordinates
    max_cells_per_group=1000,       # cells sampled per cluster for visualization
    auth_token=None,                # Bearer token (if your deployment requires one)
)

# PrepareCyteTypeR handles all preprocessing in one step
prepped_data <- PrepareCyteTypeR(
  obj = seurat_obj,
  marker_table = markers_df,       # output of FindAllMarkers()
  group_key = "seurat_clusters",   # metadata column with cluster assignments
  gene_symbols = "gene_symbols",   # gene symbol field name
  n_top_genes = 50,                # top marker genes per cluster
  aggregate_metadata = TRUE,       # include metadata context
  min_percentage = 10,             # min % threshold for metadata
  coordinates_key = "umap",        # dimensional reduction for visualization
  max_cells_per_group = 1000       # cells sampled per cluster
)

Running annotation

The study_context is the most important parameter for annotation quality. Describe your tissue, organism, disease state, and experimental setup in one or two sentences.

adata = annotator.run(
    study_context="Human colorectal cancer biopsy, tumor microenvironment, 10X Genomics 5' scRNA-seq, treatment-naive patients",
    metadata={
        "Study": "My TME atlas",
        "GEO": "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE123456",
        "DOI": "https://doi.org/10.1038/example"
    },
    n_parallel_clusters=4,          # increase for faster annotation (watch rate limits)
    results_prefix="cytetype",      # prefix for result columns
    timeout_seconds=7200,
    show_progress=True,
)

pbmc <- CyteTypeR(
  obj = seurat_obj,
  prepped_data = prepped_data,
  study_context = "Human colorectal cancer biopsy, tumor microenvironment, treatment-naive patients",
  metadata = list(
    "Study" = "My TME atlas",
    "GEO" = "https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=GSE123456",
    "DOI" = "https://doi.org/10.1038/example"
  ),
  n_parallel_clusters = 4L,
  results_prefix = "cytetype",
  timeout_seconds = 7200L,
  show_progress = TRUE
)

Accessing results

After a successful run, annotations are stored in your object and can be accessed immediately.

# Annotation columns added to adata.obs:
# cytetype_annotation_leiden       — cell type label
# cytetype_cellOntologyTerm_leiden — Cell Ontology term name
# cytetype_cellOntologyTermID_leiden — CL:xxxxxxx ID
# cytetype_cellState_leiden        — functional state

import json
results = json.loads(adata.uns["cytetype_results"]["result"])

for ann in results["annotations"]:
    print(ann["clusterId"], ann["annotation"], ann["ontologyTermID"])

# If you need to re-fetch results after disconnecting:
results = annotator.get_results()

# Annotation columns added to obj@meta.data:
# cytetype_annotation_seurat_clusters
# cytetype_cellOntologyTerm_seurat_clusters
# cytetype_cellOntologyTermID_seurat_clusters
# cytetype_cellState_seurat_clusters

# Full results table in obj@misc:
results_df <- seurat_obj@misc[["cytetype_results"]]
View(results_df)

# Available columns in results_df:
# clusterId, annotation, ontologyTerm, ontologyTermID,
# granularAnnotation, cellState, justification,
# supportingMarkers, conflictingMarkers, missingExpression, unexpectedExpression

# If you need to re-fetch results after disconnecting:
results <- GetResults(seurat_obj)

Custom LLM configuration

By default CyteType uses its own hosted model. You can bring your own LLM from any supported provider.

# Single LLM configuration
adata = annotator.run(
    study_context="...",
    llm_configs=[{
        "provider": "openai",
        "name": "gpt-4o",
        "apiKey": "sk-...",
        "baseUrl": "https://api.openai.com/v1",   # optional
        "modelSettings": {"temperature": 0.0, "max_tokens": 4096}
    }]
)

# Multiple providers (different agents can use different models)
adata = annotator.run(
    study_context="...",
    llm_configs=[
        {
            "provider": "anthropic",
            "name": "claude-3-5-sonnet-20241022",
            "apiKey": "sk-ant-...",
            "targetAgents": ["annotator", "reviewer"]
        },
        {
            "provider": "openai",
            "name": "gpt-4o-mini",
            "apiKey": "sk-...",
            "targetAgents": ["summarizer", "clinician"]
        }
    ]
)

# AWS Bedrock
adata = annotator.run(
    study_context="...",
    llm_configs=[{
        "provider": "bedrock",
        "name": "us.anthropic.claude-3-5-sonnet-20241022-v2:0",
        "awsAccessKeyId": "AKIA...",
        "awsSecretAccessKey": "...",
        "awsDefaultRegion": "us-east-1"
    }]
)

# Single LLM configuration
result <- CyteTypeR(
  obj = seurat_obj,
  prepped_data = prepped_data,
  study_context = "...",
  llm_configs = list(
    provider = "openai",
    name = "gpt-4o",
    apiKey = "sk-...",
    baseUrl = "https://api.openai.com/v1",
    modelSettings = list(temperature = 0.0, max_tokens = 4096L)
  )
)

# Multiple providers
result <- CyteTypeR(
  obj = seurat_obj,
  prepped_data = prepped_data,
  study_context = "...",
  llm_configs = list(
    list(
      provider = "anthropic",
      name = "claude-3-5-sonnet-20241022",
      apiKey = "sk-ant-...",
      targetAgents = c("annotator", "reviewer")
    ),
    list(
      provider = "openai",
      name = "gpt-4o-mini",
      apiKey = "sk-...",
      targetAgents = c("summarizer", "clinician")
    )
  )
)

Supported providers: anthropic, bedrock, fireworks, google, groq, huggingface, mistral, openai, openrouter, vertex, xai.

Authentication

For deployments that require a bearer token (private or enterprise instances):

# Pass at initialization (applies to all run() calls)
annotator = CyteType(adata, group_key="leiden", auth_token="your-token")

# Or override at run time
adata = annotator.run(study_context="...", auth_token="your-token")

# Pass auth_token to CyteTypeR
result <- CyteTypeR(
  obj = seurat_obj,
  prepped_data = prepped_data,
  study_context = "...",
  auth_token = "your-token"
)

# Or when re-fetching results
results <- GetResults(seurat_obj, auth_token = "your-token")

Every CyteType report is structured around the same set of sections. Each answers a specific question your biology team will ask when reviewing annotations.

Ontology-anchored annotation

What it is: Each cluster is assigned a Cell Ontology (CL) term — a globally standardized identifier for cell types — alongside a confidence score and a label match score comparing the CyteType call to any labels you already had.

How to read it: The CL ID links to the official ontology definition. Confidence (0–1) reflects model certainty. Label match shows alignment with your prior annotation if you provided cluster labels.

When to act: Low confidence (<0.6) or low label match when you trust your prior labels suggests the cluster may need manual review or re-clustering.

Functional state resolution

What it is: Cell states (activation, exhaustion, ECM remodeling, antigen presentation, etc.) are resolved as distinct gene programs separate from the cell type label.

How to read it: The cell state field reports co-occurring functional programs. Multiple states can be active simultaneously. Each is supported by a specific gene set.

When to act: Unexpected states — exhaustion in naive T cells, proliferation in quiescent stromal cells — should prompt review of cluster composition. These are often the most biologically interesting signals.

Coarse lineage map

What it is: Clusters are grouped into major lineages (myeloid, lymphoid, epithelial, stromal, endothelial, etc.) for rapid high-level orientation before diving into subtypes.

How to read it: Use this for first-pass triage. Lineage groups reflect broad biology before subtype resolution. Confidence indicators show certainty at the lineage level.

When to act: Clusters misassigned to an unexpected lineage may indicate doublets, ambient RNA contamination, or marker gene quality issues.

Marker-level evidence

What it is: The supporting, missing, and unexpected gene breakdown for each annotation call. Each gene is annotated with its biological role and linked to published evidence.

How to read it:

• Unexpected markers are genes inconsistent with the label (potential contamination or annotation error)
• Missing markers are canonical genes expected but not detected (may indicate incomplete capture or a cell subtype)
• Supporting markers positively support the assigned cell type

When to act: Many unexpected markers or absent canonical markers alongside low confidence is a strong signal to question the call.

Confidence and heterogeneity QC

What it is: Badges summarizing certainty and intra-cluster diversity, with narrative reasoning describing what is solid versus mixed.

How to read it: Confidence reflects how strongly the evidence points to the assigned cell type. Heterogeneity reflects how mixed the cluster is internally.

When to act: High heterogeneity clusters are candidates for re-clustering. The narrative often names which marker groups are causing the mixed signal.

Multi-expert synthesis

What it is: Several specialized AI reviewers independently assess each annotation. Their agreements, disagreements, and alternative hypotheses are surfaced before the final label is locked.

How to read it: Reviewer consensus strengthens confidence. Disagreements are not errors — they reflect genuine ambiguity in the data. Alternative hypotheses are ordered by plausibility.

When to act: When reviewers disagree on the top call, treat the listed alternatives as equally valid candidates to investigate with orthogonal methods.

Study-aware context

What it is: The annotation model is grounded in your study_context. Disease-specific, tissue-specific, and organism-specific knowledge shapes which cell types are considered and how markers are weighted.

How to read it: Context fit shows how well the assigned label fits the biological framing of your study. Keywords extracted from the study context are shown for transparency.

When to act: If labels feel generic or off-target, revisit your study_context. A vague context ("human cells") produces generic labels. A specific context ("inflamed synovium from RA patients, synovectomy samples") produces disease-relevant annotations.

Ranked pathway signals

What it is: GO and WikiPathways enrichment results for each cluster, ranked by NES (Normalized Enrichment Score). Both up-regulated and down-regulated programs are shown.

How to read it: NES indicates strength and direction of pathway activation. Focus on pathways with |NES| > 1.5 for mechanistic interpretation. Use this to connect cell identity to cellular programs.

When to act: Unexpected pathway activation may indicate contamination, a stress response, or a biologically interesting subpopulation worth further investigation.

Linked citations trail

What it is: Inline PubMed citations link specific gene claims to published literature. Hover previews and one-click links allow rapid verification without leaving the report.

How to read it: Every marker-gene explanation is backed by a citation. The source publication, journal, and year are shown in the preview.

When to act: In regulated environments, the citation trail is part of your audit record. Flag citations from out-of-context tissues or organisms for manual verification.

Decision traceability

What it is: The full candidate evaluation funnel — what cell types were considered, why each was accepted or rejected, and the quantitative evidence (Log2FC, expression %, tissue context) driving each decision.

How to read it: Accepted candidates met the evidence threshold. Rejected candidates are listed with the reason for rejection. Scores close to the winning label indicate genuine ambiguity.

When to act: When the final label surprises you, check the rejected candidate table. If a rejected candidate had a score within 0.1 of the winner, investigate both labels before accepting the call.

Interactive Cluster Copilot

What it is: A built-in chat interface connected to that cluster's expression data and pathway context. Ask biological questions and get data-grounded answers.

How to use it: Ask it questions like: "Why does this cluster express CXCL13?" or "What differentiates this cluster from the neighboring CD8 T cells?". Answers are grounded in your actual expression matrix, not generic responses.

When to use it: Use this to resolve interpretation questions in-context before escalating to manual analysis or posting to a lab meeting.

Audit-ready export

What it is: A full annotation table exportable as CSV/TSV, containing all fields needed for downstream analysis and regulatory documentation.

Exported columns: cluster ID, CL term name, CL term ID, cell type, granular annotation, cell state, confidence score, label match score, supporting markers, conflicting markers.

When to use it: Use the export for integration into adata.obs or obj@meta.data, consortium data submissions, and clinical/regulatory sign-off packages.

The multi-agent pipeline

CyteType is not a single LLM call with a prompt. It is a coordinated pipeline of specialized agents that collaborate to produce a single annotation with a full evidence trail.

Data preparation (local): Before anything is sent to the API, the client SDK preprocesses your object locally: extracting top marker genes per cluster, computing expression percentages across all genes, aggregating observation metadata per cluster, and sampling UMAP coordinates for visualization. This preprocessing runs in your environment and does not require a network connection.

Artifact generation: Two artifacts are created and uploaded alongside the annotation request:

• obs.duckdb — a DuckDB database of cell metadata, powering metadata filtering and exploration in the report
• vars.h5 — a compressed HDF5 file of the normalized expression matrix, used by the server for on-demand gene expression lookups in the interactive report

Agent roles: Six specialized agents run per cluster:

Cell Ontology mapping: Every annotation is mapped to a Cell Ontology (CL) term. CL is a community-maintained, hierarchical vocabulary for cell types. CL IDs enable cross-study comparison, downstream ontology-based analyses (e.g. enrichment against cell type databases), and regulatory traceability. The ID format is CL:xxxxxxx.

LLM infrastructure: Each cluster requires hundreds of LLM calls. The CyteType API handles rate limit management, automatic retries, health-aware model fallbacks, and parallel cluster processing. The n_parallel_clusters parameter controls how many clusters are annotated simultaneously.

Data flow summary

Your object (AnnData / Seurat)
  ↓ SDK preprocessing (local)
    marker genes, expression %, metadata, UMAP coords
  ↓ Artifact upload
    vars.h5 (expression matrix) + obs.duckdb (cell metadata)
  ↓ /annotate API call
    payload: study context, markers, expression, metadata
  ↓ Multi-agent pipeline (per cluster, in parallel)
    Contextualizer → Annotator → Reviewer × N → Summarizer → Clinician
  ↓ /results fetch
    annotations, ontology terms, confidence scores, evidence
  ↓ Results written back to your object
    adata.obs / obj@meta.data + adata.uns / obj@misc
  ↓ Interactive HTML report
    live at prod.cytetype.nygen.io/report/{job_id}