[](https://github.com/koesterlab/alignoth/actions)
[](https://codecov.io/gh/koesterlab/alignoth)
[](http://bioconda.github.io/recipes/alignoth/README.html)
[](http://bioconda.github.io/recipes/alignoth/README.html)
[](http://bioconda.github.io/recipes/alignoth/README.html)
[](http://bioconda.github.io/recipes/alignoth/README.html)
# alignoth
A tool for creating alignment plots from bam files. The generated [vega-lite](https://vega.github.io/vega-lite/) plots are written to stdout per default.
An example of a generated plot can be seen [here](http://htmlpreview.github.io/?https://github.com/koesterlab/alignoth/blob/main/examples/plot.html)
The name alignoth is derived from the visualized **align**ments combined with the star **alioth** (usage of vega plots).
Alignoth supports an interactive mode that can be activated by simply executing it without any arguments (i.e. `alignoth`).
This launches a wizard that guides you through selecting input files, defining the region of interest, and choosing between an interactive HTML output or a Vega-Lite specification.
## Usage
```alignoth```
To activate the interactive mode guiding you through the process of creating an alignment plot.
```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](https://vega.github.io/vega/usage/#cli) and [vega-lite-cli]( https://vega.github.io/vega-lite/usage/compile.html#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```
### Arguments
The following options are available when using alignoth:
| 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 | |
## Installation
There a multiple ways to install alignoth:
#### Bioconda
Rust-Bio-Tools is available via [Bioconda](https://bioconda.github.io).
With Bioconda set up, installation is as easy as
conda install alignoth
#### Cargo
If the [Rust](https://www.rust-lang.org/tools/install) compiler and associated [Cargo](https://github.com/rust-lang/cargo/) are installed, alignoth may be installed via
cargo install alignoth
#### Source
Download the source code and within the root directory of source run
cargo install
## Authors
* [Felix Wiegand](https://github.com/fxwiegand)
* [Johannes Köster](https://github.com/johanneskoester) (https://koesterlab.github.io)