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.
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.
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.
"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.
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.