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, markers=None, tables_key='table', tables_raw_counts_layer=None, tables_cell_id_key='cell_id', tables_centroid_x_key='x_centroid', tables_centroid_y_key='y_centroid', tables_gene_key=None, require_neighbor_expression=True, neighbors_key='spatial_connectivities', inplace=True)#

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 or None, default None) – Mapping of cell types to positive and negative markers: {cell_type: {“positive”: list[str], “negative”: list[str]}}. If None, markers are loaded from adata.uns[“segtraq_markers”].

  • 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, adata_ref, ref_cell_type, markers=None, tables_key='table', tables_gene_key=None, query_gene_key=None, tables_raw_counts_layer=None, ref_gene_key=None, ref_raw_counts_layer=None, min_pos_frac=0.25, max_ref_coexpression_ratio=0.75, inplace=True)#

Assess unexpected co-expression of reference-defined mutually exclusive markers.

Candidate gene pairs are derived from reciprocal positive/negative marker relationships between pairs of reference cell types. Positive markers must be detected in at least min_pos_frac of cells of their corresponding reference cell type. Pairs that are positive markers of the same cell type are excluded.

Candidate pairs are retained as mutually exclusive if their observed co-expression in the reference is at most max_ref_coexpression_ratio times the co-expression expected under independence.

For each retained pair, co-expression in the spatial data is summarized using a 2x2 detection table. A one-sided Fisher’s exact test evaluates whether the genes are positively associated in the spatial data (odds ratio > 1). P-values are corrected across all tested pairs using the Benjamini-Hochberg procedure.

Parameters:

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

  • adata_ref (AnnData) – Reference AnnData object containing annotated cells.

  • ref_cell_type (str) – Column in adata_ref.obs containing reference cell-type labels.

  • markers (dict or None, default None) – Mapping of cell types to positive and negative markers: {cell_type: {“positive”: list[str], “negative”: list[str]}}. If None, markers are loaded from sdata.tables[tables_key].uns[“segtraq_markers”].

  • tables_key (str, 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 the canonical gene identifiers used by SegTraQ. If None, var_names are used.

  • query_gene_key (str or None, default None) – Alternative column in sdata.tables[tables_key].var containing gene identifiers matching adata_ref.var[ref_gene_key]. If None, tables_gene_key is used.

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

  • ref_gene_key (str or None, default None) – Column in adata_ref.var containing gene identifiers matching the query gene identifiers. If None, adata_ref.var_names are used.

  • ref_raw_counts_layer (str or None, default None) – Layer containing raw reference counts. If None, .X is used.

  • min_pos_frac (float, default 0.25) – Minimum fraction of cells of the corresponding reference cell type in which a positive marker must be detected.

  • max_ref_coexpression_ratio (float, default 0.75) – Maximum ratio of observed to expected co-expression in the reference for a candidate pair to be considered mutually exclusive.

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

Returns:

One row per reference-defined mutually exclusive marker pair with columns gene1, gene2, odds_ratio, pvalue, pvalue_adj, a, b, c, d and coexpression_fraction.

a is the number of cells detecting both genes, b gene1 only, c gene2 only, and d neither. Odds ratios greater than 1 indicate positive association in the spatial data. pvalue is the one-sided Fisher exact p-value and pvalue_adj its Benjamini-Hochberg-adjusted value. coexpression_fraction is the fraction of cells expressing both genes.

Return type:

DataFrame

segtraq.sp.supervised.neighbor_contamination(sdata, cell_type_key, markers=None, tables_key='table', tables_raw_counts_layer=None, tables_cell_id_key='cell_id', tables_centroid_x_key='x_centroid', tables_centroid_y_key='y_centroid', tables_gene_key=None, require_neighbor_expression=True, neighbors_key='spatial_connectivities', inplace=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.

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 or None, default None) – Mapping of cell types to positive and negative markers: {cell_type: {“positive”: list[str], “negative”: list[str]}}. If None, markers are loaded from adata.uns[“segtraq_markers”].

  • 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:

  • 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