# Clinker, drawing gene cluster comparisons you can put in a paper

> Clinker takes a folder of GenBank files, aligns every gene against every other, orders the clusters by similarity and renders an interactive SVG comparison you can adjust in the browser and export. It was built for small biosynthetic clusters, and the documentation is unusually honest about where that assumption breaks.

**gamcil/clinker** — Gene cluster comparison figure generator

- Repository: https://github.com/gamcil/clinker
- Stars: 660 · Forks: 80
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/gamcil-clinker

## Small gene clusters, drawn to scale

Clinker is a pipeline for generating publication-quality gene cluster comparison figures, and the whole design follows from the fact that it deals with small regions rather than whole genomes.

The scope note in the project documentation is the most useful paragraph in the README. It says clinker was designed primarily as a simple way to visualise groups of homologous biosynthetic gene clusters, which are typically small genomic regions with not many genes. If you are looking to align entire genomes, you will likely be better served using tools built for that purpose, and it names Cactus as an example.

That candour is a good sign about the project. A tool that tells you where it does not work saves you a day of waiting for a run that will not finish.

The pipeline itself is four steps, and the documentation lists them. Given a set of GenBank files, clinker automatically extracts protein translations, performs global alignments between sequences in each cluster, determines the optimal display order based on cluster similarity, and generates an interactive visualisation using clustermap.js that can be extensively tweaked before being exported as an SVG file.

So the output is not a static figure. It is an interactive document in the browser that you adjust, and the SVG export is the last step rather than the only one. For a paper figure that usually means the author iterates on the rendering, and the tool is built for that loop.

The audience is a computational biologist or genome scientist producing figures for a manuscript, and the second audience is anyone who wants to reproduce the pipeline in an automated analysis workflow, since the tool also prints alignments to the terminal and can save a session file.

## Global pairwise alignment with a threshold, run in parallel

The alignment stage is what limits the tool, and the mechanism is simple enough to reason about.

The documentation states that it performs pairwise alignments of all genes in all input files using the aligner built into BioPython, and the alignment options in the command line help confirm the shape of it. The `-i/--identity` option sets the minimum alignment sequence identity with a default of 0.3, and the `-j/--jobs` option sets the number of alignments to run in parallel, with 0 meaning use the number of CPUs.

That threshold is a substantive design decision rather than a tuning knob. At 0.3 the default is permissive enough to connect distant homologues, which is what you want for a biosynthetic cluster where the same NRPS domain can sit at 25 percent identity across species. Raise it and the gene groups fragment; the example in the documentation shows the effect, saving alignments only for gene-gene links when identity is over 50 percent with the `-i 0.5` flag.

The `-na/--no_align` flag skips alignment entirely, which is the escape hatch for when you already know the gene correspondence and only want the layout. It pairs with the `-gf/--gene_functions` option, which takes a two-column CSV of gene identifiers and function names, and builds the gene groups from the stated function rather than from sequence similarity. The documentation's example assigns two genes to Cytochrome P450 and two to Methyltransferase, and notes that any other homologous genes identified are added to those groups automatically.

The scaling limit follows directly from the design. Pairwise alignment of all genes against all genes in all inputs is quadratic in the number of genes, and the visualisation then contains one SVG element per gene per link, so the output grows with it.

The dependency set in the packaging metadata reflects the approach: biopython at 1.80 or newer for the aligner, numpy and scipy for the numerical work, `disjoint-set` for the clustering that decides which genes belong together, and gffutils for the GFF3 input path.

## Three ways to install, and a webserver that needs none

Installation is pip, a git clone, or conda, and the three routes differ in what they assume about your environment.

The direct route is one command.

`pip install clinker`

Cloning the source and installing from the checkout is the other pip route.

```bash
git clone https://github.com/gamcil/clinker.git
cd clinker
pip install .
```

And the conda route creates a dedicated environment.

```bash
conda create -n clinker -c conda-forge -c bioconda clinker-py
conda activate clinker
```

