SpotClean

https://github.com/zijianni/spotclean
Admin
SpotClean is a computational method that adjusts for spot swapping artifacts in spatial...
Tokens:8,576
Snippets:58
Trust Score:5.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install SpotClean from Bioconductor or GitHub

Source: https://context7.com/zijianni/spotclean/llms.txt

Install the stable version from Bioconductor or the latest development version from GitHub. Ensure devtools is installed for GitHub installation.

```r
# Bioconductor
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("SpotClean")

# GitHub (latest development version)
if (!requireNamespace("devtools", quietly = TRUE))
    install.packages("devtools")
devtools::install_github("zijianni/SpotClean",
                         build_manual = TRUE,
                         build_vignettes = TRUE)

library(SpotClean)
library(S4Vectors)   # for metadata()
```

--------------------------------

### Install SpotClean from GitHub

Source: https://github.com/zijianni/spotclean/blob/master/README.md

Installs the development version of SpotClean from GitHub. Requires the devtools package. Builds vignettes for comprehensive documentation.

```r
if(!requireNamespace("devtools", quietly = TRUE))
    install.packages("devtools")

devtools::install_github("zijianni/SpotClean", build_manual = TRUE, build_vignettes = TRUE)
```

--------------------------------

### Install SpotClean from Bioconductor

Source: https://github.com/zijianni/spotclean/blob/master/README.md

Installs the stable version of SpotClean from Bioconductor. Requires the BiocManager package.

```r
if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

BiocManager::install("SpotClean")
```

--------------------------------

### Load SpotClean Package

Source: https://github.com/zijianni/spotclean/blob/master/README.md

Loads the SpotClean package into the current R session after installation.

```r
library(SpotClean)
```

--------------------------------

### Access SpotClean Vignette

Source: https://github.com/zijianni/spotclean/blob/master/README.md

Opens the SpotClean vignette, providing a detailed tutorial and examples of package usage.

```r
vignette("SpotClean")
```

--------------------------------

### Get SpotClean Citation

Source: https://github.com/zijianni/spotclean/blob/master/README.md

Retrieves the citation information for the SpotClean package, useful for academic referencing. Provides a BibTeX entry for LaTeX users.

```r
citation("SpotClean")
```

--------------------------------

### Export Decontaminated Data to Seurat with convertToSeurat

Source: https://context7.com/zijianni/spotclean/llms.txt

Converts a SpotClean slide object to a Seurat Visium object for further analysis. Requires the path to the 10x spatial folder and a slice name. 'filter_matrix = TRUE' is required if the input object contains only tissue spots.

```R
seurat_obj <- convertToSeurat(
    slide_obj     = decont_obj,
    image_dir     = spatial_dir,    # path to 10x spatial/ folder
    slice         = "slice1",       # name for stored image slot
    filter_matrix = TRUE            # keep tissue spots only (required when
)                                   # slide_obj contains only tissue spots)

str(seurat_obj, max.level = 2)
# Formal class 'Seurat'
#  ..@ assays  :List of 1: $ Spatial: ...
#  ..@ images  :List of 1: $ slice1 : ...

# Continue with standard Seurat spatial workflow
library(Seurat)
seurat_obj <- NormalizeData(seurat_obj)
seurat_obj <- FindVariableFeatures(seurat_obj)
seurat_obj <- ScaleData(seurat_obj)
seurat_obj <- RunPCA(seurat_obj)
SpatialFeaturePlot(seurat_obj, features = "Mbp")
```

--------------------------------

### Create SummarizedExperiment Slide Object

Source: https://context7.com/zijianni/spotclean/llms.txt

Combines a count matrix and slide spatial metadata into a SummarizedExperiment object. Genes with average tissue-spot expression below a specified cutoff are filtered out. The raw count matrix is stored in the 'raw' assay slot.

```r
data(mbrain_raw)   # built-in example: top-100 genes, V1_Adult_Mouse_Brain

slide_obj <- createSlide(
    count_mat  = mbrain_raw,
    slide_info = slide_info,
    gene_cutoff = 0.1,    # filter genes with avg tissue expression ≤ 0.1
    verbose     = TRUE
)
```

--------------------------------

### spotclean()

Source: https://context7.com/zijianni/spotclean/llms.txt

Decontaminates spatial expression data by estimating and correcting for spot swapping. It accepts SummarizedExperiment or SpatialExperiment objects and returns a new object with a 'decont' assay and contamination metadata.

