AutoGineer
Generated banner for Single Cell Rna Qc
Generated logo for Single Cell Rna Qc

Single Cell Rna Qc

AnthropicOfficialPublished by Anthropic

  • Skill
  • Tool integration
  • Science and research
  • Apache-2.0
  • Low risk
  • Has scripts
Download ZIP

From the author

Performs quality control on single-cell RNA-seq data (.h5ad or .h5 files) using scverse best practices with MAD-based filtering and comprehensive visualizations. Use when users request QC analysis, filtering low-quality cells, assessing data quality, or following scverse/scanpy best practices for single-cell analysis.
— the description by Anthropic

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a comprehensive toolkit for performing quality control on single-cell RNA-seq data in .h5ad or .h5 formats. It implements scverse and scanpy best practices, utilizing Median Absolute Deviation (MAD)-based filtering to identify outliers while remaining permissive enough to preserve rare cell populations. The skill offers both a ready-to-use command-line pipeline for standard analysis and a modular Python library for researchers requiring custom filtering logic or specific workflow integration.

What it does

  • Calculates essential QC metrics including count depth, gene detection, and mitochondrial/ribosomal/hemoglobin content.
  • Applies MAD-based outlier detection for robust, data-driven filtering of low-quality cells.
  • Generates comprehensive visualizations to assess data quality before and after filtering.
  • Supports standard 10X Genomics and AnnData file formats.
  • Provides modular utility functions for building custom, non-standard QC workflows.
  • Includes guidance on species-specific gene patterns and tissue-specific QC considerations.

When to use it

  • When you need to perform standard quality control on single-cell RNA-seq datasets.
  • When you want to filter low-quality cells or debris while following established scverse best practices.
  • When you need to generate visual reports to justify filtering decisions.
  • When you require a flexible, programmatic approach to QC for complex or tissue-specific experiments.
  • When you need to assess the impact of different filtering thresholds on your dataset.

Advantages

  • Data-driven filtering using MAD reduces reliance on arbitrary, fixed thresholds.
  • Permissive defaults help prevent the accidental loss of rare but viable cell populations.
  • Automated visualization helps quickly identify technical artifacts or batch effects.
  • Modular design allows for seamless integration into larger bioinformatics pipelines.
  • Supports both quick, automated processing and highly granular, custom analysis.

Usage examples

“Run the standard QC pipeline on my 10X Genomics data file named raw_data.h5.”
The agent executes the qc_analysis.py script, which calculates metrics, applies MAD-based filtering, and generates a folder containing filtered data and QC plots.
“I need to calculate QC metrics for my AnnData object but I do not want to filter any cells yet.”
The agent uses the modular qc_core.py functions to compute metrics and generate summary plots without applying the filtering step.
“How do I apply a stricter mitochondrial threshold for my specific tissue sample?”
The agent provides instructions on using the --mt-threshold parameter in the command-line tool or demonstrates how to use apply_hard_threshold in a custom script.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/anthropics/single-cell-rna-qc/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip single-cell-rna-qc.zip -d .agents/skills

Documentation by Anthropic

Single-Cell RNA-seq Quality Control

Automated QC workflow for single-cell RNA-seq data following scverse best practices.

When to Use This Skill

Use when users:

  • Request quality control or QC on single-cell RNA-seq data

  • Want to filter low-quality cells or assess data quality

  • Need QC visualizations or metrics

  • Ask to follow scverse/scanpy best practices

  • Request MAD-based filtering or outlier detection

Supported input formats:

  • .h5ad files (AnnData format from scanpy/Python workflows)

  • .h5 files (10X Genomics Cell Ranger output)

Default recommendation: Use Approach 1 (complete pipeline) unless the user has specific custom requirements or explicitly requests non-standard filtering logic.

Approach 1: Complete QC Pipeline (Recommended for Standard Workflows)

For standard QC following scverse best practices, use the convenience script scripts/qc_analysis.py:

python3 scripts/qc_analysis.py input.h5ad
# or for 10X Genomics .h5 files:
python3 scripts/qc_analysis.py raw_feature_bc_matrix.h5

The script automatically detects the file format and loads it appropriately.

When to use this approach:

  • Standard QC workflow with adjustable thresholds (all cells filtered the same way)

  • Batch processing multiple datasets

  • Quick exploratory analysis

  • User wants the "just works" solution

Requirements: anndata, scanpy, scipy, matplotlib, seaborn, numpy

