| name | bulkrna-read-alignment |
| description | Load when summarising STAR / HISAT2 / Salmon alignment-rate logs in bulk RNA-seq. Skip if data is raw FASTQ (use bulkrna-read-qc) or already counted (use bulkrna-qc), or for genome-DNA alignment (use genomics-alignment). |
| version | 0.3.0 |
| author | OmicsClaw |
| license | MIT |
| tags | ["bulkrna","alignment","STAR","HISAT2","Salmon","mapping-rate","strandedness"] |
| requires | ["numpy","pandas","matplotlib"] |
bulkrna-read-alignment
When to use
Run after the aligner / quantifier finishes, on the log file produced by
STAR (Log.final.out), HISAT2 (.log), or Salmon (meta_info.json).
Yields a one-page mapping-rate summary, strandedness inference, and a
gene-body coverage profile — the QC bridge between raw FASTQ and the
count matrix.
Inputs & Outputs
| Input | Format | Required |
|---|
| Aligner log | Log.final.out (STAR), .log (HISAT2), meta_info.json (Salmon) | yes (or --demo) |
| Output | Path | Notes |
|---|
| Mapping summary figure | figures/mapping_summary.png | unique vs multi vs unmapped |
| Gene body coverage | figures/gene_body_coverage.png | 5'→3' bias profile |
| Alignment composition | figures/alignment_composition.png | breakdown of mapping outcomes |
| Stats table | tables/alignment_stats.csv | parsed numeric metrics |
| Report | report.md + result.json | always |
Flow
- Auto-detect aligner from filename (
bulkrna_read_alignment.py:305-311): log.final.out → STAR; meta_info → Salmon; otherwise → HISAT2.
- Parse the log into a numeric stats dict.
- Run quality assessment heuristics (high/medium/low mapping-rate buckets).
- Render figures and write
report.md + tables/alignment_stats.csv.
Gotchas
- Aligner detection is filename-based, not content-based.
bulkrna_read_alignment.py:305-311 dispatches by input_path.name.lower() — anything that is neither log.final.out nor meta_info (case-insensitive substring) is silently parsed as a HISAT2 log. A renamed STAR log will produce nonsense. Pass --method star explicitly if your STAR file isn't named conventionally.
- The skill consumes the LOG, not the BAM. Feeding a
.bam or .sam file as --input will not raise — the parser just finds zero matchable lines and reports an empty stats dict. Sanity-check result.json["summary"]["total_reads"] is non-zero before trusting any downstream summary.
- Gene body coverage is synthetic in
--demo mode (bulkrna_read_alignment.py:142-150). The 5'→3' bias profile in demo runs is a fixed reproducible curve, not derived from real input — useful for layout previews but not for assessing real RNA degradation.
Key CLI
python omicsclaw.py run bulkrna-read-alignment --demo
python omicsclaw.py run bulkrna-read-alignment --input Log.final.out --output results/
See also
references/parameters.md — every CLI flag and tuning hintreferences/methodology.md — STAR / HISAT2 / Salmon parsers, strandedness inferencereferences/output_contract.md — exact output directory layout- Adjacent skills:
bulkrna-read-qc (upstream FASTQ QC), bulkrna-qc (downstream count-matrix QC), genomics-alignment (DNA-alignment sibling: BAM/SAM, not log files)
