Bio Spatial Transcriptomics High Resolution Binning

Version Compatibility

Reference examples tested with: bin2cell 0.3+, scanpy 1.10+, anndata 0.10+, spatialdata 0.1+, squidpy 1.4+

Before using code patterns, verify installed versions match. If versions differ:

• Python: pip show <package> then help(module.function) to check signatures
• R: packageVersion('<pkg>') then ?function_name to verify parameters

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

High-Resolution Binning

"Turn my Visium HD 2um bins into cells" -> Aggregate sub-cellular capture features UP into single-cell profiles, using a registered nucleus image to decide which bins belong to which cell when one exists.

• Python: Bin2cell (b2c.read_visium -> b2c.stardist -> b2c.insert_labels -> b2c.bin_to_cell) for image-guided reconstruction; scanpy/squidpy for fixed-bin aggregation when no image exists

Governing Principle

Binning is the INVERSE of deconvolution. Deconvolution takes a capture unit that is LARGER than a cell (a 55um Visium spot holding 1-10 cells) and mixes it DOWN into the cell-type fractions inside it. High-resolution platforms have the opposite geometry: a Visium HD 2um bin, a Stereo-seq ~220nm DNB spot, and a Slide-seqV2 10um bead are SMALLER than or comparable to a single cell, so each unit is a fragment of one cell, not a mixture of several. The task is to aggregate fragments UP into whole cells, never to deconvolve a mixture that does not exist. Running deconvolution on 2um bins invents fractional cell-type mixtures inside features that hold only part of one cell.

The trap that defeats the naive fix is coarse binning. The 2um bins are far too sparse to cluster directly -- most bins capture a handful of transcripts or none, so a per-bin expression vector carries no cell-type signal. The reflex is to bin up to a coarser grid (Visium HD ships 8um and 16um bins for exactly this reason). But an 8um bin still spans roughly two cells, so coarse binning trades resolution for the precise multi-cell-mixture problem the high resolution was meant to escape -- it lands back in the DECONVOLVE regime, now needing a reference and a deconvolution method. This is a genuine dilemma, not a tunable knob: too fine is unclusterably sparse, too coarse is a mixture.

The escape is to define the cell from morphology instead of from a fixed grid. When a high-quality registered image exists (Visium HD ships an H&E or DAPI image co-registered to the bin coordinates), segment nuclei on the IMAGE, then assign each 2um bin to the nucleus whose territory contains it, and sum the bins per nucleus into a real single-cell profile. The cell boundary comes from morphology, not from an arbitrary square. Without a per-feature registered cell image (Slide-seqV2 beads have no co-registered cell morphology), morphology reconstruction is impossible and fixed-bin aggregation or bead-level deconvolution (RCTD doublet-mode is common for Slide-seqV2) remains the standard. Platform plus image availability decides the approach -- not the tool.

The reconstruction decision

This skill IS the AMBIGUOUS regime of the resolution fork named in spatial-deconvolution: the near-single-cell middle where a unit holds part of, or roughly, one cell. The fork there sorts platforms into DECONVOLVE (spot >> cell), SEGMENT (imaging, already single cells), and AMBIGUOUS; everything below is the AMBIGUOUS branch.

The discriminating axis is the registered cell image, not the platform name. A Visium HD run without a usable image collapses to the Slide-seqV2 row; a Stereo-seq run with a clean registered ssDNA stain behaves like the Visium HD row. Confirm the image is registered to the bin coordinate frame before trusting any morphology reconstruction; a misregistered image assigns bins to the wrong nuclei silently. Methods here evolve quickly -- verify the current best practice and the tool's registration assumptions against its latest documentation before committing.

Loading Visium HD bins

Goal: Read the 2um bin matrix together with the registered morphology image into one object whose bin coordinates and image pixels share a frame.

Approach: Use the Bin2cell reader, which wraps the Space Ranger 2um output and attaches the full-resolution source image; Visium HD tissue positions are PARQUET, not CSV, and the reader handles that. Inspect the bin sparsity before deciding fine-reconstruct vs coarse-aggregate.

import bin2cell as b2c
import numpy as np

# square_002um is the 2um bin output; source_image_path is the full-res H&E/DAPI registered to the bins
adata = b2c.read_visium('visium_hd_outs/binned_outputs/square_002um/',
                        source_image_path='Visium_HD_tissue_image.tif',
                        spaceranger_image_path='visium_hd_outs/spatial/')

median_counts = np.median(np.asarray(adata.X.sum(axis=1)).ravel())   # 2um bins are sparse: often single-digit median UMIs
print(f'bins: {adata.n_obs}, median UMI/bin: {median_counts:.1f}')   # too sparse to cluster -> reconstruct, do not cluster bins

Morphology-driven cell reconstruction (Bin2cell)

Goal: Build true single-cell profiles by segmenting nuclei on the registered image and summing the 2um bins that fall inside each nucleus territory.

Approach: Scale the H&E to the segmentation resolution, destripe the Visium HD per-row/per-column count artifact, run StarDist for nuclei, insert the labels onto the bin coordinates, expand each nucleus to capture cytoplasmic bins, then collapse bins per label into a cell-level AnnData. Each cell records how many bins it absorbed.

import bin2cell as b2c

mpp = 0.5                                                            # microns-per-pixel for the scaled image; sets StarDist's effective resolution
b2c.scaled_he_image(adata, mpp=mpp, save_path='stardist/he.tiff')
b2c.destripe(adata)                                                 # corrects Visium HD per-row/per-column total-count striping before it biases segmentation

b2c.stardist(image_path='stardist/he.tiff', labels_npz_path='stardist/he.npz',
             stardist_model='2D_versatile_he', prob_thresh=0.01)    # H&E nuclei; '2D_versatile_fluo' for DAPI
b2c.insert_labels(adata, labels_npz_path='stardist/he.npz', basis='spatial',
                  spatial_key='spatial_cropped_150_buffer', mpp=mpp, labels_key='labels_he')
b2c.expand_labels(adata, labels_key='labels_he', expanded_labels_key='labels_he_expanded')   # nucleus -> cell territory for cytoplasmic bins

cdata = b2c.bin_to_cell(adata, labels_key='labels_he_expanded',
                        spatial_keys=['spatial', 'spatial_cropped_150_buffer'])
# cdata is cell-level: bins summed per label; cdata.obs['bin_count'] = bins absorbed per cell -> a QC handle

Bins assigned to no nucleus (label 0) are dropped -- they are inter-cellular space or unsegmented territory, and forcing them into a cell fabricates expression. A cell built from very few bins is a low-confidence reconstruction; filter on bin_count the way single-cell QC filters on UMIs. When the H&E nuclei miss sparse regions, a second StarDist pass on a gene-expression-derived image (b2c.grid_image -> 2D_versatile_fluo) plus b2c.salvage_secondary_labels rescues cells the H&E alone missed.