Skip to main content

Indel-aware consensus from aligned BAMs

Project description

Kindel: indel-aware consensus from aligned BAM

JOSS status PyPI version Python support Tests

Kindel reconciles substitutions and CIGAR-described indels to to produce a majority consensus from an aligned BAM/SAM file. Using the --realign option, unaligned gap closure using soft-clipped sequence information is also performed, a kind of local reassembly. Intended for use with small alignments of genes or virus genomes, Kindel is tested with BAMs created by aligners such as Minimap2 and BWA. No reference sequence is required, however the input BAM must contain headers (@SQ) . If you encounter problems, please open an issue. Please also cite the JOSS article if you find this useful.

Core functionality

clip-dominant region

Reassembly of clip-dominant regions (CDRs) with --realign

clip-dominant region

Features

  • Consensus of aligned substititutions, small insertions and deletions

  • Optional consensus reassembly around large unaligned 'clip-dominant' gaps (using --realign)

  • Support for short, paired and long reads mapped with e.g. Minimap2, BWA-MEM, and Segemehl

  • Support for BAMs with multiple reference contigs, chromosomes

  • Visualisation of aligned and clipped sequence depth by site alongside insertions, deletions (kindel plot)

Limitations

  • While Kindel has been tested with bacterial genomes, expect slow performance with megabase genomes
  • SAM/BAM files must contain an @SQ header line with reference sequence length(s).
  • Realignment mode (--realign) is able to close gaps of up to 2x read length

Installation

Install inside existing Python environment:

# Requires Python 3.9+ and Samtools
pip install kindel

Complete installation using a conda-compatible package manager:

conda create -y -n kindel python=3.13 samtools
conda activate kindel
pip install kindel

Development install:

git clone https://github.com/bede/kindel.git
cd kindel
pip install --editable '.[dev]'

Usage (kindel consensus)

Also see usage.ipynb

Command line

Generate a consensus sequence from an aligned BAM, saving the consensus sequence to cns.fa:

$ kindel consensus alignment.bam > cns.fa

Generate a consensus sequence from an aligned BAM with realignment mode enabled, allowing closure of gaps in the consensus sequence:

$ kindel consensus --realign alignment.bam > cns.fa

Built in help:

$ kindel -h
usage: kindel [-h] {consensus,weights,features,variants,plot} ...

positional arguments:
  {consensus,weights,features,variants,plot,version}
    consensus           Infer consensus sequence(s) from alignment in SAM/BAM
                        format
    weights             Returns table of per-site nucleotide frequencies and
                        coverage
    features            Returns table of per-site nucleotide frequencies and
                        coverage including indels
    variants            Output variants exceeding specified absolute and
                        relative frequency thresholds
    plot                Plot sitewise soft clipping frequency across reference
                        and genome
    version             Show version

optional arguments:
  -h, --help            show this help message and exit
$  kindel consensus -h
usage: kindel consensus [-h] [-r] [--min-depth MIN_DEPTH]
                        [--min-overlap MIN_OVERLAP] [-c CLIP_DECAY_THRESHOLD]
                        [--mask-ends MASK_ENDS] [-t] [-u]
                        bam_path

Infer consensus sequence(s) from alignment in SAM/BAM format

positional arguments:
  bam_path              path to SAM/BAM file

optional arguments:
  -h, --help            show this help message and exit
  -r, --realign         attempt to reconstruct reference around soft-clip
                        boundaries (default: False)
  --min-depth MIN_DEPTH
                        substitute Ns at coverage depths beneath this value
                        (default: 1)
  --min-overlap MIN_OVERLAP
                        match length required to close soft-clipped gaps
                        (default: 7)
  -c CLIP_DECAY_THRESHOLD, --clip-decay-threshold CLIP_DECAY_THRESHOLD
                        read depth fraction at which to cease clip extension
                        (default: 0.1)
  --mask-ends MASK_ENDS
                        ignore clip dominant positions within n positions of
                        termini (default: 50)
  -t, --trim-ends       trim ambiguous nucleotides (Ns) from sequence ends
                        (default: False)
  -u, --uppercase       close gaps using uppercase alphabet (default: False)

Python API

from kindel import kindel

kindel.bam_to_consensus(bam_path, realign=False, min_depth=2, min_overlap=7,
                        clip_decay_threshold=0.1, trim_ends=False, uppercase=False)

Issues

If you encounter problems please open a GitHub issue, preferably including a BAM that allows the problem to be reproduced, or else reach out via email or social media.

Visualising alignments (kindel plot)

It can be useful to visualise rates of insertion, deletion and alignment clipping across an alignment. kindel plot generates an interactive HTML plot showing relevant alignment information.

To plot aligned depth alongside insertion, deletion and soft clipping frequency:

kindel plot tests/data_minimap2/2.issue23.debug.bam

Original alignment Plot of original alignment

After alignment to Kindel consensus sequence Plot after alignment to Kindel consensus sequence

Contributing

If you would like to contribute to this project, please open an issue or contact the author directly using the details above. Please note that this project is released with a Contributor Code of Conduct, and by participating in this project you agree to abide by its terms.

Before opening a pull request, please:

  • Ensure tests pass in a local development build (see installation instructions) by executing pytest inside the package directory.
  • Increment the version number inside __init__.py according to SemVer.
  • Update documentation and/or tests if possible.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kindel-1.2.0.tar.gz (22.9 MB view details)

Uploaded Source

Built Distribution

kindel-1.2.0-py3-none-any.whl (23.6 kB view details)

Uploaded Python 3

File details

Details for the file kindel-1.2.0.tar.gz.

File metadata

  • Download URL: kindel-1.2.0.tar.gz
  • Upload date:
  • Size: 22.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.32.3

File hashes

Hashes for kindel-1.2.0.tar.gz
Algorithm Hash digest
SHA256 514d27e971f5709faa88a60841f0103d4128e7e407dd106790d4b57fc0aaf493
MD5 6651b7a1e5ce4723d2b60a508a918e69
BLAKE2b-256 4bfa2114e44c75bbad8cc212ba6e7db0b7f9a336603a2d949d09d029b5a3fd5c

See more details on using hashes here.

File details

Details for the file kindel-1.2.0-py3-none-any.whl.

File metadata

  • Download URL: kindel-1.2.0-py3-none-any.whl
  • Upload date:
  • Size: 23.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.32.3

File hashes

Hashes for kindel-1.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 4b090764c23e3ca9b9885ed0e8982ccf58724458ce81cf4ac67646b3e2f8093b
MD5 c0a663cecf7d2d59031ef29138a9393c
BLAKE2b-256 a11773eaccfd03c6f16880b8af9e999fa83757c7e3667fb381308afd2444226a

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page