R function reference

This page is generated from the help pages of CyteTypeR 0.6.0. To regenerate it, run Rscript docs/render_r_reference.R ../CyteTypeR from the root of the CyteType repository. In R, the same help is available with ? and the function name, for example ?PrepareCyteTypeR.

Prepare and run¶

Prepare a Seurat object, submit the annotation job and wait for the results, then delete the uploaded files.

PrepareCyteTypeR()¶

Prepare Seurat Object for CyteType Analysis

Prepares a Seurat object and a gene marker table for CyteType API by extracting and formatting cluster labels, metadata, marker genes, visualization coordinates, and expression data into the required data structure. It also writes the two files that CyteTypeR() uploads with the job: vars.h5 (expression) and obs.duckdb (cell metadata and coordinates).

Usage

PrepareCyteTypeR(
  obj,
  marker_table,
  group_key = "seurat_clusters",
  gene_symbols = "gene_symbols",
  n_top_genes = 50,
  aggregate_metadata = TRUE,
  min_percentage = 10,
  max_metadata_categories = 500L,
  pcent_batch_size = 5000,
  coordinates_key = "umap",
  max_cells_per_group = 1000,
  vars_h5_path = "vars.h5",
  obs_duckdb_path = "obs.duckdb"
)

Arguments

Value

A named list to pass to CyteTypeR():

• clusterLabels: List mapping the CyteType cluster IDs ("1", "2", ...) to your cluster labels

• clusterMetadata: Aggregated metadata by cluster (if enabled)

• markerGenes: List of top marker genes per cluster

• visualizationData: Sampled coordinates and cluster assignments for plotting, or NULL when no coordinates were found

• expressionData: Expression percentages by cluster

• group_key: The metadata column name used for cluster assignments

• build_succeeded: Logical indicating whether artifact files were built successfully

• vars_h5_path: Path to the generated vars.h5 file

• obs_duckdb_path: Path to the generated obs.duckdb file

• coordinates_key: The name of the reduction whose coordinates were used for the visualization, or NULL when none was used

Details

The function performs the following steps:

1. Validates the Seurat object structure and the cluster labels

2. Creates a mapping from original cluster labels to sequential numeric IDs

3. Aggregates metadata across cells within clusters (optional)

4. Filters and selects top marker genes per cluster

5. Extracts dimensional reduction coordinates for visualization

6. Calculates expression percentages across clusters

7. Builds a vars.h5 artifact from the normalized expression matrix, with the raw counts when they are whole numbers

8. Builds an obs.duckdb artifact from the cell metadata

Clusters are renumbered sequentially (1, 2, 3, ...) in the sorted order of your labels (level order for a factor) to ensure consistent formatting regardless of original cluster naming.

Expression always comes from the "RNA" assay, whatever the default assay is, and Seurat v5 layers split by sample are joined on a copy (your object is not changed). The gene names come from the same assay. When the default assay is not "RNA", a warning says that "RNA" is used.

Errors while building the two files are logged and recorded as build_succeeded = FALSE; CyteTypeR() then stops unless require_artifacts = FALSE.

Examples

# Prepare Seurat object with UMAP coordinates
prepped_data <- PrepareCyteTypeR(
  obj = seurat_obj,
  marker_table = markers_df,
  group_key = "seurat_clusters",
  n_top_genes = 30,
  coordinates_key = "umap"
)

See also

CyteTypeR() to submit the job, CleanUpArtifacts() to delete the files afterwards.

CyteTypeR()¶

Submit CyteType Analysis Job

Submits a prepared dataset to CyteType for automated cell type annotation using large language models. Handles job submission, polling for results, and integration of annotations back into the Seurat object.

Usage

CyteTypeR(
  obj,
  prepped_data,
  study_context = NULL,
  llm_configs = NULL,
  metadata = NULL,
  n_parallel_clusters = 2L,
  results_prefix = "cytetype",
  poll_interval_seconds = NULL,
  timeout_seconds = NULL,
  api_url = NULL,
  auth_token = NULL,
  save_query = TRUE,
  query_filename = "query.json",
  upload_timeout_seconds = 3600L,
  upload_max_workers = 6L,
  require_artifacts = TRUE,
  show_progress = TRUE,
  override_existing_results = FALSE,
  visibility = NULL
)

Arguments

Value

The Seurat object obj with the results added. Assign it, for example obj <- CyteTypeR(obj, prepped_data); the object you pass in is not changed.

• obj@meta.data gains the factor columns listed under results_prefix. Cells in clusters without a result get "Unknown" ("" for the cell state) in the first five columns and NA in the three older ones. The reviewer confidence column holds "High", "Moderate", "Low", or "Unknown" when it is missing; its levels follow that order, and only the levels that occur are kept.

