#plot #bam #vega-lite #alignments #html #generated #format-json

app alignoth

A tool for creating alignment plots from bam files

23 releases (10 breaking)

0.12.0 Mar 5, 2024
0.11.0 Nov 15, 2023
0.10.0 Oct 4, 2023
0.8.2 May 10, 2023
0.3.0 Jul 25, 2022

#44 in Biology

MIT license

1.5K SLoC

GitHub Workflow Status codecov Bioconda downloads Bioconda version install with bioconda Licence


A tool for creating alignment plots from bam files. The generated vega-lite plots are written to stdout per default. An example of a generated plot can be seen here The name alignoth is derived from the visualized alignments combined with the star alioth (usage of vega plots).


alignoth -b path/to/my.bam -r path/to/my/reference.fa -g chr1:200-300 > plot.vl.json

To directly generate a plot in svg, png or pdf format we advice using the vega-cli and vega-lite-cli packages:

alignoth -b path/to/my.bam -r path/to/my/reference.fa -g chr1:200-300 | vl2vg | vg2pdf > plot.pdf

To generate an interactive view within an html file use --html and capture the output to a file:

alignoth -b path/to/my.bam -r path/to/my/reference.fa -g chr1:200-300 --html > plot.html


The following options are available when using alignoth:

argument short explanation default
bam-path -b The bam file to be visualized.
reference -r The path to the reference fasta file
region -g Chromosome and region for the visualization. Example: 2:132424-132924
around -a A chromosome and a base position that will define the region that will be plotted starting 500bp before and end 500bp behind the given position. Example: 2:17348
highlight -h Interval or single base position that will be highlighted in the visualization. Example: 132400-132500 or 132440
plot-all -p Plot all reads in the given region. We advise to only use this command for small bam files with a single target. false
max-read-depth -d Set the maximum rows of reads that will be shown in the alignment plots 500
max-width -w Set the maximum width of the resulting alignment plot 1024
output -o If present, data and vega-lite specs of the generated plot will be split and written to the given directory
data-format -f Sets the output format for the read, reference and highlight data json
aux_tag -x Displays the given content of the aux tag in the tooltip of the plot. Multiple usage for more than one tag is possible.
spec-output If present vega-lite specs will be written to the given file path
read-data-output If present read data will be written to the given file path
ref-data-output If present reference data will be written to the given file path
highlight-data-output If present highlight data will be written to the given file path
html If present the generated plot will inserted into a plain html file containing the plot centered which is then written to stdout


There a multiple ways to install alignoth:


Rust-Bio-Tools is available via Bioconda. With Bioconda set up, installation is as easy as

conda install alignoth


If the Rust compiler and associated Cargo are installed, alignoth may be installed via

cargo install alignoth


Download the source code and within the root directory of source run

cargo install



~799K SLoC