pyGenomeTracks: reproducible genome browser figures from a text config

A track list in a text file, and an image out

pyGenomeTracks is described as a standalone program and library to plot beautiful genome browser tracks, and its stated aim is to produce high-quality tracks that are highly customizable. The package description calls it a command-line tool to make beautiful and reproducible genome browser snapshots, and that word reproducible is the one to hold on to.

The mechanism is a configuration file. A configuration file describing the tracks is required to run it, and the easiest way to create one is with the make_tracks_file program, which creates a configuration file with defaults that can be easily changed.

make_tracks_file --trackFiles <file1.bed> <file2.bw> ... -o tracks.ini

make_tracks_file uses the file ending to guess the file type. That single detail removes a large amount of guesswork, because a genomics file format is usually identifiable by its extension, and the alternative is a configuration that repeats the format for every single track.

The rendering step names a region and an output file.

pyGenomeTracks --tracks tracks.ini --region chr2:10,000,000-11,000,000 --outFileName nice_image.pdf

The region syntax is chr:start-end, and the ending of --outFileName defines the image format, with pdf, png and svg as the options. That last part is a small but useful design decision: the output format is chosen by filename, so the same command produces a vector PDF for a manuscript or a PNG for a slide without a separate flag.

The intended audience is stated in the package classifiers as Science and Research and Bioinformatics, and the authors are Lucille Lopez-Delisle, Leily Rabbani, Joachim Wolf and Björn Grüning, with a readthedocs site at pygenometracks.readthedocs.io.

The formats it reads, from bigwig to Hi-C matrices

The list of plottable data types is the substance of the tool, and it covers most of what a genome browser can show.

There is bigwig, which is the continuous signal format. There is bed and gtf, described as having many options, which is the interval and annotation format. There is bedgraph, and bedgraph matrices like TAD-separation scores, which is the score matrix format used for domain analysis. There is epilogos, which maps regulatory states onto a genome. There are narrow peaks, which is the called peak format from ChIP-seq style workflows.

Then the spatial ones. Links, represented as arcs, triangles or squares, which is how a viewer draws a link between two loci. Hi-C matrices, as triangle or squares, which is the contact map format. There is fasta for reference sequence, and maf, multiple alignment format, for showing where genomes align.

Note what links and Hi-C matrices have in common, and why they are separate entries. A Hi-C contact map is itself a square matrix, so the arcs, triangles and squares renderings can take a Hi-C matrix as their input. A link track is the same rendering applied to a set of paired intervals. Sharing the rendering code across both is why one bullet in the list covers two data types.

The tool can make plots with or without Hi-C data, which matters because most figures are not contact maps, and a Hi-C panel adds a large square block to the figure that changes every other panel's proportions.

The examples directory shows the same spread as the format list, with a bigwig example and its ini file, a bigwig track with genes, the same with vertical lines, an epilogos example with a categorisation JSON and its tabix-indexed source, a bedgraph matrix example in two variants, one with lines, a Hi-C example with an HDF5 data file, and two custom Python tracks, helloWorldTrack.py and BedMatrixExampleTrack.py. That last pair matters, because they show that a track can be a Python script you write, which is the extension point for data types the tool does not ship with.

Batch mode writes one file per region from a BED file

The command line options list carries the details that matter for a real workflow.

The --BED option takes a file containing the regions to plot in BED format, instead of a single --region. The documentation explains the consequence directly: if this is the case, multiple files will be created, and the value of --outFileName is used as a template with the coordinates put between the file name and the extension.

That is the batch mode, and it is the feature that turns the tool from a one-off into something you can run over a set of loci. You point it at a BED file of regions and it produces one figure per region, named consistently with the coordinates embedded, which is exactly what you want when you have forty peaks to visualise and no intention of making forty figures by hand.

Two sizing options exist. --width sets the figure width in centimeters with a default of 40, and --plotWidth sets the width in centimeters of the plotting, the central, part. The split between total figure width and plot width is a column layout control, letting the axes and labels occupy a fixed margin while the data area takes the rest.

--height is computed from the content if it is not given, which is the right default for a stacked track figure where the number and height of panels vary by region.

The configuration file itself carries the per-track options, since the options list ends with the note that the figure height is computed based on the tracks in the configuration. That separation, data and layout in the ini file, figure mechanics on the command line, is what makes a figure reproducible: the ini file is the artefact you keep with the paper and the command line is the artefact you keep with the analysis.

The documentation also has a Table of contents with sections on citation, documentation and external users, and the repository carries a docs/ directory with a readthedocs configuration and a coverage badge.

Installing it: conda first, pip second, BEDTools mandatory

pyGenomeTracks works with Python 3.8 or newer, and the recommended installation is via conda.

conda create -n pygenometracks -c bioconda -c conda-forge pygenometracks

A specific version can be pinned, and the example shows a version alongside a Python version.

conda create -n pygenometracks -c bioconda -c conda-forge pygenometracks=3.5 python=3.7

