Methods and validation
SituCraft implements each method itself, from its publication, and checks it against an independent implementation, published data, or a simulated tissue whose every cell, transcript and type is known. Each method below names its source and what it agrees with.
How methods are checked
Three kinds of check, as each method allows: the same numbers as an independent implementation of the same method, on the same inputs (scanpy, SciPy, Squidpy and the like, run by the validation suite and recorded in the repository); the truth of a simulated tissue, whose cells, transcripts, types, domains and image placements are known; and invariants worked by hand on small cases. The heaviest checks run every week. The same inputs and settings give the same bytes on any computer, so a result recorded once is checked again exactly.
| Data | What it is | Used for |
|---|---|---|
| Xenium human Lung and Breast, 2 FOVs | 10x Genomics example data, CC BY 4.0 | Development, the examples, every reader and reference comparison |
| A published breast cancer section with its H&E and immunofluorescence (Janesick et al. 2023) | 10x Genomics, CC BY 4.0 | Xenium Onboard Analysis 1.0 bundles and post-Xenium images |
| Simulated tissues | Made by situcraft simulate, seeded | Accuracy against the truth; scale, up to 55 million transcripts and a million cells |
Bundles and the tissue
SituCraft reads every file of a Xenium bundle with its own readers: Parquet, Zarr, HDF5, TIFF and OME-TIFF with JPEG 2000. Every Parquet column of both development bundles reads as DuckDB reads it, every Zarr array as zarr-python and numcodecs read it, and every TIFF's structure and pixels as tifffile and imagecodecs read them. A bundle's check recomputes 22 of the run's recorded values from its data and reproduces each; thirteen bundles broken one way each raise exactly their findings. The Viewer draws every image sample as the bundle records it: channels read back from the page at several levels equal the derived data's tiles sample for sample. Quantiles in the QC plots are Hyndman and Fan's type 7, and box plots Tukey's.
Segmentation
Nucleus expansion gives each pixel to the nearest nucleus within the distance, by exact Euclidean distance transforms (Felzenszwalb and Huttenlocher 2012). It reproduces the Lung bundle's own 5 µm expansion: the same 11,898 cells, 98.1% of pixels and 98.9% of transcripts in the same cells.
Transcript-informed segmentation is implemented from the model of Jones et al. (2025): each cell a region whose transcripts are a Poisson process with its own rate for each gene, over a background, with expression states and cell sizes as priors; segmentations are sampled from the posterior and summarized, each transcript in its most probable cell with that probability kept, and convergence judged by Geweke's diagnostic. Every update is tested against its analytic posterior. On a simulated tissue it puts 84.7% of transcripts in their true cell, against the instrument's nucleus expansion's 82.2%; in patches it is as accurate (86.1% against 86.3% in one run). Its preflight estimated the memory of a whole run of the Lung example within 5%.
Comparing segmentations pairs cells that share a nucleus, or of which half of one lies in the other, and classes each difference. Two measures read transcripts given to the wrong cell: the spurious co-expression of gene pairs relative to nuclei alone (Jones et al. 2025), and the mutually exclusive co-expression rate of markers of different lineages (Hartman and Satija 2024). On the Lung example, errors planted for practice are found exactly: 60 planted, 60 found, each in its class.
Cell types
Clusters follow scanpy's defaults (Wolf et al. 2018): each cell scaled to the median total and log-transformed, each gene scaled, 50 principal components (computed exactly, or by the Lanczos method for panels above 1,000 genes), 15 nearest neighbors (by NN-Descent, Dong et al. 2011, above 50,000 cells), and Leiden communities (Traag et al. 2019) of modularity with a resolution (Reichardt and Bornholdt 2006). Markers are the rank-sum test's (Mann and Whitney 1947). Against scanpy, leidenalg, umap-learn and scikit-learn on both bundles and the simulated tissue: components within 10⁻¹³, the same neighbors, markers' scores identical to the rank-sum test with exact ties, and on the simulated tissue the clusters agree with the true types (adjusted Rand index 0.95; Hubert and Arabie 1985).
The map is UMAP (McInnes et al. 2018) from a spectral start, its faithfulness measured as trustworthiness (Venna and Kaski 2001): the same as umap-learn's of the same graph, by every measure within its spread over five seeds.
Labels from markers score each cell's markers against control genes of similar expression (Tirosh et al. 2016), as scanpy's score_genes does: every control set scanpy's, every score within 3 × 10⁻⁷, and 97% of the simulated tissue's cells their true type. Labels from a reference correlate each cell with each label's profile and fine-tune among the leading labels, as SingleR does (Aran et al. 2019): given the same profiles, every correlation within 3 × 10⁻⁸ and the same label on 99.97% to 100% of cells. The review queue finds at least 92% of the mislabels planted in the Breast section.
Pathology images
Landmark fits are least-squares similarities (Umeyama 1991) or affine transforms, each landmark with its residual and its leave-one-out error (Stone 1974). Automatic registration separates an H&E's hematoxylin by color deconvolution (Ruifrok and Johnston 2001), finds the scale and turn from log-polar spectra (Reddy and Chatterji 1996) and the shift by phase correlation (Kuglin and Hines 1975), keeps the candidate of highest normalized mutual information (Studholme et al. 1999), refines it by compass search (Hooke and Jeeves 1961), matches patches with sub-pixel phase correlation (Foroosh et al. 2002), and fits a smooth cubic B-spline deformation (Rueckert et al. 1999) when it predicts held-out matches better. On the published section, without their alignments, the H&E and the immunofluorescence image are placed within 0.61 and 0.68 µm of 10x's alignment; on simulated images, within 0.2 µm of the truth, and each checked patch's error is measured within 0.15 µm of its true one. Regions go to and from QuPath (Bankhead et al. 2017) in its GeoJSON: written for QuPath 0.7.0, they open there as written.
Spatial analysis
| Method | Source | Checked against | Agreement |
|---|---|---|---|
| Delaunay, nearest-neighbor, radius and contact graphs | Lee and Schachter 1980; Bowyer 1981; Watson 1981; exact predicates, Shewchuk 1997 | SciPy (Qhull, cKDTree) and Squidpy 1.8.3 | every edge |
| Neighborhood enrichment | Schapiro et al. 2017; Palla et al. 2022 | Squidpy 1.8.3 on the same graphs | every count; every z within its permutation error |
| Co-occurrence | Palla et al. 2022 | Squidpy 1.8.3 | every ratio, in float64 |
| Nearest distances | Diggle 2003 | SciPy's k-d tree | every median and mean |
| Ripley's K and L, isotropic correction | Ripley 1977; Besag 1977 | astropy; the estimator by Ripley's formula | without a correction to 10⁻⁹ |
| Regions compared; across an edge | Garwood 1936; Wilson 1927; Ederer and Mantel 1974; Koopman 1984; Galon et al. 2006 | Shapely; SciPy and statsmodels for the intervals | areas to 2 × 10⁻⁷; every count; intervals to 10⁻⁹ |
| Niches | Goltsev et al. 2018; Schürch et al. 2020; k-means++, Arthur and Vassilvitskii 2007 | scikit-learn's k-means; the simulated tissue's domains | inertia within 0.2%; kinds of domain found, adjusted Rand index 0.92 |
| Moran's I; local Moran's I | Moran 1950; Cliff and Ord 1981; Anselin 1995 | Squidpy 1.8.3; an independent computation of both variances | I to 10⁻¹⁵; variances to 10⁻¹² |
Where a question tests many pairs, labels or genes, its p-values are adjusted by Benjamini and Hochberg's procedure (1995). Under another segmentation, on the simulated tissue, the enrichment of its types and its niches hardly change between its true cells, the instrument's and the refinement's (rank correlation 1.00), while the markers' Moran's I nearly doubles under the instrument's expansion and stays within 0.03 of the truth's under the refinement. At a million generated cells, on four cores, each graph takes seconds and Moran's I with its permutations 88 s in 0.94 GB.
Cohorts
| Method | Source | Checked against | Agreement |
|---|---|---|---|
| Samples far out; the pseudobulk's principal components | Iglewicz and Hoaglin 1993; Love et al. 2014 | numpy 2.5.4 | every score and share to 10⁻¹³ |
| Differential abundance: quasi-binomial and quasi-Poisson models of the design | Wedderburn 1974; McCullagh and Nelder 1989 | statsmodels 0.15.0 (and R's glm) | every coefficient, standard error, t, p and interval to 10⁻⁸ |
| Differential expression: pseudobulk, filtering, TMM, voom and the moderated t | Crowell et al. 2020; Chen et al. 2016; Robinson and Oshlack 2010; Law et al. 2014; Smyth 2004 | limma 3.68.5 and edgeR 4.10.5 (R 4.6.1) | the genes kept; every factor, weight, fold change, t and p within 10⁻⁹ |
| Spatial statistics between groups | Smyth 2004 | limma's lmFit and eBayes; statsmodels' OLS | within 10⁻¹³ |
| The tests' error rates | Squair et al. 2021 | 2,000 simulated null cohorts and 500 with known effects, weekly | 4.7% to 5.5% at 5%; a raised gene's interval covering it in 95.0% of cohorts |
Every comparison of a cohort is of its replicate units, never its cells. Tested cell by cell, the same null cohorts find differences everywhere; see Error rates and scale.
Figures and the record
| Method | Source | Checked against | Agreement |
|---|---|---|---|
| Figures: the tissue's stains composited from their samples, the cells, transcripts and plots drawn as marks, written as SVG, PDF and PNG | SituCraft's own drawing | The suite's own readers of SVG and PDF, its own composite of the tiles' samples, and the Viewer | every mark; every pixel, the Viewer's within one level of 255; no text below 6 pt |
| The methods text, written from the record of each step | SituCraft's record | The projects' own records | every step said, each number the records' own, every reference the project's |
| Certificates: the bundles' files and each step's by SHA-256, fingerprinted over canonical JSON | FIPS 180-4; JSON with its keys sorted, as JSON.stringify writes values | situcraft verify, making each step again on x86-64 and on arm64; copies tampered with | every file bit for bit; each edit found |
| Reports and packages checking themselves offline | RFC 6901 pointers into the certificate | The suite's own reading of every number, figure and text they hold | every number the certificate's; nothing left out found |
A certificate proves that these bundles, analyzed as recorded, give these files and numbers, not that a result is right; see What made a result.
Agents and scripts
| Method | Source | Checked against | Agreement |
|---|---|---|---|
| Cells and transcripts asked for by a tree of conditions (all, any and not), never a query string | SituCraft's own grammar, checked before anything is read | Counts made directly from the bundle's columns and its matrix; 500 random trees read a cell at a time; the 17 filters the window saved on the Lung from 0.1.0 to 0.6.0 | every cell kept, every filter cell for cell |
| Recipes made again without a window | Each step's record: its job and parameters | situcraft run on the same bundle, on any number of threads and on x86-64 and arm64; situcraft verify | the same ids and files, bit for bit; verified |
An agent's session through situcraft mcp | The Model Context Protocol, 2024-11-05 to 2025-11-25 | Every tool called over stdio in a headless window, with no model, in CI | every tool answering; the read-only ones changing nothing; every call logged; the guide's numbers |
| The agent benchmark's tasks | Simulated truth; the Lung bundle's own tables | A reference solution for each, through the same tools, and an agent answering nothing | 100% and 0% |
An agent's and a script's tools are SituCraft's own actions: what they compute is validated above. What is checked here is that they ask and answer as the window does, and that a result made again without it is the same.
Cite SituCraft
If you use SituCraft in your research, please cite it (the repository's CITATION.cff), with its version, the methods you used as its methods section lists them, and a result's certificate by its fingerprint:
McDermott R. SituCraft: a local-first workbench for imaging-based spatial transcriptomics. Version 0.9.0. https://github.com/robert-mcdermott/situcraftReferences
- Anselin L. Local indicators of spatial association: LISA. Geogr Anal 1995;27:93–115.
- Aran D, Looney AP, Liu L, et al. Reference-based analysis of lung single-cell sequencing reveals a transitional profibrotic macrophage. Nat Immunol 2019;20:163–172.
- Arthur D, Vassilvitskii S. k-means++: the advantages of careful seeding. SODA 2007:1027–1035.
- Bankhead P, Loughrey MB, Fernández JA, et al. QuPath: open source software for digital pathology image analysis. Sci Rep 2017;7:16878.
- Benjamini Y, Hochberg Y. Controlling the false discovery rate. J R Stat Soc B 1995;57:289–300.
- Besag J. Contribution to the discussion of Dr Ripley's paper. J R Stat Soc B 1977;39:193–195.
- Bowyer A. Computing Dirichlet tessellations. Comput J 1981;24:162–166.
- Chen Y, Lun ATL, Smyth GK. From reads to genes to pathways: differential expression analysis of RNA-Seq experiments using Rsubread and the edgeR quasi-likelihood pipeline. F1000Research 2016;5:1438.
- Cliff AD, Ord JK. Spatial Processes: Models and Applications. Pion, 1981.
- Crowell HL, Soneson C, Germain P-L, et al. muscat detects subpopulation-specific state transitions from multi-sample multi-condition single-cell transcriptomics data. Nat Commun 2020;11:6077.
- Diggle PJ. Statistical Analysis of Spatial Point Patterns, 2nd ed. Arnold, 2003.
- Dong W, Moses C, Li K. Efficient k-nearest neighbor graph construction for generic similarity measures. WWW 2011:577–586.
- Ederer F, Mantel N. Confidence limits on the ratio of two Poisson variables. Am J Epidemiol 1974;100:165–167.
- Felzenszwalb PF, Huttenlocher DP. Distance transforms of sampled functions. Theory Comput 2012;8:415–428.
- Foroosh H, Zerubia J, Berthod M. Extension of phase correlation to subpixel registration. IEEE Trans Image Process 2002;11:188–200.
- Galon J, Costes A, Sanchez-Cabo F, et al. Type, density, and location of immune cells within human colorectal tumors predict clinical outcome. Science 2006;313:1960–1964.
- Garwood F. Fiducial limits for the Poisson distribution. Biometrika 1936;28:437–442.
- Goltsev Y, Samusik N, Kennedy-Darling J, et al. Deep profiling of mouse splenic architecture with CODEX multiplexed imaging. Cell 2018;174:968–981.
- Hartman A, Satija R. Comparative analysis of multiplexed in situ gene expression profiling technologies. bioRxiv 2024. doi:10.1101/2024.01.11.575135.
- Hooke R, Jeeves TA. "Direct search" solution of numerical and statistical problems. J ACM 1961;8:212–229.
- Hubert L, Arabie P. Comparing partitions. J Classif 1985;2:193–218.
- Iglewicz B, Hoaglin DC. How to Detect and Handle Outliers. ASQC Quality Press, 1993.
- Janesick A, Shelansky R, Gottscho AD, et al. High resolution mapping of the tumor microenvironment using integrated single-cell, spatial and in situ analysis. Nat Commun 2023;14:8353.
- Jones DC, Elz AE, Hadadianpour A, Ryu H, Glass DR, Newell EW. Cell simulation as cell segmentation. Nat Methods 2025;22:1331–1342.
- Koopman PAR. Confidence intervals for the ratio of two binomial proportions. Biometrics 1984;40:513–517.
- Kuglin CD, Hines DC. The phase correlation image alignment method. Proc IEEE Conf Cybernetics and Society 1975.
- Law CW, Chen Y, Shi W, Smyth GK. voom: precision weights unlock linear model analysis tools for RNA-seq read counts. Genome Biol 2014;15:R29.
- Lee DT, Schachter BJ. Two algorithms for constructing a Delaunay triangulation. Int J Comput Inf Sci 1980;9:219–242.
- Love MI, Huber W, Anders S. Moderated estimation of fold change and dispersion for RNA-seq data with DESeq2. Genome Biol 2014;15:550.
- Mann HB, Whitney DR. On a test of whether one of two random variables is stochastically larger than the other. Ann Math Stat 1947;18:50–60.
- McCullagh P, Nelder JA. Generalized Linear Models, 2nd ed. Chapman and Hall, 1989.
- McInnes L, Healy J, Melville J. UMAP: uniform manifold approximation and projection for dimension reduction. arXiv:1802.03426, 2018.
- Moran PAP. Notes on continuous stochastic phenomena. Biometrika 1950;37:17–23.
- Palla G, Spitzer H, Klein M, et al. Squidpy: a scalable framework for spatial omics analysis. Nat Methods 2022;19:171–178.
- Reddy BS, Chatterji BN. An FFT-based technique for translation, rotation, and scale-invariant image registration. IEEE Trans Image Process 1996;5:1266–1271.
- Reichardt J, Bornholdt S. Statistical mechanics of community detection. Phys Rev E 2006;74:016110.
- Ripley BD. Modelling spatial patterns. J R Stat Soc B 1977;39:172–212.
- Robinson MD, Oshlack A. A scaling normalization method for differential expression analysis of RNA-seq data. Genome Biol 2010;11:R25.
- Rueckert D, Sonoda LI, Hayes C, Hill DLG, Leach MO, Hawkes DJ. Nonrigid registration using free-form deformations: application to breast MR images. IEEE Trans Med Imaging 1999;18:712–721.
- Ruifrok AC, Johnston DA. Quantification of histochemical staining by color deconvolution. Anal Quant Cytol Histol 2001;23:291–299.
- Schapiro D, Jackson HW, Raghuraman S, et al. histoCAT: analysis of cell phenotypes and interactions in multiplex image cytometry data. Nat Methods 2017;14:873–876.
- Schürch CM, Bhate SS, Barlow GL, et al. Coordinated cellular neighborhoods orchestrate antitumoral immunity at the colorectal cancer invasive front. Cell 2020;182:1341–1359.
- Shewchuk JR. Adaptive precision floating-point arithmetic and fast robust geometric predicates. Discrete Comput Geom 1997;18:305–363.
- Smyth GK. Linear models and empirical Bayes methods for assessing differential expression in microarray experiments. Stat Appl Genet Mol Biol 2004;3:3.
- Squair JW, Gautier M, Kathe C, et al. Confronting false discoveries in single-cell differential expression. Nat Commun 2021;12:5692.
- Stone M. Cross-validatory choice and assessment of statistical predictions. J R Stat Soc B 1974;36:111–147.
- Studholme C, Hill DLG, Hawkes DJ. An overlap invariant entropy measure of 3D medical image alignment. Pattern Recognit 1999;32:71–86.
- Tirosh I, Izar B, Prakadan SM, et al. Dissecting the multicellular ecosystem of metastatic melanoma by single-cell RNA-seq. Science 2016;352:189–196.
- Traag VA, Waltman L, van Eck NJ. From Louvain to Leiden: guaranteeing well-connected communities. Sci Rep 2019;9:5233.
- Umeyama S. Least-squares estimation of transformation parameters between two point patterns. IEEE TPAMI 1991;13:376–380.
- Venna J, Kaski S. Neighborhood preservation in nonlinear projection methods: an experimental study. ICANN 2001:485–491.
- Watson DF. Computing the n-dimensional Delaunay tessellation with application to Voronoi polytopes. Comput J 1981;24:167–172.
- Wedderburn RWM. Quasi-likelihood functions, generalized linear models, and the Gauss–Newton method. Biometrika 1974;61:439–447.
- Wilson EB. Probable inference, the law of succession, and statistical inference. J Am Stat Assoc 1927;22:209–212.
- Wolf FA, Angerer P, Theis FJ. SCANPY: large-scale single-cell gene expression data analysis. Genome Biol 2018;19:15.
Credits
The example datasets are 10x Genomics' Xenium V1 human Lung and Breast 2-FOV bundles, and the pathology fixture a section of Janesick et al. (2023), each used under the Creative Commons Attribution 4.0 license; their source and license are linked on each example's card and cited in the methods paragraph. The website, its build and parts of SituCraft's host and library are adapted from MaveScape, by the same author, under the Apache License 2.0.
SituCraft is for research use only. It is not a medical device and makes no diagnostic claims.