Trackplot

https://github.com/ygidtu/trackplot
Admin
Trackplot is a tool for visualizing next-generation sequencing (NGS) data including DNA-seq,...
Tokens:40,862
Snippets:353
Trust Score:8.9
License:BSD-3-Clause
Update:4 months ago
Show doc for...
Tokens:
Raw
### Run Trackplot AppImage

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Downloads, makes executable, and runs the Trackplot AppImage. Includes an example for starting the webserver.

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

--------------------------------

### Install and Run with uv

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Installs uv, synchronizes packages, and activates a virtual environment to run the main script or directly using uv.

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

# uv
# once facing installation issues, please try to change PyPi mirror
# create virtualenv and install required packages
uv sync

# switch to virtualenv
source .venv/bin/activate  && python main.py --help

# or just run with uv
uv run main.py --help
```

--------------------------------

### Setup GGSashimi Environment with Conda

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Creates a Conda environment for ggsashimi with Python 3.10, installs R and Python dependencies, downloads and makes the ggsashimi.py script executable, and tests the installations.

```bash
# using python 3.10 to set same python version with trackplot
conda create -n ggsashimi -y -c conda-forge -c bioconda r-base python=3.10

conda activate ggsashimi

# install R requirements
Rscript -e "install.packages(c('ggplot2', 'data.table', 'gridExtra'))"

# install python requirements
pip install pysam

# install ggsashimi.py script
wget -c -P $(dirname $(which R)) https://raw.githubusercontent.com/guigolab/ggsashimi/master/ggsashimi.py
chmod +x $(dirname $(which R))/ggsashimi.py

# test ggsashimi.py installation
ggsashimi.py --version
Rscript -e "packageVersion('ggplot2')"
Rscript -e "packageVersion('data.table')"
Rscript -e "packageVersion('gridExtra')"
conda deactivate
```

--------------------------------

### Setup Misopy Environment with Conda

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Creates a new Conda environment named 'misopy' with the misopy package, activates it, and tests the installation of its command-line tools.

```bash
conda create -n misopy -y -c bioconda misopy

# activate and test misopy installation
conda activate misopy && index_gff --help && miso --help
conda deactivate
```

--------------------------------

### Trackplot Basic Usage Example

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

A basic example of how to run the trackplot command with essential parameters like event range and output path.

```bash
trackplot -e chr1:100-200:+ -o output.png
```

--------------------------------

### Clone Trackplot Repository and Install Dependencies

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Clones the trackplot repository, navigates to the benchmark directory, installs Python dependencies, and tests the environment setup.

```bash
git clone https://github.com/ygidtu/trackplot.git trackplot

cd trackplot/bench

pip install -r requirements.txt

# Test the running env
python main.py -h 
```

--------------------------------

### Start trackplot server using AppImage

Source: https://github.com/ygidtu/trackplot/blob/main/docs/web.md

For Linux/WSL users, download the AppImage, make it executable, and then run it to start the web server. The `--plots` directory is required when using AppImages.

```bash
export VERSION=0.3.2
chmod +x trackplot-${VERSION}-x86_64.AppImage
./trackplot-${VERSION}-x86_64.AppImage --help
```

```bash
# startup webserver
./trackplot-${VERSION}-x86_64.AppImage --start-server --host 127.0.0.1 --port 5000 --plots ./plots
```

--------------------------------

### Generate Example Images with trackplot

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Use this command to generate example images with various visualization options. Ensure all specified files exist and paths are correct.

```bash
trackplot \
  -e chr1:1270656-1284730:+\
  -r example/example.sorted.gtf.gz \
  --density example/density_list.tsv \
  --show-site \
  --focus 1272656-1272656:1275656-1277656 \
  --stroke 1275656-1277656:1277856-1278656@blue \
  --sites 1271656,1271656,1272656 \
  --line example/line_list.tsv \
  -o example/example.png \
  --dpi 300 \
  --width 10 \
  --height 1 \
  --barcode example/barcode_list.tsv \
  --heatmap example/heatmap_list.tsv \
  --interval example/interval_list.tsv \
  --customized-junction example/junctions.tsv
