The supervised (sp) accessor

The supervised (sp) accessor#

The supervised metrics accessor provides metrics to compare the spatial single cell expression profiles to those from a single-cell RNA sequencing dataset.

segtraq.sp.supervised.marker_purity(sdata, cell_type_key: str, markers: dict[str, dict[str, list[str]]], tables_key: str = 'table', tables_raw_counts_layer: str | None = None, tables_cell_id_key: str = 'cell_id', tables_centroid_x_key: str = 'x_centroid', tables_centroid_y_key: str = 'y_centroid', tables_gene_key: str | None = None, require_neighbor_expression: bool = True, neighbors_key: str = 'spatial_connectivities', inplace: bool = True) → DataFrame#

Compute per-cell marker purity using balanced accuracy.

For each cell of type c:

  • positive markers of c are expected to be expressed

  • relevant negative markers are negative markers of c that are also positive markers of neighboring cell types

The score combines:

  • positive_marker_recall: fraction of expected positive markers expressed (analogous to recall/sensitivity at the marker-level)

  • negative_marker_avoidance: fraction of relevant negative markers avoided (analogous to specificity at the marker-level)

  • marker_balanced_accuracy: mean of sensitivity and specificity

Parameters:

  • sdata (SpatialData-like) – Must contain tables[tables_key] as an AnnData with expression and .obs metadata.

  • cell_type_key (str) – Column in the AnnData .obs with cell-type labels.

  • markers (dict) – A dictionary mapping cell types to their positive and negative markers, in the format {cell_type: {“positive”: list[str], “negative”: list[str]}}.

  • tables_key (str, optional, default="table") – Key of the AnnData table in sdata.tables.

  • tables_raw_counts_layer (str | None, optional) – Layer containing count data. If None, adata.X is used if it looks like counts. If a layer is specified, it must exist and contain count-like values.

  • tables_cell_id_key (str, optional, default="cell_id") – Column in the AnnData .obs with unique cell IDs.

  • tables_centroid_x_key (str or None, optional, default="x_centroid") – Column in the cell table with the x-coordinate of the cell centroid.

  • tables_centroid_y_key (str or None, optional, default="y_centroid") – Column in the cell table with the y-coordinate of the cell centroid.

  • tables_gene_key (str or None, default=None) – Column in sdata.tables[tables_key].var containing gene identifiers. If None, sdata.tables[tables_key].var_names are used.

  • require_neighbor_expression (bool, optional, default=True) – If True, contamination is only counted when the relevant gene is expressed in at least one neighboring cell of the source type.

  • neighbors_key (str, optional, default="spatial_connectivities") – Key in adata.obsp containing a cell x cell adjacency / connectivity matrix that defines the spatial neighborhood.

  • inplace (bool, optional, default=True) – If True, store marker purity results in sdata.tables[tables_key].obs.

Returns:

Columns:

  • positive_marker_recall

  • negative_marker_avoidance

  • marker_balanced_accuracy

  • n_evaluated_positive_markers

  • n_evaluated_negative_markers

Return type:

pandas.DataFrame

segtraq.sp.supervised.mutually_exclusive_coexpression_rate(sdata, markers: dict[str, dict[str, list[str]]], tables_key: str = 'table', tables_gene_key: str | None = None, tables_raw_counts_layer: str | None = None, inplace: bool = True) → DataFrame#

Assess co-expression of marker genes expected to be mutually exclusive.

Candidate gene pairs are defined from positive and negative marker sets. For each pair, a one-sided Fisher’s exact test evaluates whether the genes are detected together less frequently than expected under independence.

Parameters:

  • sdata (SpatialData-like) – Must contain tables[tables_key] as an AnnData with expression data.

  • markers (dict) – Mapping of cell types to positive and negative markers: {cell_type: {“positive”: list[str], “negative”: list[str]}}.

  • tables_key (str, optional, default="table") – Key of the AnnData table in sdata.tables.

  • tables_gene_key (str or None, default=None) – Column in sdata.tables[tables_key].var containing gene identifiers. If None, var_names are used.

  • tables_raw_counts_layer (str or None, optional) – Layer containing raw counts. If None, adata.X is used.

  • inplace (bool, optional, default=True) – If True, store the resulting DataFrame in sdata.tables[tables_key].uns[“mutually_exclusive_coexpression_rate”].

Returns:

One row per candidate marker-gene pair with columns: gene1, gene2, odds_ratio, pvalue, a, b, c, and d.

Odds ratios below 1 indicate less co-expression than expected under independence. The one-sided Fisher p-value quantifies evidence for such mutual exclusivity.

Return type:

pd.DataFrame

segtraq.sp.supervised.neighbor_contamination(sdata, cell_type_key: str, markers: dict[str, dict[str, list[str]]], tables_key: str = 'table', tables_raw_counts_layer: str | None = None, tables_cell_id_key: str = 'cell_id', tables_centroid_x_key: str = 'x_centroid', tables_centroid_y_key: str = 'y_centroid', tables_gene_key: str | None = None, require_neighbor_expression: bool = True, neighbors_key: str = 'spatial_connectivities', inplace: bool = True)#

Compute local negative-marker contamination per cell and per source-target cell-type pair.

A gene is considered a locally relevant contamination marker for a target cell if it is: 1. a negative marker of the target cell type, and 2. a positive marker of at least one neighboring source cell type.

If require_neighbor_expression=True, the gene must additionally be detected in at least one neighboring cell of the corresponding source cell type.

Per-cell outputs (written to adata.obs):
  • contamination_counts:

    Total counts of locally relevant negative-marker genes in the focal cell.

  • contamination_strength:

    contamination_counts divided by the total transcript counts of the focal cell. This estimates the fraction of assigned transcripts that correspond to plausible local contamination.

Source-target summaries (written to adata.uns):
  • contamination_matrix:

    Directed source-to-target matrix. Entry (c_src, c_tgt) is the fraction of evaluable target cells of type c_tgt that contain at least one locally relevant negative marker associated with source type c_src.

  • contamination_strength_matrix:

    Directed source-to-target matrix. Entry (c_src, c_tgt) is the mean source-specific contamination strength across evaluable target cells of type c_tgt with nonzero total counts.

  • contamination_evaluable_cells_matrix:

    Directed source-to-target matrix. Entry (c_src, c_tgt) is the number of target cells for which contamination from source type c_src could be evaluated.

Returns:

  • per_cell_df (pandas.DataFrame) – Per-cell contamination counts and contamination strength.

  • contamination_matrix_df (pandas.DataFrame) – Source-target matrix with the fraction of evaluable target cells contaminated by each source cell type.

  • contamination_strength_matrix_df (pandas.DataFrame) – Source-target matrix with mean source-specific contamination strength.

  • contamination_evaluable_cells_matrix_df (pandas.DataFrame) – Source-target matrix with the number of evaluable target cells per pair.

Contents