Convert: 10x HDF5 (Cell Ranger *_feature_bc_matrix.h5), import and export #23

Part of #20. Depends on #21. Equivalent of scanpy.read_10x_h5.

Import

v3 layout (Cell Ranger ≥ 3): /matrix/{data,indices,indptr,shape,barcodes} and /matrix/features/{id,name,feature_type,genome}.
The stored matrix is genes × cells in CSC — byte-for-byte the same as cells × genes in CSR — so data/indices/indptr copy straight across with no transpose.

v2 layout: /<genome>/{data,indices,indptr,shape,barcodes,genes,gene_names}. Select with --genome (error listing the available genomes if ambiguous).

Mapping

• obs_names ← barcodes
• var gets gene_ids, feature_types, genome (same column names as scanpy)
• var_names ← name or id via --var-names gene_symbols|gene_ids; --make-unique

Feature types (multiome Peaks, Antibody Capture, CRISPR Guide Capture, …):

• --feature-type "Gene Expression" keeps only that type
• --split-feature-types writes one output per type (out.<type>.h5ad)

Streaming: copy_dataset for data/indices; when --feature-type drops features, go through the streaming column-subset path in core/subset.py.

Export

h5ad → 10x v3 h5, as input for CellBender, SoupX, DropletUtils and other tools that expect Cell Ranger output.

• CSR cells × genes is written directly as CSC genes × cells (CSC input goes through transpose_sparse_streaming).
• var needs gene ids / names / feature types: take them from --gene-ids-column etc., refuse if missing unless --force (placeholders).
• Warn when the matrix is not integer counts; --layer to pick another matrix.

Tests

• h5py fixtures for v2 and v3, including a multi-feature-type file.
• Compare with scanpy.read_10x_h5 (uv run --with scanpy, integration marker).
• Round trip h5ad → 10x h5 → h5ad.