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