LevioSAM2: Fast and accurate coordinate conversion between assemblies

LevioSAM2 lifts over alignments accurately and efficiently using a chain file.

Text changing depending on mode. Light: 'So light!' Dark: 'So dark!'

Features

Converting aligned short and long reads records (in SAM/BAM/CRAM format) from one reference to another
Comprehensive alignment feature updating during lift-over:
- Reference name (RNAME), position (POS), alignmant flag (FLAG), and CIGAR alignment string (CIGAR)
- Mate read information (RNEXT, PNEXT, TLEN)
- (optional) Alignment tags (MD:Z, NM:i)
Multithreading support
Toolkit for "selective" pipelines which consider major changes between the source and target references
(beta) Converting intervals (in BED format) from one reference to another

Installation

LevioSAM2 can be installed using:

Conda

# The following commands install leviosam2 in a new conda environment called `leviosam2`
conda create -n leviosam2
conda activate leviosam2
conda install -c bioconda -c conda-forge leviosam2

Docker

docker pull naechyun/leviosam2:latest

Singularity

singularity pull docker://naechyun/leviosam2:latest

Built from source using CMake. See INSTALL.md for details.

Usage

Prepare chain files

LevioSAM2 performs lift-over using a chain file as the lift-over map. Many chain files are provided by the UCSC Genome Browser, e.g. GRCh38-related chains. For other reference pairs, common ways to generate chain files include using the UCSC recipe and nf-LO.

LevioSAM2-index

LevioSAM2 indexes a chain file for lift-over queries. The resulting index has a .clft extension.

leviosam2 index -c source_to_target.chain -p source_to_target -F target.fai

LevioSAM2-lift

LevioSAM2-lift is the lift-over kernel of the levioSAM2 toolkit. The levioSAM2 ChainMap index will be saved to source_to_target.clft. The output will be saved to lifted_from_source.bam.

We highly recommend to sort the input BAM by position prior to running levioSAM2-lift.

leviosam2 lift -C source_to_target.clft -a aligned_to_source.bam -p lifted_from_source -O bam

Full levioSAM2 workflow with selective re-mapping

The levioSAM2 workflow includes lift-over using the leviosam2-lift kernel and a selective re-mapping strategy. This approach can improve accuracy.

Example:

# You may skip the indexing step if you've already run it
leviosam2 index -c source_to_target.chain -p source_to_target -F target.fai
sh leviosam2.sh \
    -a bowtie2 -A -10 -q 10 -H 5 \
    -i aligned_to_source.bam \
    -o aligned_to_source-lifted \
    -f target.fna \
    -b bt2/target \
    -C source_to_target.clft \
    -t 16

See this README to learn more about running the full levioSAM2 workflow.

Publication

Nae-Chyun Chen, Luis Paulin, Fritz Sedlazeck, Sergey Koren, Adam Phillippy, Ben Langmead. Improved sequence mapping using a complete reference genome and lift-over. Nat Methods (2023). https://doi.org/10.1038/s41592-023-02069-6
Taher Mun, Nae-Chyun Chen, Ben Langmead. LevioSAM: Fast lift-over of variant-aware reference alignments, Bioinformatics, 2021;, btab396, https://doi.org/10.1093/bioinformatics/btab396

Logo credit: Ting-Wei Young

milkschen / leviosam2

readme