OSP: Agentic Single-Cell QC and Annotation Pipeline

Better single-cell analysis starts with carefully reviewed samples.

Get started     How it works     FAQ     Further reading

OSP combines sample-level quality control with AI-assisted cell-type annotation. It checks cell quality, finds cell populations, and uses an AI assistant to interpret marker genes and quality measurements together. You get proposed labels, supporting evidence, and a browser report to review before bringing samples together. OSP simply stands for "One Sample Pipeline".

OSP is part of ECA-RSI (Ensemble Cell Atlas: Recursive Self Improvement), an ecosystem for iterative quality review and cell-type annotation of single-cell datasets.

📰 News

• 2026-09-04: OSP 0.1.1. Backend-agnostic annotation agent with --harness openai|deepseek|claude, explicit input and rerun contracts with atomic output writes, a pytest suite, and rewritten documentation with an interactive workflow diagram. See the full release notes.

• 2026-09-02: OSP 0.1.0. First release on PyPI as osp-sc.

🔬 Why start with one sample?

Better inputs make downstream results easier to trust. OSP adds a dedicated review before integration:

• QC in the sample's own context. Adaptive checks use each sample's quality distribution, so differences in depth or contamination remain visible before pooling.

• Problems are easier to locate. Within a single experimental batch, inspect suspicious populations without cross-sample batch differences complicating the picture.

• Labels come with evidence. The AI assistant checks marker genes and QC profiles, can refine mixed clusters, and records uncertainty and proposed actions for your review.

Start with OSP, then use MSP: Multi-Sample Pipeline to integrate reviewed samples and continue annotation across samples.

📦 What you get

• Cell-type labels with evidence. Proposed identities, supporting genes, uncertainties, and quality concerns for each cluster.

• A report you can share. Quality measurements, cell populations, and annotation results together in one HTML file with embedded plots.

• Data ready for further analysis. An analyzed H5AD with preserved raw counts, plus marker tables, individual plots, and a record of QC removals.

🔧 How it works

One run follows a single sample through the stages below. Click the diagram to open the interactive version, with pan, zoom, search, and guided views.

Quality control in context

OSP combines fixed and sample-adaptive thresholds with doublet detection and contamination estimates to assess cell quality in context.

Interpreting each cluster

The AI assistant combines marker genes, cluster relationships, and quality evidence to propose cell identities and flag populations for closer review.

🚀 Get started

Recommended: let ECA-RSI coordinate the analysis

Prepare your data with ECA-PP, then let ECA-RSI organize samples and run OSP and the downstream analyses. ECA-PP handles counts validation, gene standardization, and sample or batch metadata identification. It can also recover counts from supported log-normalized data.

Follow the ECA-PP guide to prepare your data, then the ECA-RSI setup guide to run the workflow.

Run OSP on its own

For a standalone sample analysis, follow the three steps below.

1. Install

Use Python 3.10 or newer. Install the current GitHub version with AI support:

pip install "osp-sc[agent] @ git+https://github.com/chansigit/osp.git"

No R installation is required, including for DecontX and plotting.

pip install "osp-sc[agent]"

2. Prepare your input

Provide an H5AD file, the AnnData format commonly used with Scanpy, containing:

• Raw expression counts in layers["counts"], or in X if that layer is absent. Already normalized expression alone is not a counts input.

• A sample identifier for each cell, in obs["sample"] by default.

The file may contain several samples; each run selects one. In the example below, replace data.h5ad with your file and SAMPLE_A with a sample label from your data. If your sample column has another name, add --sample-col YOUR_COLUMN.

3. Run QC and AI annotation

The default AI backend uses Doubao through Volcengine Ark. Set your Ark API key, then run the analysis with annotation enabled. Replace the species and tissue below with your sample's context, and use a separate output directory for each sample.

export ARK_API_KEY="YOUR_ARK_API_KEY"
python -m osp data.h5ad --sample SAMPLE_A --outdir results/SAMPLE_A \
    --annotate --species mouse --tissue "bone marrow"

When the command finishes successfully, open results/SAMPLE_A/report.html in your browser. If you ran OSP on a remote server, download that HTML file to view it locally.

Start with the QC summary to see how many cells were retained and why. Then review the proposed cell types alongside their marker genes, quality profiles, and the assistant's notes.

python -m osp.annotate results/SAMPLE_A --species mouse --tissue "bone marrow"

❓ FAQ

Does OSP remove cells?

OSP preserves your original input file and writes a separate analysis dataset. Cells flagged by the configured QC thresholds or doublet detection are excluded from that output, with the reasons recorded in qc_removed.csv. Review the thresholds against your sample's biology, especially for naturally low-complexity populations.

The AI annotation stage only records proposed actions. Cells marked drop by the assistant remain in OSP's clustered.h5ad for downstream processing. For subsequent filtering, see MSP's output guide.

Can I use OSP without AI?

Yes. Omit --annotate to run QC, clustering, and report generation without an API key. For installation without the AI dependencies, omit [agent] from the package name.

Does DecontX change the expression matrix used for analysis?

OSP preserves raw counts and uses them as the starting point for normalization and clustering. DecontX stores corrected counts separately and provides contamination estimates for interpretation. Its contamination score does not directly trigger the initial QC filter.

Can I rerun an analysis?

Yes. Rerunning replaces results in the same output directory. Use a new directory to compare settings or preserve an earlier analysis, and check that a run finished successfully before relying on its output.

Can I use a large H5AD containing multiple samples?

Yes. The CLI loads only the selected sample's expression matrix into memory. Allow enough RAM for that sample and its analysis. For many samples, use ECA-RSI to manage the runs or adapt the Slurm job-array example.

📚 Further reading

Related projects in the ECA-RSI ecosystem

Use these companion projects to prepare inputs and continue from individual samples to a shared, iteratively reviewed analysis.

If these tools help your work, stars, issues, and feedback on the related repositories help others discover them and guide their development.

Documentation and examples

• Input and output reference: matrix contents, output fields, Python return values, and completion rules.

• Release notes: what changed in each version.

• Interactive workflow diagram: the pipeline map above as an explorable page, generated from docs/diagrams/osp-workflow.archify.json.

• Python sample driver: run one sample from a larger input file.

• Slurm job-array example: process samples as separate cluster jobs.

• Report an issue: describe a problem or suggest an improvement.

OSP is distributed under the MIT license. See third-party notices for included components.