scdecon.signature¶

signature ¶

Signature construction: marker selection and signature-matrix assembly.

This layer operates purely on in-memory AnnData objects and pandas structures; it performs no file I/O of its own (saving is the caller's responsibility via :mod:scdecon.io).

MarkerSelector ¶

Bases: ABC

Abstract strategy for selecting cell-type marker genes.

select `abstractmethod` ¶

select(adata: AnnData, config: SignatureConfig) -> MarkerSet

Return specific marker genes per cell type.

MarkerSet `dataclass` ¶

MarkerSet(per_type: Mapping[str, tuple[str, ...]])

Type-specific marker genes, one ordered tuple per cell type.

genes ¶

genes() -> list[str]

Return the deduplicated marker genes in deterministic order.

Genes are grouped by sorted cell type and kept in rank order within a type; this is the row order of the signature matrix.

to_frame ¶

to_frame() -> pd.DataFrame

Return a tidy, serialisable table with columns cell_type, gene, rank.

RankGenesGroupsSelector ¶

Bases: MarkerSelector

Marker selection via Scanpy rank_genes_groups + specificity filter.

RankMethod ¶

Bases: StrEnum

Differential-expression method for Scanpy rank_genes_groups.

StrEnum members are plain strings, so they pass directly to Scanpy and serialise as their value (e.g. "wilcoxon").

SignatureConfig `dataclass` ¶

SignatureConfig(cell_type_key: str = 'cell_type', n_markers_per_type: int = 25, method: RankMethod = RankMethod.WILCOXON, min_cells_per_type: int = 2)

Immutable configuration for marker selection and signature construction.

Attributes:

Name	Type	Description
`cell_type_key`	`str`	Column in `adata.obs` holding the cell-type annotation to group by.
`n_markers_per_type`	`int`	Number of top-ranked marker genes to take per cell type before the cross-type specificity filter.
`method`	`RankMethod`	Differential-expression ranking method (:class:`RankMethod`).
`min_cells_per_type`	`int`	Minimum number of cells a cell type must have; below this, ranking is unreliable and selection fails loudly.

__post_init__ ¶

__post_init__() -> None

Validate parameters, failing loudly on nonsensical values.

build_signature ¶

build_signature(adata: AnnData, markers: MarkerSet, config: SignatureConfig) -> pd.DataFrame

Build a signature matrix of linear-scale mean profiles.

The signature frame obeys this contract:

index = the marker genes, in exactly markers.genes() order. This ordering is part of the public contract and is reproducible.
columns = the reference cell types, sorted deterministically.
values = per-cell-type mean of expm1(adata.X) over the marker genes (linear scale); finite and non-negative.

Parameters:

Name	Type	Description	Default
`adata`	`AnnData`	Log-normalised reference data (as produced by :mod:`scdecon.preprocessing`). Not modified.	required
`markers`	`MarkerSet`	Marker genes per cell type; `markers.genes()` sets the row order.	required
`config`	`SignatureConfig`	Supplies `cell_type_key` (the `obs` column to group cells by).	required

Returns:

Type	Description
`DataFrame`	Genes (index, `markers.genes()` order) by cell types (sorted columns), holding linear-scale mean expression.

Raises:

Type	Description
`ValueError`	If `cell_type_key` is absent, `adata.var_names` has duplicates, a marker gene is missing from `adata`, `markers` references a cell type absent from `adata`, or the resulting matrix violates the frame contract.

select_markers ¶

select_markers(adata: AnnData, config: SignatureConfig, selector: MarkerSelector | None = None) -> MarkerSet

Select cell-type markers using selector.