Parameters:

Customize filtering thresholds and gene patterns using command-line parameters:

  • --output-dir - Output directory

  • --mad-counts, --mad-genes, --mad-mt - MAD thresholds for counts/genes/MT%

  • --mt-threshold - Hard mitochondrial % cutoff

  • --min-cells - Gene filtering threshold

  • --mt-pattern, --ribo-pattern, --hb-pattern - Gene name patterns for different species

Use --help to see current default values.

Outputs:

All files are saved to <input_basename>_qc_results/ directory by default (or to the directory specified by --output-dir):

  • qc_metrics_before_filtering.png - Pre-filtering visualizations

  • qc_filtering_thresholds.png - MAD-based threshold overlays

  • qc_metrics_after_filtering.png - Post-filtering quality metrics

  • <input_basename>_filtered.h5ad - Clean, filtered dataset ready for downstream analysis

  • <input_basename>_with_qc.h5ad - Original data with QC annotations preserved

If copying outputs for user access, copy individual files (not the entire directory) so users can preview them directly.

Workflow Steps

The script performs the following steps:

  1. Calculate QC metrics - Count depth, gene detection, mitochondrial/ribosomal/hemoglobin content

  2. Apply MAD-based filtering - Permissive outlier detection using MAD thresholds for counts/genes/MT%

  3. Filter genes - Remove genes detected in few cells

  4. Generate visualizations - Comprehensive before/after plots with threshold overlays

Approach 2: Modular Building Blocks (For Custom Workflows)

For custom analysis workflows or non-standard requirements, use the modular utility functions from scripts/qc_core.py and scripts/qc_plotting.py:

# Run from scripts/ directory, or add scripts/ to sys.path if needed
import anndata as ad
from qc_core import calculate_qc_metrics, detect_outliers_mad, filter_cells
from qc_plotting import plot_qc_distributions  # Only if visualization needed

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
# ... custom analysis logic here

When to use this approach:

  • Different workflow needed (skip steps, change order, apply different thresholds to subsets)

  • Conditional logic (e.g., filter neurons differently than other cells)

  • Partial execution (only metrics/visualization, no filtering)

  • Integration with other analysis steps in a larger pipeline

  • Custom filtering criteria beyond what command-line params support

Available utility functions:

From qc_core.py (core QC operations):

  • calculate_qc_metrics(adata, mt_pattern, ribo_pattern, hb_pattern, inplace=True) - Calculate QC metrics and annotate adata

  • detect_outliers_mad(adata, metric, n_mads, verbose=True) - MAD-based outlier detection, returns boolean mask

  • apply_hard_threshold(adata, metric, threshold, operator='>', verbose=True) - Apply hard cutoffs, returns boolean mask

  • filter_cells(adata, mask, inplace=False) - Apply boolean mask to filter cells

  • filter_genes(adata, min_cells=20, min_counts=None, inplace=True) - Filter genes by detection

  • print_qc_summary(adata, label='') - Print summary statistics

From qc_plotting.py (visualization):

  • plot_qc_distributions(adata, output_path, title) - Generate comprehensive QC plots

  • plot_filtering_thresholds(adata, outlier_masks, thresholds, output_path) - Visualize filtering thresholds

  • plot_qc_after_filtering(adata, output_path) - Generate post-filtering plots

Example custom workflows:

Example 1: Only calculate metrics and visualize, don't filter yet

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)
plot_qc_distributions(adata, 'qc_before.png', title='Initial QC')
print_qc_summary(adata, label='Before filtering')

Example 2: Apply only MT% filtering, keep other metrics permissive

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)

# Only filter high MT% cells
high_mt = apply_hard_threshold(adata, 'pct_counts_mt', 10, operator='>')
adata_filtered = filter_cells(adata, ~high_mt)
adata_filtered.write('filtered.h5ad')

Example 3: Different thresholds for different subsets

adata = ad.read_h5ad('input.h5ad')
calculate_qc_metrics(adata, inplace=True)

# Apply type-specific QC (assumes cell_type metadata exists)
neurons = adata.obs['cell_type'] == 'neuron'
other_cells = ~neurons

# Neurons tolerate higher MT%, other cells use stricter threshold
neuron_qc = apply_hard_threshold(adata[neurons], 'pct_counts_mt', 15, operator='>')
other_qc = apply_hard_threshold(adata[other_cells], 'pct_counts_mt', 8, operator='>')

