scatlastb_utils.pl.embedding

Contents

scatlastb_utils.pl.embedding#

scatlastb_utils.pl.embedding(adata, basis='X_umap', color=None, plot_centroids=None, bold_labels=None, category_order=None, na_strings=['NaN', 'None', '', 'nan', 'unknown'], min_cells_per_category=0, outlier_factor=0, gene_chunk_size=10, output_dir=None, title='', annotate_legend=True, dpi=200, n_jobs=1, figsize=(6, 6), downsample=None, adjust_text_kwargs=None, warn_on_drop=True, inplace=False, **kwargs)#

Plot a scanpy embedding for one or more colors with preprocessing and post-processing.

This wraps sc.pl.embedding with dataset cleaning, optional centroid placement and optional label-overlap resolution using adjustText.

Parameters:

  • adata – Annotated data matrix.

  • basis (str (default: 'X_umap')) – Key in adata.obsm for the embedding coordinates (e.g. "X_umap").

  • color (str | list | None (default: None)) – One or more adata.obs column names or gene names to color by.

  • plot_centroids (list | None (default: None)) – Subset of color values for which centroid labels are drawn on the embedding (sctk-style numbered circles).

  • bold_labels (list | None (default: None)) – List of category names to appear in bold in the legend.

  • category_order (object (default: None)) – Any iterable of strings for global order, or dict mapping {col_name: iterable of order}.

  • na_strings (str (default: ['NaN', 'None', '', 'nan', 'unknown'])) – For categorical or str columns, which strings to convert to NaN

  • min_cells_per_category (float (default: 0)) – Minimum number of cells required per category. Values in [0, 1) are interpreted as a fraction of the total cell count.

  • outlier_factor (float (default: 0)) – Cells whose embedding coordinate deviates more than this factor from the mean absolute value are removed. Set to 0 to disable.

  • gene_chunk_size (int (default: 10)) – Maximum number of genes rendered in a single gene-panel figure.

  • output_dir (Path | str | None (default: None)) – Directory where output PNG files are written. Set to None (default) to display figures interactively instead of saving.

  • title (str | bool (default: '')) – Prefix added to the figure suptitle (combined with the cell count).

  • annotate_legend (bool (default: True)) – Whether to append category counts to legend labels (e.g. “CD4+ T (n=123)”).

  • dpi (int (default: 200)) – Resolution used for both rendering and saving figures.

  • n_jobs (int (default: 1)) – Number of parallel threads for figure generation.

  • figsize (tuple (default: (6, 6))) – Tuple specifying figure size in inches, e.g. (8, 4) for wide aspect.

  • downsample (float | int | None (default: None)) – If float in (0, 1], randomly subsample that fraction of cells before plotting. If int > 1, randomly subsample up to that many cells. Default: None (no downsampling).

  • adjust_text_kwargs (dict | None (default: None)) – If provided, these keyword arguments will be forwarded to adjust_text (from the adjustText package) to resolve overlapping centroid labels placed by this function (when plot_centroids=True). Example keys include arrowprops (dict) and expand_text (tuple). Note: adjustText is a required dependency; import will fail with a clear error if it is not installed.

  • warn_on_drop (bool (default: True)) – If True, log warnings when colors are dropped due to invalidity or low category counts.

  • inplace (bool (default: False)) – If True, remove slots from adata inplace. This can be useful for scripts where the adata is not used afterwards, and memory footprint should be minimised to only what is essential for plotting.

  • **kwargs – Additional keyword arguments forwarded to _plot_color_axis and ultimately to sc.pl.embedding (e.g. legend_fontsize, ncols).

Examples

  • Automatic centroid placement + adjustment:

    embedding(
    adata,
    basis="X_umap",
    color="cluster_number",
    plot_centroids=True,
    adjust_text_kwargs={
        "arrowprops": {"arrowstyle": "->", "color": "black", "lw": 0.5},
        "expand_text": (1.05, 1.2),
    },
)
Contents