```APIDOC
## spotclean() — Decontaminate spot swapping

### Description
The core decontamination function. Accepts a `SummarizedExperiment` slide object (from `createSlide()`) or a `SpatialExperiment` object (from `SpatialExperiment::read10xVisium(data="raw")`). Estimates contamination parameters via gradient descent over candidate radii, then runs an EM algorithm to recover uncontaminated expression. Returns a new slide object with "decont" assay and rich contamination metadata.

### Parameters
#### Path Parameters
- **slide_obj** (SummarizedExperiment | SpatialExperiment) - Required - The input spatial data object.
- **gene_keep** (NULL | character) - Optional - Genes to keep for decontamination. If NULL, high-expressed/variable genes are auto-selected.
- **maxit** (integer) - Optional - Maximum EM iterations (default: 30).
- **tol** (numeric) - Optional - Convergence tolerance (default: 1).
- **candidate_radius** (numeric vector) - Optional - Radii to evaluate for contamination estimation (default: c(5, 10, 15, 20, 25, 30)).
- **kernel** (character) - Optional - Kernel type for estimation ('gaussian', 'linear', 'laplace', 'cauchy').
- **verbose** (logical) - Optional - Whether to print progress messages (default: TRUE).
- **gene_cutoff** (numeric) - Optional - Used when input is `SpatialExperiment` to filter genes based on expression level.

### Request Example
```r
# --- Using SummarizedExperiment (SpotClean native) ---
decont_obj <- spotclean(
    slide_obj        = slide_obj,
    gene_keep        = NULL,           # auto-select high-expressed/variable genes
    maxit            = 30,             # max EM iterations (default)
    tol              = 1,              # convergence tolerance (default)
    candidate_radius = c(5, 10, 15, 20, 25, 30),  # radii to evaluate (default)
    kernel           = "gaussian",     # "gaussian"|"linear"|"laplace"|"cauchy"
    verbose          = TRUE
)

# --- Using SpatialExperiment ---
library(SpatialExperiment)
spe <- read10xVisium(samples = "/path/to/spaceranger/", data = "raw")
decont_spe <- spotclean(spe, gene_cutoff = 0.1)
```

### Response
#### Success Response
Returns a new SummarizedExperiment or SpatialExperiment object with a "decont" assay and updated metadata including contamination rates and parameters.
```

--------------------------------

### createSlide

Source: https://context7.com/zijianni/spotclean/llms.txt

Builds a SummarizedExperiment slide object by combining the count matrix and slide metadata. Genes with low average expression are filtered out.

```APIDOC
## createSlide()

### Description
Combines the count matrix and slide metadata into a `SummarizedExperiment` slide object. Genes with average tissue-spot expression ≤ `gene_cutoff` are filtered out. The raw count matrix is stored in the `"raw"` assay slot.

### Parameters
- **count_mat** (dgCMatrix) - Required - The sparse count matrix.
- **slide_info** (list) - Required - The list containing slide metadata obtained from `read10xSlide()`.
- **gene_cutoff** (numeric) - Optional - Threshold for filtering genes based on average tissue-spot expression. Defaults to 0.1.
- **verbose** (boolean) - Optional - If TRUE, prints progress messages.

### Request Example
```r
data(mbrain_raw)   # built-in example: top-100 genes, V1_Adult_Mouse_Brain

slide_obj <- createSlide(
    count_mat  = mbrain_raw,
    slide_info = slide_info,
    gene_cutoff = 0.1,    # filter genes with avg tissue expression ≤ 0.1
    verbose     = TRUE
)
```

### Response
- **slide_obj** (SummarizedExperiment) - A SummarizedExperiment object containing the count matrix and slide metadata.
```

--------------------------------

### visualizeLabel()

Source: https://context7.com/zijianni/spotclean/llms.txt

Plots categorical spot labels (e.g., tissue, cell type) on the slide image as a colored dot plot. Labels can be from metadata or external vectors.

