SpotClean

Workflows

Standard Workflow

Load raw 10x Visium Space Ranger output, perform decontamination, visualize results, and convert to a Seurat object.

library(SpotClean)
library(S4Vectors)

# 1. Load raw data and slide information
data(mbrain_raw)
spatial_dir <- system.file(file.path("extdata", "V1_Adult_Mouse_Brain_spatial"), package = "SpotClean")
mbrain_slide_info <- read10xSlide(
  tissue_csv_file = file.path(spatial_dir, "tissue_positions_list.csv"),
  tissue_img_file = file.path(spatial_dir, "tissue_lowres_image.png"),
  scale_factor_file = file.path(spatial_dir, "scalefactors_json.json")
)

# 2. Create the slide object
slide_obj <- createSlide(count_mat = mbrain_raw, slide_info = mbrain_slide_info)

# 3. Visualize raw data
visualizeSlide(slide_obj = slide_obj)
visualizeHeatmap(slide_obj, "Mbp")

# 4. Decontaminate raw data
decont_obj <- spotclean(slide_obj, maxit = 10, candidate_radius = 20)

# 5. Visualize decontaminated gene and contamination rate
visualizeHeatmap(decont_obj, "Mbp")
visualizeHeatmap(
  decont_obj, 
  metadata(decont_obj)$contamination_rate,
  logged = FALSE, 
  legend_title = "contamination rate",
  legend_range = c(0, 1)
)

# 6. Convert to Seurat object
seurat_obj <- convertToSeurat(decont_obj, image_dir = spatial_dir)

Input: Raw count matrix and 10x Visium slide metadata. Output: A decontaminated Seurat object ready for downstream analysis.

Spatial Experiment Workflow

Decontaminate spatial transcriptomics data stored in a SpatialExperiment object.

library(SpotClean)
library(SpatialExperiment)

# Assuming slide_obj is a SpatialExperiment loaded with read10xVisium(..., data = "raw")
# slide_obj <- read10xVisium(samples = "/path/to/spaceranger/output/", data = "raw")
# decont_obj <- spotclean(slide_obj)

Input: A SpatialExperiment object containing raw spatial transcriptomics data. Output: A decontaminated SpatialExperiment object.

When to Use

• Adjusting for spot swapping (mRNA bleed) in 10x Visium spatial transcriptomics data using spotclean().
• Estimating the ambient RNA contamination lower bound in spatial transcriptomics or droplet-based single-cell data using arcScore().
• Visualizing spatial spot labels and gene expression heatmaps in 2-D slide space using visualizeLabel() and visualizeHeatmap().
• Converting decontaminated slide objects into Seurat spatial objects using convertToSeurat().

When NOT to Use

• When almost all spots on the slide are covered by tissue (less than 25% background spots), as spotclean() relies on background spots to estimate contamination.
• For normalizing sequencing depth directly, as spotclean() reassigns UMIs and changes estimated sequencing depth, which may conflict with standard depth normalization.
• For analyzing extremely lowly-expressed genes with high sparsity, where there is insufficient information to confidently reassign UMIs.

Data Requirements

• Raw gene-by-spot count matrix (e.g., loaded via read10xRaw()).
• Slide metadata including spot positions, scale factors, and low-resolution tissue images (e.g., loaded via read10xSlide()).
• Alternatively, a SpatialExperiment object constructed with data = "raw".

Key Parameters

• count_mat: The raw gene-by-spot count matrix passed to createSlide().
• slide_info: Slide metadata list passed to createSlide().
• maxit (30): Maximum number of iterations for the decontamination optimization in spotclean().
• candidate_radius: Candidate contamination search radius evaluated by spotclean().
• image_dir: Directory containing spatial images passed to convertToSeurat().
• logged (TRUE): Logical flag in visualizeHeatmap() to apply log-scaling to the heatmap values.

Best Practices

• Ensure that the input dataset has at least 25% of spots unoccupied by tissue to allow robust contamination estimation from background spots.
• Always use raw (unfiltered) count matrices as input to spotclean(), specifying data = "raw" if loading via read10xVisium().
• Visualize raw gene expression using visualizeHeatmap() before and after running spotclean() to verify the reduction of background noise.

Common Pitfalls

• Insufficient background spots: Running spotclean() on slides with nearly 100% tissue coverage leads to unreliable contamination estimates; ensure at least 25% of spots are background.
• Applying to pre-filtered/normalized data: Using normalized or tissue-selected counts instead of raw counts; fix by loading raw data with read10xRaw() or read10xVisium(..., data = "raw").

Alternatives

• Seurat: For general spatial transcriptomics downstream analysis and clustering.
• scater: For single-cell and spatial QC and visualization.
• scran: For variance modeling and normalization of single-cell/spatial data.

Citations

• Ni, Z., Prasad, A., Chen, S. et al. SpotClean adjusts for spot swapping in spatial transcriptomics data. Nat Commun 13, 2971 (2022). https://doi.org/10.1038/s41467-022-30587-y

References

• Homepage: bioconductor.org/packages/spotclean
• Vignette: https://bioconductor.org/packages/release/bioc/vignettes/spotclean/inst/doc/SpotClean.html