# Bioconductor Scuttle

> Provides basic utility functions for performing single-cell analyses, focusing on simple normalization, quality control and data transformations. Also provides some helper functions to assist development of other packages.

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

---


# scuttle

Provides basic utility functions for performing single-cell analyses, focusing on simple normalization, quality control and data transformations. Also provides some helper functions to assist development of other packages.

## Dependencies & Environment

> Package-intrinsic requirements from the Bioconductor landing page — reproduce in any R environment.

- **Version:** 1.22.0 · **Bioconductor:** 3.23 · **R:** ≥ 4.6
- **Depends:** SingleCellExperiment
- **Imports:** Matrix, Rcpp, BiocGenerics, S4Vectors, BiocParallel, GenomicRanges, SummarizedExperiment, S4Arrays, MatrixGenerics, SparseArray, DelayedArray, beachmat
- **System requirements:** C++17
- **Install:** `BiocManager::install("scuttle")`

## When to Use
- **Quality Control Metrics**: When you need to compute basic feature-level statistics (mean counts, detection rates) using `perFeatureQCMetrics` or `calculateAverage`.
- **Gene Identifier Conversion**: When you need to replace stable Ensembl identifiers with unique, non-missing gene symbols using `uniquifyFeatureNames`.
- **Data Extraction for Visualization**: When you need to extract expression profiles and metadata into a standard `data.frame` for `ggplot` or `model.matrix` using `makePerCellDF` or `makePerFeatureDF`.
- **Scaling Normalization**: When removing composition biases using median-based normalization (`medianSizeFactors`), pooling normalization (`computePooledFactors`), or spike-in normalization (`computeSpikeFactors`).

## When NOT to Use
- **For state-of-the-art single-cell pipelines**: Use `scran` instead because many of `scuttle`'s low-level utilities are legacy functions that have been superseded by more efficient implementations in other packages.
- **For complex clustering**: Use `quickCluster` from `scran` instead because `scuttle` relies on external packages for the clustering step required prior to pooled normalization.

## Data Requirements
- **Input Format**: A `SingleCellExperiment` object.
- **Data Type**: Raw count matrices (e.g., `assay.type="counts"`).
- **Annotations**: Row names should ideally be stable identifiers (like Ensembl IDs) that can be mapped to symbols.

## Key Parameters
- **subsets** (`list(Empty=1:10)`): Used in `perFeatureQCMetrics` to define control sets (e.g., empty wells) for calculating ratio metrics.
- **assay.type** (`"counts"`): Specifies which assay to extract data from in `makePerCellDF` and `makePerFeatureDF`.
- **features** (`"Tspan12"`): Specifies the specific genes to extract expression data for in `makePerCellDF`.
- **cells** (`c(...)`): Specifies the specific cells to extract expression profiles for in `makePerFeatureDF`.
- **clusters** (`clusters`): Used in `computePooledFactors` to apply normalization within predefined clusters before adjusting across clusters.

## Best Practices
- Publish unfiltered count matrices with stable identifiers (e.g., Ensembl IDs) rather than filtered matrices with gene symbols, as filtered features cannot be recovered for data integration.
- Use `uniquifyFeatureNames` to safely convert Ensembl IDs to gene symbols for interactive analysis, ensuring duplicates are appended with identifiers and missing symbols are replaced.
- Perform a rough clustering (e.g., using `scran::quickCluster`) prior to running `computePooledFactors` on heterogeneous populations to avoid violating the assumption that most genes are non-DE.

## Common Pitfalls
- **Negative size factor estimates**: Low-quality cells with very few expressed genes can produce negative size factors during normalization; fix this by performing strict quality control to remove damaged cells before running `computePooledFactors`.
- **Duplicated row names**: Blindly replacing stable IDs with gene symbols can create duplicate row names; fix this by wrapping the replacement in `uniquifyFeatureNames`.
- **Violating non-DE assumptions**: Running `computePooledFactors` globally on a highly heterogeneous dataset can distort scaling factors; fix this by supplying a `clusters` argument to normalize within subpopulations first.

## Alternatives
- **scran**: Provides more advanced and actively maintained implementations of single-cell utilities, including the `quickCluster` function required for pooled normalization.
- **DESeq2**: Provides the original median ratio normalization approach that `medianSizeFactors` adapts for single-cell data.

## Citations
- McCarthy, D. J., Campbell, K. R., Lun, A. T., & Wills, Q. F. (2017). Scater: pre-processing, quality control, normalization and visualization of single-cell RNA-seq data in R. *Bioinformatics*, 33(8), 1179-1186.

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

<!-- biomate-cta -->
---

## Run this on BioMate

This skill is the **knowledge layer** — when, why, and how to use `scuttle`. To **run this analysis on your own data** with managed compute, automated QC, and reproducible outputs, use **[BioMate](https://www.biomate.ai?ref=kb&pkg=scuttle)** — free to start.

▶ **[Open `scuttle` on BioMate →](https://www.biomate.ai?ref=kb&pkg=scuttle)**