```

--------------------------------

### Install Python from Source and Trackplot

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Install a specific Python version from source if the default version is insufficient, then install Trackplot using pip in editable mode.

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

--------------------------------

### Start Trackplot Webserver

Source: https://github.com/ygidtu/trackplot/blob/main/README.md

Command to start the Trackplot webserver, specifying host, port, and the directory for plots. The --plots argument is required when using AppImages.

```bash
./trackplot-${VERSION}-x86_64.AppImage --start-server --host 0.0.0.0 --port 5000 --plots ./plots
```

--------------------------------

### Install and Run Trackplot AppImage

Source: https://github.com/ygidtu/trackplot/blob/main/README.md

Steps to download, make executable, and run the Trackplot AppImage. Ensure you use the correct version number.

```bash
export VERSION=0.3.3
gunzip trackplot-${VERSION}-x86_64.AppImage
chmod +x trackplot-${VERSION}-x86_64.AppImage
./trackplot-${VERSION}-x86_64.AppImage --help
```

```bash
./trackplot-${VERSION}-x86_64.AppImage --start-server --host 0.0.0.0 --port 5000 --plots ./plots
```

--------------------------------

### Start trackplot server from command line

Source: https://github.com/ygidtu/trackplot/blob/main/docs/web.md

Use this command to start the trackplot web server directly from the command line. Specify the host, port, and the directory for plots.

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

--------------------------------

### Import Trackplot and Set Matplotlib Backend

Source: https://github.com/ygidtu/trackplot/blob/main/docs/interactive.ipynb

Initializes the environment by setting the matplotlib backend to inline and importing necessary libraries. Prints the installed trackplot version.

```python
# before import trackplot please switch matplotlib to inline mode|
%matplotlib inline

import matplotlib   # used to change prevew image size
import trackplot
from trackplot.plot import Plot

print(trackplot.__version__)
```

--------------------------------

### Benchmark Statistics Output Format

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Example format of the stats.txt file, showing event, time, memory, software, number of files, and number of jobs.

```bash
event   time    memory  software        num_of_files    n_jobs
ENSG0000022397  31.42   86331392        miso    6       1
ENSG0000022397  35.95   253845504       trackplot       6       1
ENSG0000022397  6.700000000000005       253845504       ggsashimi       6       1
ENSG0000022723  80.27000000000002       253845504       miso    6       1
ENSG0000022723  86.10000000000001       289869824       trackplot       6       1
ENSG0000022723  21.92999999999999       289869824       ggsashimi       6       1
```

--------------------------------

### Setup Trackplot Environment with Conda

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Creates a new Conda environment named 'trackplot' with Python 3.10, activates it, installs the trackplot package, and tests the installation.

```bash
conda create -n trackplot -y -c conda-forge python=3.10

# activate and install trackplot
conda activate trackplot
pip install trackplot

# test trackplot installation
trackplot --version
conda deactivate
```

--------------------------------

### Install trackplot using pip

Source: https://github.com/ygidtu/trackplot/blob/main/README.md

Install trackplot using pip. Ensure Python 3.8 or higher is installed. If you encounter issues with PyPI mirrors, try another mirror.

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

--------------------------------

### Install Trackplot and Optional Dependencies from PyPI

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Install the trackplot package and optional dependencies for bigWig, bigBed, and hicMatrix support using pip. Ensure Python version 3.8 or higher is installed.

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

--------------------------------

### Run Trackplot via Command Line

Source: https://github.com/ygidtu/trackplot/blob/main/README.md

Basic command to start the Trackplot server using the command line interface.

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

--------------------------------

### Install Trackplot from Source with Available Python 3

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Clone the Trackplot repository and install it in editable mode using pip. This method is suitable when Python 3 is already available and meets the requirements.

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

--------------------------------

### ggsashimi Input File Format

Source: https://github.com/ygidtu/trackplot/blob/main/bench/pipeline.md

Example format for the ggsashimi input file, which maps sample names to their corresponding BAM file paths. Files must be tab-separated.

```bash
HEK293_Control_R1   ./STAR/SRR1032173.Aligned.sortedByCoord.out.bam
HEK293_Control_R2   ./STAR/SRR1032174.Aligned.sortedByCoord.out.bam
Stau1_KnockDown_R1  ./STAR/SRR1032175.Aligned.sortedByCoord.out.bam
Stau1_KnockDown_R2  ./STAR/SRR1032176.Aligned.sortedByCoord.out.bam
Stau1_Overexpression_R1 ./STAR/SRR1032177.Aligned.sortedByCoord.out.bam
Stau1_Overexpression_R2 ./STAR/SRR1032178.Aligned.sortedByCoord.out.bam
```

--------------------------------

### Deploy Trackplot with Docker

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Pulls the Trackplot Docker image and runs it as a container, mapping ports and volumes for data and plots, and starting the server.

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

--------------------------------

### GGSashimi Input Data Format

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Example of the 3-column tab-separated list required for GGSashimi, including BAM alias, BAM path, and color.

```bash
HEK293_Control_R1     ./STAR/SRR1032173.Aligned.sortedByCoord.out.bam  #CC0011
HEK293_Control_R2     ./STAR/SRR1032174.Aligned.sortedByCoord.out.bam  #CC0011
Stau1_KnockDown_R1    ./STAR/SRR1032175.Aligned.sortedByCoord.out.bam  #FF8800
Stau1_KnockDown_R2    ./STAR/SRR1032176.Aligned.sortedByCoord.out.bam  #FF8800
Stau1_Overexpression_R1       ./STAR/SRR1032177.Aligned.sortedByCoord.out.bam  #0080FF
Stau1_Overexpression_R2       ./STAR/SRR1032178.Aligned.sortedByCoord.out.bam  #0080FF
```

--------------------------------

### Show Site and Strand Density in Trackplot

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Visualizes the density of reads starting at specific sites and separated by strand using `--show-site`, `--focus`, and `--sites` parameters. Requires an event region, reference GTF, and density list.

```bash
trackplot \
  -e chr1:1270656-1284730:+ \
  -r example/example.sorted.gtf.gz \
  --density example/density_list.tsv \
  --show-site \
  --focus 1272656-1272656:1275656-1277656 \
  --sites 1271656,1272656 \
  --output example.pdf
