iscc.data.Visium

Visium(count_model='dm', batch_label=None, n_reads=None, spot_pitch=None, spot_radius=None, mu_counts=None, sigma_counts=None, field_lengthscale=None, field_sigma=None, edge_sigma=None, diffusion_sigma=None, sigma_batch=None, ambient_frac=None, kappa=None, nb_dispersion=None, section_frac=None, placement=None, rotation=0.0, n_spots_x=None, n_spots_y=None, seed=42)

Bases: Assay

Visium spatial assay: lays spots over the section, aggregates cells, applies a VisiumBatch.

Any hyper-parameter below can be overridden explicitly (None keeps the default, which is calibrated to a real 10x Visium section). Legacy aliases are accepted: n_reads maps onto mu_counts, and a spot grid requested via n_spots_x / n_spots_y derives spot_pitch from grid_side at run time. The number of spots (and cells per spot) follows from grid_side (passed to run) and the sampled cell_data, so there is no n_cells.

Parameters:

Name	Type	Description	Default
count_model	str	Final count-emission model: "dm" Dirichlet-multinomial (compositional per-spot capture, the Visium default) or "nb" negative-binomial (independent per-gene).	"dm"
batch_label	str	Section/batch label; defaults to f"visium{seed}".	None
n_reads	float	Legacy alias for mu_counts (mean per-spot library size).	None
spot_pitch	float	Spot centre-to-centre spacing (coordinate units); sets spot density / number of spots. Overridden at run time if n_spots_x / n_spots_y are given.	2.0
spot_radius	float	Spot capture radius: cells within this distance of a spot centre are pooled into it (~1-10 cells / spot).	1.0
mu_counts	float	Mean per-spot library size (total UMIs / spot); ell_s ~ LogNormal(log mu_counts, sigma_counts^2) × capture_field.	20000.0
sigma_counts	float	Per-spot library-size LogNormal sd (spot-to-spot depth variation).	0.45
field_lengthscale	float	Spatial autocorrelation length of the capture-efficiency field (the squared-exponential GP length-scale, in coordinate units); larger -> smoother field -> higher Moran's I.	18.0
field_sigma	float	Capture-field strength (log-space sd of the smooth positive field); 0 -> flat field (no spatial capture bias).	0.70
edge_sigma	float	Tissue-boundary capture falloff: the very edge of the section is reduced by this fraction, the interior stays ~1. 0 disables; a value < 1 keeps efficiency positive.	0.30
diffusion_sigma	float	Lateral mRNA-bleed Gaussian kernel sd, spreading each spot's expression into its neighbours before counting; 0 disables (no bleed).	0.0
sigma_batch	float	Per-gene batch-factor LogNormal sd, shared across spots (Splatter batch.facScale).	0.10
ambient_frac	float	Fraction of each spot's library drawn as ambient "soup" contamination.	0.05
kappa	float	Dirichlet-multinomial concentration (only for count_model="dm"); large -> ~ multinomial, small -> lumpy proportions.	50.0
nb_dispersion	float	Negative-binomial overdispersion phi (var = mu + phi*mu^2; only for count_model="nb").	0.30
section_frac	float	Take a thin physical section of a count-based (deme) tumor before assaying: place each deme's cells within its unit cell and keep this fraction of each deme's 3-D column (see :func:iscc.sample.spatialize). The tissue is then centred on the fixed slide and a morphology image is attached to the output. None (default) uses cell_crd as given (no placement) — appropriate when the coordinates are already at cell resolution. This thins the same 3-D column as :meth:iscc.sample.Resection.slice's depth_frac, so the two compose multiplicatively — keep one at 1.0 (the tutorials slice via Resection and pass section_frac=1.0 here).	None
placement	tuple of float	Where the fixed slide sits on the section, as a (row, col) in the section's coordinate frame that the slide's capture area is centred on. None (default) centres the section's centroid on the slide. When the section is larger than the slide the slide images only the part it covers, so placement chooses which region (e.g. a particular lesion) is captured rather than always the middle. The slide's footprint is placement ± (slide_height/2, slide_width/2) in section coordinates.	None
rotation	float	Degrees to rotate the section on the slide before placing it (about placement / the centroid). The v1 slide is wider than it is tall, so a tall section captures more of itself rotated 90° to lie along the slide's long axis.	0.0
n_spots_x	int	Legacy alias: request a fixed spot-grid width. When both n_spots_x and n_spots_y are set, the pitch is derived as grid_side / max(n_spots_x, n_spots_y) at run time instead of using spot_pitch.	None
n_spots_y	int	Legacy alias: request a fixed spot-grid height (see n_spots_x).	None
seed	int	RNG seed. Fixes the technical signature (per-gene batch factor, spatial capture field, per-spot depth) and is reproducible.	42

