/liftover-coordinates

name: liftover-coordinates
description: Convert genomic coordinates between assembly versions (GRCh37/hg19 to GRCh38/hg38, mm9 to mm10). Guides UCSC liftOver for BED files, CrossMap for VCF/bigWig, and handles unmapped regions with provenance logging.

Convert Genomic Coordinates Between Assembly Versions

When to Use

• User needs to convert genomic coordinates between assemblies (hg19↔hg38, mm9↔mm10)
• User asks about "liftover", "coordinate conversion", "assembly mismatch", or "CrossMap"
• User has data in hg19/GRCh37 that needs conversion to GRCh38 (or vice versa) before integration
• User wants to use UCSC liftOver or CrossMap for BED, VCF, bigWig, or BAM files
• Example queries: "convert my hg19 peaks to hg38", "liftover coordinates for integration with ENCODE", "my data is in mm9, how do I convert to mm10?"

Guide coordinate liftover between genome assemblies using UCSC liftOver, CrossMap, Ensembl REST API, and rtracklayer. Assembly conversion is one of the most common pitfalls in genomics — this skill provides the definitive workflow for safe, reproducible liftover with full provenance tracking.

Scientific Rationale

**The question**: "How do I safely convert my genomic coordinates from one assembly to another without losing data or introducing errors?"

Assembly conversion is referenced as a critical step in 10+ other ENCODE Toolkit skills because ENCODE spans multiple data releases: some experiments were processed against hg19/GRCh37, while most current data uses GRCh38/hg38. Combining data across assemblies without proper liftover is one of the most common and most dangerous errors in computational genomics — coordinates that look valid in both assemblies may refer to completely different genomic locations.

The Core Problem

Genome assemblies are updated to fix errors, fill gaps, add alternative haplotypes, and improve centromeric/telomeric sequence. Between hg19 and hg38, approximately 1,000 sequence gaps were closed, 8% of the genome was modified, and several regions were rearranged. A coordinate like chr17:41,197,694 in hg19 (BRCA1) maps to chr17:43,044,295 in GRCh38 — a shift of nearly 2 Mb. Using the wrong assembly silently produces incorrect results.

When to Liftover

Common scenarios requiring coordinate conversion:

• **Combining ENCODE data from different releases**: Some hg19, some GRCh38 — must unify before intersection
• **Integrating GWAS Catalog results**: Many GWAS hits are still reported in hg19/GRCh37 coordinates
• **Using gnomAD**: gnomAD v4 uses GRCh38; older v2 datasets use GRCh37
• **Cross-species comparison**: Mouse data across mm9/mm10/GRCm39
• **Legacy datasets**: Published supplementary files often use older assemblies
• **ClinVar integration**: Some ClinVar entries reference GRCh37 positions
• **GTEx cross-reference**: GTEx v8 uses GRCh38, earlier versions used GRCh37

Literature Support

• **Kent et al. 2002** (Genome Research, ~5,000 citations): UCSC Genome Browser and the liftOver tool. The original chain/net alignment framework for coordinate conversion between genome assemblies. [DOI](https://doi.org/10.1101/gr.229102)
• **Zhao et al. 2014** (Bioinformatics, ~800 citations): CrossMap — a versatile tool for coordinate conversion between genome assemblies. Handles VCF, BAM, bigWig, GFF, and Wiggle formats that UCSC liftOver cannot process natively. [DOI](https://doi.org/10.1093/bioinformatics/btt730)
• **Hinrichs et al. 2006** (Nucleic Acids Research, ~1,200 citations): UCSC genome browser chain/net alignment methodology. Defines the reciprocal-best chain alignment that underpins coordinate conversion. [DOI](https://doi.org/10.1093/nar/gkj144)
• **Kuhn et al. 2013** (Nucleic Acids Research, ~600 citations): Assembly updates and the implications for re-annotation. Documents the biological impact of assembly changes on gene models and regulatory element coordinates. [DOI](https://doi.org/10.1093/nar/gks1195)
• **Schneider et al. 2017** (Genome Research, ~400 citations): GRCh38 improvements over GRCh37 — gap closures, centromere models, alternative haplotypes. Quantifies what changed and why liftover is necessary. [DOI](https://doi.org/10.1101/gr.213611.116)
• **Amemiya et al. 2019** (Scientific Reports, ~1,372 citations): ENCODE Blacklist regions — some blacklisted regions are assembly-specific. Liftover of blacklist files must use the correct version. [DOI](https://doi.org/10.1038/s41598-019-45839-z)

Assembly Version Mapping

| Common Name | UCSC Name | NCBI/GRC Name | Species | Release Year | |------------|-----------|---------------|---------|-------------| | hg19 | hg19 | GRCh37 | Human | 2009 | | hg38 | hg38 | GRCh38 | Human | 2013 | | mm9 | mm9 | MGSCv37 | Mouse | 2007 | | mm10 | mm10 | GRCm38 | Mouse | 2012 | | mm39 | mm39 | GRCm39 | Mouse | 2020 |

Naming Convention Alert

The same assembly has different names depending on the source:

• **UCSC convention**: `hg19`, `hg38`, `mm10` — used in filenames, chromosome prefixes (`chr1`)
• **NCBI/GRC convention**: `GRCh37`, `GRCh38`, `GRCm38` — used in publications, Ensembl
• **Ensembl convention**: Chromosomes without `chr` prefix (`1` instead of `chr1`)

Always verify which naming convention your data uses. Mixing `chr1` (UCSC) with `1` (Ensembl) causes silent failures in bedtools intersection and peak overlap analysis.

Chain Files

Chain files encode the alignment between assemblies and are the essential input for liftover.

Source: UCSC (Recommended)

https://hgdownload.soe.ucsc.edu/goldenPath/{from}/liftOver/{from}To{To}.over.chain.gz

Common chain files: | Conversion | Chain File | URL | |-----------|-----------|-----| | hg19 to hg38 | hg19ToHg38.over.chain.gz | `https://hgdownload.soe.ucsc.edu/goldenPath/hg19/liftOver/hg19ToHg38.over.chain.gz` | | hg38 to hg19 | hg38ToHg19.over.chain.gz | `https://hgdownload.soe.ucsc.edu/goldenPath/hg38/liftOver/hg38ToHg19.over.chain.gz` | | mm9 to mm10 | mm9ToMm10.over.chain.gz | `https://hgdownload.soe.uc