```

--------------------------------

### Install trackplot using Conda

Source: https://github.com/ygidtu/trackplot/blob/main/README.md

Install trackplot into a new conda environment. Activate the environment to use the command-line tool.

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

--------------------------------

### Prepare Reference GTF File

Source: https://github.com/ygidtu/trackplot/blob/main/example/Article_figures/FigS3/B/README.md

Downloads, sorts, and indexes a human reference GTF file using aria2c, bedtools, and tabix. Ensure these tools are installed and accessible in your PATH.

```bash
aria2c -c https://ftp.ensembl.org/pub/release-87/gtf/homo_sapiens/Homo_sapiens.GRCh37.87.chr.gtf.gz
bedtools sort -i Homo_sapiens.GRCh37.87.chr.gtf.gz | bgzip > Homo_sapiens.GRCh37.87.chr.sorted.gtf.gz
tabix -p gff Homo_sapiens.GRCh37.87.chr.sorted.gtf.gz
```

--------------------------------

### Prepare SplicePlot Environment

Source: https://github.com/ygidtu/trackplot/blob/main/bench/pipeline.md

Sets up a Conda environment for SplicePlot, installs Python and command-line tool dependencies, and downloads/tests the SplicePlot scripts.

```bash
conda create -n spliceplot -c conda-forge python=2.7

conda activate spliceplot

# install python requirements
pip install pysam matplotlib scipy numpy pandas

# install required command line tools
conda install -c bioconda samtools tabix

# setup SplicePlot scripts
wget -c https://github.com/wueric/SplicePlot/archive/refs/tags/1.1.tar.gz
tar -xzf 1.1.tar.gz && cd SplicePlot-1.1

# test SplicePlot installation
python check_module_availability.py && python plot.py -h

conda deactivate
```

--------------------------------

### Aggregate Sample Files in Trackplot

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Aggregates multiple input files into a single track using the `--density` parameter with a configuration file. This example shows aggregation for scRNAseq or splice-QTL datasets.

```bash
trackplot \
  -e chr9:112296343-112335026 \
  -r Homo_sapiens.GRCh38.101.chr.gtf.gz \
  --density bam.tsv \
  -o PTBP3.agg.pdf \
  --dpi 300 \
  --width 6 \
  --height 1 --show-junction-num \
  --included-junctions chr9:112297917-112330441:-,chr9:112297917-112333470:-,chr9:112330475-112333470:-