Best Practices

  1. Be permissive with filtering - Default thresholds intentionally retain most cells to avoid losing rare populations

  2. Inspect visualizations - Always review before/after plots to ensure filtering makes biological sense

  3. Consider dataset-specific factors - Some tissues naturally have higher mitochondrial content (e.g., neurons, cardiomyocytes)

  4. Check gene annotations - Mitochondrial gene prefixes vary by species (mt- for mouse, MT- for human)

  5. Iterate if needed - QC parameters may need adjustment based on the specific experiment or tissue type

Reference Materials

For detailed QC methodology, parameter rationale, and troubleshooting guidance, see references/scverse_qc_guidelines.md. This reference provides:

  • Detailed explanations of each QC metric and why it matters

  • Rationale for MAD-based thresholds and why they're better than fixed cutoffs

  • Guidelines for interpreting QC visualizations (histograms, violin plots, scatter plots)

  • Species-specific considerations for gene annotations

  • When and how to adjust filtering parameters

  • Advanced QC considerations (ambient RNA correction, doublet detection)

Load this reference when users need deeper understanding of the methodology or when troubleshooting QC issues.

Next Steps After QC

Typical downstream analysis steps:

  • Ambient RNA correction (SoupX, CellBender)

  • Doublet detection (scDblFinder)

  • Normalization (log-normalize, scran)

  • Feature selection and dimensionality reduction

  • Clustering and cell type annotation

Files

references/scverse_qc_guidelines.md

scverse Quality Control Guidelines

This document provides detailed information about quality control best practices for single-cell RNA-seq data, following the scverse ecosystem recommendations.

Quality Control Metrics

Count Depth (Total Counts)

  • What it measures: Total number of UMI/reads per cell

  • Why it matters: Low count cells may be empty droplets, debris, or poorly captured cells

  • Typical range: 500-50,000 counts per cell (varies by protocol)

  • Red flags: Bimodal distributions may indicate mixing of high and low-quality cells

Gene Detection (Genes per Cell)

  • What it measures: Number of genes with at least 1 count

  • Why it matters: Strongly correlates with count depth; low values indicate poor capture

  • Typical range: 200-5,000 genes per cell

  • Red flags: Very low values (<200) suggest technical failures

Mitochondrial Content

  • What it measures: Percentage of counts from mitochondrial genes

  • Why it matters: High MT% indicates cell stress, apoptosis, or lysed cells

  • Typical range: <5% for most tissues, up to 10-15% for metabolically active cells

  • Species-specific patterns:

    • Mouse: Genes start with 'mt-' (e.g., mt-Nd1, mt-Co1)

    • Human: Genes start with 'MT-' (e.g., MT-ND1, MT-CO1)

  • Context matters: Some cell types (cardiomyocytes, neurons) naturally have higher MT content

Ribosomal Content

  • What it measures: Percentage of counts from ribosomal protein genes

  • Why it matters: Can indicate cell state or contamination

  • Patterns: Genes start with 'Rpl'/'RPL' (large subunit) or 'Rps'/'RPS' (small subunit)

  • Note: High ribosomal content isn't always bad - metabolically active cells have more ribosomes

Hemoglobin Content

  • What it measures: Percentage of counts from hemoglobin genes

  • Why it matters: Indicates blood contamination in non-blood tissues

  • Patterns: Genes matching '^Hb[^(p)]' or '^HB[^(P)]' (excludes Hbp1/HBP1)

  • When to use: Particularly important for tissue samples (brain, liver, etc.)

MAD-Based Filtering Rationale

Why MAD Instead of Fixed Thresholds?

Fixed thresholds (e.g., "remove cells with <500 genes") fail because:

  • Different protocols yield different ranges

  • Different tissues have different characteristics

  • Different species have different gene counts

  • Fixed thresholds are arbitrary and not data-driven

MAD (Median Absolute Deviation) is robust to outliers and adapts to your dataset:

MAD = median(|X - median(X)|)
Outlier bounds = median ± n_MADs × MAD
Recommended MAD Thresholds

Following scverse best practices (deliberately permissive):

5 MADs for count depth (log-transformed)

  • Very permissive to retain rare cell populations

  • Catches extreme outliers (empty droplets, debris)

  • Log transformation handles the typical right-skewed distribution

5 MADs for gene counts (log-transformed)

  • Parallels count depth filtering

  • Most informative when combined with count filtering

  • Log transformation normalizes the distribution

