Chromosome Naming Harmonizer for Genomics Pipelines

Pain point

Tools like bedtools/samtools-based workflows may return empty intersections or fail when chromosome names

differ between inputs (e.g., "chr1" vs "1").

Repro/diagnostic steps

1. Compare headers: BAM @SQ, FASTA .fai, and first column of BED/GTF.
2. Run a quick intersection on a known region and confirm expected overlap.

Root causes (common)

• Mixing UCSC- and Ensembl-style references/annotations.
• Files derived from different reference builds or naming standards.
• Hidden scaffolds/unplaced contigs present in one file but not another.

Fix workflow

1. Standardize naming at the earliest reproducible stage (preferably regenerate from original reference).
2. If transformation is unavoidable, apply a consistent rename map and re-index.
3. Add a "header compatibility check" step to pipelines before heavy compute.

Expected result

• Intersections/annotations produce non-empty results that match expectations.

References

• https://www.biostars.org/p/138011/
• https://www.reddit.com/r/bioinformatics/comments/lxqssk/bedtools_intersect/
• https://www.seqanswers.com/forum/bioinformatics/bioinformatics-aa/69299-unable-to-intersect-bam-file-with-bedtools
• https://github.com/nf-core/sarek/blob/master/docs/usage.md