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 |
Bioconductor compatibility
Direct .rds / .rda import is not implemented yet. Export SingleCellExperiment, SpatialExperiment, or SummarizedExperiment objects to .h5ad first. 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 | Convert → processed .h5ad with automatic orientation detection |
| 10x Genomics HDF5 | .h5 | Convert |
| 10x MTX bundle | .zip | Convert (matrix + barcodes + genes) |
CSV/10x conversion stores raw counts in layers['counts'] and attempts to restore sample / condition from sidecar metadata when present. 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.