Convert between formats

Inspect a file, convert it, and check the result, from the command line, Python and R.

This page takes one small H5Seurat file, looks inside it, converts it to AnnData .h5ad, and checks the result. Each step is shown three ways: with the scx command line, with the Python package and with the R package. All three call the same engine, so they detect the same formats and use the same defaults.

The example file, tiny_v4.h5seurat, is a 6-cell by 5-gene dataset from the SCX test fixtures. The second cell has no counts and two genes are each expressed in a single cell, so empty cells and sparse genes are part of the example.

Look before converting

inspect reads only metadata: the format, the shape, the column names and the embedding keys. The count matrix is not loaded, whatever the file size.

scx inspect tiny_v4.h5seurat
File   : tiny_v4.h5seurat
Format : H5Seurat
Shape  : 6 obs × 5 vars
X dtype: float64
X      : nnz=9  sparse=70.0%  nnz/cell Q1=1  med=2  Q3=2  max=2

obs (7 columns):
  cell_type                      categorical  — 3 levels [B, NK, T]
  batch                          int32  — min=0  Q1=0  med=1  Q3=2  max=2
  flag                           bool
  score                          float64  — min=-2  Q1=0  med=0.5  Q3=1.5  max=3.25  (1 missing)
  is_doublet                     bool
  donor                          categorical  — 2 levels [d0, d1]
  n_counts                       float64  — min=0  Q1=3  med=7  Q3=11  max=17

var (0 columns):
  (none)

obsm (1 keys):
  X_pca                          (6, 2)

varm (0 keys):
  (none)

layers (1 keys):
  data                           6 × 5  nnz=9  sparse=70.0%  nnz/cell Q1=1  med=2  Q3=2  max=2

obsp (0 keys):
  (none)

provenance
  (none)

uns (0 keys):
  (none)
import picklerick as pk

info = pk.inspect("tiny_v4.h5seurat")
{key: info[key] for key in ("format", "n_obs", "n_vars", "obs_cols")}
{'format': 'H5Seurat',
 'n_obs': 6,
 'n_vars': 5,
 'obs_cols': ['cell_type',
  'batch',
  'flag',
  'score',
  'is_doublet',
  'donor',
  'n_counts']}
library(picklerick)

info <- inspect("tiny_v4.h5seurat")
info[c("format", "n_obs", "n_vars", "obs_cols")]
$format
[1] "H5Seurat"

$n_obs
[1] 6

$n_vars
[1] 5

$obs_cols
[1] "cell_type"  "batch"      "flag"       "score"      "is_doublet"
[6] "donor"      "n_counts"  

Convert

The input format is detected from the file’s content; the output format is chosen by the extension of the output path. The matrix is streamed in chunks of 5000 cells by default, so peak memory does not grow with the number of cells.

scx convert tiny_v4.h5seurat tiny_cli.h5ad
2026-11-21T13:51:22.424121Z  INFO scx: starting conversion output=.partial-tiny_cli.h5ad n_obs=6 n_vars=5 dtype=float32 format="h5ad" bpcells=false dgcmatrix=false x_slot="X"
2026-11-21T13:51:22.424187Z  INFO scx: metadata loaded in 3.62ms obs_cols=7 var_cols=0 layers=1 obsp=0
2026-11-21T13:51:22.431216Z  INFO scx: read obsm, varm embeddings=1 varm=0
2026-11-21T13:51:22.431685Z  INFO scx: streaming layer name=data shape=(6, 5)
2026-11-21T13:51:22.436932Z  INFO scx: matrix streamed in 1.78ms n_chunks=1 total_nnz=9 throughput_cells_s=3364
2026-11-21T13:51:22.438460Z  INFO scx_core::h5ad::writer: h5ad finalized n_obs=6 n_vars=5 nnz=9
2026-11-21T13:51:22.438852Z  INFO scx: conversion complete total=18.282056ms output=.partial-tiny_cli.h5ad
pk.convert("tiny_v4.h5seurat", "tiny_py.h5ad")
PosixPath('tiny_py.h5ad')
convert("tiny_v4.h5seurat", "tiny_r.h5ad")

Check the result

The converted file has the same shape and cell metadata as the source.

scx inspect tiny_cli.h5ad
File   : tiny_cli.h5ad
Format : H5AD
Shape  : 6 obs × 5 vars
X dtype: float32
X      : nnz=9  sparse=70.0%  nnz/cell Q1=1  med=2  Q3=2  max=2

