File formats
Primary format: AnnData (.h5ad)
All analysis runs use AnnData as the internal model. Users upload .h5ad directly or convert from other formats on the Data page.
Expected structure:
| Component | Purpose |
|---|---|
X or layers['counts'] | Expression matrix |
layers['counts'], layers['logcounts'], layers['scale.data'] | Recognized as Bioconductor-style assay roles when present |
obs | Cell or sample metadata (barcodes as index) |
var | Gene metadata (gene symbols in index or gene_symbols column) |
obsm['spatial'] | Required for spatial workflows (x/y coordinates) |
obsm['protein'] / obsm['X_adt'] | Recognized as protein/ADT multimodal hints when present |
obsm['X_umap'] | Written by clustering; used by UMAP explorer |
Seurat objects
Upload a Seurat object saved with saveRDS() (.rds) or save() (.rda / .RData), then click Import. The file is read directly in Python; you don't need R, and no R code in the file is ever run.
| Seurat part | Lands in |
|---|---|
Active assay counts (v3/v4 counts slot, or v5 counts layers) | X and layers['counts'] |
Split v5 layers (counts.1, counts.2, ...) | Joined across cells |
Normalised data | layers['seurat_data'] |
meta.data | obs columns (factors stay categorical) |
Reductions (pca, umap, harmony, ...) | obsm['X_<name>'] |
active.ident | obs['active_ident'] |
| Variable features, feature metadata | var['highly_variable'] and var columns |
scale.data is skipped because the pipeline recomputes it. If the active assay has no counts (for example SCT) but an RNA assay does, the RNA assay is used. Provenance (Seurat version, assay, layers, anything skipped) is recorded in uns['r_import'] and shown with the dataset.
SingleCellExperiment and SummarizedExperiment objects (assays, colData, rowData, reducedDims), and plain sparse count matrices (dgCMatrix, genes × cells with names), are accepted the same way. Objects whose counts are stored on disk (DelayedArray, HDF5Array, BPCells) can't be read from the .rds alone; convert them to an in-memory matrix before saving. .h5Seurat files are not supported; save the object with saveRDS() instead. Only binary (default) .rds files can be read, not saveRDS(ascii = TRUE).
To bring existing annotations along with an MTX zip instead, add these optional files at the top level of the zip:
| File | Contents | Lands in |
|---|---|---|
cell_metadata.csv | One row per cell, a barcode column plus any annotations (sample, condition, cluster, cell type) | obs columns |
embedding_<name>.csv | A barcode column plus one column per dimension (e.g. embedding_umap.csv) | obsm['X_<name>'] |
Rows are matched by barcode. An embedding that does not cover every cell is skipped and listed in uns['bundle_extras']['embeddings_skipped'].
Bioconductor compatibility
SingleCellExperiment and SummarizedExperiment .rds / .rda files import directly (see Seurat objects); SpatialExperiment spatial coordinates are not read yet, so export spatial objects to .h5ad. On ingest, the app inspects AnnData layers and obsm entries for counts, logcounts, scaled data, protein/ADT, spatial coordinates, and conversion provenance in uns['import_provenance'].
Analyze steps that depend on the expression matrix can use detected layers through the advanced Matrix source control. Counts-oriented workflows should use raw counts when available; clustering, annotation, DE, trajectory, and scoring workflows usually use log-normalized or normalized expression.
Upload formats
| Format | Extension | Conversion |
|---|---|---|
| AnnData | .h5ad | Direct ingest |
| Count matrix | .csv, .tsv | Import → processed .h5ad with automatic orientation detection |
| 10x Genomics HDF5 | .h5 | Import |
| 10x MTX bundle | .zip | Import (matrix + barcodes + genes, plus optional cell_metadata.csv and embedding_*.csv; see Seurat objects) |
| Raw droplet matrix (optional) | .h5, .zip | Added per dataset with Add raw droplet matrix; Cell Ranger's unfiltered raw_feature_bc_matrix, used by ambient RNA correction |
| Seurat / SingleCellExperiment / count matrix | .rds, .rda, .RData | Import (read in Python; see Seurat objects) |
| h5Seurat | .h5Seurat | Refused; save with saveRDS() and upload the .rds |
| Loom (velocyto) | .loom | Not a dataset: attach it to a dataset as Velocity counts (see below) |
CSV/10x conversion stores raw counts in layers['counts'] and attempts to restore sample / condition from sidecar metadata when present (for a zip, a cell_metadata.csv or obs_metadata.csv with a barcode column). CSV/TSV import defaults to automatic orientation detection; it records whether rows or columns were treated as genes in import provenance.
Gene identifiers
Enrichment and pathway tools expect gene symbols (for example HGNC for human). Ensembl IDs or custom prefixes may yield empty enrichment results. Dataset ingest now reports gene identifier quality warnings when identifiers look synthetic, duplicated, or unmapped. Demo fixtures use real HGNC symbols from bundled GO reference sets.
Spatial bundles
Full Visium output folders (H&E images, scale factors, JSON) are not yet ingested natively. Prepare a spatial .h5ad with coordinates in obsm['spatial'], or use the included Visium test fixture.
Export formats
| Output | Format |
|---|---|
| Report composer figure pages | PDF (client-side export at /report) |
| Individual chart panels (UMAP, volcano, WGCNA hub network, spatial map, etc.) | PNG (per-panel download button) |
| Result tables (DE, enrichment, WGCNA, coverage DEG, spatial, biomarker) | TSV download buttons on each result page |
| Standalone vector export (SVG) | Not yet available |
| Processed checkpoints | .h5ad on server disk (not user-downloadable in prototype) |
Size guidance
The prototype runs locally with datasets up to a few thousand cells comfortably. Large single-cell and spatial datasets will require cloud storage, lazy loading, and tiled imagery in production — see internal architecture docs.
Velocity counts (spliced / unspliced)
RNA velocity needs spliced and unspliced counts, which Cell Ranger's filtered matrix doesn't contain. After the dataset is imported, click Add velocity counts under it on the Data page and choose one of:
- a velocyto
.loomfile (velocyto run10xon the Cell Ranger BAM), withlayers/splicedandlayers/unspliced; - an
.h5adwithlayers['spliced']andlayers['unspliced'], from STARsolo (--soloFeatures Gene Velocyto), alevin-fry, or kb (--workflow lamanno/ USA mode).
Cells are matched to the dataset by barcode. velocyto's sample:BARCODEx and Cell Ranger's BARCODE-1 spellings are matched automatically. A barcode that appears in more than one sample of the velocity file is skipped, and the match rate is shown with the results. An .h5ad dataset that already has spliced and unspliced layers needs no extra file.