Metadata-Version: 2.1
Name: trackplot
Version: 0.3.2
Summary: 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/
License: BSD-3
Author: ygidtu
Author-email: ygidtu@gmail.com
Requires-Python: >=3.8,<3.12
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: adjusttext (>=0.7.3,<0.8.0)
Requires-Dist: cairocffi (>=1.4.0,<2.0.0)
Requires-Dist: click (>=8.1.3,<9.0.0)
Requires-Dist: click-option-group (>=0.5.5,<0.6.0)
Requires-Dist: filetype (>=1.2.0,<2.0.0)
Requires-Dist: flask (>=2.3.2,<3.0.0)
Requires-Dist: hicmatrix (>=15,<16)
Requires-Dist: loguru (>=0.6.0,<0.7.0)
Requires-Dist: matplotlib (>=3.6.3,<4.0.0)
Requires-Dist: numpy (>=1.24.1,<2.0.0)
Requires-Dist: pandas (>=1.5.3,<2.0.0)
Requires-Dist: pybigwig (>=0.3.18,<0.4.0)
Requires-Dist: pysam (>=0.21.0,<0.22.0)
Requires-Dist: requests (>=2.28.2,<3.0.0)
Requires-Dist: scipy (>=1.10.0,<2.0.0)
Requires-Dist: seaborn (>=0.12.2,<0.13.0)
Requires-Dist: xmltodict (>=0.13.0,<0.14.0)
Description-Content-Type: text/markdown

# trackplot

[![PyPI version](https://badge.fury.io/py/trackplot.svg)](https://pypi.org/project/trackplot/)
[![PyPI download](https://img.shields.io/pypi/dm/trackplot.svg)](https://pypi.org/project/trackplot/)
[![install with bioconda](https://img.shields.io/badge/install%20with-bioconda-brightgreen.svg?style=flat)](http://bioconda.github.io/recipes/trackplot/README.html)
[![Documentation Status](https://readthedocs.org/projects/trackplot/badge/?version=latest)](https://trackplot.readthedocs.io/en/latest/)
[![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%20v3-clause.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![DOI](https://img.shields.io/badge/DOI-10.1101%2F2022.11.02.514803%20-blue)](https://www.biorxiv.org/content/10.1101/2022.11.02.514803v1)

---

![](example/diagram.png)

[Tutorials](https://trackplot.readthedocs.io/en/latest/)

## 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](https://github.com/deeptools/pyBigWig) optional]
- bigWig [[pyBigWig](https://github.com/deeptools/pyBigWig) optional]
- naive Hi-C format [[hicmatrix](https://github.com/deeptools/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](https://github.com/deeptools/pyBigWig) and [hicmatrix](https://github.com/deeptools/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.

```bash
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](https://github.com/ygidtu/trackplot/releases) (Linux/WSL 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 and Windows subsystem 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.

```bash
# example with version v0.3.2, please using your interested version according to your needs
export VERSION=0.3.2
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.

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

---


4. install from bioconda

First make sure your conda is properly installed.

```bash
# 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

```bash
# 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
```

---

For additional installation information please visit [here.](https://trackplot.readthedocs.io/en/latest/)  

### Using trackplot by a local webserver

1. [AppImage](https://github.com/ygidtu/trackplot/releases) (Linux/WSL x86_64 only)

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

# startup webserver
./trackplot-${VERSION}-x86_64.AppImage --start-server --host 127.0.0.1 --port 5000 --plots ./plots
```
    
**Note:** the `--plots` were required while using appimages

---

2. Running using command line

```bash
trackplot --start-server --host 127.0.0.1 --port 5000 --plots ./plots
```

3. Running using docker image

```bash
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
```

`-p`: public and private port for the server, default:5000(public):5000(private)
- `-v`, `--volume`: mount the working directory to docker container, for example, the `$PWD/data` could replace by the path to your directory contains all necessary data
- `--user`: prevent docker read and write file using root privileges
- the rest usage please check [Command line usage](./command.md)

---

## Example

The `example` folder is downloaded from [here.](https://github.com/ygidtu/trackplot/archive/refs/heads/main.zip) 
And a more detailed tutorial could be found at [here.](https://trackplot.readthedocs.io/en/latest/)  

```bash
# 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

```bash
## 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](https://raw.githubusercontent.com/ygidtu/trackplot/main/example/example.png).


## Questions

Visit [issues](https://github.com/ygidtu/trackplot/issues) or 
contact [Yiming Zhang](https://github.com/ygidtu) or 
[Ran Zhou](https://github.com/zhou-ran)

## Citation

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

[Zhang et al. bioRxiv, 2022.11.02.514803.](https://www.biorxiv.org/content/10.1101/2022.11.02.514803v1)