obs (7 columns):
  cell_type                      categorical  — 3 levels [B, NK, T]
  batch                          int32  — min=0  Q1=0  med=1  Q3=2  max=2
  flag                           bool
  score                          float64  — min=-2  Q1=0  med=0.5  Q3=1.5  max=3.25  (1 missing)
  is_doublet                     bool
  donor                          categorical  — 2 levels [d0, d1]
  n_counts                       float64  — min=0  Q1=3  med=7  Q3=11  max=17

var (0 columns):
  (none)

obsm (1 keys):
  X_pca                          (6, 2)

varm (0 keys):
  (none)

layers (1 keys):
  data                           6 × 5  nnz=9  sparse=70.0%  nnz/cell Q1=1  med=2  Q3=2  max=2

obsp (0 keys):
  (none)

provenance
  scx_version      0.6.2
  source.path      tiny_v4.h5seurat
  source.hash      blake3:91aa0b36f3084b66853c1c3b0636b35b8ef35958ea0b1b125b6d16e6fea0c16b

uns (0 keys):
import anndata as ad

ad.read_h5ad("tiny_py.h5ad")
AnnData object with n_obs × n_vars = 6 × 5
    obs: 'cell_type', 'batch', 'flag', 'score', 'is_doublet', 'donor', 'n_counts'
    obsm: 'X_pca'
    layers: 'data', None (.X)
sce <- read_h5ad("tiny_r.h5ad")
sce
class: SingleCellExperiment 
dim: 5 6 
metadata(1): .uns_path
assays(2): counts data
rownames(5): gene0 gene1 gene2 gene3 gene4
rowData names(0):
colnames(6): cell0 cell1 ... cell4 cell5
colData names(7): cell_type batch ... donor n_counts
reducedDimNames(1): X_pca
mainExpName: NULL
altExpNames(0):

inspect shows shapes and names. scx diff compares the data: it reads both files, in any formats SCX reads, and reports slot by slot whether the values survived. Matrices are streamed, so it also works on atlas-sized files.

scx diff tiny_v4.h5seurat tiny_cli.h5ad
SAME    shape                6 x 5
SAME    obs index            6 names, same order
SAME    var index            5 names, same order
SAME    obs columns          7 same, 0 different, 0 only in A, 0 only in B
SAME    var columns          0 same, 0 different, 0 only in A, 0 only in B
SAME    obsm/X_pca           6 x 2, max abs diff 0
SAME    uns                  0 keys
SAME    X                    9 nnz, max abs diff 0
SAME    layers/data          9 nnz, max abs diff 0

All 9 slots the same.

Each slot is SAME, DIFF, ONLY A or ONLY B, or SKIPPED when it can’t be compared. Floats are equal within --rtol (default 1e-6, so an f64 to f32 conversion passes); --exact turns the tolerance off. What a conversion legitimately changes, such as a storage dtype or the order of categorical levels, is printed as a NOTE and is not a difference. --only X,obs limits the comparison to some slots, --map X=layers/data pairs matrices stored under different names, and --json prints the report for a script. diff exits 0 when everything compared is the same and 1 when something differs or was skipped, so a pipeline can stop on a lossy conversion. It is in the command line only; the full rules are in docs/diff.md.

Convert a subset of cells

--where writes only the cells whose obs matches, without reading the whole file into memory first: the matrix still streams in chunks. Give it column=value; repeat it to accept more values of a column (they OR together) or to filter on more columns (they AND together). Values are compared as text, booleans as True/False, and missing values never match. Python and R take the same filter as a dict or a named list.

scx convert tiny_v4.h5seurat tcells_cli.h5ad --where cell_type=T
scx inspect tcells_cli.h5ad
2026-11-21T13:51:24.249238Z  INFO scx: --where keeps 2 cells n_obs=2
2026-11-21T13:51:24.251120Z  INFO scx: starting conversion output=.partial-tcells_cli.h5ad n_obs=2 n_vars=5 dtype=float32 format="h5ad" bpcells=false dgcmatrix=false x_slot="X"
2026-11-21T13:51:24.251146Z  INFO scx: metadata loaded in 1.81ms obs_cols=7 var_cols=0 layers=1 obsp=0
2026-11-21T13:51:24.257285Z  INFO scx: read obsm, varm embeddings=1 varm=0
2026-11-21T13:51:24.257741Z  INFO scx: streaming layer name=data shape=(2, 5)
2026-11-21T13:51:24.262573Z  INFO scx: matrix streamed in 1.51ms n_chunks=1 total_nnz=2 throughput_cells_s=1321
2026-11-21T13:51:24.264384Z  INFO scx_core::h5ad::writer: h5ad finalized n_obs=2 n_vars=5 nnz=2
2026-11-21T13:51:24.264786Z  INFO scx: conversion complete total=15.446956ms output=.partial-tcells_cli.h5ad
File   : tcells_cli.h5ad
Format : H5AD
Shape  : 2 obs × 5 vars
X dtype: float32
X      : nnz=2  sparse=80.0%  nnz/cell Q1=0  med=2  Q3=2  max=2