```APIDOC
## visualizeLabel() — Plot categorical spot labels on slide

### Description
Renders categorical spot metadata (e.g., tissue/background, cell-type annotation) as a colored dot plot in 2-D slide space. `label` can be a metadata column name or an external character vector.

### Parameters
#### Path Parameters
- **object** (SummarizedExperiment) - Required - The slide object containing spot data.
- **label** (character) - Required - The metadata column name or vector containing labels to plot.
- **title** (character) - Optional - A title for the plot.
- **legend_title** (character) - Optional - A title for the plot legend.

### Request Example
```r
# Plot tissue vs. background from built-in slide metadata
gp <- visualizeLabel(
    object        = slide_obj,
    label         = "tissue",           # column in metadata(slide_obj)$slide
    title         = "Tissue coverage",
    legend_title  = "Region"
)
plot(gp)
```

### Response
#### Success Response
Returns a `ggplot2` object with categorical labels plotted on the slide.
```

--------------------------------

### convertToSeurat()

Source: https://context7.com/zijianni/spotclean/llms.txt

Converts a SpotClean slide object to a Seurat Visium spatial object, loading the tissue image from the original 10x spatial folder. Enables direct use of all Seurat spatial analysis functions (normalization, clustering, spatially variable gene detection, etc.).

```APIDOC
## convertToSeurat() — Export decontaminated data to Seurat

### Description
Converts a SpotClean slide object to a Seurat `Visium` spatial object, loading the tissue image from the original 10x spatial folder. Enables direct use of all Seurat spatial analysis functions (normalization, clustering, spatially variable gene detection, etc.).

### Request Example
```R
seurat_obj <- convertToSeurat(
    slide_obj     = decont_obj,
    image_dir     = spatial_dir,    # path to 10x spatial/ folder
    slice         = "slice1",       # name for stored image slot
    filter_matrix = TRUE            # keep tissue spots only (required when
)                                   # slide_obj contains only tissue spots)

str(seurat_obj, max.level = 2)
# Formal class 'Seurat'
#  ..@ assays  :List of 1: $ Spatial: ...
#  ..@ images  :List of 1: $ slice1 : ...

# Continue with standard Seurat spatial workflow
library(Seurat)
seurat_obj <- NormalizeData(seurat_obj)
seurat_obj <- FindVariableFeatures(seurat_obj)
seurat_obj <- ScaleData(seurat_obj)
seurat_obj <- RunPCA(seurat_obj)
SpatialFeaturePlot(seurat_obj, features = "Mbp")
```
```

--------------------------------

### visualizeHeatmap()

Source: https://context7.com/zijianni/spotclean/llms.txt

Renders a continuous value (gene expression, contamination rate, total UMIs, etc.) as a heatmap dot plot in 2-D slide space. Accepts a gene name string, a metadata column name, or a numeric vector. Supports log1p color scaling and both viridis and Spectral rainbow palettes.

```APIDOC
## visualizeHeatmap() — Plot continuous spot values on slide

### Description
Renders a continuous value (gene expression, contamination rate, total UMIs, etc.) as a heatmap dot plot in 2-D slide space. Accepts a gene name string, a metadata column name, or a numeric vector. Supports log1p color scaling and both viridis and Spectral rainbow palettes.

### Request Example
```R
# Gene expression before decontamination
gp_raw <- visualizeHeatmap(slide_obj, "Mbp",
                           title        = "Mbp (raw)",
                           legend_title = "UMI count",
                           logged       = TRUE,
                           viridis      = TRUE)
plot(gp_raw)

# Gene expression after decontamination
gp_decont <- visualizeHeatmap(decont_obj, "Mbp",
                              title  = "Mbp (decontaminated)")
plot(gp_decont)

# Per-spot contamination rate (unlogged, fixed 0–1 scale)
gp_cont <- visualizeHeatmap(
    decont_obj,
    value         = metadata(decont_obj)$contamination_rate,
    logged        = FALSE,
    legend_title  = "Contamination rate",
    legend_range  = c(0, 1),
    viridis       = FALSE   # rainbow palette
)
plot(gp_cont)

# Total UMI counts stored as a new metadata column
metadata(slide_obj)$slide$total_counts <- Matrix::colSums(mbrain_raw)
gp_total <- visualizeHeatmap(slide_obj, "total_counts",
                             legend_title = "Total UMIs")
plot(gp_total)
```
```

--------------------------------

### read10xRawH5

Source: https://context7.com/zijianni/spotclean/llms.txt

Reads the raw count matrix from a 10x Space Ranger HDF5 file (.h5 format). The interface is identical to `read10xRaw()`.

