save#

SingleCell.save(filename, /, *, assay='RNA', X_key='counts', overwrite=False, preserve_strings=False, empty_X=False, v3=False, sce=False)[source]#

Save this SingleCell dataset to a file. File format will be inferred from the file extension (e.g. .h5ad).

Parameters:

  • filename: str | Path

    an AnnData .h5ad file, Seurat .rds or .h5Seurat file, SingleCellExperiment .rds file, or 10x .h5 or .mtx/.mtx.gz file to save to. If the extension is .rds, the sce argument will determine whether to save to a Seurat or a SingleCellExperiment object.

    • When saving to a Seurat .rds file, to match the requirements of Seurat objects, the ‘X_’ prefix (often used by Scanpy) will be removed from each key of obsm where it is present (e.g. ‘X_umap’ will become ‘umap’).

    • When saving to a Seurat .rds file, Seurat will add ‘orig.ident’, ‘nCount_RNA’ and ‘nFeature_RNA’ as gene-level metadata by default; you can disable the calculation of the latter two columns with:

      from ryp import r
r('options(Seurat.object.assay.calcn = FALSE)')

    • When saving to a Seurat .rds or .h5Seurat file or a SingleCellExperiment .rds file, varm will not be saved.

    • When saving to a 10x .h5 file, obs[‘barcodes’], var[‘feature_type’], var[‘genome’], var[‘id’], and var[‘name’] must all exist. Only X and these columns will be saved, along with whichever of var[‘pattern’], var[‘read’], and var[‘sequence’] exist. All of these columns (if they exist) must be String, Enum, or Categorical.

    • When saving to a 10x .mtx file, barcodes.tsv and features.tsv will be created in the same directory. Only X, obs and var will be saved.

    • When saving to a 10x .mtx.gz file, barcodes.tsv.gz and features.tsv.gz will be created in the same directory. Only X, obs and var will be saved.

  • assay: str

    when saving to a Seurat .rds or .h5Seurat file, the name to use for the active assay

  • X_key: str

    when saving to a Seurat .rds or .h5Seurat file, the name of the layer within the active assay to save X to; must be ‘counts’ or ‘data’. When saving to a SingleCellExperiment .rds file, the name of the layer within @assays@data to save X to.

  • overwrite: bool

    if False, raises an error if (any of) the file(s) exist; if True, overwrites them

  • preserve_strings: bool

    if False, encode string columns with duplicate values as Enums to save space, when saving to AnnData .h5ad or Seurat or SingleCellExperiment .rds; if True, preserve these columns as string columns. (Regardless of the value of preserve_strings, String columns with null values will be encoded as Enums when saving to .h5ad, since the .h5ad format cannot represent them otherwise.)

  • empty_X: bool

    if True, allow saving of SingleCell datasets with missing counts (i.e. where self.X is None), by saving an empty, dummy count matrix with no non-zero entries

  • v3: bool

    if True, use Seurat’s version 3 format instead of the more current version 5 format when saving to a Seurat .rds file. When v3=True, the Seurat object’s assay is created with CreateAssayObject() instead of CreateAssay5Object(). v3=True cannot be specified when saving to .h5Seurat, since .h5Seurat files do not support Seurat version 5 and so saving to .h5Seurat will always save to version 3.

  • sce: bool

    if True and the extension of filename is .rds, save to a SingleCellExperiment object instead of a Seurat object

Return type:

None

Examples

Save to an AnnData .h5ad file:

>>> sc.save('data.h5ad')

Overwrite an existing file:

>>> sc.save('data.h5ad', overwrite=True)

Save to a Seurat .h5Seurat file:

>>> sc.save('seurat_obj.h5Seurat')

Save to a Seurat .rds file:

>>> sc.save('seurat_obj.rds')

Save to a Seurat .rds file using the ‘data’ layer instead of ‘counts’:

>>> sc.save('seurat_obj.rds', X_key='data')

Save to a Seurat version 3 .rds file:

>>> sc.save('seurat_v3.rds', v3=True)

Save to a SingleCellExperiment .rds file:

>>> sc.save('sce_obj.rds', sce=True)

Save to a 10x Genomics .h5 file (requires obs to contain a ‘barcodes’ column and var to contain ‘feature_type’, ‘genome’, ‘id’, and ‘name’ columns):

>>> sc.save('matrix.h5')

Save to a 10x Genomics .mtx.gz file (creates barcodes.tsv.gz and features.tsv.gz in the same directory; unlike when saving to .h5, obs and var are not required to contain any specific columns):

>>> sc.save('matrix.mtx.gz')

Allow saving when X is missing by writing an empty count matrix:

>>> sc.save('empty.h5ad', empty_X=True)

Preserve string columns instead of encoding them as Enums:

>>> sc.save('data_preserve_strings.h5ad',
...         preserve_strings=True)
On this page