• obj@misc[[paste0(prefix, "_jobDetails")]] holds job_id, report_url, api_url, group_key, cluster_labels and, when set, visibility.

• With the default prefix, obj@misc$cytetype_results is a data.frame with one row per annotated cluster and the columns clusterId (your cluster label), annotation, ontologyTerm, ontologyTermID, granularAnnotation, cellState, justification, supportingMarkers, conflictingMarkers, missingExpression, unexpectedExpression, reviewerConfidence, isHeterogeneous and heterogeneityType. Its attributes "job_id" and "result" hold the job ID and the full results in the form returned by GetResults().

• With another prefix, obj@misc[[paste0(prefix, "_results")]] is a list with job_id and result (the full results), and obj@misc$cytetype_results is left as it is.

Details

The function performs the following workflow:

1. Constructs the analysis query from prepared data

2. Optionally saves the query to a JSON file

3. Uploads the artifact files and submits the job

4. Polls for job completion with progress updates

5. Retrieves results and integrates annotations into the Seurat object

The evidence columns of the results table (justification, supportingMarkers, conflictingMarkers, missingExpression and unexpectedExpression) are filled from the structured output of current jobs when the stored fields are empty. supportingMarkers and conflictingMarkers list genes separated by "; ".

While waiting, network errors are retried until timeout_seconds is reached. Other errors while checking the job stop the run after five in a row. When the results of a completed job cannot be fetched, the rate limit and server errors (HTTP 500, 502, 503 and 504) are retried in the same way, and other errors, such as a deleted report (HTTP 410), stop the run at once. These errors signal a cytetype_api_error() condition. If the run stops or is interrupted, the job keeps running on the server: retrieve its results with GetResults(job_id = "<job_id>"), using the job ID printed when the job was submitted.

Examples

# Basic usage with prepared data
annotated_seurat <- CyteTypeR(
  obj = seurat_obj,
  prepped_data = prepped_data,
  study_context = "Single-cell analysis of human brain tissue"
)

# With custom settings and metadata
annotated_seurat <- CyteTypeR(
  obj = seurat_obj,
  prepped_data = prepped_data,
  study_context = "Alzheimer's disease brain samples",
  metadata = list(
    "DOI" = "10.1038/example",
    "GEO_Accession" = "GSE123456"
  ),
  timeout_seconds = 1800,
  poll_interval_seconds = 60,
  visibility = "public"
)

See also

PrepareCyteTypeR() for data preparation, GetResults() for manual result retrieval

CleanUpArtifacts()¶

Clean Up Artifacts

Deletes the artifact files (vars.h5 and obs.duckdb) that PrepareCyteTypeR() wrote, once CyteTypeR() has uploaded them.

Usage

CleanUpArtifacts(prepped_data)

Arguments

Value

Invisibly, TRUE when the artifact files had been built and are now removed, and FALSE when they were never built (nothing is deleted).

Examples

prepped_data <- PrepareCyteTypeR(pbmc, pbmc.markers)
pbmc <- CyteTypeR(pbmc, prepped_data, study_context = "Human PBMCs")
CleanUpArtifacts(prepped_data)

Results¶

Read the results stored in a Seurat object, or fetch the results of a job by its ID.

GetResults()¶

Retrieve CyteType Analysis Results

If obj and results_prefix are given, tries to load from obj@misc first. If no local result exists but job details are available, fetches the result from the API. If only job_id is given, fetches the result from the API.

Usage

GetResults(
  obj = NULL,
  job_id = NULL,
  results_prefix = "cytetype",
  auth_token = NULL,
  api_url = NULL,
  save_json = TRUE
)

Arguments

Value

Depends on where the results come from:

• GetResults(obj) after a run with the default prefix: the data.frame in obj@misc$cytetype_results (see CyteTypeR()).

• Results stored under another prefix, or fetched for the job stored in obj: a list with annotations (one list per annotated cluster with clusterId, the CyteType cluster ID, annotation, ontologyTerm, ontologyTermID, granularAnnotation, cellState, justification, supportingMarkers, conflictingMarkers, missingExpression, unexpectedExpression, reviewerConfidence, isHeterogeneous and heterogeneityType), raw_annotations (the server’s per-cluster results, unchanged) and the server’s studyContext, summary, semanticOrder, clusterCategories and displayLevel.

• GetResults(job_id = ...): a data.frame with the same columns as obj@misc$cytetype_results, where clusterId is the CyteType cluster ID. Its attributes "job_id" and "result" hold the job ID and the list described above.

• NULL, with a message, when the job has not finished yet or is not found.

Details

