The volume (vl) accessor

The volume (vl) accessor#

The volume accessor provides metrics about the 3D spatial distribution of transcripts.

segtraq.vl.volume.fraction_heterotypic_overlap(sdata: SpatialData, shapes_key_list: list[str] | None, tables_key: str = 'table', tables_cell_id_key: str = 'cell_id', cell_type_key: str = 'transferred_cell_type', shapes_cell_id_key: str = 'cell_id', unknown_label: str = 'Unknown', unknown_policy: str = 'treat_as_label', inplace: bool = True) → DataFrame#

Compute cross-depth heterotypic overlap fraction per cell using one representative polygon per cell (chosen as the polygon with the largest area across z layers).

For a representative polygon i (cell_id, z_layer) with geometry P_i and type t_i:

overlap_area_i = Area( P_i ∩ Union_{j: z_j != z_i, id_j != id_i, t_j != t_i} P_j ) overlap_fraction_i = overlap_area_i / Area(P_i)

Candidates are restricted to bbox-overlapping polygons via a spatial index.

Unknown/NA types:

  • unknown_policy=”exclude”: cells with NA/unknown type return NaN, and unknown-type candidates are excluded from overlap.

  • unknown_policy=”treat_as_label”: NA is replaced by unknown_label and treated as a real category.

Parameters:

  • sdata (SpatialData) – A SpatialData object containing cell boundary polygons in multiple z layers and a cell table with transferred cell type labels.

  • shapes_key_list (list[str]) – Keys in sdata.shapes for per-z-layer cell boundary polygons (e.g. [“cell_boundaries_z0”, …, “cell_boundaries_z3”]).

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

  • cell_type_key (str, default="transferred_cell_type") – Column in the cell table containing cell-type labels (e.g. transferred from scRNA-seq).

  • shapes_cell_id_key (str, optional, default="cell_id") – Index name of shapes GeoDataFrame linking polygons to cell IDs.

  • unknown_label (str, default="Unknown") – Label name to use when treating NA as a separate category (unknown_policy=”treat_as_label”).

  • unknown_policy (str, default="exclude") –

    How to handle Unknown/NA cell types:

    • ”exclude”: exclude polygons with NA/unknown types from comparisons. If the focal cell has NA/unknown type, its overlap fraction is set to NaN.

    • ”treat_as_label”: convert NA to unknown_label and treat it as a valid category.

  • inplace (bool, default=True) – Whether to merge the aggregated per-cell result into sdata.tables[tables_key].obs.

Returns:

DataFrame with columns [tables_cell_id_key, “heterotypic_overlap_area”, “heterotypic_overlap_fraction”].

Return type:

pd.DataFrame

