# Spotclean

> SpotClean

- Skill: `biomate-ai/spotclean` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/spotclean`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/spotclean/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/spotclean

---


# SpotClean

## Workflows

### Standard Workflow

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

```r
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.

```r
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