```APIDOC
## read10xRawH5()

### Description
Reads the raw count matrix from a 10x Space Ranger HDF5 file (`.h5` format). Interface is identical to `read10xRaw()`.

### Parameters
- **row_name** (string) - Required - Specifies whether to use gene symbols or Ensembl IDs as row names ('symbol' or 'id').
- **meta** (boolean) - Required - If TRUE, returns a list containing the count matrix and gene metadata.

### Request Example
```r
count_mat <- read10xRawH5("/path/to/raw_feature_bc_matrix.h5",
                           row_name = "symbol",
                           meta     = FALSE)

# With metadata
result    <- read10xRawH5("/path/to/raw_feature_bc_matrix.h5",
                           row_name = "symbol",
                           meta     = TRUE)
count_mat <- result$CountMatrix
gene_meta <- result$Metadata
```

### Response
- **CountMatrix** (dgCMatrix) - The sparse count matrix.
- **Metadata** (data.frame) - Gene-level metadata including id, symbol, and type.
```

--------------------------------

### Decontaminate Spatial Transcriptomics Data with spotclean()

Source: https://context7.com/zijianni/spotclean/llms.txt

Use `spotclean()` to estimate and remove spot-swapping contamination from spatial transcriptomics data. It accepts `SummarizedExperiment` or `SpatialExperiment` objects. The function returns a new object with a 'decont' assay and contamination metadata. Adjust `maxit`, `tol`, `candidate_radius`, and `kernel` for fine-tuning.

```R
decont_obj <- spotclean(
    slide_obj        = slide_obj,
    gene_keep        = NULL,           # auto-select high-expressed/variable genes
    maxit            = 30,             # max EM iterations (default)
    tol              = 1,              # convergence tolerance (default)
    candidate_radius = c(5, 10, 15, 20, 25, 30),  # radii to evaluate (default)
    kernel           = "gaussian",     # "gaussian"|"linear"|"laplace"|"cauchy"
    verbose          = TRUE
)
```

```R
library(SpatialExperiment)
spe <- read10xVisium(samples = "/path/to/spaceranger/", data = "raw")
decont_spe <- spotclean(spe, gene_cutoff = 0.1)
```

```R
str(assays(decont_spe)$decont)
```

--------------------------------

### Plot Categorical Spot Labels with visualizeLabel()

Source: https://context7.com/zijianni/spotclean/llms.txt

Display categorical spot metadata, such as tissue or cell-type annotations, on the slide using `visualizeLabel()`. This function generates a colored dot plot in slide space. The `label` argument can specify a metadata column name or an external character vector.

```R
# Plot tissue vs. background from built-in slide metadata
gp <- visualizeLabel(
    object        = slide_obj,
    label         = "tissue",           # column in metadata(slide_obj)$slide
    title         = "Tissue coverage",
    legend_title  = "Region"
)
plot(gp)
```

--------------------------------

### read10xRaw

Source: https://context7.com/zijianni/spotclean/llms.txt

Reads the raw gene-by-spot count matrix from a 10x Space Ranger output directory. It can return a sparse matrix or a list containing the matrix and gene-level metadata.

```APIDOC
## read10xRaw()

### Description
Reads the raw gene-by-spot count matrix from a 10x Space Ranger output directory (requires `barcodes.tsv.gz`, `features.tsv.gz`, `matrix.mtx.gz`). Returns a sparse `dgCMatrix`; when `meta = TRUE` returns a list with both the matrix and gene-level metadata.

### Parameters
- **row_name** (string) - Required - Specifies whether to use gene symbols or Ensembl IDs as row names ('symbol' or 'id').
- **meta** (boolean) - Required - If TRUE, returns a list containing the count matrix and gene metadata.

### Request Example
```r
# Read count matrix (gene symbols as row names)
count_mat <- read10xRaw("/path/to/raw_feature_bc_matrix/",
                        row_name = "symbol",   # or "id" for Ensembl IDs
                        meta     = FALSE)

# Read with gene metadata
result <- read10xRaw("/path/to/raw_feature_bc_matrix/",
                     row_name = "symbol",
                     meta     = TRUE)
count_mat   <- result$CountMatrix   # dgCMatrix
gene_meta   <- result$Metadata      # data.frame: id, symbol, type
```

### Response
- **CountMatrix** (dgCMatrix) - The sparse count matrix.
- **Metadata** (data.frame) - Gene-level metadata including id, symbol, and type.
```

--------------------------------

### read10xSlide