segtraq.vl.volume.similarity_top_bottom(sdata, tables_key: str = 'table', tables_cell_id_key: str = 'cell_id', tables_gene_key: str | None = None, 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', points_z_key: str = 'z', correct_z_drift: bool = True, max_points: int = 1000000, seed: int | None = 0, q: float = 0.3, scale: float = 10000.0, min_genes: int = 5, min_transcripts: int = 10, n_permutations: int = 200, random_state: int | None = 42, n_jobs: int | None = None, parallel_backend: str = 'threading', inplace: bool = True) → DataFrame#

Compute PFlog1pPF cosine similarity between the bottom and top of each cell.

Transcripts are split into bottom and top regions using within-cell z-quantiles, optionally after correcting global z-drift. The resulting count profiles are transformed with PFlog1pPF (shifted CLR) and compared using cosine similarity; larger values indicate more similar transcript composition across cell depth.

If n_permutations >= 100, a conditional permutation test pools the bottom and top counts and reallocates transcripts while preserving both region totals. The lower-tail p-value quantifies whether the observed similarity is smaller than expected under a shared-composition null model.

Parameters:

  • sdata (SpatialData) – A SpatialData object containing 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.

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

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

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

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

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

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

  • points_z_key (str, default="z") – Column specifying the z coordinate / depth for each transcript.

  • correct_z_drift (bool, default=True) – If True, correct global z-drift before computing within-cell z-quantiles. The corrected values are used only for defining top/bottom subsets.

  • max_points (int, default=1_000_000) – Maximum number of points used to fit the regression for z-drift correction.

  • seed (int or None, default=0) – Random seed used for subsampling during z-drift correction. If None, sampling is not reproducible.

  • q (float, default=0.30) – Quantile defining the bottom and top parts: bottom <= q and top >= 1 - q.

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

  • min_genes (int, default=5) – Minimum number of genes with nonzero counts across bottom and top required to score a cell.

  • min_transcripts (int, default=10) – Minimum number of transcripts required in each part to score a cell.

  • n_permutations (int, default=200) – Number of conditional permutations used to compute the p-value. Must be >= 100.

  • random_state (int or None, default=42) – Random seed used to generate reproducible per-cell permutation streams.

  • n_jobs (int or None, default=None) – Number of parallel jobs used for per-cell profile comparisons.

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

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

Returns:

DataFrame with tables_cell_id_key and similarity_top_bottom. If n_permutations >= 100, similarity_top_bottom_p_value is also returned.

Return type:

pd.DataFrame

segtraq.vl.volume.vertical_signal_integrity_per_cell(sdata, ovrlp: Ovrlp | None = None, points_key: str = 'transcripts', points_gene_key: str = 'feature_name', points_cell_id_key: str = 'cell_id', points_x_key: str = 'x', points_y_key: str = 'y', points_z_key: str = 'z', tables_key: str = 'table', tables_cell_id_key: str = 'cell_id', points_background_id: str | int = 'UNASSIGNED', n_jobs: int | None = None, random_state: int = 123, ovrlpy_init_kwargs: dict[str, Any] | None = None, ovrlpy_analyse_kwargs: dict[str, Any] | None = None, inplace: bool = True) → DataFrame#

Compute per-cell mean VSI by sampling a precomputed VSI map at transcript locations.

This metric assumes vsi_map is defined on the same coordinate system and scaling as the transcript coordinates in sdata.points[points_key], i.e. VSI values are indexed directly by integer x/y coordinates after optional shift-to-origin.

If ovrlp is provided, the existing ovrlpy.Ovrlp object is used directly. If ovrlp=None, ovrlpy is run internally. For each transcript, the VSI value is read from the ovrlpy object and then averaged across transcripts belonging to each cell.

Parameters:

  • sdata (SpatialData) – A SpatialData object.

  • ovrlp (ovrlpy.Ovrlp or None, default=None) – Precomputed ovrlpy object with VSI already calculated. If None, ovrlpy is run internally using n_comp.

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

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

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

  • points_x_key (str, default="x") – Column in the points table containing transcript x-coordinates.

  • points_y_key (str, default="y") – Column in the points table containing transcript y-coordinates.

  • points_z_key (str, default="z") – Column in the points table containing transcript z-coordinates.

  • tables_key (str, default="table") – Key in sdata.tables for the cell-level metadata table. If inplace=True, results are merged into sdata.tables[tables_key].obs.

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

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

  • n_jobs (int or None, default=None) – Number of jobs passed to ovrlpy.Ovrlp if ovrlp=None.

  • random_state (int, default=42) – Random seed passed to ovrlpy.Ovrlp if ovrlp=None.

  • ovrlpy_init_kwargs (dict or None, default=None) – Additional keyword arguments passed to ovrlpy.Ovrlp if ovrlp=None.

  • ovrlpy_analyse_kwargs (dict or None, default=None) – Additional keyword arguments passed to ovrlpy.Ovrlp.analyse if ovrlp=None.

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

Returns:

DataFrame with columns [tables_cell_id_key, “vertical_signal_integrity”].

Return type:

pd.DataFrame

Contents