trackplot

Tutorials

What is trackplot

Trackplot is a tool for visualizing various next-generation sequencing (NGS) data, including DNA-seq, RNA-seq, single-cell RNA-seq and full-length sequencing datasets.

Features

1. Support various file formats as input
2. Support strand-aware coverage plot
3. Visualize coverage by heatmap, including HiC diagram
4. Visualize protein domain based the given gene id
5. Demultiplex the single-cell RNA/ATAC-seq which used cell barcode into cell population
6. Support visualizing individual full-length reads in read-by-read style
7. Support visualize circRNA sequencing data

Input

trackplot supports almost NGS data format, including

• BAM
• Bed
• Depth file generated by samtools depth
• bigBed [pyBigWig optional]
• bigWig [pyBigWig optional]
• naive Hi-C format [hicmatrix optional]

Output

The output will be a pdf and other image file formats which satisfy the requirement of the major journals, and each track on output corresponds these datasets from config file.

Usage

Trackplot is based on Python3 (python_requires='>=3.8'), and we have simplified the installation process on the main page. For a more comprehensive installation guide, please refer to this link.

Quick start

pip install trackplot
trackplot --help

# or using trackplot by conda

conda create -n trackplot -c bioconda -c conda-forge trackplot
conda activate trackplot
trackplot --help

Notes

1. For users on Microsoft Windows, Mac (Apple Silicon), and other ARM platforms, please note that Trackplot may not be installable via PyPI or Conda due to compatibility issues with pysam, pybigwig, and hicmatrix libraries on these platforms. As an alternative, we recommend using the Docker image for installation.

2. If you encounter a segment fault error during multiple processing, you may want to consider using the Docker image or running the command with the -p 1 flag.

3. If you encounter the message Please install pyBigWig and hicmatrix, you can refer to the official documentation for pyBigWig and hicmatrix to fulfill their requirements and resolve the issue.

pip install trackplot
# __Note:__ We noticed some pypi mirrors are not syncing some packages we depend on, 
# therefore please try another pypi mirror once you encounter 
# `No local packages or working download links found for xxx`

# build the AppBundle from source (version auto-detected from pyproject.toml)
sh build-appbundle.sh

# the output filename and appbundle ID are printed at the end of the script
# package with pelf (see https://github.com/xplshn/pelf)
pelf \
    --add-appdir "./trackplot.AppDir" \
    --appbundle-id "$APPBUNDLE_ID" \
    --output-to "$OUTPUT_FILE"

chmod +x "$OUTPUT_FILE"
./"$OUTPUT_FILE" --help

docker pull ygidtu/trackplot
docker run --rm ygidtu/trackplot --help

# install trackplot into the default conda env 
conda install -c bioconda -c conda-forge trackplot

# or install trackplot into an isolated environments
conda create -n trackplot -c bioconda -c conda-forge trackplot

# activate the trackplot environment and execute the command line tool
conda activate trackplot
trackplot --help

# OUTPUT_FILE is printed by build-appbundle.sh
chmod +x "$OUTPUT_FILE"
./"$OUTPUT_FILE" --help

# startup webserver
./"$OUTPUT_FILE" --start-server --host 0.0.0.0 --port 5000 --plots ./plots

trackplot --start-server --host 0.0.0.0 --port 5000 --plots ./plots

docker pull ygidtu/trackplot

# Deploy the server
docker run --name trackplot \
  --rm -v $PWD/example:/data -v $PWD/plots/:/plots -p 5000:5000 ygidtu/trackplot \
  --start-server \
  --host 0.0.0.0 \
  --data /data \
  --plots /plots

Example

The example folder is downloaded from here. And a more detailed tutorial could be found at here.

# example of basic plot types
trackplot \
  -e chr1:1270656-1284730:+ \
  -r example/example.sorted.gtf.gz \
  --interval example/interval_list.tsv \
  --density example/density_list.tsv \
  --show-junction-num \
  --igv example/igv.tsv \
  --heatmap example/heatmap_list.tsv \
  --focus 1272656-1272656:1275656-1277656 \
  --stroke 1275656-1277656:1277856-1278656@blue \
  --sites 1271656,1271656,1272656 \
  --line example/line_list.tsv \
  -o example.png \
  --dpi 300 \
  --width 10 \
  --height 1 \
  --barcode example/barcode_list.tsv \
  --domain --remove-duplicate-umi \
  --normalize-format cpm \
  --annotation-scale .3 \
  -p 4

If trackplot was installed via docker, here is the cmd:

## The absolute path is required in Docker env.
 
cat $PWD/example/interval_list.tsv |grep -v '^#' | while read line; do echo $PWD/${line}; done > $PWD/example/interval_list.abspath.tsv
cat $PWD/example/density_list.tsv |grep -v '^#' | while read line; do echo $PWD/${line}; done > $PWD/example/density_list.abspath.tsv
cat $PWD/example/igv.tsv |grep -v '^#' | while read line; do echo $PWD/${line}; done > $PWD/example/igv.abspath.tsv
cat $PWD/example/heatmap_list.tsv |grep -v '^#' | while read line; do echo $PWD/${line}; done > $PWD/example/heatmap_list.abspath.tsv

docker run -v $PWD:$PWD -w $PWD --rm ygidtu/trackplot \
  -e chr1:1270656-1284730:+ \
  -r $PWD/example/example.sorted.gtf.gz \
  --interval $PWD/example/interval_list.tsv \
  --density $PWD/example/density_list.tsv \
  --show-junction-num \
  --igv $PWD/example/igv.tsv \
  --heatmap $PWD/example/heatmap_list.tsv \
  --focus 1272656-1272656:1275656-1277656 \
  --stroke 1275656-1277656:1277856-1278656@blue \
  --sites 1271656,1271656,1272656 \
  --line $PWD/example/line_list.tsv \
  -o example.png \
  --dpi 300 \
  --width 10 \
  --height 1 \
  --barcode $PWD/example/barcode_list.tsv \
  --domain --remove-duplicate-umi \
  --normalize-format cpm \
  --annotation-scale .3 \
  -p 4

Here is the output file.

For AI agents (auto-install the trackplot skill)

This repo ships a ready-to-use skill that teaches an AI coding agent how to invoke trackplot. When an agent is asked to create a trackplot/sashimi figure, it should install this skill once (path relative to this file):

# opencode / Claude Code style: point the skill manager at the bundled skill
cp -r skills/trackplot ~/.config/opencode/skills/trackplot   # or ~/.claude/skills/trackplot

Then the agent reads skills/trackplot/SKILL.md (plus skills/trackplot/references/config_files.md and skills/trackplot/references/python_api.md) and follows it to:

1. Confirm the input region in chr:start-end:strand form and the annotation GTF.
2. Build the matching config TSV(s) for the requested track type(s) (see the # filepath category label color conventions).
3. Run trackplot -e <region> -r <gtf> --density <list.tsv> -o <out>.pdf (or the equivalent Python Plot(...).set_region(...).add_density(...).plot(...) chain).
4. Verify the output exists; if pybigwig/hicmatrix are needed for bigWig/HiC, install them first.

The skill is the single source of truth for trackplot usage; keep it in sync with docs/command.md and docs/interactive.md.

Questions

Visit issues or contact Yiming Zhang or Ran Zhou

Citation

If you use trackplot in your publication, please cite:

Zhang Y, Zhou R, Liu L, et al. Trackplot: A flexible toolkit for combinatorial analysis of genomic data. PLoS Computational Biology, 2023, 19(9): e1011477.