bulkrna-qc
Bulk RNA-seq count matrix quality control — library sizes, gene detection, sample correlation, outlier detection, CPM normalization.
SKILL.mdSkills/bulkrna/bulkrna-qc/SKILL.md
GitHubBulk RNA-seq Count Matrix QC
Quality control assessment of bulk RNA-seq count matrices. Computes library sizes, gene detection rates, sample-to-sample correlations (log-CPM Pearson), outlier detection, and CPM normalization.
Core Capabilities
- Compute per-sample library sizes and gene detection rates
- Log-CPM Pearson correlation heatmap with automatic outlier flagging (MAD-based)
- CPM normalization output for downstream analysis
- Expression density plots for cross-sample comparison
- Auto-detect sample group labels from naming conventions
CLI Reference
python omicsclaw.py run bulkrna-qc --demo
python omicsclaw.py run bulkrna-qc --input <counts.csv> --output <dir>
python bulkrna_qc.py --input counts.csv --output results/
python bulkrna_qc.py --demo --output /tmp/qc_demo
Why This Exists
- Without it: Researchers manually inspect count matrices, compute library sizes in R/Python, generate correlation heatmaps, and visually scan for outlier samples — each step requiring separate scripts and ad-hoc thresholds.
- With it: A single Python command runs the full QC pipeline — library sizes, gene detection, log-CPM correlation, outlier flagging, CPM export — and produces publication-ready figures and a structured report.
- Why OmicsClaw: Integrates best-practice QC metrics (log-CPM correlation, MAD-based outlier detection) into the OmicsClaw reporting framework with auto-generated demo data for testing.
Algorithm / Methodology
Library Size Analysis
- Raw counts per sample are summed to compute library size
- Coefficient of variation (CV) across samples quantifies library size imbalance
Gene Detection
- Genes detected in each sample (count > 0) are counted
- Distribution shows data sparsity patterns
Sample Correlation
- Pearson correlation is computed on log2(CPM + 1) transformed data
- Using log-CPM rather than raw counts avoids domination by highly-expressed genes
Outlier Detection
- Mean inter-sample correlation per sample is compared against the cohort median
- Samples below
median − 2 × MAD × 1.4826are flagged as potential outliers
CPM Normalization
- Counts Per Million:
CPM_ij = count_ij / library_size_j × 10^6
Input Formats
| Format | Extension | Description |
|---|---|---|
| Count matrix | .csv |
Genes as rows, samples as columns; first column is gene identifiers |
Workflow
- Load: Read a genes-by-samples raw count matrix (CSV).
- Library sizes: Sum counts per sample, compute mean, median, and CV.
- Gene detection: Count samples detecting each gene (count >0).
- CPM normalize: Compute Counts Per Million for downstream use.
- Correlate: Pearson correlation on log2(CPM+1) values.
- Outlier detection: Flag samples with low mean correlation via MAD threshold.
- Visualize: Generate library size bar chart, gene detection histogram, correlation heatmap, and expression density plot.
- Report: Write markdown report, result.json, tables (sample stats, CPM), and reproducibility script.
Example Queries
- "Check the quality of my bulk RNA-seq count matrix"
- "Are there any outlier samples in my data?"
- "Generate a sample correlation heatmap"
- "Normalize my counts to CPM"
Output Structure
output_directory/
├── report.md
├── result.json
├── figures/
│ ├── library_sizes.png
│ ├── gene_detection.png
│ ├── sample_correlation.png
│ └── expression_density.png
├── tables/
│ ├── sample_stats.csv
│ └── cpm_normalized.csv
└── reproducibility/
└── commands.sh
Parameters
| Parameter | Default | Description |
|---|---|---|
--input |
— | Path to count matrix CSV (genes x samples) |
--output |
— | Output directory (required) |
--demo |
— | Run with bundled/auto-generated demo data |
Safety
- Local-first: All processing runs locally; no data is uploaded to external services.
- Disclaimer: Every report includes the standard OmicsClaw disclaimer.
- Audit trail: Parameters, sample metadata, and input checksums are recorded in result.json.
Integration with Orchestrator
Trigger conditions:
- Automatically invoked when user intent matches count matrix QC, library size, or sample quality keywords.
Chaining partners:
bulkrna-de— Downstream: differential expression on QC-verified databulkrna-coexpression— Downstream: co-expression network analysisbulkrna-deconvolution— Downstream: cell type deconvolution
Version Compatibility
Reference examples tested with: scipy 1.11+, pandas 2.0+, numpy 1.24+, matplotlib 3.7+
Dependencies
Required: numpy, pandas, scipy, matplotlib
Related Skills
bulkrna-read-qc— Upstream: FASTQ quality assessmentbulkrna-read-alignment— Upstream: alignment statisticsbulkrna-de— Downstream: differential expression analysisbulkrna-coexpression— Downstream: co-expression network analysisbulkrna-deconvolution— Downstream: cell type deconvolution