alitvteam / alitv

Visualize whole genome alignments as linear maps

AliTV

Tutorial

Read the documentation at readthedocs.

Dependencies

• A web browser
• For the perl part, see AliTV-perl-interface

Installation

You do not need to install anything to try the interactive visualization of AliTV. Just navigate to the demo page to try all the features on an example dataset (seven chloroplast genomes). You can also import your own json files on that page. When loading your own data into AliTV it is not transferred to a server but remains on your local machine.

If you want to generate the json file for your genomes you can use the command line script alitv.pl as follows:

# Install perl dependencies e.g. with cpan, cpanm or package manager (example: apt)
# apt install libyaml-perl libhash-merge-perl bioperl
git clone --recursive https://github.com/AliTVTeam/AliTV

Usage

AliTV.pl can be called directly on your input files or in advanced mode supplying a yaml configuration file. The output is a json object as required by the visualization part of AliTV (see details) in the file <project>.json (project can be set via command line parameter, otherwise a random name is generated). For more details about alitv.pl please see the documentation.

Simple mode: Just supply your files and redirect to json file

cd AliTV-perl-interface
perl bin/alitv.pl --project simple data/chloroset/*.fasta

Advanced mode: Supply a config yaml file

cd AliTV-perl-interface
perl bin/alitv.pl --project advanced data/chloroset/input.yml

Input

Input for the simple mode should be in one of the Bioperl supported formats (currently 42 different). Annotation files can be supplied in tsv format (have to be specified in the yml file, example file for ndh genes). Documentation for the yaml file is soon to be added for now consult this example file for usage information.

Output

By default, AliTV generates a configuration file (yaml format) if none is supplied, a log file and a json string on standard out. The json can then be visualized with AliTV on the demo page or locally in d3/AliTV.html. The format of the json file is specified in the [source documentation](https://alitvteam.github.io/AliTV/d3/doc/AliTV.html) relevant members are “conf”, “data”, and “filters”.

Homepage

For further information visit the homepage.

Citing AliTV

An article about AliTV has been published in PeerJ Computer Science Please cite this article if you use AliTV in your project. Additionally the software in any specific version can be cited via its zenodo doi, latest:

Please also cite:

• lastz
• bioperl

Contact

If you have any questions or encounter problems or potential bugs, don’t hesitate to contact us. Either report issues on github or write an email to:

• Markus Ankenbrand - [email protected]

License

AliTV itself is available under MIT license. The licenses of included libraries might differ, please see LICENSES/README.org for details.

Build

Repo Status

Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.

Changelog

Next release

• Fix karyo shift error with big number of genomes
• Fix link length filter (#146)
• Add CITATION.cff
• Add repo status badge

1.0.6 <2018-06-08>

• Update AliTV-perl-interface to v1.0.6

1.0.5 <2018-05-15>

• Add experimental auto-ordering
• Fix context menu bug

1.0.4 <2018-01-05>

• Use karyo names rather than ids in web interface
• Add google analytics to collect usage stats (with opt-out possibility)

1.0.3 <2017-06-16>

• Fix split feature bug (#131)
• Add citation info

1.0.2 <2017-04-25>

• Add documentation of perl part (rtd)
• Add demo sets bacteria, chromosomes
• Fix svg namespace (#116)
• Remove genome color gradient from chloro demo
• Include perl part version 1.0.2

1.0.1 <2017-04-20 Do>

• Include perl part version 1.0.1

1.0.0 <2017-04-13 Do>

• Include perl part version 1.0.0

0.4.1 <2016-08-05 Fr>

• Fix corner cases for move chromosome left/right
• Fix corner cases for move genome up/down
• Add linkOpacity setting (#104)
• Remove circular from headline (#102)
• Fix special characters in id bug (#108)
• Add feature labels
• Update perl part to version 0.1.7

0.4.0 <2016-06-18 Sa>

• Include new perl interface
• Update documentation

0.3.9 <2016-06-09 Do>

• Move to AliTVTeam organization

0.3.8 <2016-06-06 Mo>

• Update bootstrap-select to version 1.10.0
• Update colorpicker to version 2.3.2
• Update bootstrap to version 3.3.6
• Update jQuery-UI to version 1.11.4
• Update jQuery to version 2.2.4
• Update d3.js to version 3.5.17

0.3.7 <2016-06-02 Do>

• Improve general layout and style
• Improve tab structure of Advanced Settings (#89)
• Fix getter/setter for shifting chromosomes (#91)
• Display name and genome of a seq (#96)

0.3.6 <2015-11-02 Mo>

• Highlight active slider range (#84)
• Update slider range (#85)
• Fix feature hiding bug (#87)
• Fix tree drawing bug (#88)

0.3.5 <2015-09-24 Do>

• Add version number to html page
• Auto adjust tree representation when reordering genomes
• Warn if tree is not concordant with genome order
• Legend for biological feature types
• Color scale for link identity

0.3.4 <2015-09-16 Mi>

• Add custom features via the interface

0.3.3 <2015-09-11 Fr>

• Bug fix in template

0.3.2 <2015-09-11 Fr>

• rotation of circular sequences
• dynamic (biological) feature menus
• code cleanup

0.3.1 <2015-08-13 Do>

• Strand specific features
• Reset for genome zooming
• Libraries for contextMenu are update with generateJSONFiles.pl
• Fix #52: allow hiding of features with non-unique names
• Add new alerts and error messages

0.3 <2015-07-31 Fr>

• Show selected genome regions (independent)
• Horizontal scroll bar
• Add complete tab structure for the interface
• Add context menus for chromosomes, features and links
• Allow reordering of genomes and chromosomes by using the context menus
• Allow specific hiding of features, links and chromosomes

0.2.1 <2015-07-16 Do>

• Added MIT License
• Included License information for third party libraries

0.2.0 <2015-07-16 Do>

• allow for input as tsv and bed files as alternative to fasta files
• demo data added - seven chloroplast genomes
• documentation added
• test cases added
• added interactive JavaScript output
• renamed to Alignment Toolbox and Visualization (AliTV)

0.1.0 <2015-01-31 Sa>

• First release of the wgaPipeline code.
• Automated whole genome alignment and circos visualization from two fasta files.

alitv's Issues

Javascript part finished for v1.0

This issue should be closed if the milestone Javascript is finished for version v1.0

BioJS

Contact the developers of BioJS and discuss the possibility of integrating AliTV.pl into BioJS.

Distinguish AliTV from other software packages

We need to distinguish AliTV from other software packages dealing with the some problem (eg. Easyfig, Mauve, BRIG, etc.)

Implement rotation of the tree

Documentation part finished for version v1.0

This issue should be closed if the milestone Documentation is finished for v1.0

Logo for AliTV

Creation of a new AliTV logo

Tracks on Chromosomes (Perl part)

AliTV should be able to display track information on the chromosomes. Therefore AliTV.pl has to import those data and provide them to the Javascript part.

Make z level of feature type configurable

The user should be able to define the z level for each feature type. So features are drawn in a defined order.

Bring grunt functionality into testing branch

Perl part finished for version v1.0

This issue should be closed if the milestone Perl is finished for v1.0

Performance testing

Performance tests should be integrated into the project build process. Most performance testing tools (like the ones described here: http://cognition.happycog.com/article/grunt-plugins-reviewed) require a publicly hosted version of the page. We would need a more generic approach where we run javascript code locally with different input data and monitor the execution times. Moreover the common "performance budgeting" does not fit perfectly for our purpose.

Create demo sets

Update circular layout

Reverse feature orientation leads to wrong visualization

Features with a start value greater than the end value are not displayed correctly. They start at the start value but are always drawn right with width = Math.abs(feature.end - feature.start). The Math.abs() call leads to the wrong behaviour in this case.

Hiding of elements with non-unique names

When trying to hide an element with a non unique-name with the context menu only the first one in features array is hidden. That is not necessarily the one which was clicked on. Furthermore it is not possible to hide the other one.
Reproduce with demo:

• Right click on the ycf2 feature in the second inverted repeat of O. europaea.
• Select Hide.
• The ycf2 in the first inverted repeat disappears while this one remains.
• Repeat the procedure multiple times.
• Nothing else happens.

generateJSONfiles.pl: Creation of the destination folder caused die

When executing the pipeline on an existing dataset with an existing output folder, the program generateJSONfiles.pl will die.

generateJSONfiles.pl: Error message during copying of files should contain the filename

The error messages should contain the file name, otherwise it is hard to track which file caused the copy process to die.

Set HTML ids for svg elements

Set karyoIDs, linkIDs and featureIDs to the svg elements.
This improves the capability of explicit selection of specific elements.
This is especially important to write stable test cases.
There are also other possible benefits like specific deletion.

generate default filters on setData

For an AliTV object to function properly an appropriate filter is required for each data set. Therefore a default filter should be generated when setData is called (it can set all chromosomes to visible and not reversed).

Build button for testing_d3 branch links to grunt branch

The build button inside the readme links to the grunt branch which does not exist anymore. This should be fixed.

Implement dynamic feature menus

Add a legend

Add a clear function

There should be a function to clear the complete drawing area by removing all children from the svg.
like:

var svg = $('#ali');
var ali = new AliTV(svg);
ali.clear();

Version number for frontend

Frontend needs a single version number which should be consistent with the version number of the backend script.

Perl part finished

This issue should be closed if the milestone Perl is finished

Update readthedocs

Ribbons have arc in wrong direction if endAngle < startAngle

When the endAngle is lower than the startAngle in a link of the circular layout the arc on the chromosome is drawn in the wrong direction (see attached image). This has to be fixed, the arc should always be drawn to follow the karyo.

Import Genbank files for features

The script AliTV.pl has to handle Genbank files as input for features of genomes.

Improve skipping of chromosomes with no visible linkage information in the current configurations.

With the new function filterCurrentVisibleChromosomes it is possible to filter all chromosomes without visible links when you filter the minLinkIdentity or/and the maxLinkIdentity.
The problem is, when you skip chromosomes without visible links you cannot restore their coordinates, because they are no longer calculated in getLinearKaryoCoords. When you want to restore all chromosomes you have to reload the page.
But I think it is better when you can dynamically restore hidden chromosomes without reloading the page. Maybe it is possible to add the statement if chromosomes are visible or not before drawing them.

Central version number for Perl code

The AliTV.pl script needs a single version number which should be consistent with the version number of the interface.

Automatic ordering/rotating

AliTV.pl has to reorder/rotate automatically according to the input data.

Add license information for thirt party libraries

This has to be fixed immediately.

Make fade values configurable

At the moment the links are drawn with 100% opacity and fade to 10% on mouse over.
Those values should not be hard coded but taken from the conf property.

Tutorial for the backend

Import GFF file for features

The script AliTV.pl has to handle GFF files as input for features of genomes.

Auto update values of UI elements based on values from AliTV object.

The sliders, checkboxes and textfields of the HTML user interface should be set to the values used by the AliTV object on startup and after changes (new file loaded, jsoneditor, api, automatic,...).
Otherwise undesired side effects take place when the user hits the Apply button.

Log time recycles after 24 hours.

The way the elapsed_time is calculated for logging in the Verbose module is only correct for values below 24h. After 24h the number of days is just ignored and 25h will look like this: [01:00:00].
This should be changed by moving the whole logging mechanism from Verbose to log4perl

add validity check to setData

check the provided data for validity, each chromosome should have non negative length, for each feature the chromosome should exist in karyo and the coordinates should be valid, for each link the source and target feature should exist and the identity should be between 0 and 100.
The check function should be called from setData and warn if inconsistencies are found.

Tutorial for the frontend

Use case

Define and describe a use case for AliTV.pl

add validity check to setFilters

When setFilters is called, it is important, that the filters fit the current data. Therefore a check is required that tests if each chromosome in data.karyo.chromosomes has its counterpart in filters.karyo.chromosomes, etc.

Implement chromosome rotation

Tracks on Chromosomes (Javascript part)

AliTV should be able to display track information on the chromosomes. Therefore the Javascript has to display those information provided by the AliTV.pl script.

Evaluate mobile compatibility

Fade on mouseover removes the wrong links.

When hovering over a chromosome some links fade out. In the current version in d3.js branch the wrong links are displayed.

Import newick tree

The AliTV.pl script have to handle newick trees if provided.

Draw Linear/Circular Buttons to Switch

Instead of separate buttons to draw linear or circular implement a switch to set the corresponding conf option. The layout to be drawn is a graphical parameter just like all the others and as such should not be treated differently. The apply button should be the only action to actually draw/redraw.

Fixed Limit for MaxLinkLength Slider

The Slider to set the MaxLinkLength has a fixed maximum at 1000. This is not appropriate for many cases. The maximum of the MaxLinkLength has to be at least as big as the maximum actual link length observed in the data.

Autoadjust "Spacer between genomes in the linear Layout" wastes space

The calculation of the genome distance wastes vertical space due to the way it is calculated:

var genomeDistance = this.getCanvasHeight() * 1 / this.filters.karyo.genome_order.length;

Because there is one less spacer required than there are genomes, the denominator can be decreased by one. However there is one additional karyoHeight required otherwise the last genome is just outside of the canvas (substract this from the numerator):

var genomeDistance = (this.getCanvasHeight() - this.getKaryoHeight) / (this.filters.karyo.genome_order.length - 1);

Tests have to be updated.

Autoadjust "Spacer between genomes in the linear Layout"

The spacer between genomes in the linear layout can be automatically calculated to use the vertical space. So the user can change the canvas height in order to change the spacing between genomes.
Otherwise those parameters have to be adjusted simultanously.

The function should be similar to getOuterRadius for the circular layout. Remove the conf value and replace it with a getter function that dynamically calculates the value. Add tests to check if the value is calculated correctly for different number of genomes and different heights.