Fetching asks the server for the job’s status and, when the job has completed, for its results: two requests, without waiting. A failed job stops with an error. When the status or the results cannot be fetched, GetResults() signals a cytetype_api_error() condition whose error_code holds the server’s code when it sent one, such as "REPORT_DELETED". Problems with the API key signal its subclass cytetype_auth_error.

reviewerConfidence is "High", "Moderate" or "Low" (NULL in the list and NA in the table when missing), isHeterogeneous is TRUE or FALSE (or missing), and heterogeneityType names the kind of heterogeneity the reviewer found. In the list, supportingMarkers and conflictingMarkers are lists of gene names.

Fetched results are not added to obj; R does not modify the object you pass in.

Examples

# Results stored in the object by CyteTypeR()
results <- GetResults(annotated_seurat)

# Results of a job by its ID, without saving the JSON file
results <- GetResults(job_id = "<JOB_ID>", save_json = FALSE)

See also

CyteTypeR() for job submission

Sign-in and the cytetyper command¶

Save an API key, open the dashboard or a job’s report, and install the cytetyper terminal command. Each cytetyper command calls one of these functions (see the Command-line reference).

SetupCyteTypeR()¶

Set up CyteType authentication

Validates matching saved credentials. When none are available, opens CyteType sign-in in a browser and stores the resulting personal API key.

Usage

SetupCyteTypeR(api_url = NULL, force = FALSE)

Arguments

Value

The saved credential metadata, invisibly.

Details

The browser flow verifies the user’s email with a one-time code and returns to a local callback server. CyteTypeR and the Python client use the same credentials file. For development, pass the development server origin as api_url. If a saved key is invalid or inactive, use force = TRUE.

Examples

SetupCyteTypeR()
SetupCyteTypeR(force = TRUE)
SetupCyteTypeR(api_url = "<URL>")

LoginCyteTypeR()¶

Save an existing CyteType API key

Validates an API key and stores it for later CyteTypeR requests.

Usage

LoginCyteTypeR(api_token = NULL, api_url = NULL)

Arguments

Value

The saved credential metadata, invisibly.

Examples

LoginCyteTypeR()
LoginCyteTypeR(api_url = "<URL>")

LogoutCyteTypeR()¶

Remove local CyteType credentials

Usage

LogoutCyteTypeR()

Value

TRUE when credentials were removed, otherwise FALSE, invisibly.

Details

This removes only the local credentials file. Revoke an API key from the dashboard when it must also be invalidated on the server.

Examples

LogoutCyteTypeR()

OpenCyteTypeDashboard()¶

Open the CyteType dashboard

Usage

OpenCyteTypeDashboard()

Value

The dashboard URL, invisibly.

Details

Uses the dashboard associated with saved credentials. When credentials are absent, opens the production dashboard at https://cytetype.nygen.io/dashboard.

Examples

OpenCyteTypeDashboard()

ViewCyteTypeJob()¶

Open a CyteType job

Usage

ViewCyteTypeJob(job_id, api_url = NULL)

Arguments

Value

The sign-in URL for the job, invisibly.

Examples

ViewCyteTypeJob("<JOB_ID>")
ViewCyteTypeJob("<JOB_ID>", api_url = "<URL>")

InstallCyteTypeRCli()¶

Install the cytetyper terminal command

Usage

InstallCyteTypeRCli(destination = NULL, overwrite = FALSE)

Arguments

Value

The installed command path, invisibly.

Details

After installation, run cytetyper setup in a terminal to authenticate against https://cytetype.nygen.io. During development, use cytetyper setup --api-url "<URL>".

Examples

InstallCyteTypeRCli()

Errors¶

The condition that CyteTypeR signals when the status or the results of a job cannot be fetched (see Errors and error codes).

cytetype_api_error()¶

Custom API Error

Creates the condition that CyteTypeR signals when the status or the results of a job cannot be fetched: by GetResults(), and by CyteTypeR() when it stops waiting for a job because of such errors. Errors about the API key are signalled as cytetype_auth_error, a subclass.

Usage

cytetype_api_error(message, call = NULL, error_code = NULL, status_code = NULL)

Arguments

Value

An error condition of class cytetype_api_error, with the elements message, call, error_code and status_code. Printing it shows CyteType API Error: <message>.

Examples

error <- cytetype_api_error(
  paste(
    "Error while checking job status: HTTP 410 [REPORT_DELETED]",
    "This report has been deleted by the owner"
  ),
  call = "api",
  error_code = "REPORT_DELETED",
  status_code = 410L
)
print(error)

# Handle the condition by its class and read the server's code.
tryCatch(
  stop(error),
  cytetype_api_error = function(e) e$error_code
)