Contour-aware density profiling across Squidpy and SpatialData

[hutaobo]

Summary

This issue tracks today’s hackathon work on contour-aware density profiling across Squidpy and SpatialData.

The motivating use case was to quantify cells or transcripts in inward and outward bands around polygon annotations such as tumor boundaries, lumen edges, or tissue compartment interfaces. This led to a local prototype implementation, real-data testing on Xenium-derived contours, and upstream discussion in both Squidpy and SpatialData.

Work completed today

• Formalized the feature request upstream in Squidpy as scverse/squidpy#1160.
• Opened a draft upstream PR in Squidpy as scverse/squidpy#1163.
• Implemented a local ring-based density workflow around polygon contours.
• Implemented a local smooth signed-distance density prototype for transcripts.
• Ran the workflow on a real example using VIM transcripts around protein_cluster_contours with assigned_structure == "Structure 4".
• Generated static profile plots for both the discrete ring-based summary and the smooth signed-distance prototype.

Preliminary real-data readout:

• n = 23 contours
• The ring-based profile showed a modest inward-to-outward decrease in VIM transcript density.
• The smooth profile preserved the same aggregate direction, but also exposed normalization instability where the local geometry measure becomes very small.

Upstream references

• Squidpy feature request: scverse/squidpy#1160
• Squidpy draft PR: scverse/squidpy#1163
• Related SpatialData discussion: scverse/spatialdata#975
• Related hackathon design context:
  • #6 Link representation between table(s) and SpatialElement(s)
  • #7 Utility function to trace links between elements

Local prototype artifacts

Local prototype scripts:

• scripts/run_local_squidpy_ring_density.py
• scripts/plot_ring_density_profile.py
• scripts/plot_smooth_density_profile.py

Local result files:

• results/protein_cluster_contours_transcripts_vim_structure4_ring_density.csv
• results/protein_cluster_contours_transcripts_vim_structure4_ring_density_profile.png
• results/protein_cluster_contours_transcripts_vim_structure4_ring_density_profile.svg
• results/protein_cluster_contours_transcripts_vim_structure4_smooth_density_by_distance.csv
• results/protein_cluster_contours_transcripts_vim_structure4_smooth_density_by_distance_profile.png
• results/protein_cluster_contours_transcripts_vim_structure4_smooth_density_by_distance_profile.svg

Real data source:

• Xenium-derived SpatialData input used for local testing: https://drive.google.com/file/d/1Bfg0oJO749lUIyc_-4HMHsuxNGDLdaex/view?usp=drive_link

Why this matters for SpatialData design

This work is not only about a new analysis function in Squidpy. The contour-density use case also stresses the current representation of links between polygon annotations, points, and table-linked observations across SpatialData elements.

In particular, the workflow reinforces why the broader annotation/linking discussion in scverse/spatialdata#975 and the local hackathon design issues #6 and #7 matter: contour-aware analysis becomes easier to reason about when relationships between tables and spatial elements are explicit, queryable, and composable.

Next steps

• Decide whether the smooth method should remain in the same upstream Squidpy PR or be split into a follow-up PR.
• Tighten the geometry normalization used by the smooth signed-distance estimator.
• Decide whether a lower-level signed-distance primitive should be factored out separately from the density APIs.
• Push the local prototype scripts and result summaries into a shareable form if we want other hackathon participants to reproduce the workflow directly from this repository.