alshai / leviosam Goto Github PK

View Code? Open in Web Editor NEW

33.0 2.0 4.0 38.02 MB

Lift-over alignments from variant-aware references

License: MIT License

C++ 87.04% CMake 0.50% Python 5.46% C 5.95% Shell 0.96% Dockerfile 0.08%

leviosam's Introduction

levioSAM: accurate and efficient lift-over of alignments

LevioSAM lifts over alignments accurately and efficiently using a VCF or a chain file.

Features

Converting SAM/BAM records from one reference to another using either a VCF file or a chain file
Converting alignment information, including:
- Contig
- Position
- Alignmant flag
- CIGAR string
- Mate read information
- MD:Z and NM:i tag (optional)
Multithreading support

Installation

LevioSAM can be installed using:

Conda (please make sure the version number is specified)

conda install -c conda-forge -c bioconda leviosam=0.5.1

Docker

docker pull alshai/leviosam

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

Usage (VcfMap)

LevioSAM can perform lift-over using a VCF file as the lift-over map. Please visit the VcfMap Usage Page for detailed instructions.

Quick run:

leviosam index -v <vcf> -s <sample_name> -p <output_prefix>
leviosam lift -a <sam> -l <lft> -p <output_prefix> -O bam

The levioSAM VcfMap index will be saved to <output_prefix>.lft. The output will be saved to <output_prefix>.bam.

Example (with pre-built 1000-Genomes-Project indexes)

We provide the Bowtie 2 (which are compatible with Bowtie, too!) and levioSAM indexes for the major-allele references based on the 1000 Genomes Project. Please navigate to the bowtie-majref repo for more comprehensive description and more resources.

We provide more detailed instructions of how to use levioSAM in common variant-aware reference pipelines (major-allele reference and personalized reference) in the levioSAM wiki.

Usage (ChainMap)

If you'd like to perform lift-over using a chain file, please visit our new levioSAM2 page. We will not update chain-related updates in this repo.

LevioSAM can also perform lift-over using a chain file as the lift-over map since v0.5.0. Using ChainMap enables assembly-to-assembly lift-over and is usually faster. Please visit the ChainMap Usage Page for detailed instructions.

Quick run:

leviosam index -c a_to_b.chain -p a_to_b -F dest.fai
leviosam lift -C a_to_b.clft -a aligned_to_a.bam -p lifted_from_a -O bam

The levioSAM ChainMap index will be saved to a_to_b.clft. The output will be saved to lifted_from_a.bam.

Publication

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

leviosam's People

Contributors

Stargazers

Watchers

Forkers

seifudd maxrossi91 unique379r ultimagen

leviosam's Issues

Treat overlapping variants as bcftools v1.11

Feature request

Switch to the bcftools v1.11 (especially for bcftools consensus) logic in levioSAM serialize when dealing with overlapping variants. LevioSAM is developed base on some logic between bcftools v1.9 and v1.10, but sadly it is no longer the official logic right now.

An example

$bcftools view -H wg-maj.vcf.gz chr20:5099236-5099250
chr20	5099236	.	C	A
chr20	5099236	.	CAATCAATCAATA	C
chr20	5099240	.	C	A
chr20	5099244	.	C	A

Using bcftools v1.11

$samtools faidx wg-maj.chr20.v1_11.fa chr20:5099100-5099500
>chr20:5099100-5099500
TGTCTCAAAATAAATAAATAAATAAATAAATAAATAAATAAATAAATAAATAATAAATAA
AAAAACCAAATCATTTGGTTGGCCAAAACCTTCTGATCTGAGCTTTGCTCGGCAACCACT
CTCCAAGATAAAGCTTTATGTATCACCTCACATATTCACTGTCAAGGCTCAGGCACTCTA
GATTACTGGACTCCCCAGTCAACATTCCCATTACCAAAAGTCCCTAATCTTGGAGGCTGC
TTCAGGTCACCCTCTCTTTGTCCCTCACTTCCTGAGTTTTTTTTTTTTCCTCCAACTATA
CTCACTCTACTGGTGATCTCAAACAGCCCTCTAGCTTTTAAGATACTGTCCAAATGCTGA
CTCCCAAATTTCTATTTCCATCCAAGACCCACTCTTAAACT

Using bcftools v1.9-206-g4694164

The 11-bp deletion (CAATCAATCAATA>C) is not updated here.

$samtools faidx wg-maj.chr20.v1_9_206_g4694164.fa chr20:5099100-5099500
>chr20:5099100-5099500
TGTCTCAAAATAAATAAATAAATAAATAAATAAATAAATAAATAAATAAATAAATAAATA
AATAATAAATAAAAAAACCAAATCATTTGGTTGGCCAAAACCTTCTGATCTGAGCTTTGC
TCGGCAACCACTCTCCAAGATAAAGCTTTATGTATCACCTCACATATTCACTGTCAAGGC
TCAGGCACTCTAGATTACTGGACTCCCCAGTCAACATTCCCATTACCAAAAGTCCCTAAT
CTTGGAGGCTGCTTCAGGTCACCCTCTCTTTGTCCCTCACTTCCTGAGTTTTTTTTTTTT
CCTCCAACTATACTCACTCTACTGGTGATCTCAAACAGCCCTCTAGCTTTTAAGATACTG
TCCAAATGCTGACTCCCAAATTTCTATTTCCATCCAAGACC

Use of unphased genomes?

Hello! Reading the documentation, it didn't seem like there was anything written about the use of phased vs. unphased VCFs. Is levioSAM capable of taking in unphased VCFs to perform lift overs?

Support soft clipping

This includes changing CIGAR and trimming corresponding SEQ and QUAL bases.

Integrate alignment MAPQ filter

For each alignment, optionally write it in a FASTQ file (or a pair of) if the MAPQ of it is below a given cutoff. If this option gets activated, don't write low-MAPQ alignments to the lifted BAM output.

Are SA tags lifted?

Hello,
The documentation does not list the SA flag as lifted, and from reading the code I think that it is indeed not the case. Could you confirm this?
Is this a development you are considering? I guess the logic would be fairly similar to ChainMap::lift_segment, would it not?
Thanks and best regards,
Daniel Naro