The documentation adds a practical note: conda installation can be quite slow, so using mamba can help, which means creating the environment with mamba and python first, activating it, and then installing pygenometracks with mamba.

conda activate pygenometracks
mamba install -c conda-forge -c bioconda pygenometracks

pip is also supported.

pip install pyGenomeTracks

The dependency that catches people is BEDTools. Since version 3.5, pyGenomeTracks uses BEDTools, and the documentation tells you not to forget to install it or load it into your environment. That is the cost of pybedtools, which is in the dependency list.

The dependency set explains the rest of the design. pyBigWig for bigwig files, hicmatrix for Hi-C contact maps, pysam for BED and tabix handling, bx-python and pyfaidx for fasta, gffutils for gene annotation databases, intervaltree for interval overlap queries, numpy and matplotlib for the drawing itself, and tqdm for progress bars on the file operations.

The matplotlib constraint is worth noting: the manifest specifies matplotlib >=3.1.1,<3.9, an upper bound that will block a pip install into an environment with a newer matplotlib. The conda route avoids this because the bioconda recipe pins a consistent set.

Three console scripts are installed: make_tracks_file for the configuration generator, pyGenomeTracks for the renderer, and pgt as a short alias for the same entry point, which is the one you will type most often.

What pyGenomeTracks cannot do for you

The limits here are clear from the design, and they are the right ones for the tool's purpose.

The first is that the output is static. There is no interactive browser, no zoom, no click on a peak to see the underlying values. If your question is what is at this coordinate, you need a genome browser for that, and pyGenomeTracks is a figure generator for the other question, what does this region look like across these data types.

The second is that it handles one region per figure, or one file per region in batch mode. There is no multi-region contact sheet, so a figure showing twenty loci side by side means writing that figure yourself, or using a different tool.

The third is that it does not interpret the data. It draws what the files contain, and a mislabelled track stays mislabelled. The configuration file controls presentation, not meaning, so the usual figure errors of a genomics figure, a wrong region, a mismatched reference assembly between two tracks, an axis that hides a peak because it is auto-scaled, are all still possible. The tool makes figures that look consistent; it does not make them correct.

The fourth limit is the extension model. A custom track is a Python script, as the helloWorldTrack.py example shows, which is powerful, but it means custom tracks run in your own Python environment with your own dependencies, and a track script that works on one machine is not automatically reproducible on another.

The alternative approach depends on what you need. For a quick look at a locus, an interactive browser such as IGV or the UCSC browser answers the question better and takes no setup. For a figure panel with a specific layout, specific track types and a specific region set, which is what a paper needs, pyGenomeTracks is the tool built for that, and its reproducibility is the reason it exists rather than a browser screenshot.

Licence, release cadence and where the tool is used

The licence field on the repository says GPL-3.0, and the package metadata points the license at the LICENSE file in the repository root. The GPL is a strong copyleft licence, and for a script and configuration file that generates a figure rather than software you distribute, the practical impact is smaller than for a library, but any organisation embedding the tool in a pipeline should read the terms. This is not legal advice.

The release history is dated rather than numbered only, and the release names carry their character. There is 3.9, the Mid-2024 Release from 2024-05-06, 3.8, the Happy New Year 2023 Release from 2023-01-23, and 3.7, the Spring 2022 Release from 2022-03-22. The package version in pyproject.toml is 3.9, and the pyproject also pins requires-python to >=3.8,<4.

The last push was on 2026-10-03, which is recent, while the newest tagged release is from 2024. So the tree is being worked on but the packaging has not been re-cut, and for a tool whose dependency constraints, the matplotlib upper bound in particular, age quickly, that gap is worth checking against the current release before you pin anything.

The distribution channels are broader than PyPI alone. The readme carries a PyPI badge and a bioconda badge, and there is a Galaxy server badge pointing at the European Galaxy server with the tool registered under tool_id=pygenomeTracks, which is how a lot of life science researchers actually run this kind of tool, through a Galaxy instance with the dependencies already resolved.

The project is part of the deepTools family, whose output the documentation cites in the example figure from Ramírez et al. 2017, and the graphical abstract is from Lopez-Delisle et al. 2020 in Bioinformatics. Those two citations are the scholarly provenance of the tool, and for a figure generator the reference that matters is the one showing what the output looks like in a published paper.

Editorial conclusion

pyGenomeTracks suits a genomics researcher who needs to produce a figure panel per genomic region for a paper or a thesis, and who wants the figure to be regenerable from a file rather than adjusted by hand in a graphics program. It does not suit someone who wants an interactive genome browser, since the output is a static image, and it does not suit a workflow that needs many regions rendered at once, since the batch mode is driven by a BED file and still writes one file per region. Before adopting it, check the matplotlib constraint in the dependencies, since the manifest caps matplotlib below 3.9, and install BEDTools, which the documentation says is required since version 3.5.

Frequently asked questions

Official sources

1. deeptools/pyGenomeTracks on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases