trackplot 0.2.8

The 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. https://sashimi.readthedocs.io/

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 of trackplot

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

The trackplot is written in Python3 (python_requires='>=3.8'), and user could install it in a variety of ways as follows

Notes

1. For microsoft windows, mac (apple silicon) and other arm platform users, due to pysam, pybigwig and hicmatrix do not support those platforms, trackplot couldn't be installed by pypi or conda, pleas use docker image as alternative
2. if segment fault with multiple processing, please try to use docker image, or just run with -p 1.
3. if Please install pyBigWig and hicmatrix occurs, please check the official document of pyBigWig and hicmatrix to solve their requirements.

Using trackplot by a command line

1. install from PyPi

Before running this command line, please check python (>=3.8) was installed.

# optional, enable bigWig, bigBed and hicMatrix support
pip install pybigwig hicmatrix

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`

---

2. AppImage (Linux x86_64 platform only)

All the AppImage files were tested on the official pre-built GNU/Linux distributions docker images:

• Arch: appimagecrafters/tests-env:archlinux-latest
• Fedora: appimagecrafters/tests-env:fedora-30
• Debian: appimagecrafters/tests-env:debian-stable
• Ubuntu: appimagecrafters/tests-env:ubuntu-bionic
• Centos: appimagecrafters/tests-env:centos-7

Due to the limitation of AppImage technic itself, we only provide AppImage for linux (x86_64 platform) users. Once you have installation issues and not familiar with docker, please download the AppImage file from our releases.

Once the AppImage file couldn't work properly please open an issue in this repo, and provide us the system platform and full error messages for us to debug.

Notes:

1. the AppImage will decompress all bundled files before execution, therefore it will a little bit slower than command line tools and source code
2. please use absolute path instead of relative path.

# example with version v0.2.6, please using your interested version according to your needs
export VERSION=0.2.6
chmod +x trackplot-${VERSION}-x86_64.AppImage
./trackplot-${VERSION}-x86_64.AppImage --help

---

3. using docker image

Known issue: the logging time may have several hours mismatch with your local time, due to timezone settings inner the image.

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

# or build docker image from source
git clone https://github.com/ygidtu/trackplot trackplot
cd trackplot
docker build -t ygidtu/docker .
docker run --rm ygidtu/trackplot --help

---

4. install from source code

Prior to installing the tool from the source code, users should verify their Python version (>=3.8).

python --version
# Python 3.10.8

4.1 python3 is not available

If your Python version does not match the requirements of Trackplot, users could follow the cmd to install and more detailed instruction for different system please refer to here.

# If the default Python version does not meet the requirements of Trackplot, 
# users should install an appropriate version. 

# 1. install from source code
#   1.1 Step 1: Download the Source Code 
wget https://www.python.org/ftp/python/3.10.12/Python-3.10.12.tgz
tar -xvzf Python-3.10.12.tgz

#   1.2 Step 2: Build Python
find ./Python-3.10.12/Python -type d | xargs chmod 0755
cd Python-3.10.12
./configure --prefix=$PWD/Python-3.10.12/Python
make
make install

# 2. install trackplot
git clone https://github.com/ygidtu/trackplot trackplot

$PWD/Python-3.10.12/python -m pip install -e trackplot/

# 3. check trackplot
$PWD/Python-3.10.12/Python-3.10.12/Python/bin/trackplot --help

4.2 python3 is available

# 1. download the trackplot
git clone https://github.com/ygidtu/trackplot trackplot
cd trackplot

# 2. install the trackplot and it's requirements to python env
pip install -e .
trackplot --help  # or python main.py --help

# Note: pybigwig hicmatrix were optional, used to enable bigWig, bigBed and hicMatrix support
# Once the installation of pybigwig and hicmatrix fails, and these two formats are not necessary, 
# you still can using trackplot in the following way
pip install -r requirements.txt
python main.py --help

---

5. install from bioconda

First make sure your conda is properly installed.

# Check if conda has been successfully installed.
conda --version

# if conda is not installed, refer to https://conda.io/projects/conda/en/latest/user-guide/install/download.html

After successful installation

# 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

# if conda is getting stuck at solving environment', please refer to https://stackoverflow.com/a/66963979

# or install latest trackplot  
git clone https://github.com/ygidtu/trackplot.git trackplot
cd trackplot
conda env update -n trackplot --file environment.yaml

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

---

6. for pipenv or poetry users

Install pipenv or poetry

git clone https://github.com/ygidtu/trackplot
cd trackplot

# pipenv
# create virtualenv and install required packages
pipenv install
# optional, with `--pypi-mirror https://pypi.tuna.tsinghua.edu.cn/simple` to specify your faverate PyPi mirror
# optional, with `--skip-lock` once encounter locking issues

# switch to virtualenv
pipenv shell && python main.py --help

# or just run with pipenv
pipenv run python main.py --help


# poetry
# once facing installation issues, please try to change PyPi mirror in tool.poetry.source section of pyproject.toml 
# create virtualenv and install required packages
poetry install

# switch to virtualenv
poetry shell  && python main.py --help

# or just run with poetry
poetry run python main.py --help

Using trackplot by a local webserver

1. using AppImage (Linux x86_64 only)

# example with version v0.2.6, please using your interested version according to your needs
export VERSION=0.2.6
gunzip trackplotweb-${VERSION}-x86_64.AppImage
chmod +x trackplotweb-${VERSION}-x86_64.AppImage
./trackplotweb-${VERSION}-x86_64.AppImage --help

# startup webserver
./trackplotweb-${VERSION}-x86_64.AppImage --host 127.0.0.1 --port 5000 --plots ./plots

Note: the --plots were required while using appimages

---

2. Install from a docker image

docker pull ygidtu/trackplotweb

# -v map the current working directory into docker containers
# -p map the outer port to inner port of docker container
docker run --name trackplotweb \
 --rm -v $PWD:$PWD \
 -p 5000:5000 \
 ygidtu/trackplotweb

---

3. Install from source code

Before this, please make sure that trackplot has been properly installed in your env.

git clone https://github.com/ygidtu/trackplot trackplot
cd trackplot/web

# build the frontend static files; If npm was not found, please install nodejs(https://nodejs.org).
npm install -g vue-cli vite && npm install
vite build

# check whether the ui is successfully compiled
ls ../ui

# prepare the backend server
pip install flask

# before startup, check whether the trackplot properly installed
python -c "import trackplot; print(trackplot.__version__)"

cd ../
python server.py --help

---

Example

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

# example of basic plot types
python ../main.py \
  -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 by 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 --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.

Questions

Visit issues or contact Yiming Zhang or Ran Zhou

Citation

If you use the tool in your publication, please cite by

Zhang et al. bioRxiv, 2022.11.02.514803.