obs (7 columns):
  cell_type                      categorical  — 3 levels [B, NK, T]
  batch                          int32  — bool-like  0: 2 (100.0%)  1: 0 (0.0%)
  flag                           bool
  score                          float64  — min=1.5  Q1=1.5  med=3.25  Q3=3.25  max=3.25
  is_doublet                     bool
  donor                          categorical  — 2 levels [d0, d1]
  n_counts                       float64  — min=0  Q1=0  med=17  Q3=17  max=17

var (0 columns):
  (none)

obsm (1 keys):
  X_pca                          (2, 2)

varm (0 keys):
  (none)

layers (1 keys):
  data                           2 × 5  nnz=2  sparse=80.0%  nnz/cell Q1=0  med=2  Q3=2  max=2

obsp (0 keys):
  (none)

provenance
  scx_version      0.6.2
  source.path      tiny_v4.h5seurat
  source.hash      blake3:91aa0b36f3084b66853c1c3b0636b35b8ef35958ea0b1b125b6d16e6fea0c16b

uns (0 keys):
pk.convert("tiny_v4.h5seurat", "tcells_py.h5ad", where={"cell_type": "T"})
ad.read_h5ad("tcells_py.h5ad").obs[["cell_type", "donor"]]
"tiny_v4.h5seurat" |> convert("tcells_r.h5ad", where = list(cell_type = "T"))
colnames(read_h5ad("tcells_r.h5ad"))
[1] "cell1" "cell5"

The output holds the matching cells in X, every layer, raw counts, obs and obsm. Cell-by-cell graphs in obsp keep only the rows and columns of those cells, renumbered. Genes (var, varm) and uns are copied unchanged. A filter that matches nothing writes a valid file with no cells; a column that obs doesn’t have is an error that lists the columns it has.

On .h5ad, Zarr, dgCMatrix H5Seurat and 10x HDF5 input only the matching cells of the matrix are read. BPCells and MatrixMarket input can’t read a range of cells on its own, so it is read through and the other cells are dropped as they pass: the same output, at the cost of a full read. The values follow the shell’s quoting rules, so quote one that has spaces: --where "cell_type=CD4 T". Everything up to the first = is the column name.

Provenance

scx convert records where its output came from, in two places. The provenance section of scx inspect tiny_cli.h5ad above is the first: a block in uns["scx_provenance"] with the SCX version and the source file’s path and hash (BLAKE3 by default). It depends only on the input, so it is the same every time that input is converted.

The second is a sidecar file next to the output, which adds what is particular to one run: when the conversion ran, and the output’s hash and shape.

cat tiny_cli.h5ad.prov.json
{
  "scx_version": "0.6.2",
  "converted_at": "2026-11-21T13:51:22Z",
  "source": {
    "path": "tiny_v4.h5seurat",
    "hash": "blake3:91aa0b36f3084b66853c1c3b0636b35b8ef35958ea0b1b125b6d16e6fea0c16b"
  },
  "output": {
    "path": "tiny_cli.h5ad",
    "hash": "blake3:bc249b3f150a5c0aef730cb29f351e83241bebe91825b8c88be46341f01cbd99",
    "n_obs": 6,
    "n_vars": 5
  }
}

A conversion with --where adds the filter to both records, as "where": {"cell_type": ["T"]}.

In a pipeline that downloads its input, --source-url adds the origin URL to both records. --source-hash sha256 records the SHA-256 that repositories publish instead of BLAKE3, and --source-sha256 passes in a hash the downloader already computed, so SCX doesn’t hash the source itself.

Provenance is written by the command line only: convert() in Python and R writes neither the block nor the sidecar. The record formats are described in docs/provenance.md.

Options shared by all three

Option CLI Python R Default
Cells per streamed chunk --chunk-size chunk_size= chunk_size = 5000
Output matrix type --dtype dtype= dtype = f32
Seurat assay (H5Seurat input) or MuData modality (.h5mu) to read --assay assay= assay = RNA; for .h5mu the only modality, else rna
Seurat layer to read (H5Seurat input) --layer layer= layer = counts
Keep only matching cells --where col=value where={"col": v} where = list(col = v) every cell

The full lists are in each reference: scx convert --help, picklerick.convert and ?picklerick::convert.