Source: https://context7.com/zijianni/spotclean/llms.txt

Reads slide spatial metadata and tissue image from 10x Space Ranger output. Returns a list containing a slide data frame and a tissue image.

```APIDOC
## read10xSlide()

### Description
Reads the spot position CSV, tissue low-resolution image, and scale-factor JSON from 10x Space Ranger output. Returns a named list with a `slide` data frame (one row per spot, columns: `barcode`, `tissue`, `row`, `col`, `imagerow`, `imagecol`, `height`, `width`) and a `grob` Grid Graphical Object of the tissue image.

### Parameters
- **tissue_csv_file** (string) - Required - Path to the tissue positions CSV file.
- **tissue_img_file** (string) - Optional - Path to the tissue low-resolution image file.
- **scale_factor_file** (string) - Optional - Path to the scale-factor JSON file.

### Request Example
```r
spatial_dir <- system.file(file.path("extdata",
                                     "V1_Adult_Mouse_Brain_spatial"),
                           package = "SpotClean")

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"),  # optional
    scale_factor_file = file.path(spatial_dir, "scalefactors_json.json")   # optional
)
```

### Response
- **slide** (data.frame) - A data frame with spatial metadata for each spot.
- **grob** (Grid Graphical Object) - A graphical object representing the tissue image.
```

--------------------------------

### Read 10x HDF5 Count Matrix

Source: https://context7.com/zijianni/spotclean/llms.txt

Reads a raw count matrix from a 10x Space Ranger HDF5 file. The interface is identical to read10xRaw.

```r
count_mat <- read10xRawH5("/path/to/raw_feature_bc_matrix.h5",
                           row_name = "symbol",
                           meta     = FALSE)

# With metadata
result    <- read10xRawH5("/path/to/raw_feature_bc_matrix.h5",
                           row_name = "symbol",
                           meta     = TRUE)
count_mat <- result$CountMatrix
gene_meta <- result$Metadata
```

--------------------------------

### Plot Gene Expression Heatmap with visualizeHeatmap

Source: https://context7.com/zijianni/spotclean/llms.txt

Renders gene expression as a heatmap. Supports log scaling and different color palettes. Use 'logged = TRUE' for gene expression and 'logged = FALSE' for contamination rates.

```R
# Gene expression before decontamination
gp_raw <- visualizeHeatmap(slide_obj, "Mbp",
                           title        = "Mbp (raw)",
                           legend_title = "UMI count",
                           logged       = TRUE,
                           viridis      = TRUE)
plot(gp_raw)
```

```R
# Gene expression after decontamination
gp_decont <- visualizeHeatmap(decont_obj, "Mbp",
                              title  = "Mbp (decontaminated)")
plot(gp_decont)
```

```R
# Per-spot contamination rate (unlogged, fixed 0–1 scale)
gp_cont <- visualizeHeatmap(
    decont_obj,
    value         = metadata(decont_obj)$contamination_rate,
    logged        = FALSE,
    legend_title  = "Contamination rate",
    legend_range  = c(0, 1),
    viridis       = FALSE   # rainbow palette
)
plot(gp_cont)
```

```R
# Total UMI counts stored as a new metadata column
metadata(slide_obj)$slide$total_counts <- Matrix::colSums(mbrain_raw)
gp_total <- visualizeHeatmap(slide_obj, "total_counts",
                             legend_title = "Total UMIs")
plot(gp_total)
```

--------------------------------

### Read 10x Raw Count Matrix

Source: https://context7.com/zijianni/spotclean/llms.txt

Reads a gene-by-spot count matrix from a 10x Space Ranger output directory. Can optionally return gene-level metadata.

```r
# Read count matrix (gene symbols as row names)
count_mat <- read10xRaw("/path/to/raw_feature_bc_matrix/",
                        row_name = "symbol",   # or "id" for Ensembl IDs
                        meta     = FALSE)

str(count_mat)
# Formal class 'dgCMatrix' [package "Matrix"]
#  ..@ Dim: int [1:2] 33538 4992
#  ..@ Dimnames:List of 2
#  .. ..$ : chr [1:33538] "MIR1302-2HG" "FAM138A" ...
#  .. ..$ : chr [1:4992] "AAACAAGTATCTCCCA-1" ...

# Read with gene metadata
result <- read10xRaw("/path/to/raw_feature_bc_matrix/",
                     row_name = "symbol",
                     meta     = TRUE)
count_mat   <- result$CountMatrix   # dgCMatrix
gene_meta   <- result$Metadata      # data.frame: id, symbol, type
```

