GSoC 2026 Final Work Product — StaR

Contributor: Xindi Wei Mentor: Ziheng Duan Organisation: UC Santa Cruz Open Source Program Office (UC OSPO) / OSRE 2026 Project: StaR — A Stability-Aware Representation Learning Framework for Spatial Domain Identification Code: this repository (star/, scripts/, slurm/) License: MIT

In one sentence: we showed that state-of-the-art spatial-domain methods are far more sensitive to the random seed than the published gaps between them, and we built a model — StaR — that removes most of that sensitivity while also being the most accurate of the six methods compared.

If you only read one thing, read Results; if you only run one thing, run python scripts/smoke_test.py.

1. Project goals

The proposal set out to address a reproducibility problem in spatial transcriptomics. Graph neural network (GNN) methods for spatial domain identification — partitioning a tissue section into biologically coherent regions — are benchmarked as if they were deterministic, but their output depends on the random seed. The proposed goals were:

1. Quantify seed sensitivity across leading GNN methods at a scale large enough to be conclusive.
2. Implement a deterministic spatial prior that all seeds are pulled toward.
3. Integrate it into a variational objective via KL regularisation.
4. Add optimisation-side stabilisers (β-annealing, Stochastic Weight Averaging).
5. Run comprehensive benchmarking and mechanistic ablations.

All five were completed. Goal 4 completed with a negative result, which is reported as such — see §6.

2. What was delivered

3. Results

3.1 Seed sensitivity is large enough to invalidate single-seed benchmarks

Five published methods were run with 1,000 independent seeds on each of the 12 DLPFC sections. Pooled coefficient of variation (CV) of ARI ranges from 14.4% to 27.0%. On section 151669 STAGATE reaches CV = 28.4% — roughly a third of its reported accuracy is seed noise, which is larger than the published gaps between competing methods.

3.2 StaR: accuracy and worst-case reproducibility

DLPFC, all six methods, 1,000 seeds × 12 sections (12,000 pooled runs each):

StaR leads on mean, median, P5 and P95, and beats the strongest baseline (GraphST) on all 12 sections (Wilcoxon signed-rank p = 0.0002). Note the honest caveat: StaR is not the lowest-variance method — GraphST is — but StaR’s distribution stochastically dominates GraphST’s at every percentile, so the wider spread is upward reach, not downside risk.

3.3 Ablation: the structured prior does the work

Leave-one-out on the full benchmark (12 sections × 50 seeds):

Removing the structured prior collapses accuracy and more than doubles inter-seed CV. The two optimisation-side stabilisers do nothing measurable.

3.4 Two follow-ups that sharpen the story

• Clustering the prior directly — no VAE training at all — already reaches 0.534 mean ARI on DLPFC, above every baseline, at zero seed variance.
• The VAE earns its keep when genes are scarce. As highly variable genes drop from 3,000 (Visium) to 200 (targeted-panel / imaging scale), the static prior collapses while StaR holds: the gap grows from +0.015 to +0.277 ARI.

3.5 Generalisation to a different platform and tissue

MOSTA Stereo-seq adult mouse hemibrain (10,000 spots, 19 anatomical regions), 20 seeds, using the DLPFC hyperparameters unchanged:

StaR’s worst 5% of seeds still beat the mean of every other method.

4. The code contribution

Everything in this repository is work produced for this project. Nothing is vendored from upstream projects; the baselines are invoked through their own published packages.

4.1 Library — star/

The core idea in two lines:

mu_prior = (I + alpha * L_norm)^{-1} PCA(X)      # deterministic, identical for every seed
ELBO     = || X - X_hat ||^2  +  beta * KL( q(z|X,G) || N(mu_prior, I) )

Library defaults are the canonical configuration behind every number in §3 (alpha=0.5, beta_max=0.05, SWA from epoch 600, 800 epochs, Mclust seed 2020), so train_star(data, adata) with no arguments reproduces the reported setup.

4.2 Experiments — scripts/

5. Reproducing the work