The conda route installs `clinker-py`, not `clinker`, which is worth knowing before you go looking for the wrong package name on bioconda. The environment is also the one that will have Biopython and the scientific stack already resolved, which matters because the packaging metadata requires biopython 1.80 or newer, numpy 1.13.3 or newer, scipy 1.3.3 or newer, disjoint-set 0.7.1 or newer and gffutils, with Python 3.6 or newer.

There is also a Docker route that the repository supports with a Dockerfile at the root, built on ubuntu:20.04 with python3 and python3-pip installed, the source copied into the image and installed with pip3.

And there is the option that requires no installation at all. The project documentation notes that both cblaster and clinker can be used without installation on the CAGECAT webserver, which is the fastest way for someone to see whether the tool is even the right one before setting up an environment.

The console entry point is `clinker`, mapped to `clinker.main:main`. The version number is read out of `clinker/__init__.py` by a small function in setup.py that regex-matches the `__version__` assignment, so the version has a single source of truth.

## From a folder of GenBank files to an interactive figure

The usage section is short, and the shortest command already does something useful.

`clinker clusters/*.gbk`

This reads in all GenBank files inside the folder, aligns them, and prints the alignments to the terminal. That is the alignment half of the pipeline on its own, and it is what you would run if you wanted to check the gene groups before committing to a figure.

The plot argument adds the visualisation. With `-p/--plot` and no path, the plot is served dynamically using Python's HTTP server, which is the interactive editing session. With a path, you get a portable HTML file at that path.

`clinker clusters/*.gbk -p <optional: file name to save static HTML>`

GFF3 input works the same way.

`clinker cluster1.gff3 cluster2.gff3 -p`

But there is a catch for GFF3, and it is a common one. A corresponding FASTA file of the same name, with the extension .fa, .fsa, .fna, .fasta or .faa, must be found in the same directory as the GFF3. So cluster1.gff3 needs cluster1.fa sitting next to it, and if it is missing the run fails in a way that is not obvious from the error.

The examples directory in the repository is a working set rather than a toy. It holds GenBank files for species in the Aspergillus genus, A. alliaceus CBS 536.65, A. burnettii MST-FP2249, A. mulundensis DSM 5745 and A. versicolor CBS 583.65, alongside P. vexata CBS 129021, plus a note.md explaining the set. Four or five related clusters is exactly the size the tool was designed for.

The other options worth knowing are the output controls. `-o` saves alignments to a file, `-dl` sets the output delimiter with a human-readable default, `-dc` sets the number of decimal places, `-s` saves a session for later, `-mo` writes the cluster similarity matrix to a file, and `-ufo/--use_file_order` displays the clusters in the order you passed them rather than the computed optimal order.

## Where clinker stops, stated by the project itself

The scope note in the documentation is worth repeating in full, because it is the design constraint that determines whether you should use this at all.

The alignment stage will scale very poorly to multiple genomes with many genes, and the resulting visualisation will also be very slow given how many SVG elements it will contain.

Both failure modes are the same failure mode seen from two sides. Every gene is aligned against every gene in every other cluster, so the alignment cost grows with the square of the gene count. And the SVG holds an element per gene and per link, so the browser has to lay out an enormous document, which is why the documentation says the visualisation will be very slow rather than merely large.

That second point has a consequence the README does not spell out. The interactive editing session runs in a browser, and the browser is the thing that has to hold the figure. A figure with a few hundred genes is fine. A figure with tens of thousands is a browser tab that hangs, and the export path is the same document, so the SVG you would publish inherits the problem.

There is also a dependency outside Python that is easy to miss. The visualisation is generated using clustermap.js, a separate JavaScript library, and the tooling that produces it is not part of the Python package. The documentation links it as the project that the interactive visualisation is built with, and the citation covers both together. If you are generating figures in a headless pipeline with no browser, you need to know how that library is reached in that environment before you commit to the approach.

