The results in this repository accompany a manuscript that has not been submitted, reviewed or published. They should be treated as a preprint-grade research artefact. Nothing here has been independently verified, and the analysis module that produced the model results is no longer available (see
REPRODUCIBILITY.md). Please do not cite these numbers as established findings.
Transcriptomic cartography of periodontal bone-destructive niches from 10x Visium data
A biology-constrained spatial graph-transformer that reconstructs a continuous, spatially resolved field of inferred destructive potential from spatial transcriptomics alone, without paired radiographic supervision.
What this model does not do. It maps the transcriptome to a continuous scalar field over tissue coordinates. It is not image reconstruction and produces no image of bone. The tissue analysed is oral mucosa and contains no alveolar bone; no radiographic, tomographic or histomorphometric ground truth exists for this or any comparable periodontal spatial transcriptomic dataset; and no output was ever compared against an image of a mineralised structure. The names
DefectFieldDecoderandBioSpATIAL-DefectNetare historical, kept so the specification matches the archived code, and are not descriptive of the outputs.On the decoded outputs. It does not predict bone-loss geometry. The reconstructed fields represent biologically inferred destructive potential derived from transcriptomic gene programme activity; they are not measurements of alveolar crest height, probing depth, defect morphology, or any other structural clinical endpoint. No radiographic or histological ground truth was available at any stage of this study. The high-risk region mask and risk-gradient map are uncalibrated biological risk proxies and must not be treated as radiographic measurements.
| Path | What it holds |
|---|---|
notebooks/BioSpATIAL_analysis.ipynb |
The end-to-end analysis on GSE206621 that produced every reported figure, table and statistic |
results/ |
The committed result artefacts underlying the manuscript — training history, cross-validation results, per-section metrics, gene programme coverage, ranked gene signatures |
docs/ARCHITECTURE.md |
Full specification of the seven modules and their parameter counts |
docs/RESULTS.md |
Every headline number, with the file it is derived from |
docs/FIGURE_PROVENANCE.md |
How every figure was produced, and which ones must be replaced before submission |
analysis/ |
Post-hoc signature and stability analyses — fully reproducible from the committed CSVs, no lost module required |
REPRODUCIBILITY.md |
Read this before attempting to reproduce anything. States exactly what is and is not available |
legacy_sn2d/ |
A superseded prototype (SpatialNiche2Defect). Not the model described in the manuscript. See its README |
This repository does not currently contain a runnable implementation of BioSpATIAL-DefectNet.
The model, preprocessing and programme-scoring code used to generate the reported results lived
in a single module, BioSpATIAL_DefectNet.py, which has been lost from the authors' working
environment. The architecture is fully specified in the manuscript, in docs/ARCHITECTURE.md and
in results/table5_architecture.csv, and the analysis notebook records every call made against
it — but bit-exact reproduction of the reported values is not currently possible.
REPRODUCIBILITY.md sets this out in full, including what would be required to rebuild it.
Seven jointly optimised modules, 2,846,577 parameters, six loss objectives.
Visium spots (N x 2000 HVGs + N x 2 coordinates)
|
v (i) BiologicalProgramEncoder 273,926 params
2000-d expression -> 6-d biology score vector per spot
|
v (ii) SpatialGraphBuilder 1 param
k-NN graph over tissue coordinates (k = 8), single learnable
scalar alpha balancing spatial proximity vs expression cosine similarity
|
v (iii) SpatialGraphEncoder 327,136 params
3-layer GAT, 4 heads, 128-d, sinusoidal coordinate injection per layer
|
v (iv) NicheCrossAttention 215,936 params
4-head cross-attention: graph embeddings (Q) x biology scores (K, V)
|
v (v) MorphologyTransformer 843,392 params
top-64 highest-risk spots -> 4-layer transformer -> section embedding
|
v (vi) DefectFieldDecoder 1,152,259 params
64 x 64 continuous destructive-potential field + binary mask (75th pct) + risk-gradient map
|
v (vii) BiologyConsistencyHead 33,927 params
section-level destructive burden + per-programme contributions
See docs/ARCHITECTURE.md for the full specification and results/table5_architecture.csv
for the parameter table as reported.
No dataset pairs spatial transcriptomics of periodontal tissue with co-registered radiographic bone-loss measurements. The supervised-learning impasse this creates is resolved with a biology-constrained surrogate target: six curated gene programmes, combined into a per-spot score
D = 0.25*P_inflammation
+ 0.25*P_osteoclast_matrix
+ 0.15*P_fibro_inflammatory
+ 0.15*P_epithelial_barrier
+ 0.10*P_angiogenic_stress
- 0.10*P_regeneration
min-max normalised to [0, 1] within each section. The 29 unique genes are listed in
docs/ARCHITECTURE.md.
Two properties govern the interpretation of every result in this repository.
-
D is a deterministic function of genes the model also receives as input. Concordance between prediction and D therefore measures structured reconstruction of a handcrafted composite, not prediction of an external outcome.
-
The epithelial barrier programme dominates D. It is the only programme detected in full (4/4 genes) in every section, and supplies 78.6% of the positive mass of mean D across the cohort — 88.4% in cryosections, where the inflammation, osteoclast–matrix and angiogenic programmes were undetectable. In cryopreserved material D is close to a four-gene epithelial score (
KRT6A,KRT16,S100A8,S100A9), and those four genes cannot serve as independent markers of the risk architecture the model learns.
| Metric | Value |
|---|---|
| Full-training Pearson r | 0.9623 (range 0.8803–0.9977) |
| Full-training Spearman rho | 0.9689 (range 0.8976–0.9979) |
| Permutation test | Z = 44.3 (Pearson), Z = 46.0 (Spearman), p < 0.01 |
| Mean risk separation | 0.425 |
| LOSO-CV Pearson r | 0.015 +/- 0.208 — not distinguishable from zero (one-sample t-test p = 0.853) |
| LOSO-CV Spearman rho | 0.043 +/- 0.186 (p = 0.560) |
| Cryo -> FFPE transfer | r = 0.004, -0.090, 0.142, -0.148 |
| FFPE -> cryo transfer | r = -0.078, -0.025, 0.013, 0.142 |
| Gene programme coverage | FFPE 84.1% vs cryo 25.8% — a 3.3-fold advantage |
Why cross-section generalisation fails. Highly variable genes were selected independently within each section and the resulting matrices zero-padded to a common width of 2,000. Feature index j therefore denotes a different gene in each section, and no shared expression space exists across folds. Cross-section transfer is limited by the encoding itself; the LOSO-CV result is a floor on transferability, not a property of the architecture or of the cohort size. Re-training on a shared gene space — the intersection of per-section HVGs together with the full curated programme set — is the primary methodological priority for the next iteration.
Per-programme reconstruction is confined to what dominates the target. Only the fibro-inflammatory (r = 0.545) and epithelial barrier (r = 0.407) programmes are recovered above chance. The three programmes carrying the mechanistic core of bone destruction are recovered at or below chance: inflammation (r = -0.109), osteoclast–matrix (r = -0.234), angiogenic stress (r = -0.003). The reconstructed fields encode epithelial and fibro-inflammatory activity, not osteoclastic activity.
The BiologyConsistencyHead collapsed. It predicted an identical section-level burden (0.515) for all eight sections, i.e. it converged to the cohort mean rather than to section-specific estimates. This module did not perform its intended function; it is reported as a negative architectural result.
Of the 160 top-ranked risk gene entries across the eight sections, 31 correspond to genes that carry weight in a programme used to build D, and 129 (81%) do not. The out-of-target genes do not appear as scattered noise but as three coherent, section-specific transcriptional modules:
| Section | Module | Representative genes (log2FC) |
|---|---|---|
| A2 | Cornified envelope | SPRR2A (1.95), SPRR3 (1.93), SPRR1A (1.83), CRNN (1.83), SPRR2E (1.82), TGM3 (1.81), CNFN (1.80) |
| C2 | Fibroblast–ECM | IGFBP4 (3.32), LUM (3.01), SPARC (2.98), CFD (2.96), AEBP1 (2.91), TIMP2 (2.82), COL6A2 (2.74) |
| B2 | Immune–vascular | FDCSP (2.33), RHCG (1.50), IL36G (1.47), FOSB (1.29), NFKBIA (1.25), CLDN4 (1.24), IL1RN (1.21) |
Two further analyses (analysis/, fully reproducible from the committed CSVs) sharpen this:
- Programme genes dominate the head of every signature — mean rank 5.8 vs 11.6 for out-of-target genes (Mann-Whitney p = 4.1e-7); they hold 52% of rank-1..5 slots while being 19% of entries. The top of the signature is substantially a readout of the target.
- But the between-section heterogeneity is not. Programme genes are 8.6-fold associated with pan-section rather than section-specific occurrence (Fisher p = 0.017).
- And that heterogeneity is biological, not technical. Tested two ways. Categorically: mean signature overlap is 0.073 among the four technically matched, gene-rich FFPE sections against 0.406 among the gene-poor cryosections (Mann-Whitney p = 0.0023). Continuously, over all 28 section pairs: pair mean sequencing depth predicts overlap at Spearman rho = -0.486 (p = 0.0087) — deeper sequencing gives less overlap, the opposite of what a detection-depth artefact predicts — while the absolute difference in depth predicts nothing (rho = -0.110, p = 0.577). Two FFPE pairs share no top-20 gene at all.
- The region mask carries no information. It is the field thresholded at its own 75th percentile, so it covers 25% of every section with zero variance. A percentile operation, not a segmentation.
What is not established: that the heterogeneity comes from the architecture rather than from D itself. Reconstructed risk tracks D at r = 0.962, so thresholding on D directly would select a largely overlapping spot set. The no-graph ablation needed to separate them requires the per-spot outputs and the lost module.
This is evidence of learned tissue context, not external validation. These modules are
co-expression neighbours of the target genes. S100A8, S100A9, KRT6A and KRT16 are
constituents of the epithelial barrier programme; their appearance among the top-ranked risk
genes is an expected consequence of the target definition and carries no independent evidential
weight.
All spatial transcriptomic data are public: NCBI GEO accession GSE206621 — eight 10x Visium sections of human oral mucosa (four cryopreserved: A1, B1, C1, D1; four FFPE: A2, B2, C2, D2).
Subject status, read from the series SOFT record, is five healthy and three periodontitis:
A1, B1, C1, D1 and A2 are healthy; B2, C2 and D2 are periodontitis. The cryopreserved arm is
two subjects each sampled twice — A1/B1 and C1/D1 are declared technical replicate pairs — so
the eight sections derive from six independent biological specimens. The three niche types
reported in the manuscript are carried by the three periodontitis sections; A2 is the healthy
FFPE control. Cross-validation in results/ was partitioned by section and not by subject, so
the four cryopreserved folds are upper bounds. See analysis/disease_stratified_analysis.py.
Raw count matrices are not redistributed here.
- Single dataset, eight sections, no external validation cohort.
- All sections derive from chronic-disease patients; no disease-versus-healthy comparison or severity gradient is available.
- The programme weights are a literature-derived prior, not calibrated against bone loss. Alternative weightings would yield a different target.
- No inter-section batch correction was applied.
- The risk-gradient decoder output is unsupervised and uncalibrated; the region mask is a percentile threshold and carries no section-level information.
- The 90th-percentile signature threshold and 75th-percentile mask threshold were fixed a priori and not subjected to sensitivity analysis; the stability of the three niche modules to these choices is untested.
See CITATION.cff.
MIT — see LICENSE.