FlexiDot: Highly customizable, ambiguity-aware dotplots for visual sequence analyses

FlexiDot is a cross-platform dotplot suite generating high quality self, pairwise and all-against-all visualizations of transposons and other discrete sequences.

To improve dotplot suitability for comparison of consensus and error-prone sequences, FlexiDot supports strict (k-mer based) and relaxed handling of mismatches and ambiguous residues, as well as plotting of pre-computed alignments (i.e. from BLAST or Nucmer).

The custom shading modules facilitate dotplot interpretation and feature identification by adding information on feature annotations and sequence similarities to the images.

Combined with collage-like outputs, FlexiDot supports simultaneous visual screening of large sequence sets, allowing dotplot use in routine screening workflows.

Citation

If you use FlexiDot in your research, please cite us:

Kathrin M. Seibt, Thomas Schmidt, and Tony Heitkam (2018) "FlexiDot: Highly customizable, ambiguity-aware dotplots for visual sequence analyses". Bioinformatics 34 (20), 3575–3577, doi: 10.1093/bioinformatics/bty395 - Read article

FlexiDot versions and updates

<img align="right" width="100" height="100" src="https://github.com/flexidot-bio/flexidot/blob/master/docs/images/FlexiLogo.png?raw=true">

Current version (Jan 2026): FlexiDot v2.1.1

For an overview of FlexiDot version updates please see the code history.

Documentation

• In depth documentation (This readme gives an overview, and more detail is in the documentation.)
• Parameter cheat sheet v1.0.6
• Artificial test sequences used for the examples
• Example: Adding annotation-based shading to a dotplot
• Example: Plotting alignments from BLASTn or Nucmer
• Presentation slides introducing dotplots and our FlexiDot tool

Implementation

FlexiDot is implemented in Python 3, with dependencies:

• numpy
• matplotlib
• biopython
• regex
• colormap
• easydev (required for colormap)
• colour

You can create a Conda environment with these dependencies using the YAML file in this repo.

conda env create -f environment.yml

conda activate flexidot

After activating the flexidot environment you can use pip to install the latest version of FlexiDot.

Installing FlexiDot

Installation options:

Install from PyPI (recommended):

pip install flexidot

Install from bioconda:

conda install -c bioconda flexidot

pip install the latest development version directly from this repo.

pip install git+https://github.com/flexidot-bio/flexidot.git

Test installation.

# Print version number and exit.
flexidot --version

# Get usage information
flexidot --help

Setup Development Environment

If you want to contribute to the project or run the latest development version, you can clone the repository and install the package in editable mode.

# Clone repository
git clone https://github.com/flexidot-bio/flexidot.git && cd flexidot

# Create virtual environment
conda env create -f environment.yml

# Activate environment
conda activate flexidot

# Install package in editable mode
pip install -e '.[dev]'

# Optional: Install pre-commit hooks
pre-commit install

Use FlexiDot

Processing fasta files

FlexiDot accepts one or more uncompressed fasta files as input. The files can contain multiple sequences.

By default, FlexiDot will use shared k-mers between sequence pairs to generate the dot-plot.

# Use individual fasta file (can contain multiple sequences)
flexidot -i input.fasta [optional arguments]

# Use multiple fasta files
flexidot -i input1.fasta input2.fasta [optional arguments]

# Use all fasta files in current directory
flexidot -i *.fasta [optional arguments]

Optional arguments are explained below and in detail with the --help option.

Importantly, -k defines the word size (e.g. -k 10) and -t specifies the sequence type (-t nuc for DNA [default]; -t aa for proteins). The plotting mode is chosen via -m and described below.

Processing pre-computed alignments

FlexiDot can also process pre-calculated alignments from tools such as blastn or nucmer. This approach is often faster than k-mer indexing and is tolerant of gaps and mismatches.

See pre-calculated alignment tutorial for detailed examples.

FlexiDot can process BLAST fmt 6 output or PAF alignment files.

