scparadise.scnoah.balance

Contents

scparadise.scnoah.balance#

scparadise.scnoah.balance(adata, celltype_keys, target_per_class=None, min_keep_frac=0.5, max_oversample_factor=7.0, min_oversample_cells=5, random_state=0)[source]#

Balance cell types by undersampling large classes and oversampling small classes with PCA-based synthetic-cell interpolation.

The class definition is based on the most granular annotation level among celltype_keys.

Parameters:

  • adata (anndata.AnnData) – Input AnnData object.

  • celltype_keys (list[str]) – Candidate annotation columns in adata.obs. The column with the largest number of unique non-null categories is used for balancing.

  • target_per_class (int or None (default = None)) – Common target number of cells per cell type. If None, the rounded mean number of cells per non-null class in the selected annotation level is computed from the original input AnnData.

  • min_keep_frac (float (default = 0.5)) – Minimum fraction retained from each large class during undersampling. Must be in (0, 1].

  • max_oversample_factor (float (default = 7.0)) – Maximum final size of a small class relative to its original size during oversampling. Must be at least 1.

  • min_oversample_cells (int (default = 5)) – For classes smaller than this threshold, oversampling is capped at this final class size, subject to other limits.

  • random_state (int or None (default = 0)) – Random seed used in undersampling and synthetic cell generation.

Returns:

Balanced in-memory AnnData object. Its .obs contains is_synthetic and source_obs_name, added by oversample().

Return type:

anndata.AnnData

Notes

The output does not preserve cell-level embeddings, neighbor graphs, or layers unless your oversample() has been explicitly extended to generate and validate them for synthetic cells.

Contents