bulkrna-qc

name	bulkrna-qc
description	Bulk RNA-seq count matrix quality control — library sizes, gene detection, sample correlation, outlier detection, CPM normalization.
version	0.3.0
author	OmicsClaw
license	MIT
tags	["bulkrna","QC","count-matrix","library-size","gene-detection","sample-correlation","CPM"]
requires	["numpy","pandas","matplotlib","scipy"]
metadata	{"omicsclaw":{"domain":"bulkrna","emoji":"📊","trigger_keywords":["bulk QC","library size","count matrix","sample quality","gene detection","RNA-seq quality","count QC"],"allowed_extra_flags":[],"legacy_aliases":["bulk-align"],"saves_h5ad":false}}

Bulk 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.4826 are flagged as potential outliers

CPM Normalization

• Counts Per Million: CPM_ij = count_ij / library_size_j × 10^6

Input Formats