# Run BLASTN with output format 6
blastn -query sSaTar.fas -subject sSaTar.fas -outfmt 6 -out alignments.blast6 \
-word_size 4 -evalue 1e-3 -perc_identity 60.0 -max_target_seqs 10000

# Plot alignments
flexidot -i sSaTar.fas -m 2 -a alignments.blast6 -o blast_dotplot \
--gff sSaTar.gff3 --gff_color_config sSaTar.config

Output:

<p align="center"> <img src="https://github.com/flexidot-bio/flexidot/blob/master/docs/images/blast_dotplot-Polydotplot.png?raw=true" width="400"> </p>

When aligning sequences with nucmer the alignment .delta file can be converted to PAF using paftools.js which comes bundled with Minimap2.

### Using Nucmer

# Self-alignment with nucmer (use --nosimplify for repeats in self alignments)
nucmer --maxmatch --nosimplify --minmatch 10 --mincluster 30 --diagfactor 0.12 \
--prefix self_align sSaTar.fas sSaTar.fas

# Convert directly using paftools (if installed with minimap2)
paftools.js delta2paf self_align.delta > self_align.paf

# Plot alignments
flexidot -i sSaTar.fas -m 2 -a self_align.paf -o nucmer_dotplot \
--gff sSaTar.gff3 --gff_color_config sSaTar.config

Output:

<p align="center"> <img src="https://github.com/flexidot-bio/flexidot/blob/master/docs/images/nucmer_dotplot-Polydotplot.png?raw=true" width="400"> </p>

Plotting modes

FlexiDot allows sequence investigation in three run modes via the option -m/--mode:

-m 0 self sequence comparison -m 1 pairwise sequence comparison -m 2 all-to-all sequence comparison

To run multiple plotting modes, call the option multiple times i.e. -m 0 -m 1 -m 2.

Self dotplots

with -m/--mode 0

In self dotplot mode, each sequence is compared with itself. The resulting dotplots can be combined to form a collage (with --collage) or written to separate files.

# A single sequence compared to itself
flexidot -i Seq2.fasta -m 0 -k 10 -P 15

# Single sequence with annotations
flexidot -i Seq2.fasta -m 0 -k 10 -P 15 -g example.gff3 -G gff_color.config

# Collage of 6 sequences each compared to themselves with Seq2 annotated (shown above)
flexidot -i test-seqs.fasta -m 0 -k 10 --n_col 6 -P 15 -g example.gff3 -G gff_color.config --collage

Pairwise comparisons

with -m/--mode 1

For pairwise dotplots, the collage output is recommended for larger numbers of sequences. The collage output of the 15 pairwise dotplots for the test sequences is shown below. By default, dotplot images are in square format (panel A). This maximizes the visibility of matches, if the compared sequences differ drastically in length. To enable scaling according to the respective sequence lengths, the FlexiDot scaling feature is callable via option -L/--length_scaling (panel B). If scaling is enabled, a red line indicates the end of the shorter sequence in the collage output.

Pairwise comparisons can be limited to only pairs that contain the first sequence in a fasta file using --only_vs_first_seq.

<img src="https://github.com/flexidot-bio/flexidot/blob/master/docs/images/pairwise_low_res.png?raw=true" width="600">

# Panel A
flexidot -i test-seqs.fasta -m 1 -k 10 --n_col 3 -c
# Panel B (with length scaling)
flexidot -i test-seqs.fasta -m 1 -k 10 --n_col 3 -c -L

All-against-all comparisons

with -m/--mode 2

In all-against-all mode, FlexiDot compares each pair from a set of input sequences. To enable the identification of long shared subsequences at a glance, FlexiDot offers similarity shading (switched on/off via option -x/--lcs_shading) based on the LCS length in all-against-all comparisons (see below).

<img src="https://github.com/flexidot-bio/flexidot/blob/master/docs/images/all_against_all.png?raw=true" width="500">

# All-by-all plot, LCS shading using maximal LCS length
# -y/--lcs_shading_ref: 0 = maximal LCS length
# -x/--lcs_shading
flexidot -i test-seqs.