The region similarity (rs) accessor

The region similarity (rs) accessor#

The region similarity accessor provides metrics to evaluate how well intracellular regions align.

segtraq.rs.region_similarity.border_admixture_score(sdata: SpatialData, tables_key: str = 'table', tables_cell_id_key: str = 'cell_id', tables_gene_key: str | None = None, shapes_key: str = 'cell_boundaries', points_key: str = 'transcripts', points_cell_id_key: str = 'cell_id', points_background_id: str | int = 'UNASSIGNED', points_x_key: str = 'x', points_y_key: str = 'y', points_gene_key: str = 'feature_name', border_fraction_of_radius: float = 0.2, buffer_fraction_of_radius: float = 0.1, neighborhood_radius_factor: float = 1.0, min_transcripts: int = 10, min_genes: int = 5, pseudocount: float = 0.5, n_permutations: int = 200, random_state: int | None = 42, n_jobs: int | None = None, parallel_backend: str = 'threading', inplace: bool = True) → DataFrame#

Return null-corrected border admixture improvement and permutation p-value.

The metric asks whether a cell’s border profile is better explained as a mixture of its center and neighboring-cell expression than by its center alone. The mixture coefficient is fitted between the center and neighborhood profiles, and the resulting improvement quantifies how much adding the neighborhood component improves the border fit. The observed improvement is calibrated against a permutation null, with bootstrap confidence intervals used to summarize uncertainty.

Parameters:

  • sdata – SpatialData object.

  • tables_key (str, default="table") – Key in sdata.tables for the cell table.

  • tables_cell_id_key (str, default="cell_id") – Column in the cell table containing cell ids.

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

  • shapes_key (str, default="cell_boundaries") – Key in sdata.shapes containing cell polygons.

  • points_key (str, default="transcripts") – Key in sdata.points containing transcript points.

  • points_cell_id_key (str, default="cell_id") – Column in the transcript table containing transcript-assigned cell ids.

  • points_background_id (str or int, default="UNASSIGNED") – Identifier used for background or unassigned transcripts.

  • points_x_key (str, default="x") – X-coordinate column in the transcript table.

  • points_y_key (str, default="y") – Y-coordinate column in the transcript table.

  • points_gene_key (str, default="feature_name") – Column containing gene names.

  • border_fraction_of_radius (float, default=0.2) – Fraction of the equivalent radius used to define the thickness of the border region (outer ring).

  • buffer_fraction_of_radius (float, default=0.1) – Additional fraction of the equivalent radius used to define the gap between the border and center regions.

  • neighborhood_radius_factor (float, default=1.0) – Neighbor distance threshold expressed as a multiple of the median equivalent cell radius.

  • min_transcripts (int, default=10) – Minimum number of transcripts required in each region.

  • min_genes (int, default=5) – Minimum number of genes required across the three regions combined.

  • pseudocount (float, default=0.5) – Pseudocount used when converting counts to proportions.

  • n_permutations (int, default=200) – Number of permutations per cell. Must be >= 100.

  • random_state (int or None, default=42) – Seed for reproducible cell-wise permutations.

  • n_jobs (int or None, default=None) – Number of parallel jobs across cells. -1 uses all available CPU cores.

  • parallel_backend (str, default="threading") – Parallelization backend passed to joblib.

  • inplace (bool, default=True) – If True, merge the results into sdata.tables[tables_key].obs.

Returns:

One row per cell with null-corrected border-admixture score and permutation p-value.

Return type:

pd.DataFrame

segtraq.rs.region_similarity.match_nuclei_to_cells(sdata: SpatialData, tables_key: str = 'table', tables_cell_id_key: str = 'cell_id', shapes_key: str = 'cell_boundaries', nucleus_shapes_key: str = 'nucleus_boundaries', select_by: str = 'nucleus_fraction', min_intersection_area: float = 0.0, n_jobs: int | None = None, parallel_backend: str = 'threading', inplace: bool = True) → DataFrame#

Compute the best-matching nucleus for each cell.

Matching is based on Intersection-over-Union (IoU) or nucleus fraction (area(cell ∩ nucleus) / area(nucleus)). Candidate nuclei are identified by spatial overlap, and the highest-scoring nucleus is retained for each cell. The final result also enforces a one-to-one assignment so that a nucleus is not matched to multiple cells.

