Fix: Critical updates for Seurat v5, spacexr 2.0, and robust spot alignment

[Atakannl]

Hi VoltRon team,

While utilizing getDeconvolution() for a GBM spatial analysis, I encountered breaking compatibility issues with Seurat v5 (layer handling) and spacexr 2.0+ (Reference object requirements).

This PR implements the following fixes to modernize the vrDeconvolution module while maintaining strict backward compatibility:

Seurat v5 Support: Added a check for JoinLayers to correctly handle count retrieval (layer="counts" vs slot="counts"), fixing the "slot 'counts' not found" error.

spacexr 2.0 Compliance:

• Implemented the native spacexr::Reference constructor for v2.0+ users.

• Updated getRCTD to use the SpatialRNA constructor with data.frame coordinates (required by v2.0).

• Preserved the legacy SpatialExperiment path for users on older versions.

Robust Spot Alignment: Added logic to align RCTD results back to the original VoltRon spot IDs. This fixes issues where RCTD drops spots during QC or sanitizes barcodes (e.g., changing - to .), which previously resulted in dimension mismatches or silent data loss.

Safety Validations:

• Added explicit checks for sc.cluster existence in metadata to prevent cryptic errors.

• Added hard failure stops if spot alignment finds zero matches.

I have verified these fixes on a merged GBM cohort using both Seurat v5 and spacexr v2.2.1.

Thanks for the great tool!

[Artur-man]

Thanks so much for the PR @Atakannl, I will review this one with my use cases and get back to you! Artür

[Artur-man]

Dear @Atakannl, thanks so much for the PR. Can you take a look at my review and correct if can.

In summary, i do not believe we should implicitly join layers of a Seurat object. I would rather mention this in the documentation/tutorial, you can attempt this for the doc/rmd of the website which is here in the package too.

I would explain that people who use v5 should join layers first (I find the need to do JoinLayers in Seurat pretty annoying btw)

VoltRon/docs/nicheclustering.Rmd

Lines 289 to 311 in ecd8f23

	Thus, we first deconvolute spots into cells using a single cell reference in order to later use the resultsing cell type abundances per each spot for clustering.
	We will use the public single nucleus RNA-seq (snRNA-seq) data from available [here](https://libd-snrnaseq-pilot.s3.us-east-2.amazonaws.com/SCE_DLPFC-n3_tran-etal.rda). See [(Tran, Maynard, Spangler et al., 2021)](https://linkinghub.elsevier.com/retrieve/pii/S0896-6273(21)00655-3) for more information.
	We will use this reference for deconvoluting each Visium across
	each for Visium assay in the VoltRon object. See [Niche Clustering](nicheclustering.html)
	tutorial for more information on spot deconvolution.
	```{r class.source="watch-out", eval = FALSE}
	# single cell reference
	load("SCE_DLPFC-n3_tran-etal.rda")
	# prepare reference
	tab <- table(sce.dlpfc.tran$cellType)
	sce.dlpfc.tran <- sce.dlpfc.tran[,sce.dlpfc.tran$cellType %in% names(tab)[tab > 25]]
	sce.dlpfc.tran.seu <- Seurat::as.Seurat(sce.dlpfc.tran)
	# Spot deconvolution
	library(spacexr)
	SRBlock <- readRDS("Visium&Visium_data_registered.rds")
	SRBlock <- getDeconvolution(SRBlock, sc.object = sce.dlpfc.tran,
	sc.cluster = "cellType", max_cores = 2)
	SRBlock
	```

[Atakannl]

Thanks for the suggestion @Artur-man . I removed the implicit JoinLayers call and now explicitly check for multi-layer assays in Seurat v5. If multiple layers are detected, the user is instructed to run JoinLayers beforehand. No automatic layer modification is performed anymore. I will also add a note to the documentation for Seurat v5 users.

[Atakannl]

I added the Seurat v5 compatibility note to both RCTD sections in the niche clustering vignette. The documentation now explicitly states that users must run SeuratObject::JoinLayers() before calling getDeconvolution() when multiple assay layers are present. @Artur-man

[Artur-man]

@Atakannl thanks so much. I have left some comments I think this PR would make VoltRon comply with Seurat v5 and recent version of spacexr. We should only make the PR a bit cleaner and reduce unnecessary if statements, otherwise I like it.

If you like I can resolve the conflicts for you, then you can continue updating.

[Atakannl]

That would be great, @Artur-man, thank you. I will continue refining the conditional logic once the conflicts are resolved.

[Artur-man]

@Atakannl ready for you now. Let me know if you have any questions.