The counter-case, for balance, is that for a small set of homologous clusters this is exactly the right tool, and the number of steps between a folder of GenBank files and a figure is very short.

## A figure generator with a citation requirement

Two details are easy to overlook and both matter if this goes into a manuscript.

The first is the citation. The documentation asks that if you found clinker useful you cite the paper, and gives the reference as clinker and clustermap.js: Automatic generation of gene cluster comparison figures, by Gilchrist and Chooi, published in Bioinformatics with the DOI 10.1093/bioinformatics/btab007. The repository also carries a CITATION.cff file at the top level, which is the machine-readable form of the same thing and is what tooling reads to attribute the software.

That is a well-formed citation request rather than a demand, and citing the software that produced your figure is normal academic practice, so the cost of compliance is one line in your references.

The second is the licence. The project is MIT, the packaging metadata classifies it under the MIT License and declares the package as operating system independent. There is no restriction on the figures you produce, which matters because a figure in a paper is a derived work of the tool's output in a way that a tool that only writes a file would not care about.

The release history is the other thing to check before you install. The recorded versions are v0.0.30 from 2024-09-24, v0.0.31 from 2024-11-25 and v0.0.32 from 2025-12-22, and the last push to the repository was on 2026-10-18. The project is not archived, and the version scheme is still in the zero series, so the API is not promised to be stable.

The zero-series version is also a signal about the project's shape. This is a research tool that grew into a publication tool, with features appearing in point releases such as the colour map for gene functions that the documentation dates to v0.0.28. Expect to read the changelog rather than a migration guide when you upgrade, and pin a version in any workflow that has to reproduce a figure.

## Conclusion

Clinker suits a microbiologist or genome scientist with a handful of related biosynthetic gene clusters who needs a figure for a paper in an afternoon, and it suits anyone who wants a view they can interrogate in the browser before committing to a static image. It does not suit a project aligning whole genomes or hundreds of clusters, because the pairwise alignment stage scales badly and the SVG becomes enormous, and the documentation points you at Cactus for that. Verify first that your clusters are in the small-regions regime the tool was designed for, that the identity threshold you set produces the gene groups you expect, and that the companion clustermap.js library is reachable in the environment where you intend to edit the figure.

## FAQ

### What is clinker used for?

It is a pipeline for generating publication-quality gene cluster comparison figures. Given GenBank files it extracts protein translations, aligns sequences between clusters, determines the display order from cluster similarity, and produces an interactive visualisation that can be tweaked and exported as SVG.

### How do I install clinker?

Through pip with pip install clinker, from a git clone followed by pip install ., or through conda with conda create -n clinker -c conda-forge -c bioconda clinker-py. There is also a Dockerfile at the repository root, and the documentation notes that clinker and cblaster can be used with no installation at all on the CAGECAT webserver.

### What is the minimum alignment identity and how do I change it?

The -i/--identity option sets the minimum alignment sequence identity and defaults to 0.3. The documentation example raises it to 0.5 with clinker files/*.gbk -i 0.5, which saves only gene-gene links above that identity.

### Does clinker work with GFF3 files?

Yes, with a constraint. A corresponding FASTA file of the same name, using the extension .fa, .fsa, .fna, .fasta or .faa, must be found in the same directory as the GFF3, so cluster1.gff3 needs cluster1.fa beside it.

### What should I use instead of clinker for whole genome alignments?

The project documentation says the alignment stage scales very poorly to multiple genomes with many genes and that the resulting visualisation will be very slow given how many SVG elements it will contain, and it points at tools built for that purpose, naming Cactus as an example.

## Sources

- [gamcil/clinker on GitHub](https://github.com/gamcil/clinker)
- [Issues](https://github.com/gamcil/clinker/issues)
- [License: MIT](https://github.com/gamcil/clinker/blob/master/LICENSE)
- [README](https://github.com/gamcil/clinker/blob/master/README.md)
- [Releases](https://github.com/gamcil/clinker/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gamcil-clinker