Parameters:

  • sdata (SpatialData) – A SpatialData object containing segmented and transcript-assigned spatial transcriptomics data (images, tables, points, shapes and optional labels).

  • tables_key (str, default="table") – Key in sdata.tables for the cell-level metadata table.

  • tables_cell_id_key (str, default="cell_id") – Column in the cell table uniquely identifying each cell.

  • shapes_key (str, default="cell_boundaries") – Key in sdata.shapes for cell boundary polygons.

  • nucleus_shapes_key (str, default="nucleus_boundaries") – Key in sdata.shapes for nucleus boundary polygons, if available.

  • select_by (str, default="nucleus_fraction") – Score used to select the best-matching nucleus per cell. Options: - “iou”: maximize Intersection-over-Union (cell vs nucleus). - “nucleus_fraction”: maximize area(cell ∩ nucleus) / area(nucleus). If multiple nuclei have the same score (e.g. fully inside the cell), the larger nucleus (by area) is selected.

  • min_intersection_area (float, default=0.0) – Minimum area (cell ∩ nucleus) required to consider a nucleus as a candidate. Overlaps <= this threshold are ignored.

  • n_jobs (int or None, default=None) – Number of parallel jobs across cells. -1 uses all available CPU cores.

  • parallel_backend (str, default="threading") – Parallelization backend passed to joblib.

  • inplace (bool, default=True) – Whether to merge the results into sdata.tables[tables_key].obs.

Returns:

One row per cell with the matched nucleus ID, IoU, and nucleus fraction.

Return type:

pandas.DataFrame

segtraq.rs.region_similarity.similarity_nucleus_cell(sdata: SpatialData, tables_key: str = 'table', tables_cell_id_key: str = 'cell_id', tables_gene_key: str | None = None, shapes_key: str = 'cell_boundaries', nucleus_shapes_key: str = 'nucleus_boundaries', points_key: str = 'transcripts', points_cell_id_key: str = 'cell_id', points_background_id: str | int = 'UNASSIGNED', points_gene_key: str = 'feature_name', points_x_key: str = 'x', points_y_key: str = 'y', tables_raw_counts_layer: str | None = None, min_transcripts: int = 10, min_genes: int = 5, scale: float = 10000.0, select_by: str = 'nucleus_fraction', min_intersection_area: float = 0.0, n_jobs: int | None = None, parallel_backend: str = 'threading', inplace: bool = True, n_permutations: int = 200, random_state: int | None = 42) → DataFrame#

Compare whole-cell and matched-nucleus profiles using PFlog1pPF cosine similarity.

The whole-cell expression profile is compared with the transcript profile inside its matched nucleus after PFlog1pPF transformation. Because the cell and nucleus profiles can share transcripts, the permutation null preserves their observed transcript overlap. A lower-tail permutation p-value tests whether the observed similarity is smaller than expected under this null.

Parameters:

  • sdata (SpatialData) – A SpatialData object containing segmented and transcript-assigned spatial transcriptomics data.

  • tables_key (str, default="table") – Key in sdata.tables for the cell-level metadata table.

  • tables_cell_id_key (str, default="cell_id") – Column in the cell table uniquely identifying each cell.

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

  • shapes_key (str, default="cell_boundaries") – Key in sdata.shapes for cell boundary polygons.

  • nucleus_shapes_key (str, default="nucleus_boundaries") – Key in sdata.shapes for nucleus boundary polygons.

  • points_key (str, default="transcripts") – Key in sdata.points for spot/transcript-level data.

  • points_cell_id_key (str, default="cell_id") – Column in the points table linking each transcript/spot to a cell.

  • points_background_id (str or int, default="UNASSIGNED") – Identifier for transcripts not assigned to any cell.

  • points_gene_key (str, default="feature_name") – Column specifying the gene/feature name for each transcript/spot.

  • points_x_key (str, default="x") – Column for the x-coordinate of each transcript/spot.

  • points_y_key (str, default="y") – Column for the y-coordinate of each transcript/spot.

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

  • min_transcripts (int, default=10) – Minimum number of transcripts required in both cell and nucleus.

  • min_genes (int, default=5) – Minimum number of non-zero genes required across cell and nucleus.

  • scale (float, default=1e4) – Scale factor used for the PFlog1pPF transformation.

  • select_by (str, default="nucleus_fraction") – Score used to select the best-matching nucleus per cell. Options: - “iou”: maximize Intersection-over-Union (cell vs nucleus). - “nucleus_fraction”: maximize area(cell ∩ nucleus) / area(nucleus). If multiple nuclei have the same score, the larger nucleus is selected.

  • min_intersection_area (float, default=0.0) – Minimum area(cell ∩ nucleus) required to consider a nucleus as a candidate. Overlaps <= this threshold are ignored.

  • n_jobs (int or None, default=None) – Number of parallel jobs across cells. -1 uses all available CPU cores.

  • parallel_backend (str, default="threading") – Parallelization backend passed to joblib.

  • inplace (bool, default=True) – Whether to merge the results into sdata.tables[tables_key].obs.

  • n_permutations (int, default=200) – Number of conditional permutations per cell. Must be >= 100.

  • random_state (int or None, default=42) – Seed for reproducible cell-wise permutations.