Methods:

Name	Description
capture_shape	(rows, cols) extent of the v1 capture area, in the units spot_pitch is given in.
place_grid	Place the fixed spot grid on a section WITHOUT assaying it, and store the placement.
section_image	Render the placed tissue section as an H&E-like image, without running the assay.
run	Assay a 10x Visium spatial-transcriptomics section over the placed spot grid.
to_anndata	Standard 10x AnnData of the spot grid. Works after :meth:place_grid (the placed grid on

capture_shape staticmethod

capture_shape(spot_pitch=2.0)

(rows, cols) extent of the v1 capture area, in the units spot_pitch is given in.

With spot_pitch in deme-widths this is the window of tissue one slide covers, so it is what to pass to tumor.primary_window(side=...) to section exactly one capture area::

win = Visium.capture_shape(spot_pitch=2.0)          # (110, 156) demes
tumor.make_cell_data(region=tumor.primary_window(side=win, center=...))

The area is wider than it is tall (78 x 64 spots), so a tall section captures far more of itself placed on the slide at rotation=90.

place_grid

place_grid(cell_data, grid_side=None, px=6)

Place the fixed spot grid on a section WITHOUT assaying it, and store the placement.

Lays the slide over the (placed, optionally rotated) section, records which spots cover tissue, and renders the section's H&E over its whole extent. Afterwards :meth:to_anndata returns a standard 10x AnnData of the spot grid on the full H&E — with an in_tissue flag but ZERO expression — ready to plot with squidpy/scanpy to judge the placement before assaying::

vz.place_grid(section)
sq.pl.spatial_scatter(vz.to_anndata(), color="in_tissue", img=True)   # check the placement
vz.run()                                                              # then assay it

:meth:run calls this itself if you did not, and reuses it if you did.

Parameters:

Name	Type	Description	Default
cell_data	dict	The section to image (e.g. from :meth:Resection.slice).	required
grid_side	int	Capture-area side; None (default) uses the fixed v1 slide.	None
px	int	Pixels per coordinate unit for the H&E image (only rendered when section_frac is set).	6

section_image

section_image(cell_data, grid_side=None, px=6)

Render the placed tissue section as an H&E-like image, without running the assay.

Preview the slide's tissue morphology before assaying it. This runs the same :meth:place_grid step the assay uses (frame, placement, rotation and px all match), so the returned image is byte-identical to the img=True background of the AnnData that :meth:to_anndata / :meth:run produce. It also leaves the grid placed, so a following :meth:run (with no argument) reuses this exact placement. Requires section_frac to be set (otherwise there is no placement to render).

Parameters:

Name	Type	Description	Default
cell_data	dict	The section to image (uses cell_deme + cell_crd).	required
grid_side	int	Capture-area side; None (default) uses the fixed v1 slide (4,992 spots).	None
px	int	Pixels per coordinate unit (must match :meth:place_grid to align with the assay).	6

Returns:

Type	Description
(ndarray, shape(H, W, 3), float32)	The H&E-like tissue-morphology image (see :func:iscc.sample.tissue_image).

run

run(cell_data=None, grid_side=None)

Assay a 10x Visium spatial-transcriptomics section over the placed spot grid.

The slide is a fixed capture grid laid over the section (see :meth:place_grid): it pools each spot's cells, applies lateral mRNA diffusion and a smooth spatial capture field, and draws per-spot UMI counts. If you called :meth:place_grid first, run reuses that placement; otherwise pass the section here and run places it itself (per placement / rotation). A morphology tissue image is attached to :meth:to_anndata for img=True overlays.

Parameters:

Name	Type	Description	Default
cell_data	dict	The section to assay; omit only if :meth:place_grid was already called. Passing it (re-)places the grid.	None
grid_side	int	Capture-area side; None (default) uses the fixed 10x v1 slide (4,992 spots).	None

Returns:

Type	Description
Visium	self, with the spot-by-gene UMI matrix in spot_counts etc. Export with :meth:to_anndata / write.

to_anndata

to_anndata()

Standard 10x AnnData of the spot grid. Works after :meth:place_grid (the placed grid on the H&E, X all zero — just the placement) or after :meth:run (with UMI counts).

Technology presets

Platform	Parameters	Notes
10x Visium	defaults (spot_pitch = 2, spot_radius = 1, mu_counts ≈ 20000)	~55 µm spots, ~1–10 cells / spot.
Visium HD	smaller spot_pitch / spot_radius, lower mu_counts	High-resolution (near-single-cell): many more, smaller spots.