git clone https://github.com/GITHUB_USER/StaR.git
cd StaR
conda create -n star python=3.8 -y && conda activate star
pip install -r requirements.txt && pip install -e .
# R side, for the Mclust readout:  install.packages("mclust")

# 1. Verify the install (no dataset needed, ~30 s on CPU)
python scripts/smoke_test.py

# 2. Point at the data (see README for where to download it)
export STAR_DATA_ROOT=/path/to/10XVisium/DLPFC

# 3. Reproduce the main benchmark, then the tables
sbatch slurm/sbatch_star_1000.sh
python scripts/analyze_1000seed.py

Every result in §3 is derived from per-seed ARI CSVs written by the runner scripts; analyze_1000seed.py recomputes the tables from those CSVs, so a reviewer can check the statistics without re-running 72,000 trainings. A single StaR run on one DLPFC section (≈4,000 spots, 800 epochs) takes about 1.5 minutes on an A100, comparable to STAGATE.

6. Challenges and lessons learned

Compute orchestration at benchmark scale. 72,000 training runs on a shared SLURM cluster only works if every job is resumable. The runners checkpoint to per-seed CSVs and skip completed seeds on restart, so a pre-empted node costs minutes rather than days.

Making the comparison genuinely fair. A stability claim is worthless if the comparison is rigged. Every baseline runs with its authors’ recommended settings, its own seed propagated through NumPy, PyTorch and R, and the same Mclust readout with a fixed clustering seed — so the variance we report comes from network initialisation alone, not from the clustering step. A large share of the project went into this rather than into the model.

The ablation contradicted part of the proposal, and that became a result. The proposal weighted the deterministic prior, KL regularisation and the optimisation tricks (SWA, β-annealing) roughly equally. The ablation showed the optimisation tricks contribute nothing measurable (Δ ARI = +0.001, p = 0.63) and the prior does essentially all the work. They are kept in the codebase as optional, off-by-default-irrelevant components and reported honestly rather than quietly retained as decoration.

Red-teaming our own method produced the most interesting finding. Asking “what if the VAE isn’t needed at all?” showed the deterministic prior alone nearly matches the full model on Visium data. Rather than bury that, we went looking for the regime where the VAE does matter and found it: sparse gene coverage, where the gap grows to +0.277 ARI. That result only exists because we tried to falsify our own contribution.

7. Current state and what remains

Working today: the model, all six-method benchmarks, the ablations, the generalisation study and every figure and table can be regenerated from this repository given the public datasets.

Known limitations, stated plainly:

• The prior is built from a dense pairwise distance matrix, which is O(N²) in memory. It is fine up to ~10,000 spots but needs a sparse/k-NN formulation for whole-slide imaging-based data.
• Hyperparameters (α = 0.5, β_max = 0.05) were tuned on DLPFC only and carried over unchanged elsewhere. They transfer well to Stereo-seq, but this is one transfer, not a guarantee.
• Generalisation evidence beyond DLPFC currently rests on a single additional dataset.
• The number of domains K is supplied by the user, as with all compared methods.

Next steps, in priority order:

1. Sparse k-NN prior construction to lift the O(N²) ceiling.
2. Broader benchmarking across platforms and organisms (Xenium, MERFISH, non-brain tissue).
3. Test the structured prior as a drop-in stabiliser inside other backbones (STAGATE, GraphST) — the original “plug-in framework” ambition of the proposal, now with evidence about which component to plug in.

Anyone picking this up should start at star/model.py; items 2 and 4 are both localised to compute_spatial_prior.

8. Data availability

No data is redistributed here. The DLPFC benchmark (12 × 10x Visium sections, 151507–151676) comes from spatialLIBD; the generalisation dataset is the MOSTA Stereo-seq adult mouse hemibrain. Point STAR_DATA_ROOT and STAR_STEREOSEQ_ROOT at your local copies.

9. Acknowledgements

Thanks to my mentor Ziheng Duan for the guidance and compute, and to UC OSPO / CROSS and the OSRE 2026 program for supporting this work.