cell-annotator 0.1.5

A tool to annotate cell types

CellAnnotator

CellAnnotator is an scverse ecosystem package, designed to annotate cell types in scRNA-seq data based on marker genes using OpenAI models.

Key features

• Automatically annotate cells including type, state and confidence fields.
• Generate consistent annotations across samples of your study.
• Optionally infuse prior knowledge by providing information about your biological system.
• Retrieve reliable results thanks to OpenAI structured outputs
• Use this tool to quickly generate pre-integration cell type labels to either score your integration quality (e.g. scIB metrics) or to guide your integration effort (e.g. scPoli, scANVI).

Note that this package is based on output generated by large language models and might sometimes make mistakes. We use some safeguards, like anchoring the tool in a multi-step process, and using structured output predictions, but mistakes are still possible. We recommend using this tool as a first step in an annotation workflow to generate an initial, coarse set of annotations that must be further refined.

Installation

You need to have Python 3.10 or newer installed on your system. If you don't have Python installed, we recommend installing Mambaforge.

PyPI

Install by running:

pip install cell-annotator

Development version

To install the latest development version from GitHub, run

pip install git+https://github.com/quadbio/cell-annotator.git@main

Getting started

After installation, head over to OpenAI to generate your API key

Keep this key private and don't share it with anyone. CellAnnotator will try to read the key as an environmental variable - either expose it to the environment yourself, or store it as an .env file anywhere within the repository where you conduct your analysis and plan to run CellAnnotator. The package will then use dotenv to export the key from the env file as an environmental variable.

Here's the simplest way to annotate your data:

from cell_annotator import CellAnnotator

cell_ann = CellAnnotator(
    adata, species="human", tissue="heart", cluster_key="leiden", sample_key="samples",
).annotate_clusters()

By default, this will store annotations in adata.obs['cell_type_predicted']. Head over to our tutorials to see more advanced use cases, and learn how to adapt this to your own data. You can run CellAnnotator for just a single sample of data, or across multiple samples. In the latter case, it will attempt to harmonize annotations across samples.

Costs and models

The default model is currently gpt-4o-mini, which is included in OpenAI's Free Usage Tier. Thus, you can get started for free and experiment with our tutorials and with your own data. If you want to get accurate cell type labels for complex tissues, we strongly recommend using more powerful models, like gpt-4o, gpt-4.1, etc, or reasoning models like o3-mini, for which you will have to pay a small fee to OpenAI. As an orientation, running both tutorials with o3-mini will cost around 1 USD. Take a look at the OpenAI API docs to learn more about the different available models.

Data privacy

This package sends cluster marker genes to OpenAI, but no actual gene expression values. In addition, it sends the species and tissue you define. Make sure your usage of this package aligns with your institutions guidelines on data privacy and AI models.

Credits

This tool was inspired by Hou et al., Nature Methods 2024 and https://github.com/VPetukhov/GPTCellAnnotator.

Contact

If you found a bug, please use the issue tracker.