--------------------------------

### Plot Custom Annotation Vector with visualizeLabel

Source: https://context7.com/zijianni/spotclean/llms.txt

Visualizes custom cell type annotations on a slide. Ensure 'cell_types' vector length matches the number of tissue spots.

```R
cell_types <- c(rep("neuron", 1500), rep("glia", 1993))   # length = n tissue spots
gp2 <- visualizeLabel(
    object           = slide_obj,
    label            = cell_types,
    subset_barcodes  = metadata(slide_obj)$slide$barcode[
                           metadata(slide_obj)$slide$tissue == 1],
    title            = "Cell types"
)
plot(gp2)
```

--------------------------------

### Read Slide Spatial Metadata and Image

Source: https://context7.com/zijianni/spotclean/llms.txt

Reads spatial metadata (spot positions, tissue information) and optionally the tissue image and scale factors from 10x Space Ranger output. Returns a list containing a slide data frame and a graphical object of the tissue image.

```r
spatial_dir <- system.file(file.path("extdata",
                                     "V1_Adult_Mouse_Brain_spatial"),
                           package = "SpotClean")

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"),  # optional
    scale_factor_file = file.path(spatial_dir, "scalefactors_json.json")   # optional
)

str(slide_info$slide)
# 'data.frame': 4992 obs. of 8 variables:
#  $ barcode : chr  "AAACAAGTATCTCCCA-1" ...
#  $ tissue  : Factor w/ 2 levels "0","1": ...
#  $ row     : int  50 3 ...
#  $ col     : int  102 43 ...
#  $ imagerow: num  ...
#  $ imagecol: num  ...
#  $ height  : int  600
#  $ width   : int  565
```

--------------------------------

### Visualize Tissue H&E Image with visualizeSlide()

Source: https://context7.com/zijianni/spotclean/llms.txt

Render the stored tissue H&E image as a `ggplot2` object using `visualizeSlide()`. The image is positioned in slide pixel coordinates and can be further customized using `ggplot2` functions. This function requires the slide object to have an image loaded.

```R
gp <- visualizeSlide(slide_obj, title = "V1 Adult Mouse Brain")
plot(gp)
```

```R
# Further ggplot2 customization
library(ggplot2)
gp + theme(plot.title = element_text(size = 14, face = "bold"))
```

--------------------------------

### visualizeSlide()

Source: https://context7.com/zijianni/spotclean/llms.txt

Renders the stored tissue H&E image as a ggplot2 object, positioned in slide pixel coordinates. Useful for overlaying spatial data.

```APIDOC
## visualizeSlide() — Display tissue H&E image

### Description
Renders the stored tissue image (loaded by `read10xSlide()`) as a `ggplot2` object positioned in slide pixel coordinates. Returns the `ggplot2` object for further customization.

### Parameters
#### Path Parameters
- **object** (SummarizedExperiment) - Required - The slide object containing image information.
- **title** (character) - Optional - A title for the plot.

### Request Example
```r
gp <- visualizeSlide(slide_obj, title = "V1 Adult Mouse Brain")
plot(gp)

# Further ggplot2 customization
library(ggplot2)
gp + theme(plot.title = element_text(size = 14, face = "bold"))
```

### Response
#### Success Response
Returns a `ggplot2` object representing the tissue image.
```

--------------------------------

### arcScore()

Source: https://context7.com/zijianni/spotclean/llms.txt

Computes the Ambient RNA Contamination (ARC) score, a model-free lower bound on the fraction of contaminated UMIs. Can be applied to raw count matrices or slide objects.

```APIDOC
## arcScore() — Ambient RNA Contamination (ARC) score

### Description
Computes a model-free lower bound on the fraction of contaminated UMIs, calculated as (total background UMIs / total spots) / (mean tissue-spot UMIs). Works on both raw count matrices and slide objects.

### Parameters
#### Path Parameters
- **object** (matrix | SummarizedExperiment) - Required - The input count matrix or slide object.
- **background_bcs** (character vector) - Optional - A vector of barcodes identified as background. Required if `object` is a raw count matrix.

### Request Example
```r
# From a raw matrix + background barcode vector
background_bcs <- dplyr::filter(slide_info$slide, tissue == 0)$barcode
arc <- arcScore(mbrain_raw, background_bcs)
# [1] 0.054   → at least ~5.4% of observed expressions are contamination

