# leviosam2

**Repository Path**: Billsfriend/leviosam2

## Basic Information

- **Project Name**: leviosam2
- **Description**: fork of https://github.com/milkschen/leviosam2
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-10
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LevioSAM2: Fast and accurate coordinate conversion between assemblies

[![Docker](https://img.shields.io/docker/v/naechyun/leviosam2?label=Docker)](https://hub.docker.com/r/naechyun/leviosam2)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/leviosam2/badges/version.svg)](https://anaconda.org/bioconda/leviosam2)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/leviosam2/badges/downloads.svg)](https://anaconda.org/bioconda/leviosam2)
![Cmake build](https://github.com/milkschen/leviosam2/actions/workflows/cmake_htslib.yml/badge.svg)
![Integration](https://github.com/milkschen/leviosam2/actions/workflows/integration-test.yml/badge.svg)

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

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./figures/levioSAM_S_bw_dark.png"  width="300">
  <img alt="Text changing depending on mode. Light: 'So light!' Dark: 'So dark!'" src="./figures/levioSAM_S_bw.png"  width="300">
</picture>

## 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](https://anaconda.org/bioconda/leviosam2)

```shell
# 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](https://hub.docker.com/r/naechyun/leviosam2)

```shell
docker pull naechyun/leviosam2:latest
```

- [Singularity](https://hub.docker.com/r/naechyun/leviosam2)

```shell
singularity pull docker://naechyun/leviosam2:latest
```

- Built from source using CMake. See [INSTALL.md](INSTALL.md) for details.


## Usage

### Prepare chain files

LevioSAM2 performs lift-over using a [chain file](http://hgw1.soe.ucsc.edu/goldenPath/help/chain.html) as the lift-over map.
Many chain files are provided by the UCSC Genome Browser, e.g. [GRCh38-related chains](https://hgdownload.soe.ucsc.edu/goldenPath/hg38/liftOver/).
For other reference pairs, common ways to generate chain files include using the [UCSC recipe](http://genomewiki.ucsc.edu/index.php/LiftOver_Howto) and [nf-LO](https://github.com/evotools/nf-LO).

### LevioSAM2-index

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

```shell
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.__

```shell
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:

```shell
# 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](https://github.com/milkschen/leviosam2/blob/main/workflow/README.md) 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_