# Spotsweeper

> SpotSweeper

- Skill: `biomate-ai/spotsweeper` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/spotsweeper`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/spotsweeper/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/spotsweeper

---


# SpotSweeper

## Workflows

### Standard Workflow

Identify and visualize spatially-aware local outliers based on library size, unique genes, and mitochondrial percentage.

```r
library(SpotSweeper)
library(SpatialExperiment)

# 1. Load example data and drop out-of-tissue spots
spe <- STexampleData::Visium_humanDLPFC()
spe <- spe[, spe$in_tissue == 1]

# 2. Calculate QC metrics using scuttle
rownames(spe) <- rowData(spe)$gene_name
is.mito <- rownames(spe)[grepl("^MT-", rownames(spe))]
spe <- scuttle::addPerCellQCMetrics(spe, subsets = list(Mito = is.mito))

# 3. Identify local outliers
spe <- localOutliers(spe, metric = "sum", direction = "lower", log = TRUE)
spe <- localOutliers(spe, metric = "detected", direction = "lower", log = TRUE)
spe <- localOutliers(spe, metric = "subsets_Mito_percent", direction = "higher", log = FALSE)

# 4. Combine all outliers into "local_outliers" column
spe$local_outliers <- as.logical(spe$sum_outliers) | 
                      as.logical(spe$detected_outliers) | 
                      as.logical(spe$subsets_Mito_percent_outliers)

# 5. Visualize local outliers
library(escheR)
plotQCmetrics(spe, metric = "sum_log", outliers = "local_outliers", point_size = 1.1, stroke = 0.75) +
  ggtitle("All Local Outliers")
```
Input: A `SpatialExperiment` object with raw counts. Output: A `SpatialExperiment` object with identified local outliers annotated in `colData`.

### Technical Artifact Detection

Identify and visualize technical artifacts (such as tissue hangnails) using local variance of mitochondrial metrics across multiple neighborhood sizes.

```r
library(SpotSweeper)

# 1. Load data with artifact
data(DLPFC_artifact)
spe <- DLPFC_artifact

# 2. Visualize raw mitochondrial percentage
plotQCmetrics(spe, metric = "expr_chrM_ratio", outliers = NULL, point_size = 1.1) +
  ggtitle("Mitochondrial Percent")

# 3. Run findArtifacts to identify artifacts
spe <- findArtifacts(
  spe, 
  mito_percent = "expr_chrM_ratio", 
  mito_sum = "expr_chrM", 
  n_order = 5, 
  name = "artifact"
)

# 4. Visualize identified artifacts
plotQCmetrics(spe, metric = "expr_chrM_ratio", outliers = "artifact", point_size = 1.1) +
  ggtitle("Hangnail artifact")
```
Input: A `SpatialExperiment` object containing technical artifacts (e.g., tissue hangnails). Output: A `SpatialExperiment` object with artifact spots labeled in `colData`.

## When to Use
- Detecting spot-level local outliers in spatial transcriptomics data based on library size, unique genes, and mitochondrial percentage using `localOutliers()`.
- Identifying large technical artifacts (such as tissue hangnails) using local variance of mitochondrial metrics across multiple neighborhood sizes with `findArtifacts()`.
- Visualizing spatial QC metrics and highlighting outliers or artifacts using `plotQCmetrics()`.

## When NOT to Use
- For non-spatial single-cell RNA-seq data, as the outlier detection methods rely on spatial coordinates and nearest-neighbor structures.
- When spatial coordinate metadata is missing from the input `SpatialExperiment` object.

## Data Requirements
- A `SpatialExperiment` object containing spatial coordinates and count data.
- Pre-calculated QC metrics (such as sum, detected genes, and mitochondrial percentage) in the `colData` of the object (e.g., added via `scuttle::addPerCellQCMetrics()`).

## Key Parameters
- **metric**: The QC metric column name in `colData` evaluated by `localOutliers()`.
- **direction**: The direction of outlier detection (`"lower"` or `"higher"`) in `localOutliers()`.
- **log**: Logical flag indicating whether to log-transform the metric in `localOutliers()`.
- **mito_percent**: Column name for mitochondrial percentage in `findArtifacts()`.
- **mito_sum**: Column name for mitochondrial sum in `findArtifacts()`.
- **n_order**: Neighborhood order size used to calculate local variance in `findArtifacts()`.
- **name**: Column name to store the identified artifact logical vector in `colData`.
- **outliers**: Column name of outliers to highlight in `plotQCmetrics()`.

## Best Practices
- Filter out out-of-tissue spots (e.g., `spe$in_tissue == 1`) before running outlier detection.
- Log-transform highly skewed metrics like library size (`sum`) and unique genes (`detected`) by setting `log = TRUE` in `localOutliers()`.
- Combine individual outlier logical vectors (e.g., `sum_outliers`, `detected_outliers`) into a single logical column for comprehensive visualization.

## Common Pitfalls
- *Including out-of-tissue spots*: Running `localOutliers()` on background spots can skew the local neighborhood statistics; subset the object to `in_tissue == 1` first.
- *Using raw values for skewed metrics*: Failing to log-transform library size or detected genes can lead to poor outlier detection; ensure `log = TRUE` is set for these metrics.

## Alternatives
- `scuttle`: For standard non-spatial single-cell quality control metrics.
- `escheR`: For custom spatial visualization of transcriptomics data.

## Citations
- Tott, M. (2026). Getting Started with SpotSweeper. R Package Vignette.

## References
- Homepage: bioconductor.org/packages/spotsweeper
- Vignette: https://bioconductor.org/packages/release/bioc/vignettes/spotsweeper/inst/doc/getting_started.html