# Directly from a slide object
arc <- arcScore(slide_obj)
# [1] 0.054

# ARC score is also stored automatically in decontamination output
metadata(decont_obj)$ARC_score
```

### Response
#### Success Response
Returns a numeric value representing the ARC score.
```

--------------------------------

### Calculate Ambient RNA Contamination (ARC) Score with arcScore()

Source: https://context7.com/zijianni/spotclean/llms.txt

Compute a model-free lower bound on the fraction of contaminated UMIs using `arcScore()`. This function can operate on raw count matrices with a background barcode vector or directly on slide objects. The ARC score is also automatically stored in the output of `spotclean()`.

```R
background_bcs <- dplyr::filter(slide_info$slide, tissue == 0)$barcode
arc <- arcScore(mbrain_raw, background_bcs)
```

```R
arc <- arcScore(slide_obj)
```

```R
metadata(decont_obj)$ARC_score
```

--------------------------------

### Filter Genes with keepHighGene()

Source: https://context7.com/zijianni/spotclean/llms.txt

Identify highly expressed or highly variable genes using `keepHighGene()`. This function can return either a filtered count matrix or just the names of the selected genes. It is useful for reducing matrix size before decontamination. Parameters `top_high` and `mean_cutoff` control the gene selection criteria.

```R
data(mbrain_raw)
dim(mbrain_raw)   # 100 4992

# Return filtered matrix instead of gene names
mbrain_filtered <- keepHighGene(
    count_mat     = mbrain_raw,
    top_high      = 5000,        # consider top 5000 expressed genes (default)
    mean_cutoff   = 1,           # keep if mean expression ≥ 1 (default)
    return_matrix = TRUE,
    verbose       = TRUE
)
# Kept 87 highly expressed or highly variable genes.
dim(mbrain_filtered)   # 87 4992
```

```R
# Return only gene names (default)
gene_names <- keepHighGene(mbrain_raw, mean_cutoff = 100)
# Kept 12 highly expressed or highly variable genes.
head(gene_names)   # chr [1:12] "Mbp" "Plp1" "Snap25" ...
```

--------------------------------

### keepHighGene()

Source: https://context7.com/zijianni/spotclean/llms.txt

Filters genes based on expression level or variability. It identifies genes with mean expression above a cutoff or high variability among the top expressed genes. Can return filtered gene names or a filtered count matrix.

```APIDOC
## keepHighGene() — Filter to highly expressed / variable genes

### Description
Identifies genes that are either highly expressed (mean ≥ `mean_cutoff`) or highly variable (via Seurat's mean-variance plot method) among the top `top_high` expressed genes. Used internally by `spotclean()` but can be called independently to reduce matrix size before decontamination.

### Parameters
#### Path Parameters
- **count_mat** (matrix) - Required - The input count matrix.
- **top_high** (integer) - Optional - Consider the top N expressed genes for variability assessment (default: 5000).
- **mean_cutoff** (numeric) - Optional - Minimum mean expression to consider a gene highly expressed (default: 1).
- **return_matrix** (logical) - Optional - If TRUE, returns the filtered count matrix; otherwise, returns gene names (default: FALSE).
- **verbose** (logical) - Optional - Whether to print progress messages (default: TRUE).

### Request Example
```r
data(mbrain_raw)
dim(mbrain_raw)   # 100 4992

# Return filtered matrix instead of gene names
mbrain_filtered <- keepHighGene(
    count_mat     = mbrain_raw,
    top_high      = 5000,        # consider top 5000 expressed genes (default)
    mean_cutoff   = 1,           # keep if mean expression ≥ 1 (default)
    return_matrix = TRUE,
    verbose       = TRUE
)
# Kept 87 highly expressed or highly variable genes.
dim(mbrain_filtered)   # 87 4992

# Return only gene names (default)
gene_names <- keepHighGene(mbrain_raw, mean_cutoff = 100)
# Kept 12 highly expressed or highly variable genes.
head(gene_names)   # chr [1:12] "Mbp" "Plp1" "Snap25" ...
```

### Response
#### Success Response
Returns either a character vector of gene names or a filtered count matrix, depending on the `return_matrix` argument.
```
Tokens:
Raw