scArches: mapping query single-cell data onto a reference atlas by architecture surgery
Reference mapping for single-cell genomics
At a glance
- What is it?
- scArches is a Python package for reference-based analysis of single-cell data. It trains a query-specific mapping onto an existing integrated reference so that labels and embeddings transfer, and the README points to the documentation for the actual workflow rather than spelling it out.
- Who is it for?
- Adopt scArches when you already have a reference atlas you trust and a query dataset that needs labels or an embedding placed in that reference space, and you can accept that the mapping quality is bounded by the reference. Do not adopt it as a general batch-correction or clustering toolkit, and do not expect the README to carry you: the repository itself defers to the Read the Docs site for usage and tutorials.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 82 days ago.
- What is it written in?
- Mainly Jupyter Notebook, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem scArches addresses: placing new cells into an atlas you already built
Single-cell datasets are expensive to annotate. A lab that has spent months curating an atlas of cell types across tissues does not want to repeat that work every time a new cohort arrives. The naive alternative is to concatenate the new query with the reference and re-run integration from scratch, which means retraining on data you already processed and produces an embedding that shifts every time the query changes. scArches takes the opposite position. The reference stays fixed, and the query is fitted into it.
The README states the package is for "reference-based analysis of single-cell data" and that it lets "your single-cell query data to be analyzed by integrating it into a reference atlas." Three downstream uses are named explicitly: transferring cell-type annotation from reference to query, identifying disease states by mapping to a healthy atlas, and applications the README calls advanced, namely imputing missing data modalities or spatial locations. That third item is the interesting one. It implies the reference does not have to be an expression matrix alone; a reference carrying paired modality or spatial information can be used to infer what the query is missing.
The audience is computational biologists and methods developers who work with scanpy-style AnnData objects and who already have a reference. If you have no reference and no intention of building one, the package has nothing to offer you.
What architecture surgery actually changes in the model
The name is literal. A reference model, typically a variational autoencoder trained on the atlas, has an encoder that maps expression to a latent space and a decoder that maps back. To adapt it to a query, scArches adds new, query-specific parameters and trains those while holding the reference weights fixed. The README does not enumerate the parameter blocks, so the precise surgery is something you have to read out of the documentation and the paper it cites, Lotfollahi et al., Nature Biotechnology 2021, "Mapping single-cell data to reference atlases by transfer learning."
The data flow that follows from this is: reference AnnData plus trained reference model, query AnnData, a surgery step that produces a query-adapted model, then a latent embedding for the query that lives in the same coordinate system as the reference. Because the reference weights are frozen, the reference embedding does not move. That is the whole point, and it is also the constraint. Anything the reference model never learned to represent, the query encoder has to express through a small number of new parameters, and it will do so badly.
A detail worth noting about the repository: the primary language is listed as Jupyter Notebook. That is a signal about where the working examples live. The Python package is real, but the tutorials that show the surgery in practice are notebooks, and the README pushes you to the Read the Docs site rather than reproducing any of them inline.
Getting it installed and finding the entry points
The README is short on commands. It says "See here for documentation and tutorials" with a link to scarches.readthedocs.io, and the PyPI badge points at pypi.org/project/scarches. The conventional install is therefore via pip from PyPI, and the package name matches the repository name. Beyond that, the README does not give a configuration reference, a list of model classes, or a worked example with arguments.
That absence matters for evaluation. If you are deciding whether to adopt scArches, the README alone will not tell you which reference architectures are supported, what the surgery function signatures look like, or what the expected AnnData keys are. You have to go to the documentation site and the notebooks. The README does say that if you have "a question or new architecture or a model that could be integrated into our pipeline" you can open an issue or email the maintainer, which tells you the set of supported architectures is treated as extensible rather than closed.
One thing the README does give you cleanly is the citation block, a BibTeX entry for the 2021 Nature Biotechnology paper. For a methods package in this field that is effectively required infrastructure, and it is present.
Where the reference-fixed design breaks down
The central limitation is the one the design guarantees. Because reference weights are frozen, the query can only be described in terms the reference already knows. Map a query from a tissue, developmental stage, or disease context that the atlas never sampled, and the model has no vocabulary for it. The embedding will still be produced. It will just be wrong in a way that is hard to detect, because the output is a smooth latent coordinate, not an error message. This is the failure mode to worry about most, and it is not something the README warns about.
A second constraint is that the reference is a dependency with its own quality. If the atlas was integrated poorly, or its cell-type labels are coarse, the transferred annotation inherits both problems. scArches does not correct the reference; it propagates it.
Third, the release cadence visible in the repository listing is slow. The tagged releases shown are v0.4.0 (August 2021), v0.5.0 (February 2022), and v0.5.1 (June 2023), and the v0.5.1 note describes it as "adding Zenodo DOI." A release whose headline change is a DOI is a maintenance release, not a feature release. The last push timestamp is much more recent than the last tag, so development continues between tags, but if you pin to a released version you may be pinning to something from 2023. Whether that matters depends on how fast your surrounding stack (scanpy, PyTorch, AnnData) moves underneath it.
Finally, the notebook-heavy repository layout means the canonical usage examples are not importable code you can call in a test. Reproducing a result means running a notebook.
How this differs from concatenate-and-reintegrate approaches
The obvious alternative is to concatenate reference and query and run a batch-integration method over the combined object, the way scanpy's ingest or a Harmony-style integration would be used. The difference in approach is structural, not a matter of tuning. Concatenation methods recompute a joint embedding from all cells present, so the reference representation changes each time you add data, and the cost scales with the size of the combined dataset. scArches trains a mapping onto a frozen reference, so the reference representation is stable across queries and the cost scales with the query plus the surgery, not with a full re-integration.
That stability is what makes label transfer meaningful over time. If you map ten cohorts across two years and the reference embedding never moves, coordinates are comparable across those cohorts. Under repeated re-integration they are not, unless you go to some effort to anchor them.
The trade is expressiveness. A full re-integration can, in principle, discover structure that neither the reference nor the query showed alone. scArches cannot, because the reference side is fixed by construction. If your scientific question is "what is new in this query," a reference-mapping tool is the wrong shape of tool. If your question is "where do these cells sit relative to what we already know," it is the right one.
Licence, maintenance and what the BSD-3-Clause terms mean here
The repository is BSD-3-Clause. That is a permissive licence: it allows use, modification, and redistribution, including in closed products, provided the copyright notice and licence text are retained and the names of the project and its contributors are not used to endorse derived work without permission. This is not legal advice, and the exact obligations depend on how you redistribute, but the practical consequence for a research group is that incorporating scArches into an internal pipeline or a published analysis carries no copyleft requirement on your own code.
Maintenance cost is the more concrete question. The tagged releases in the listing are sparse, and the most recent one is described only as adding a Zenodo DOI. That means you should not expect a stream of tagged versions to pin against. Track the master branch or pin a commit if you need recent behaviour, and budget for the possibility that a dependency upgrade breaks the notebooks before it breaks the library.
The contribution path is stated plainly in the README: open an issue, or email the maintainer at the address given, if you have a question or a new architecture or model that could be integrated. For a package whose supported model set is meant to grow, that is the mechanism by which it grows.
Editorial conclusion
Adopt scArches when you already have a reference atlas you trust and a query dataset that needs labels or an embedding placed in that reference space, and you can accept that the mapping quality is bounded by the reference. Do not adopt it as a general batch-correction or clustering toolkit, and do not expect the README to carry you: the repository itself defers to the Read the Docs site for usage and tutorials. Before committing, verify that the reference you intend to use was built with a compatible model, check which architecture classes the installed version exposes, and confirm the release you are pinning against, given that the most recent tagged release in the repository listing is v0.5.1 from June 2023.
Community notes