scparadise.scnoah.oversample#
- scparadise.scnoah.oversample(adata, celltype_keys, target_per_class=None, max_oversample_factor=7.0, min_oversample_cells=5, random_state=0)[source]#
Oversample underrepresented cell types in an AnnData object using PCA-based interpolation.
Synthetic cells are generated only for classes below target_per_class. The generated cells are appended to the original expression matrix.
- Parameters:
adata (anndata.AnnData) – Input AnnData object. Uses adata.X as the expression matrix. Both sparse and dense matrices are supported.
celltype_keys (list[str]) – Names of annotation columns in adata.obs. The column containing the largest number of unique non-null annotations is selected as the target cell-type level for balancing.
target_per_class (int or None (default = None)) – Target number of cells per cell type. If None, uses the rounded mean number of cells per cell type in the most granular annotation level.
max_oversample_factor (float (default = 7.0)) – Maximum allowed final size of a cell type relative to its original size. For a class with n cells, its final size cannot exceed floor(max_oversample_factor * n).
min_oversample_cells (int (default = 5)) – Classes smaller than this threshold are only expanded up to this threshold, subject to target_per_class and max_oversample_factor. This prevents aggressive generation from extremely rare classes.
random_state (int or None (default = 0)) – Random seed for synthetic-cell generation and metadata bootstrap sampling. Set to None for non-deterministic output.
- Returns:
An in-memory AnnData object containing original and synthetic cells.
Synthetic cells are identified by: - adata.obs[“is_synthetic”] == True - adata.obs[“source_obs_name”], which stores the original cell name
whose metadata were bootstrapped.
The output preserves var and shallow-copies uns. Cell-level embeddings, graphs, layers, raw data, and pairwise matrices are not copied because they are not valid for newly generated cells.
- Return type:
anndata.AnnData