3 MADs for mitochondrial percentage

  • More stringent because high MT% strongly indicates dying cells

  • Uses raw percentages (not log-transformed)

  • Combined with hard threshold for extra stringency

Hard threshold: 8% mitochondrial content

  • Additional filter beyond MAD-based detection

  • Conservative cutoff that works across most tissues

  • Adjust higher (10-15%) for metabolically active cell types

Why Be Permissive?

The default thresholds intentionally err on the side of keeping cells because:

  1. Rare populations: Stringent filtering may remove rare but viable cell types

  2. Biological variation: Some healthy cells naturally have extreme values

  3. Reversibility: Easier to filter more later than to recover lost cells

  4. Downstream robustness: Modern normalization methods handle moderate quality variation

Interpreting QC Visualizations

Histograms

  • Bimodal distributions: May indicate mixing of cell types or quality issues

  • Long tails: Common for count depth; MAD filtering handles this

  • Sharp cutoffs: May indicate prior filtering or technical artifacts

Violin Plots

  • Shows distribution shape and density

  • Median (line) and mean (diamond) should be similar for symmetric distributions

  • Wide distributions suggest high heterogeneity

Scatter Plots

Counts vs Genes (colored by MT%)

  • Should show strong positive correlation (R² > 0.8 typical)

  • Points deviating from trend may be outliers

  • High MT% cells often cluster at low counts/genes

Counts vs MT%

  • Negative correlation expected (dying cells have fewer counts)

  • Vertical stratification may indicate batch effects

  • Cells with high counts + high MT% are suspicious

Genes vs MT%

  • Similar to counts vs MT%, but often weaker correlation

  • Useful for identifying cells with gene detection issues

Gene Filtering

After filtering cells, remove genes detected in fewer than 20 cells:

  • Why 20?: Balances noise reduction with information retention

  • Benefits: Reduces dataset size, speeds up computation, removes noisy genes

  • Trade-offs: May lose very rare markers; adjust to 10 if studying rare populations

Species-Specific Considerations

Mouse (Mus musculus)

  • Mitochondrial genes: mt-* (lowercase)

  • Ribosomal genes: Rpl*, Rps* (capitalized first letter)

  • Hemoglobin genes: Hb* (but not Hbp1)

Human (Homo sapiens)

  • Mitochondrial genes: MT-* (uppercase)

  • Ribosomal genes: RPL*, RPS* (all uppercase)

  • Hemoglobin genes: HB* (but not HBP1)

Other Species

Adjust gene name patterns in the script to match your organism's gene nomenclature. Consult Ensembl or your reference annotation for correct prefixes.

When to Adjust Parameters

Consider adjusting filtering thresholds when:

More stringent (lower MADs)

  • High ambient RNA contamination suspected

  • Many low-quality cells observed in visualizations

  • Downstream analysis shows quality-driven clustering

More permissive (higher MADs)

  • Studying rare cell populations

  • Dataset has high technical quality

  • Cell types naturally have extreme values (e.g., neurons with high MT%)

Tissue-specific adjustments

  • Brain/neurons: May need higher MT% threshold (10-15%)

  • Blood: Can be more stringent with MT% (5-8%)

  • Tumor samples: Often need more permissive thresholds due to biological variation

Advanced QC Considerations

Not Included in This Workflow

Ambient RNA correction

  • Tool: SoupX, CellBender, DecontX

  • When: High background RNA in droplet-based data

  • Effect: Removes contamination from lysed cells

Doublet detection

  • Tool: scDblFinder, scrublet, DoubletFinder

  • When: Always recommended for droplet-based data

  • Effect: Identifies and removes multiplets (2+ cells in one droplet)

Cell cycle scoring

  • Tool: scanpy's score_genes_cell_cycle

  • When: Cell cycle effects confound biological signal

  • Effect: Allows regressing out or accounting for cell cycle phase

Batch correction

  • Tool: Harmony, scVI, ComBat

  • When: Integrating data from multiple batches/experiments

  • Effect: Removes technical batch effects while preserving biology

References

Requirements and compatibility

Written for: Claude Code, Claude apps

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

Security

What our scanner noticed· Low risk

  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
Anthropic
Publisher
Anthropic (Official)
Source
anthropics/knowledge-work-plugins · bio-research/skills/single-cell-rna-qc · commit e050c2e
Licence
Apache License 2.0 (redistribution allowed)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Anthropic.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download single-cell-rna-qc.zip