Convert a single-cell file to another format

Description

Streams the input file through the SCX engine and writes the result to output. No R objects are constructed; memory usage is bounded by chunk_size regardless of dataset size.

Usage

convert(
  input,
  output,
  chunk_size = 5000L,
  dtype = "f32",
  assay = NULL,
  layer = "counts",
  where = NULL
)

Arguments

input Path to the input file or directory.
output Path to the output: .h5ad, .h5seurat or .zarr.
chunk_size Number of cells per streaming chunk. Default 5000L.
dtype Output numeric type: "f32", "f64", "i32", or "u32". Default "f32".
assay Seurat assay to convert. Default NULL: "RNA" for H5Seurat input, the object’s active assay for a Seurat .rds; for MuData .h5mu input, the modality (the only one, else "rna"). Also the assay name of H5Seurat output ("RNA" when NULL).
layer Seurat layer to convert (H5Seurat inputs only). Default "counts".
where Keep only some cells: a named list mapping obs columns to the values they may take, e.g. list(cell_type = c("B", "T"), donor = "d1"). A cell is kept when every column holds one of its values. Values are compared as text (TRUE/FALSE match Python’s True/False); NA never matches. X, layers, raw counts, obs and obsm keep the matching cells, and obsp graphs those cells on both axes; genes and uns are unchanged. The matrix still streams: h5ad, Zarr, dgCMatrix H5Seurat and 10x HDF5 inputs read only the matching rows, others read everything and drop the rest. No match writes a file with 0 cells; an unknown column is an error. Default NULL: every cell.

Details

The input format is detected from the content: AnnData .h5ad, AnnData Zarr stores, H5Seurat, 10x HDF5, 10x MatrixMarket directories, BPCells directories. The output format is chosen by the extension of output: .h5ad, .h5seurat (SeuratDisk dgCMatrix layout) or .zarr (AnnData Zarr v3 store, a directory).

Value

output path, invisibly.

Examples

convert("pbmc3k.h5seurat", "pbmc3k.h5ad")
convert("pbmc3k.h5ad", "pbmc3k.zarr")
convert("pbmc3k.h5seurat", "pbmc3k_f64.h5ad", dtype = "f64", chunk_size = 2000L)
"atlas.h5ad" |> convert("tcells.h5ad", where = list(cell_type = "T cell"))