Returns:

One row per cell with nucleus-match information, null-corrected nucleus-cell similarity, and its permutation p-value.

Return type:

pd.DataFrame

segtraq.rs.region_similarity.similarity_nucleus_cytoplasm(sdata: SpatialData, tables_key: str = 'table', tables_cell_id_key: str = 'cell_id', tables_gene_key: str | None = None, shapes_key: str = 'cell_boundaries', nucleus_shapes_key: str = 'nucleus_boundaries', points_key: str = 'transcripts', points_cell_id_key: str = 'cell_id', points_background_id: str | int = 'UNASSIGNED', points_gene_key: str = 'feature_name', points_x_key: str = 'x', points_y_key: str = 'y', min_transcripts: int = 10, min_genes: int = 5, scale: float = 10000.0, select_by: str = 'nucleus_fraction', min_intersection_area: float = 0.0, n_jobs: int | None = None, parallel_backend: str = 'threading', inplace: bool = True, n_permutations: int = 200, random_state: int | None = 42) → DataFrame#

Compare matched nuclear and cytoplasmic profiles using PFlog1pPF cosine similarity.

For each cell, transcripts are separated into those inside the matched nucleus and those in the remaining cytoplasmic region. The two count profiles are PFlog1pPF-transformed before cosine similarity is computed. When n_permutations >= 100, a lower-tail permutation p-value tests whether the observed similarity is smaller than expected under a shared-profile null.

Parameters:

  • sdata (SpatialData) – A SpatialData object containing segmented and transcript-assigned spatial transcriptomics data.

  • tables_key (str, default="table") – Key in sdata.tables for the cell-level metadata table.

  • tables_cell_id_key (str, default="cell_id") – Column in the cell table uniquely identifying each cell.

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

  • shapes_key (str, default="cell_boundaries") – Key in sdata.shapes for cell boundary polygons.

  • nucleus_shapes_key (str, default="nucleus_boundaries") – Key in sdata.shapes for nucleus boundary polygons.

  • points_key (str, default="transcripts") – Key in sdata.points for spot/transcript-level data.

  • points_cell_id_key (str, default="cell_id") – Column in the points table linking each transcript/spot to a cell.

  • points_background_id (str or int, default="UNASSIGNED") – Identifier for transcripts not assigned to any cell.

  • points_gene_key (str, default="feature_name") – Column specifying the gene/feature name for each transcript/spot.

  • points_x_key (str, default="x") – Column for the x-coordinate of each transcript/spot.

  • points_y_key (str, default="y") – Column for the y-coordinate of each transcript/spot.

  • min_transcripts (int, default=10) – Minimum number of transcripts required in both nuclear and cytoplasmic regions.

  • min_genes (int, default=5) – Minimum number of non-zero genes required across nuclear and cytoplasmic regions.

  • scale (float, default=1e4) – Common target sum used for the first and second proportional-fitting steps.

  • select_by (str, default="nucleus_fraction") – Score used to select the best-matching nucleus per cell. Options: - “iou”: maximize Intersection-over-Union (cell vs nucleus). - “nucleus_fraction”: maximize area(cell ∩ nucleus) / area(nucleus). If multiple nuclei have the same score, the larger nucleus is selected.

  • min_intersection_area (float, default=0.0) – Minimum area (cell ∩ nucleus) required to consider a nucleus as a candidate. Overlaps <= this threshold are ignored.

  • n_jobs (int or None, default=None) – Number of parallel jobs across cells. -1 uses all available CPU cores.

  • parallel_backend (str, default="threading") – Parallelization backend passed to joblib.

  • inplace (bool, default=True) – Whether to merge the results into sdata.tables[tables_key].obs.

  • n_permutations (int, default=200) – Number of conditional permutations per cell. Must be >= 100.

  • random_state (int or None, default=42) – Seed for reproducible cell-wise permutations.

Returns:

One row per cell with nucleus-match information and null-calibrated nucleus-cytoplasm similarity score and its permutation p-value.

Return type:

pd.DataFrame

Contents