data-io-loading
OmicVerse data I/O: use ov.read(), ov.io.read_h5ad, read_10x_h5, read_10x_mtx, read_visium, read_visium_hd, read_nanostring instead of scanpy. Covers h5ad, 10x, spatial, CSV formats.
omicverse · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add omicverse/omicclaw --skill data-io-loadingAbout this skill
name: data-io-loading title: OmicVerse data I/O description: "OmicVerse data I/O: use ov.read(), ov.io.read_h5ad, read_10x_h5, read_10x_mtx, read_visium, read_visium_hd, read_nanostring instead of scanpy. Covers h5ad, 10x, spatial, CSV formats."
OmicVerse Data I/O
OmicVerse provides its own data readers under ov.io. These replace scanpy's IO functions with better format handling, spatial geometry support, and Rust backend options. When working in an OmicVerse project, always use ov.io.* for data loading — never fall back to sc.read_* or scanpy.read_*.
Why this matters
OmicVerse's readers are not thin wrappers — they are independent implementations that handle edge cases scanpy misses:
- 10x H5/MTX: Proper v2/v3 format detection, flexible prefix/compression options
- Visium: Auto-resolves tissue positions (parquet > csv > legacy csv), loads images + scale factors
- Visium HD: Cell segmentation with GeoJSON→WKT polygon conversion (not available in scanpy at all)
- Nanostring SMI: Auto-detects column names across CosMx format variants (not in scanpy)
Migration table: scanpy → OmicVerse
| Task | DON'T use | Use instead |
|---|---|---|
| Read any file | sc.read(path) | ov.read(path) |
| Read h5ad | sc.read_h5ad(f) | ov.read(f) or ov.io.read_h5ad(f) |
| Read 10x H5 | sc.read_10x_h5(f) | ov.io.read_10x_h5(f) |
| Read 10x MTX dir | sc.read_10x_mtx(d) | ov.io.read_10x_mtx(d) |
| Read Visium | sc.read_visium(d) | ov.io.spatial.read_visium(d) |
| Read Visium HD | (not available) | ov.io.read_visium_hd(d) |
| Read Nanostring | (not available) | ov.io.read_nanostring(d, counts, meta) |
| Read CSV/TSV | pd.read_csv(f) | ov.read(f) or ov.io.read_csv(f) |
| Save Python object | pickle.dump(...) | ov.io.save(obj, path) |
| Load Python object | pickle.load(...) | ov.io.load(path) |
Access paths
ov.read(path) # Top-level universal reader (lazy attr)
ov.io.read_h5ad(filename) # h5ad
ov.io.read_10x_h5(filename) # 10x Genomics H5
ov.io.read_10x_mtx(path) # 10x Matrix Market directory
ov.io.spatial.read_visium(path) # Visium (standard Space Ranger)
ov.io.read_visium_hd(path) # Visium HD (auto-detect bin vs seg)
ov.io.read_visium_hd_bin(path) # Visium HD bin-level
ov.io.read_visium_hd_seg(path) # Visium HD cell segmentation
ov.io.read_nanostring(path, ...) # Nanostring SMI / CosMx
ov.io.read_csv(**kwargs) # CSV/TSV wrapper
ov.io.save(obj, path) # Pickle serialization
ov.io.load(path) # Pickle deserialization
Note: read_visium (standard) is under ov.io.spatial, not directly under ov.io. All other readers are at ov.io level.
Universal reader: ov.read(path, backend='python')
Auto-detects format by file extension and returns the appropriate object:
| Extension | Returns | Backend |
|---|---|---|
.h5ad | AnnData | Python (anndata) or Rust (snapatac2) |
.csv | DataFrame | pandas |
.tsv, .txt | DataFrame | pandas (tab-separated) |
.csv.gz, .tsv.gz, .txt.gz | DataFrame | pandas (gzip) |
import omicverse as ov
# h5ad → AnnData
adata = ov.read('pbmc3k.h5ad')
# CSV → DataFrame
df = ov.read('counts.csv')
# Gzipped TSV → DataFrame
df = ov.read('metadata.tsv.gz')
# Rust backend for large h5ad files (requires snapatac2)
adata = ov.read('large_dataset.h5ad', backend='rust')
# Remember: call adata.close() when done with Rust backend
Single-cell readers
ov.io.read_h5ad(filename, **kwargs)
Direct h5ad reader. All kwargs forwarded to anndata.read_h5ad().
adata = ov.io.read_h5ad('sample.h5ad')
adata = ov.io.read_h5ad('large.h5ad', backed='r') # Backed mode for large files
ov.io.read_10x_h5(filename, *, genome=None, gex_only=True)
Read 10x Genomics HDF5 count matrices. Handles both legacy (v2) and v3+ formats automatically.
adata = ov.io.read_10x_h5('filtered_feature_bc_matrix.h5')
# Multi-genome file: filter by genome
adata = ov.io.read_10x_h5('raw_feature_bc_matrix.h5', genome='GRCh38')
# Keep all feature types (Gene Expression + Antibody Capture + CRISPR Guide)
adata = ov.io.read_10x_h5('filtered_feature_bc_matrix.h5', gex_only=False)
ov.io.read_10x_mtx(path, *, var_names='gene_symbols', make_unique=True, gex_only=True, prefix=None, compressed=True)
Read 10x Matrix Market directory (contains matrix.mtx, features.tsv/genes.tsv, barcodes.tsv).
adata = ov.io.read_10x_mtx('filtered_feature_bc_matrix/')
# Use Ensembl gene IDs instead of symbols
adata = ov.io.read_10x_mtx('filtered_feature_bc_matrix/', var_names='gene_ids')
# STARsolo output (uncompressed files)
adata = ov.io.read_10x_mtx('Solo.out/Gene/filtered/', compressed=False)
Spatial readers
ov.io.spatial.read_visium(path, *, count_file='filtered_feature_bc_matrix.h5', library_id=None, load_images=True, ...)
Read standard 10x Visium Space Ranger output. Loads count matrix, tissue positions, images, and scale factors.
adata = ov.io.spatial.read_visium('spaceranger_output/outs/')
# Use raw counts
adata = ov.io.spatial.read_visium('outs/', count_file='raw_feature_bc_matrix.h5')
# Skip image loading (faster, less memory)
adata = ov.io.spatial.read_visium('outs/', load_images=False)
Output structure:
adata.obsm['spatial']— spot pixel coordinatesadata.uns['spatial'][library_id]['images']— hires/lowres imagesadata.uns['spatial'][library_id]['scalefactors']— scale factorsadata.obs['in_tissue'],array_row,array_col— tissue position metadata
ov.io.read_visium_hd(path, ...) / read_visium_hd_bin / read_visium_hd_seg
Read Visium HD data. The unified read_visium_hd auto-detects bin vs segmentation format.
# Auto-detect
adata = ov.io.read_visium_hd('spaceranger_hd_output/ou
Read the complete source ↗