CyteArc for Scanpy users

This guide maps familiar Scanpy stages to CyteArc’s store-backed API. Use the workflow map below to find the equivalent task, or try the Quick start to inspect a prepared result. For optional background on how CyteArc stores and reuses results, see How CyteArc compares with Scanpy and Seurat.

Workflow map¶

Scanpy commonly composes stages as separate sc.pp, sc.tl, and sc.pl calls. CyteArc provides the same level of control through individual methods, while ds.pipeline.run() is the shortest path through the standard RNA workflow. It returns a durable PipelineRun with frozen views and leaves live metadata unchanged.

The rows below map intent, not identical statistical implementations. CyteArc selects highly variable genes before normalizing on that feature set, which differs from the common Scanpy order of normalization, log transformation, and then HVG selection.

Goal	Scanpy	CyteArc
Load counts	`sc.read_*` returns an `AnnData`	A reader and `*ToZarr` writer create the store; `DataStore` opens it
Calculate QC metrics	`sc.pp.calculate_qc_metrics`	Opening a new `DataStore` calculates count and feature metrics, plus detected RNA mitochondrial and ribosomal percentages
Filter cells	`sc.pp.filter_cells` or an `obs` mask	`ds.qc.filter` or `ds.qc.auto_filter` returns a cell-selection artifact without deleting cells or changing `I`
Select and normalize features	`sc.pp.normalize_total`, `sc.pp.log1p`, `sc.pp.highly_variable_genes`	`ds.features.hvgs`, then `ds.features.normalize`, using the same cell-selection ref
Run PCA and find neighbours	`sc.pp.pca`, then `sc.pp.neighbors`	`ds.reduction.pca`, then CyteArc’s neighbour-graph methods
Embed the graph	`sc.tl.umap`	`ds.embeddings.umap`
Cluster cells	`sc.tl.leiden`	`ds.clusters.leiden`; Paris hierarchy diagnostics are covered in the advanced clustering guide
Find marker genes	`sc.tl.rank_genes_groups`	`ds.markers.search`, then `ds.markers.load`
Plot results	`sc.pl.*`	`ds.plots.embedding`, `ds.plots.dotplot`, and other `ds.plots` methods
Export an assay	`adata.write_h5ad`	`ds.to_anndata()` or `cytearc.to_h5ad`

CyteArc marker search reports AUC, two-sided Mann-Whitney p-values, and within-group Benjamini-Hochberg adjustment over tested features. It is not replicate-aware differential expression. See Build a neighborhood graph stage by stage for the complete manual graph chain and Identify PBMC populations with scRNA-seq for stage-by-stage biological interpretation.

Move data through H5AD¶

CyteArc reads and writes H5AD, so CyteArc and Scanpy can be used at different stages of one project. Import an H5AD file into a CyteArc store:

import cytearc

inspection = cytearc.inspect_h5ad("data.h5ad")
reader = cytearc.H5adReader.from_inspect(
    inspection,
    embedding_roles={"X_umap": "umap"},
    cluster_keys=("clusters",),
)
imported = cytearc.H5adToZarr(
    reader,
    zarr_loc="data.zarr",
    analysis_assay="RNA",
).dump()
ds = cytearc.DataStore("data.zarr")
ds.plots.embedding(
    layout=imported.embeddingArtifacts["X_umap"],
    color_by=imported.clusterArtifacts["clusters"],
)

Selected embeddings and clusterings become immutable artifacts rather than live metadata columns. Use their returned refs directly or inspect a payload with ds.artifacts.load(ref).

Export to an in-memory AnnData object or directly to H5AD:

adata = ds.to_anndata()
cytearc.to_h5ad(ds.RNA, "analysis.h5ad")

To export a completed pipeline’s frozen cells, feature universe, and result fields, pass its run:

adata = ds.to_anndata(run=run)
cytearc.to_h5ad(ds.RNA, "pipeline-analysis.h5ad", run=run)

Run export writes frozen UMAP coordinates to obsm["X_umap"] and frozen cluster labels to obs["clusters"]. A run with umap=False does not invent an embedding. Both calls export the same object: ds.to_anndata holds it in memory, while cytearc.to_h5ad streams it to disk and needs neither the anndata package nor memory for the complete matrix. X holds raw counts over the run’s feature universe. Pass matrix="normed" to either call for the values that the run’s PCA read: its stored normalized values, float32, over its highly variable genes only, which then become var.

ds.to_anndata() defaults to active cells and all features. Pass feature_indexes or feature_names to subset features. Without run, cytearc.to_h5ad writes the full assay to disk, including cells with I=False, without first constructing an in-memory AnnData.

Counts and metadata transfer, but CyteArc’s neighbourhood graphs, provenance records, and multimodal relationships do not map directly to AnnData. The exported H5AD may therefore need a new neighbour graph in Scanpy. See Import and export for format details and export options.