sc_tools.utils — Utilities#

General-purpose helpers for signature score retrieval and versioned file paths.

from sc_tools.utils.signatures import get_signature_columns, get_signature_df

cols = get_signature_columns(adata)
score_df = get_signature_df(adata)

Signature Helpers#

sc_tools.utils.get_signature_columns(adata, prefix='sig:', suffix='_z')[source]#

Get all signature column names. Prefer obsm[‘signature_score_z’] if present; else obs columns.

Parameters:

  • adata (AnnData) – Annotated data object

  • prefix (str) – Prefix for obs-based signature columns (default: ‘sig:’)

  • suffix (str) – Suffix for obs-based signature columns (default: ‘_z’)

Returns:

List of signature column names (obsm full-path or obs sig:…_z)

Return type:

list of str

sc_tools.utils.filter_signatures(signature_list, include=None, exclude=None)[source]#

Filter signatures based on include/exclude criteria.

Parameters:

  • signature_list (list) – List of signature column names (e.g., ‘sig:Tumor_Cells-EMT_Tumor_z’)

  • include (list or None) – List of signatures to include. Can be: - Exact matches (with or without ‘sig:’ prefix and ‘_z’ suffix) - Patterns (substring search, case-insensitive) - None to include all

  • exclude (list or None) – List of signatures to exclude. Same format as include. - None to exclude none

Returns:

Filtered list of signatures

Return type:

list

sc_tools.utils.clean_sig_name(sig, max_length=40)[source]#

Clean signature name for display.

Parameters:

  • sig (str) – Signature name (e.g., ‘sig:Tumor_Cells/EMT_Tumor_z’)

  • max_length (int) – Maximum length for truncated names (default: 40)

Returns:

Cleaned signature name

Return type:

str

Versioned Save Paths#

sc_tools.utils.get_version_prefix(dt=None)[source]#

Return a version prefix string for filenames: YYDDMM.hh.mm.

Parameters:

dt (datetime, optional) – Use this datetime; if None, uses now().

Returns:

e.g. “250208.14.30” for 2025-02-08 14:30

Return type:

str

sc_tools.utils.versioned_filename(basename, ext, dt=None)[source]#

Build a versioned filename: YYDDMM.hh.mm.basename.ext (no path).

Parameters:

  • basename (str) – Base name (no extension), e.g. “volcano_faceted”

  • ext (str) – Extension without dot, e.g. “pdf” or “png”

  • dt (datetime, optional) – Use this datetime; if None, uses now().

Returns:

e.g. “250208.14.30.volcano_faceted.pdf”

Return type:

str

sc_tools.utils.versioned_path(base_dir, basename, ext, subdir=None, dt=None)[source]#

Build full path for a versioned file, optionally under a subdir (e.g. pdf/, png/).

Parameters:

  • base_dir (str or Path) – Root output directory (e.g. figures/process_colocalization)

  • basename (str) – Base name (no extension)

  • ext (str) – Extension without dot (e.g. “pdf”, “png”)

  • subdir (str, optional) – Subdirectory under base_dir (e.g. “pdf”, “png”). Created if missing.

  • dt (datetime, optional) – Use this datetime; if None, uses now().

Returns:

e.g. base_dir/pdf/250208.14.30.volcano_faceted.pdf

Return type:

Path