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, shapes_key_list, tables_key='table', tables_cell_id_key='cell_id', cell_type_key='transferred_cell_type', shapes_cell_id_key='cell_id', unknown_label='Unknown', unknown_policy='treat_as_label', inplace=True)#

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:

DataFrame

segtraq.vl.volume.similarity_top_bottom(sdata, tables_key='table', tables_cell_id_key='cell_id', tables_gene_key=None, points_key='transcripts', points_cell_id_key='cell_id', points_background_id='UNASSIGNED', points_gene_key='feature_name', points_x_key='x', points_y_key='y', points_z_key='z', exclude_gene_prefixes=('MT-', 'RPL', 'RPS'), correct_z_drift=True, max_points=1000000, seed=0, q=0.3, scale=10000.0, min_genes=5, min_transcripts=10, n_permutations=200, random_state=42, n_jobs=None, parallel_backend='threading', inplace=True)#

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.

  • exclude_gene_prefixes (str, list of str, tuple of str, or None, optional) – Gene prefixes excluded. By default (("MT-", "RPL", "RPS")), mitochondrial and ribosomal genes are excluded. Set to None to use all genes.

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

DataFrame

segtraq.vl.volume.vertical_signal_integrity_per_cell(sdata, ovrlp=None, points_key='transcripts', points_gene_key='feature_name', points_cell_id_key='cell_id', points_x_key='x', points_y_key='y', points_z_key='z', tables_key='table', tables_cell_id_key='cell_id', points_background_id='UNASSIGNED', n_jobs=None, random_state=123, ovrlpy_init_kwargs=None, ovrlpy_analyse_kwargs=None, inplace=True)#

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:

DataFrame

Contents