```

--------------------------------

### Generate Basic Plot Types with Trackplot

Source: https://github.com/ygidtu/trackplot/blob/main/README.md

Example command for generating various plot types using Trackplot, specifying input files for intervals, density, IGV, heatmap, and lines, along with output and display options.

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

--------------------------------

### Run Trackplot with Docker and Absolute Paths

Source: https://github.com/ygidtu/trackplot/blob/main/README.md

Example command to run Trackplot within a Docker container, using absolute paths for input files and specifying various plotting parameters. This ensures correct file access within the containerized environment.

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

--------------------------------

### Miso Benchmarking Configuration

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Sets up the `miso.txt` file for Miso benchmarking. This file lists the path to aligned BAM files, an alias for each sample, and a color code for visualization.

```bash
./STAR/SRR1032173.Aligned.sortedByCoord.out.bam  HEK293_Control_R1     #CC0011
./STAR/SRR1032174.Aligned.sortedByCoord.out.bam  HEK293_Control_R2     #CC0011
./STAR/SRR1032175.Aligned.sortedByCoord.out.bam  Stau1_KnockDown_R1    #FF8800
./STAR/SRR1032176.Aligned.sortedByCoord.out.bam  Stau1_KnockDown_R2    #FF8800
./STAR/SRR1032177.Aligned.sortedByCoord.out.bam  Stau1_Overexpression_R1       #0080FF
./STAR/SRR1032178.Aligned.sortedByCoord.out.bam  Stau1_Overexpression_R2       #0080FF
```

--------------------------------

### Motif weight matrix format

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Example format for a motif weight matrix in bedGraph format, including chromosome, start, end, and weights for A, T, C, G.

```bash
# chromosome  start end A_weight T_weight C_weight G_weight
chr1  100 101 0.1 0.2 -0.3  -0.4 
```

--------------------------------

### Display All Command Line Arguments

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

This command lists all available arguments and their descriptions for the main script, useful for understanding customization options.

```bash
python main.py --help
```

--------------------------------

### Install Trackplot using Conda

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Install Trackplot into a Conda environment using bioconda and conda-forge channels. This includes options for installing into the default environment or a new isolated environment.

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

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

--------------------------------

### Check Python Version

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Verify that Python version 3.8 or higher is installed before installing Trackplot from source.

```bash
python --version
# Python 3.10.8
```

--------------------------------

### Generate BAM List for Benchmark (bam_list.txt)

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Format for bam_list.txt, containing BAM file path, alias, and color for multiple BAM files.

```bash
./STAR/SRR1032173.Aligned.sortedByCoord.out.bam        HEK293_Control_R1   #CC0011
./STAR/SRR1032174.Aligned.sortedByCoord.out.bam        HEK293_Control_R2   #CC0011
./STAR/SRR1032175.Aligned.sortedByCoord.out.bam        Stau1_KnockDown_R1  #FF8800
./STAR/SRR1032176.Aligned.sortedByCoord.out.bam        Stau1_KnockDown_R2  #FF8800
./STAR/SRR1032177.Aligned.sortedByCoord.out.bam        Stau1_Overexpression_R1 #0080FF
./STAR/SRR1032178.Aligned.sortedByCoord.out.bam        Stau1_Overexpression_R2 #0080FF
```

--------------------------------

### Generate BAM List for Benchmark (bam_list2.txt)

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Format for bam_list2.txt, containing BAM file path, alias, and color for a single BAM file.

```bash
./C143/outs/possorted_genome_bam.bam        BALF_C143   #CC0011
```

--------------------------------

### Run MISO Pipeline

Source: https://github.com/ygidtu/trackplot/blob/main/bench/pipeline.md

Activates the MISO environment, generates a MISO index, and runs the MISO pipeline for each aligned BAM file to prepare for sashimi plotting.

```bash
conda activate misopy

# generate miso index
cd ref
zcat Homo_sapiens.GRCh38.101.chr.gff3 > Homo_sapiens.GRCh38.101.chr.gff3
index_gff --index Homo_sapiens.GRCh38.101.chr.gff3 miso_index/

mkdir miso
for i in $(ls STAR/*.Aligned.sortedByCoord.out.bam);
do
  echo $i
  mkdir miso/${$(basename $i)/.Aligned.sortedByCoord.out.bam/""}
  miso --run ref/miso_index/ $i --output-dir miso/${$(basename $i)/.Aligned.sortedByCoord.out.bam/""} --read-len 44 -p 20
done
```

--------------------------------

### Add Focus Regions and Strokes to Plot

Source: https://github.com/ygidtu/trackplot/blob/main/docs/interactive.ipynb

Use this snippet to add highlighted focus regions and custom strokes to a plot. Specify regions by start and end sites, and strokes by start, end, and color. Named parameters can be used for strokes.

```python
plot.add_focus(
    f"{1270656 + 2000}-{1270656 + 3000}"                                                      # the focus region in start_site-end_site format
).add_focus(
    f"{1270656 + 5000}-{1270656 + 7000}"
).add_stroke(
    f"{1270656 + 5000}-{1270656 + 7000}:{1270656 + 7200}-{1270656 + 8000}@blue"               # the stroke in start_site-end_site:start_site-end_site@color format, this will add 2 strokes and the last on will be blue
).add_stroke(                                                                                 # add stroke with named parameters
    start=1270656 + 7500,                                                                     # the start site of added stroke
    end=1270656 + 8200,                                                                       # the end site of added stroke
    color="green",                                                                            # the color of added stroke
    label="test"                                                                              # the label of added stroke
)

plot.plot(
    threshold=10,
    height = 1,
    width=10
)
```

--------------------------------

### set_region

Source: https://github.com/ygidtu/trackplot/blob/main/docs/interactive.md

Changes the plot region by specifying the chromosome, start, end, and strand.

```APIDOC
## set_region

### Description
Changes the plot region by specifying the chromosome, start, end, and strand.

### Method
```python
def set_region(self, chromosome: str, start: int, end: int, strand: str = "+")
```

### Parameters
#### Path Parameters
- **chromosome** (str) - Required - The chromosome of the given region.
- **start** (int) - Required - The start site of the given region.
- **end** (int) - Required - The end site of the given region.
- **strand** (str) - Optional - The strand of the given region. Defaults to "+".
```

--------------------------------

### Check and Preview Benchmark Results with R

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Use this R script to verify the proper generation of benchmark results and to preview them.

```bash
Rscript plot.R
```

--------------------------------

### Download Sample Data for Trackplot

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Downloads necessary sample data including GTF annotation, BAM files, and bigWig files required for trackplot analysis.

```bash
# annotation gtf file
wget -c https://ftp.ensembl.org/pub/release-101/gtf/homo_sapiens/Homo_sapiens.GRCh38.101.chr.gtf.gz

# bam files
aria2c -x 16 https://www.encodeproject.org/files/ENCFF125RUG/@@download/ENCFF125RUG.bam
aria2c -x 16 https://www.encodeproject.org/files/ENCFF854PFR/@@download/ENCFF854PFR.bam
aria2c -x 16 https://www.encodeproject.org/files/ENCFF709LHN/@@download/ENCFF709LHN.bam
aria2c -x 16 https://www.encodeproject.org/files/ENCFF613CGT/@@download/ENCFF613CGT.bam

# bigWig files
aria2c -x 16 https://www.encodeproject.org/files/ENCFF936SHU/@@download/ENCFF936SHU.bigWig
aria2c -x 16 https://www.encodeproject.org/files/ENCFF363UDO/@@download/ENCFF363UDO.bigWig
aria2c -x 16 https://www.encodeproject.org/files/ENCFF051PIE/@@download/ENCFF051PIE.bigWig
aria2c -x 16 https://www.encodeproject.org/files/ENCFF245YUN/@@download/ENCFF245YUN.bigWig
aria2c -x 16 https://www.encodeproject.org/files/ENCFF556EQK/@@download/ENCFF556EQK.bigWig
aria2c -x 16 https://www.encodeproject.org/files/ENCFF476HFB/@@download/ENCFF476HFB.bigWig

aria2c -x 16 http://hgdownload.cse.ucsc.edu/goldenpath/hg38/phastCons470way/hg38.phastCons470way.bw%
```

--------------------------------

### Trackplot Benchmarking Configuration

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Sets up the `trackplot.txt` file for Trackplot benchmarking. This file includes the path to BAM files, their type ('bam'), an alias, and a color code.

```bash
./STAR/SRR1032173.Aligned.sortedByCoord.out.bam  bam     HEK293_Control_R1     #CC0011
./STAR/SRR1032174.Aligned.sortedByCoord.out.bam  bam     HEK293_Control_R2     #CC0011
./STAR/SRR1032175.Aligned.sortedByCoord.out.bam  bam     Stau1_KnockDown_R1    #FF8800
./STAR/SRR1032176.Aligned.sortedByCoord.out.bam  bam     Stau1_KnockDown_R2    #FF8800
./STAR/SRR1032177.Aligned.sortedByCoord.out.bam  bam     Stau1_Overexpression_R1       #0080FF
./STAR/SRR1032178.Aligned.sortedByCoord.out.bam  bam     Stau1_Overexpression_R2       #0080FF
```

--------------------------------

### Prepare Reference and STAR Index

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Downloads human genome reference files (GTF, GFF3, FASTA) and generates STAR and Cell Ranger indices. This step requires significant disk space and processing time.

```bash
mkdir ref && cd ref
wget -c https://ftp.ensembl.org/pub/release-101/gtf/homo_sapiens/Homo_sapiens.GRCh38.101.chr.gtf.gz
wget -c https://ftp.ensembl.org/pub/release-101/gff3/homo_sapiens/Homo_sapiens.GRCh38.101.chr.gff3.gz
wget -c https://ftp.ensembl.org/pub/release-101/fasta/homo_sapiens/dna/Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz

# generate STAR index
zcat Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz > Homo_sapiens.GRCh38.dna.primary_assembly.fa

STAR --runThreadN 20 \
   --runMode genomeGenerate \
   --genomeDir STAR_index \
   --genomeFastaFiles Homo_sapiens.GRCh38.dna.primary_assembly.fa \
   --sjdbGTFfile Homo_sapiens.GRCh38.101.chr.gtf \
   --sjdbOverhang 99

# generate cellranger index
cellranger mkref --nthreads=20 --genome=Homo_sapiens --genes =Homo_sapiens.GRCh38.101.chr.gtf.gz --fasta=Homo_sapiens.GRCh38.dna.primary_assembly.fa.gz
rm Homo_sapiens.GRCh38.101.chr.gtf Homo_sapiens.GRCh38.dna.primary_assembly.fa

# sort gtf and create tabix index
bedtools sort -i Homo_sapiens.GRCh38.101.chr.gtf.gz | bgzip > Homo_sapiens.GRCh38.101.chr.sorted.gtf.gz
tabix -p gff Homo_sapiens.GRCh38.101.chr.sorted.gtf.gz

# sort gff and create tabix index
bedtools sort -i Homo_sapiens.GRCh38.101.chr.gff3.gz | bgzip > Homo_sapiens.GRCh38.101.chr.sorted.gff3.gz
tabix -p gff Homo_sapiens.GRCh38.101.chr.sorted.gff3.gz

cd ..
```

--------------------------------

### Trackplot Benchmark CLI Options

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Displays the command-line options available for the trackplot benchmark script, including input file, output directory, reference genome, event IDs, repeat count, and number of jobs.

```bash
Usage: main.py [OPTIONS]

Options:
  -i, --infile PATH           Path to filelist with three columns, 1st path to
                              bam; 2nd alias of bam; 3rd color of bam.
                              [required]
  -o, --output PATH           Path to output directory.  [required]
  -g, --reference TEXT        Prefix of gtf and gff3.
  -e, --event TEXT            comma seperated gene ids  [default:
                              ENSG0000022397,ENSG0000022723]
  -r, --repeat INTEGER RANGE  How many files to generated.  [default: 6; x>=1]
  -n, --n-jobs INTEGER RANGE  How many processes to use.  [default: 1; x>=1]
  -h, --help                  Show this message and exit.
```

--------------------------------

### Set Plot Region

Source: https://github.com/ygidtu/trackplot/blob/main/docs/interactive.md

Defines the specific genomic region to be displayed in the plot. Requires chromosome, start, and end coordinates, with an optional strand parameter.

```python
def set_region(self, chromosome: str, start: int, end: int, strand: str = "+")
```

--------------------------------

### Generate Plot with Trackplot (Docker)

Source: https://github.com/ygidtu/trackplot/blob/main/example/Article_figures/FigS4/A/README.md

Runs trackplot within a Docker container, mapping local directories to ensure file access. This is an alternative to local installation.

```bash
docker run -v $PWD:$PWD --rm ygidtu/trackplot  \
  -e 17:35832921-35835600 \
  -r $PWD/Mus_musculus.GRCm38.101.chr.sorted.gtf.gz \
  --density $PWD/density_list_abspath.tsv \
  -o $PWD/hsc_8w.Tubb5.remove_dup.2.pdf \
  --dpi 300 \
  --width 6 \
  --height 1 -t 100000 \
  --barcode $PWD/cell_meta.tsv --remove-duplicate-umi -p 12
```

--------------------------------

### Run Main Benchmark Script

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Command to run the main benchmark script using an input BAM list and reference genome.

```bash
python main.py -i bam_list.txt -o benchmark -g ./ref/Homo_sapiens.GRCh38.101.chr.sorted
```

--------------------------------

### Add Highlight Region Under Transcripts

Source: https://github.com/ygidtu/trackplot/blob/main/docs/interactive.md

Add a highlighted stroke under transcripts. Supports custom stroke definitions with labels and colors, or by specifying start and end positions.

```python
def add_stroke(
                self,
                stroke: Optional[str] = None,
                start: int = 0,
                end: int = 0,
                label: str = "",
                color: str = "black"
)
```

--------------------------------

### Run Trackplot AppImage

Source: https://github.com/ygidtu/trackplot/blob/main/docs/installation.md

Execute the Trackplot AppImage on Linux or WSL. Ensure the AppImage file is downloaded from releases and made executable. Use absolute paths for the AppImage.

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

--------------------------------

### Set Region of Interest

Source: https://github.com/ygidtu/trackplot/blob/main/docs/interactive.ipynb

Defines the specific genomic region (chromosome, start, end, and strand) for visualization. This is crucial for focusing the plot on a particular area of interest.

```python
plot.set_region(
    chromosome="chr1",                                                                        # chromosome
    start=1270656,                                                                            # start site
    end=1284730,                                                                              # end site
    strand="+"                                                                                # strand
)
```

--------------------------------

### Scale Heatmap Values

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Use the --heatmap-scale parameter to scale heatmap values. This is demonstrated with 'Raw value' and 'Scaled value' examples, affecting the color intensity.

```bash
# Example: --heatmap-scale
# Raw value
# Scaled value
```

--------------------------------

### Run GGSashimi Benchmark

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Command to run the GGSashimi benchmark with specified GTF file, gene, output name, and BAM list file.

```bash
python run_ggsashimi.py  -g ./ref/Homo_sapiens.GRCh38.101.chr.sorted.gtf.gz -e ENSG00000186007 -o ggsashimi -b ggsashimi.txt
```

--------------------------------

### Add Highlight Background to Track

Source: https://github.com/ygidtu/trackplot/blob/main/docs/interactive.md

Define a focus region with a background highlight. Specify the region using a string format like '100-200:300-400' or by start and end integers.

```python
def add_focus(self, focus: Optional[str], start: int = 0, end: int = 0)
```

--------------------------------

### Generate Sashimi Plots with ggsashimi

Source: https://github.com/ygidtu/trackplot/blob/main/bench/pipeline.md

Activates the ggsashimi environment and runs the ggsashimi.py script to generate sashimi plots. Performance is measured using hyperfine.

```bash
conda actiavte ggsashimi
hyperfine 'ggsashimi.py -b ggsashimi.txt -g ref/Homo_sapiens.GRCh38.101.chr.sorted.gtf.gz -c 1:10000-20000 -o test'
```

--------------------------------

### MISO Plot Settings Configuration

Source: https://github.com/ygidtu/trackplot/blob/main/bench/pipeline.md

Configuration file for sashimi_plot, specifying directories for BAM and MISO output, BAM files, MISO files, and plotting parameters.

```yaml
[data]
# directory where BAM files are
bam_prefix = ./STAR/
# directory where MISO output is
miso_prefix = ./miso/

bam_files = [
   "SRR1032173.Aligned.sortedByCoord.out.bam",
   "SRR1032174.Aligned.sortedByCoord.out.bam",
   "SRR1032175.Aligned.sortedByCoord.out.bam",
   "SRR1032176.Aligned.sortedByCoord.out.bam",
   "SRR1032177.Aligned.sortedByCoord.out.bam",
   "SRR1032178.Aligned.sortedByCoord.out.bam"
]

miso_files = [
   "SRR1032173",
   "SRR1032174",
   "SRR1032175",
   "SRR1032176",
   "SRR1032177",
   "SRR1032178"
]

[plotting]
# Dimensions of figure to be plotted (in inches)
fig_width = 7
fig_height = 5
# Factor to scale down introns and exons by
intron_scale = 30
exon_scale = 4
# Whether to use a log scale or not when plotting
logged = False
font_size = 6

# Max y-axis
ymax = 150

# Whether to plot posterior distributions inferred by MISO
show_posteriors = True

# Whether to show posterior distributions as bar summaries
bar_posteriors = False

# Whether to plot the number of reads in each junction
number_junctions = True

resolution = .5
posterior_bins = 40
gene_posterior_ratio = 5

# List of colors for read densities of each sample
colors = [
   "#CC0011",
   "#CC0011",
   "#FF8800",
   "#FF8800",
   "#0080FF",
   "#0080FF",
]

```

--------------------------------

### Run Miso Analysis

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Executes the Miso script for benchmarking, providing the path to the sorted GFF3 file, the gene of interest, an output directory, and the sample configuration file. It reports execution time and max memory usage.

```bash
python run_miso.py -g ./ref/Homo_sapiens.GRCh38.101.chr.sorted.gff3.gz -e gene:ENSG00000186007 -o miso -b miso.txt
# execution_time=39.83; max_memory=137523200
```

--------------------------------

### Trackplot Help Command

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Displays the help message for the trackplot command, listing all available options and their descriptions. This is useful for understanding the full range of functionalities.

```bash
trackplot --help
```

--------------------------------

### Download and Prepare Reference GTF File

Source: https://github.com/ygidtu/trackplot/blob/main/example/Article_figures/FigS2/A/README.md

Downloads a GTF file using aria2c, sorts it with bedtools, and indexes it with tabix for genomic analysis.

```bash
aria2c -c https://ftp.ensembl.org/pub/release-101/gtf/homo_sapiens/Homo_sapiens.GRCh38.101.chr.gtf.gz
bedtools sort -i Homo_sapiens.GRCh38.101.chr.gtf.gz | bgzip > Homo_sapiens.GRCh38.101.chr.sorted.gtf.gz
tabix -p gff Homo_sapiens.GRCh38.101.chr.sorted.gtf.gz
```

--------------------------------

### Include Domain Categories

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Includes specific domain categories and types for visualization. Domains not matching the specified criteria will be excluded.

```shell
--include PTM:DOMAIN_AND_SITES:STRUCTURAL,helix
```

--------------------------------

### Download FASTQ Data

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

Downloads gzipped FASTQ files from the EBI SRA FTP server. Ensure you have sufficient disk space and a stable internet connection.

```bash
mkdir fastq && cd fastq
wget -c ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR103/003/SRR1032173/SRR1032173.fastq.gz
wget -c ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR103/004/SRR1032174/SRR1032174.fastq.gz
wget -c ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR103/005/SRR1032175/SRR1032175.fastq.gz
wget -c ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR103/006/SRR1032176/SRR1032176.fastq.gz
wget -c ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR103/007/SRR1032177/SRR1032177.fastq.gz
wget -c ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR103/008/SRR1032178/SRR1032178.fastq.gz

cd ..
```

--------------------------------

### Prepare Input Files for Docker Execution

Source: https://github.com/ygidtu/trackplot/blob/main/README.md

Commands to convert relative paths in input files to absolute paths, which is necessary when running Trackplot within a Docker container.

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

--------------------------------

### Visualize BAM Tags (m6A and PolyA) with Sashimi

Source: https://github.com/ygidtu/trackplot/blob/main/docs/command.md

Command to generate a Sashimi plot that visualizes m6A modification and PolyA length from BAM tags.

```bash
trackplot \
  -e chr1:13362-29900:+ \
  --igv example/igv.m6a.tsv \
  -o igv.m6a.pdf \
  --dpi 300 \
  --width 5 \
  --height 1 --rs rs --polya pa --m6a ma
```

--------------------------------

### Prepare and index reference GTF file

Source: https://github.com/ygidtu/trackplot/blob/main/example/Article_figures/FigS3/A/README.md

Downloads, sorts, and indexes a GTF reference file for Homo sapiens. This ensures the reference genome is correctly formatted and accessible for trackplot.

```bash
aria2c -c https://ftp.ensembl.org/pub/release-101/gtf/homo_sapiens/Homo_sapiens.GRCh38.101.chr.gtf.gz
bedtools sort -i Homo_sapiens.GRCh38.101.chr.gtf.gz | bgzip > Homo_sapiens.GRCh38.101.chr.sorted.gtf.gz
tabix -p gff Homo_sapiens.GRCh38.101.chr.sorted.gtf.gz

```

--------------------------------

### Deploy trackplot server using Docker

Source: https://github.com/ygidtu/trackplot/blob/main/docs/web.md

Run the trackplot web server within a Docker container. This method is recommended and involves pulling the Docker image and executing a run command with volume mounts and port mapping.

```shell
docker pull ygidtu/trackplot
```

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

--------------------------------

### Add Custom Site Annotations

Source: https://github.com/ygidtu/trackplot/blob/main/docs/interactive.ipynb

Use `add_sites` to mark specific positions for annotation and `plot` to render the track with these sites. Different colors can distinguish repeat sites.

```python
plot.add_sites(
    1270656 + 1000                                                                            # the highlight site
).add_sites(
    1270656 + 1000                                                                            # the repeat highlight site will show in different color with normal highlight site
).add_sites(
    1270656 + 2000
)

plot.plot(
    threshold=10,
    height=1, 
    width = 10
)
```

--------------------------------

### Generate Benchmark Results with Python

Source: https://github.com/ygidtu/trackplot/blob/main/bench/README.md

This Python script generates a list of commands to run benchmark tests with varying parameters and then executes them in parallel using multiprocessing.

```python
cmds = []
for i in range(0, 20, 5):
  for j in range(0, 20, 5):
    if i == 0:
      i = 1
    if j == 0:
      j = 1
    cmds.append(f"python main.py -i bam_list.txt -o benchmark_r{i}_n{j}/ -g ref/Homo_sapiens.GRCh38.101.chr --repeat {i} --n-jobs {j} --event 1000")

import os
from multiprocessing import Pool
with Pool(4) as p:
  p.map(os.system, cmds)
```
Tokens:
Raw