Trackplot

https://trackplot.readthedocs.io/en/latest/
Admin
A feature-rich sashimi plot framework written in pure Python for bioinformatics visualization.
Tokens:22,369
Snippets:192
Trust Score:9.6
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install trackplot using uv

Source: https://trackplot.readthedocs.io/en/latest/installation

Clone the trackplot repository and prepare for installation using the 'uv' package installer. Notes suggest trying different PyPi mirrors if installation issues arise.

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

# uv
# once facing installation issues, please try to change PyPi mirror
```

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

### Create Virtual Environment and Install Packages

Source: https://trackplot.readthedocs.io/en/latest/installation

Sets up a Python virtual environment and installs required packages using 'uv'.

```bash
uv sync
```

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

### Generate Example Images

Source: https://trackplot.readthedocs.io/en/latest/command

Use this command to generate example images with various plotting options. Ensure all specified files exist.

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

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

### Build and install Python from source

Source: https://trackplot.readthedocs.io/en/latest/installation

Steps to download, build, and install a specific Python version from its source code if the default version does not meet requirements.

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

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

### Install trackplot and optional dependencies from PyPI

Source: https://trackplot.readthedocs.io/en/latest/installation

Install trackplot using pip. Optional packages for bigWig, bigBed, and hicMatrix support can be installed first.

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

pip install trackplot
```

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

### Install optional dependencies for trackplot

Source: https://trackplot.readthedocs.io/en/latest/installation

Install optional dependencies for trackplot from requirements.txt if pybigwig and hicmatrix are not needed or fail to install.

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

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

### Start TrackPlot Server via Command Line

Source: https://trackplot.readthedocs.io/en/latest/web

Use the trackplot command-line tool to start the web server. Specify the host, port, and the directory for plots.

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

```

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

### Install trackplot from source with available Python

Source: https://trackplot.readthedocs.io/en/latest/installation

Clone the trackplot repository and install it into the current Python environment using pip in editable mode.

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

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

### Check trackplot installation with custom Python

Source: https://trackplot.readthedocs.io/en/latest/installation

Verify the trackplot installation by running its help command using the custom Python interpreter.

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

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

### Show read start sites and strand information

Source: https://trackplot.readthedocs.io/en/latest/command

Utilize `--show-site` and `--show-strand` to visualize the density of read starts separately for forward and reverse strands. The `--focus` and `--sites` options allow for highlighting specific regions and sites.

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

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

### Start TrackPlot Server using AppImage

Source: https://trackplot.readthedocs.io/en/latest/web

Execute the TrackPlot AppImage to start the web server. Ensure the AppImage is executable and specify server options. The --plots directory is required when using AppImages.

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

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

```

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

### Check Conda installation

Source: https://trackplot.readthedocs.io/en/latest/installation

Verify if Conda is installed on the system by checking its version.

```bash
conda --version
```

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

### Check Python version

Source: https://trackplot.readthedocs.io/en/latest/installation

Verify that Python version 3.8 or higher is installed, which is a prerequisite for installing trackplot from source.

```bash
python --version
```

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

### Install trackplot from source with custom Python

Source: https://trackplot.readthedocs.io/en/latest/installation

After building a custom Python version, install trackplot using pip in editable mode with the custom Python interpreter.

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

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

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

### Install trackplot into default Conda environment

Source: https://trackplot.readthedocs.io/en/latest/installation

Install trackplot into the currently active Conda environment using the bioconda and conda-forge channels.

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

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

### Install latest trackplot from environment.yaml using Conda

Source: https://trackplot.readthedocs.io/en/latest/installation

Clone the trackplot repository and update a Conda environment using the provided environment.yaml file to install the latest version.

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

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

### Create and install trackplot into isolated Conda environment

Source: https://trackplot.readthedocs.io/en/latest/installation

Create a new Conda environment named 'trackplot' and install trackplot within it using the bioconda and conda-forge channels.

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

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

### Prepare and Run Trackplot AppImage

Source: https://trackplot.readthedocs.io/en/latest/installation

Downloads, prepares, and runs the Trackplot AppImage for Linux. Ensure you replace '0.3.2' with your desired version.

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

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

### Build and run trackplot Docker image from source

Source: https://trackplot.readthedocs.io/en/latest/installation

Clone the trackplot repository, build a Docker image from the source code, and then run the image.

```bash
git clone https://github.com/ygidtu/trackplot trackplot
cd trackplot
docker build -t ygidtu/docker .
docker run --rm ygidtu/trackplot --help
```

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

### Configure Plotting Parameters and Add Visualizations

Source: https://trackplot.readthedocs.io/en/latest/interactive

This snippet demonstrates how to initialize a plot and add various data layers including intervals, density plots, line plots, heatmaps, and IGV tracks. It also shows how to highlight specific sites and define focus regions or strokes.

```python
plot.add_interval(
    interval="../example/PolyASite.chr1.atlas.clusters.2.0.GRCh38.96.simple.bed.gz",          # path to list of interval files in bed format, 1st column is path to file, 2nd column is the label
    interval_label="polyAS"                                                                   # the label of added interval
).set_region(
    chromosome="chr1", start=1270656, end=1284730, strand="+"                                 # chromosome, start site, end site and strand were required
).add_density(
    path="../example/bams/1.bam",                                                             # path to input file
    category="bam",                                                                           # the category of given file
    color="blue",                                                                             # color of this density
    show_site_plot=True,                                                                      # whether to show site plot
).add_density(
    path="../example/bws/2.bw",
    category="bw",
    color="green"
).add_line(
    path="../example/bams/1.bam",                                                             # path to input file
    category="bam",                                                                           # the category of given file
    group="1",                                                                                # the group of this line, used to control color etc.
    color="blue",                                                                             # color of this line and other lines belong to group 1
    line_attrs={"lw": 3}                                                                      # additional parameters in dict to control the layout of line
).add_line(
    path="../example/bams/2.bam",
    category="bam",
    group="2",
    color="red",
    line_attrs={"linestyle": "dashed"}                                                        # additional parameters in dict to control the layout of line, for instance this changes the line style
).add_heatmap(
    path="../example/bams/1.bam",                                                             # path to input file
    category="bam",                                                                           # the category of given file
    group="1",                                                                                # the group of this file, only files belong to same group will be drawn in same heatmap.
).add_heatmap(
    path="../example/bams/2.bam",
    category="bam",
    group="1"
).add_igv(
    path="../example/bams/3.bam",                                                             # path to input file
    features={
        "m6a": "ma",
        "real_strand": "rs",
        "polya": "pa"
    },
    category="igv",                                                                           # the category of given file
    label="igv"                                                                               # the label of this plot
).add_igv(
    path="../example/SRX9697989.corrected_reads.bed.gz",
    category="igv",
    label="bed12"
).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
).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(
    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
)

```

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

### List All Command Line Arguments

Source: https://trackplot.readthedocs.io/en/latest/command

Execute this command to display all available command-line arguments and their descriptions for the Trackplot tool.

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

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

### Download sample data

Source: https://trackplot.readthedocs.io/en/latest/command

Commands to download necessary annotation GTF files, BAM files, and bigWig files for use with trackplot.

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

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

### Activate Virtual Environment and Run Script

Source: https://trackplot.readthedocs.io/en/latest/installation

Activates the virtual environment and runs a Python script with arguments.

```bash
source .venv/bin/activate  && python main.py --help
```

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

### set_region

Source: https://trackplot.readthedocs.io/en/latest/interactive

Changes the plot region to a specified chromosome, start, end, and strand.

```APIDOC
## set_region

### Description
Changes the plot region to a specified 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 "+".
```

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

### Set Plot Region

Source: https://trackplot.readthedocs.io/en/latest/interactive

Defines the genomic region for the plot. Specify chromosome, start, end, and optionally strand.

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

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

### Motif Weight Matrix Format

Source: https://trackplot.readthedocs.io/en/latest/command

Defines the expected format for the motif weight matrix, which should be in a customized bedGraph format. This includes chromosome, start, end, and weights for A, T, C, and G.

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

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

### Run AppImage with a specific version

Source: https://trackplot.readthedocs.io/en/latest/installation

Execute the trackplot AppImage for Linux/WSL. Ensure the AppImage file is executable and use an absolute path for execution. Replace VERSION with the desired release number.

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

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

### add_sites

Source: https://trackplot.readthedocs.io/en/latest/interactive

Adds multiple highlight sites to the track. Sites can be specified as a string in '100,200' format or as integers.

```APIDOC
## add_sites

### Description
Adds multiple highlight sites to the track. Sites can be specified as a string in '100,200' format or as integers.

### Method
```python
def add_sites(self, sites)
```

### Parameters
#### Path Parameters
* **sites** - Required - string in 100,200 format or int
```

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

### Configure BAM file aggregation

Source: https://trackplot.readthedocs.io/en/latest/command

Prepare a TSV file to configure BAM files for aggregation, specifying sample names, types, and grouping identifiers.

```bash
# we use third column to group the different data to aggregate datasets.
ENCFF125RUG.bam bam PTBP1_KD_agg    #0084d1 frf
ENCFF854PFR.bam bam PTBP1_KD_agg    #0084d1 frf
ENCFF854PFR.bam bam PTBP1_KD_2  #0084d1 frf
```

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

### Prepare Trackplot Config File

Source: https://trackplot.readthedocs.io/en/latest/command

Create a configuration file for trackplot, specifying the H5 file path, category, label, color, transform, and depth. This file is used as input for the trackplot command.

```text
# filepath  file_category   label   color  transform depth
example/ENCFF931NQV.h5 hic ENCFF931NQV RdYlBu_r log2 30000
```

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

### Generate Sashimi Plot with IGV Input

Source: https://trackplot.readthedocs.io/en/latest/command

Generates a Sashimi plot using an IGV configuration file. Ensure the IGV file is correctly formatted with filepath, file_category, label, and color.

```bash
trackplot \
  -e 1:10024601-10038168:+ \
  -r example/example.sorted.gtf.gz \
  --igv example/igv.tsv \
  -o igv.1.pdf \
  --dpi 300 \
  --width 10 \
  --height 1

```

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

### Add Highlight Sites

Source: https://trackplot.readthedocs.io/en/latest/interactive

Adds multiple highlight sites to the track. Sites can be specified as a string or integer.

```python
def add_sites(self, sites)


```

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

### Activate Conda environment and run trackplot

Source: https://trackplot.readthedocs.io/en/latest/installation

Activate the 'trackplot' Conda environment and then execute the trackplot command-line tool.

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

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

### Deploy TrackPlot Server using Docker

Source: https://trackplot.readthedocs.io/en/latest/web

Run the TrackPlot web server within a Docker container. This method requires pulling the Docker image and configuring volume mounts for data and plots, as well as port mapping.

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

```

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

### Convert Pairs to Cool and H5 Formats

Source: https://trackplot.readthedocs.io/en/latest/command

Download a pairs format file, index it with pairix, load it into a cooler, and then convert the cooler file to H5 format. This is an alternative method for HiC data preparation, especially if encountering UnicodeDecodeError.

```bash
wget https://www.encodeproject.org/files/ENCFF931NQV/@@download/ENCFF931NQV.pairs.gz
wget http://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.chrom.sizes
pairix ENCFF931NQV.pairs.gz
cooler cload pairix -p 16 hg38.chrom.sizes:1000 ENCFF931NQV.pairs.gz ENCFF931NQV_1kb.cool
hicConvertFormat -m ENCFF931NQV_1kb.cool --inputFormat cool --outputFormat h5 -o ENCFF931NQV.h5
```

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

### Density Plot Input File Formats

Source: https://trackplot.readthedocs.io/en/latest/command

Specifies input files for density plots, including BAM, BigWig, or depth files, with options for labels and colors. Use to define data sources for density visualization.

```bash
# filepath  file_category   label   color
example/bams/1.bam bam
example/bams/2.bam bam  2bam
example/bams/3.bam bam  3bam    blue
example/bws/2.bw    bw bw green
example/bams/sc.bam bam sc

```

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

### Generate Sashimi Plot with BAM Tags for m6A and PolyA

Source: https://trackplot.readthedocs.io/en/latest/command

Generates a Sashimi plot visualizing m6A modification and poly(A) length from BAM tags. Use --polya and --m6a flags to specify the respective 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

```

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

### Pull and run trackplot Docker image

Source: https://trackplot.readthedocs.io/en/latest/installation

Download the official trackplot Docker image and run it to access the command-line tool. The --rm flag removes the container after execution.

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

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

### Run Script Directly with uv

Source: https://trackplot.readthedocs.io/en/latest/installation

Executes a Python script using 'uv' without explicit virtual environment activation.

```bash
uv run main.py --help
```

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

### Aggregate multiple files into one track

Source: https://trackplot.readthedocs.io/en/latest/command

Aggregate data from multiple BAM files into a single track using the `--density` option with a configuration file.

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

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

### Set Sequence Display

Source: https://trackplot.readthedocs.io/en/latest/interactive

Displays the corresponding sequence under the x-axis by providing a path to an indexed FASTA file.

```python
def set_sequence(self, fasta: str)


```

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

### Generate Motif Plot

Source: https://trackplot.readthedocs.io/en/latest/command

Create a motif plot by specifying the region, density file, and motif BED file. The motif weight matrix should be in a customized bedGraph format and bgzipped/tabix indexed.

```bash
trackplot \
  -e chr1:1270656-1270776:+\
  --density example/density_list.tsv \
  -o motif.pdf \
  --dpi 300 \
  --width 10 \
  --height 1 \
  --raster \
  -r example/example.sorted.gtf.gz \
  --motif example/motif.bed.gz \
  --motif-region 1270756-1270760
```

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

### Include Domain Categories

Source: https://trackplot.readthedocs.io/en/latest/command

Includes specific domain categories and types for annotation. Use to filter and display only relevant protein information.

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

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

### Run Trackplot for HiC Visualization

Source: https://trackplot.readthedocs.io/en/latest/command

Execute the trackplot command to generate a HiC visualization. Specify the region, GTF file, HiC data, output file, and other parameters like DPI, width, and height.

```bash
trackplot \
    -e chr19:35600000-35800000:+\
    -r example/example.sorted.2.gtf.gz \
    --hic example/hic.2.tsv \
    -o hic.2.png \
    --dpi 300 \
    --width 10 \
    --height 1 
```

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

### Add Highlight Background (Focus Region)

Source: https://trackplot.readthedocs.io/en/latest/interactive

Adds a highlight background to the track, defining a focus region. Supports string ranges or start/end integers.

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


```

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

### Generate Sashimi Plot with Focus Exon

Source: https://trackplot.readthedocs.io/en/latest/command

Generates a Sashimi plot, focusing on specific alternative exons. The --focus flag takes a comma-separated list of exon coordinates.

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

trackplot \
  -r example/Homo_sapiens.GRCh38.101.chr.gtf.gz \
  -e 21:43092956-43107570:+ \
  --igv example/igv.3.tsv \
  --focus 43100453-43100519:43101366-43101432 \
  -o test_igv_plot.3.pdf \
  --dpi 300 \
  --width 6 \
  --height 1

```

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

### add_manual

Source: https://trackplot.readthedocs.io/en/latest/interactive

Adds a line, density, or heatmap plot based on manually provided data. Allows customization of labels, colors, and themes.

```APIDOC
## add_manual

### Description
Adds a line, density, or heatmap plot based on manually provided data. Allows customization of labels, colors, and themes.

### Method Signature
```python
def add_manual(self, 
               data: np.array, 
               image_type: str = "line", 
               label: str = "",
               group: str = "",
               color: str = "blue", 
               font_size: int = 8, 
               n_y_ticks: int = 1, 
               show_y_label: bool = True, 
               theme: str = "ticks_blank",)
```

### Parameters
#### Arguments
- **data** (np.array) - Required - The manual data object, should be 1D np.array with same length of target region.
- **image_type** (str) - Optional - The plotting type, one of `line` [default], `density`, `heatmap`.
- **label** (str) - Optional - The label of given manual data.
- **group** (str) - Optional - The group of given data, used for `line` or `heatmap` plot.
- **color** (str) - Optional - The color of given data.
- **font_size** (int) - Optional - The font size of this plot.
- **n_y_ticks** (int) - Optional - The number of y ticks to show.
- **show_y_label** (bool) - Optional - Whether to show y label.
- **theme** (str) - Optional - The build-in theme, including `blank`, `ticks`, `ticks_blank`.

### Returns
`Plot`
```

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

### add_interval

Source: https://trackplot.readthedocs.io/en/latest/interactive

Adds a local interval file to the track with a specified label.

```APIDOC
## add_interval

### Description
Adds a local interval file to the track with a specified label.

### Method
```python
def add_interval(self, interval: str, interval_label: str)
```

### Parameters
#### Path Parameters
* **interval** (str) - Required - path to local interval file
* **interval_label** (str) - Required - the label of given interval
```

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

### Trackplot Visualize Coverage by Count

Source: https://trackplot.readthedocs.io/en/latest/command

Visualize genomic coverage using raw counts. This command is useful for initial data exploration without normalization.

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

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

### Convert HiC to Cool and H5 Formats

Source: https://trackplot.readthedocs.io/en/latest/command

Download a HiC file and convert it to cool and then to H5 format using hicConvertFormat. This is useful for preparing HiC data for analysis.

```bash
wget https://encode-public.s3.amazonaws.com/2016/12/01/a241cba5-df2e-45fb-9a8f-5af5587fb02a/ENCFF121YPY.hic
hicConvertFormat -m ENCFF121YPY.hic --inputFormat hic --outputFormat cool -o ENCFF121YPY.cool --resolutions 1000
hicConvertFormat -m ENCFF121YPY_1000.cool --inputFormat cool --outputFormat h5 -o ENCFF121YPY.h5
```

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

### Load Custom Interval Annotation

Source: https://trackplot.readthedocs.io/en/latest/command

Adds custom genomic features to the annotation track from a specified TSV file. Use for integrating external annotation data.

```bash
$ cat example/interval_list.tsv
#file_location  label_of_file
example/PolyASite.chr1.atlas.clusters.2.0.GRCh38.96.simple.bed.gz   polyAS 

```

```bash
trackplot --interval example/interval_list.tsv
```

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

### Trackplot with Additional Annotations

Source: https://trackplot.readthedocs.io/en/latest/command

Generate a plot with additional annotations including focus regions, stroke lines, and sites. This command also utilizes a raster output and a GTF file.

```bash
trackplot \
  -e chr1:1270656-1284730:+\
  --focus 1272656-1272656:1275656-1277656 \
  --stroke 1275656-1277656:1277856-1278656@blue \
  --sites 1271656,1271656,1272656 \
  -o additional.pdf \
  --dpi 300 \
  --width 10 \
  --height 1 \
  --raster \
  -r example/example.sorted.gtf.gz \
  --line example/line_list.tsv
```

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

### Add Interval

Source: https://trackplot.readthedocs.io/en/latest/interactive

Adds an interval to the track from a local interval file, with a specified label.

```python
def add_interval(self, interval: str, interval_label: str)


```

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

### set_sequence

Source: https://trackplot.readthedocs.io/en/latest/interactive

Displays the corresponding DNA sequence under the x-axis. Requires a path to an indexed FASTA file.

```APIDOC
## set_sequence

### Description
Displays the corresponding DNA sequence under the x-axis. Requires a path to an indexed FASTA file.

### Method
```python
def set_sequence(self, fasta: str)
```

### Parameters
#### Path Parameters
* **fasta** (str) - Required - path to indexed fasta file
```

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

### add_focus

Source: https://trackplot.readthedocs.io/en/latest/interactive

Adds a focus region to the track, highlighting a specific background area. The focus can be defined by a string range or start/end integers.

```APIDOC
## add_focus

### Description
Adds a focus region to the track, highlighting a specific background area. The focus can be defined by a string range or start/end integers.

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

### Parameters
#### Path Parameters
* **focus** (Optional[str]) - Optional - string in 100-200:300-400 format
* **start** (int) - Optional - start site
* **end** (int) - Optional - end site
```

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

### Control intron shrinkage in visualization

Source: https://trackplot.readthedocs.io/en/latest/command

Adjust the intron shrinkage scale using the `--intron-scale` parameter. A scale of 1 shows no shrinkage, while smaller values reduce intron size in the plot.

```bash
# Without shrinkage of the intron (shrinkage_scale: 1)
trackplot \
  -e chr9:112296343-112335026 \
  -r Homo_sapiens.GRCh38.101.chr.gtf.gz \
  --density bam.tsv \
  -o PTBP3.1.pdf \
  --dpi 300 \
  --width 6 \
  --height 1 --show-junction-num \
  --included-junctions chr9:112297917-112330441:-,chr9:112297917-112333470:-,chr9:112330475-112333470:- \
  --intron-scale 1

# with shrinkage of the intron (shrinkage_scale: 0.001)
trackplot \
  -e chr9:112296343-112335026 \
  -r Homo_sapiens.GRCh38.101.chr.gtf.gz \
  --density bam.tsv \
  -o PTBP3.001.pdf \
  --dpi 300 \
  --width 6 \
  --height 1 --show-junction-num \
  --included-junctions chr9:112297917-112330441:-,chr9:112297917-112333470:-,chr9:112330475-112333470:- \
  --intron-scale .01
```

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

### Trackplot Single Cell Analysis with Barcodes and Grouping

Source: https://trackplot.readthedocs.io/en/latest/command

This command enables single-cell analysis by specifying a barcode list to separate BAM files and grouping the results by cell type.

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

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

### Initialize Trackplot Plot

Source: https://trackplot.readthedocs.io/en/latest/interactive

Initializes the Plot object for Trackplot. Allows configuration of logging, matplotlib backend, and font family.

```python
from trackplot.plot import Plot

# logfile: save progress logs to file, default: None [stdout]
# backend: switch the matplotlib backend, default: agg
# font_family: change the font family in trackplot, default: None [system default font family]
plot = Plot(logfile=None, backend="agg", font_family=None)
```

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

### Basic Domain Annotation Plot

Source: https://trackplot.readthedocs.io/en/latest/command

Generates a plot with domain information fetched from Uniprot/Ensemble, mapping amino acid to genomic coordinates. This is the default behavior when --domain is used.

```bash
trackplot \
  -e 7:107830089-107832297 \
  -r example/Article_figures/FigS1/A/Homo_sapiens.GRCh37.87.gtf.sorted.gz \
  -o domain.raw.pdf \
  --dpi 300 \
  --width 6 \
  --height 1 --show-junction-num -t 10 --domain
```

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

### Trackplot with Fixed Intron Size

Source: https://trackplot.readthedocs.io/en/latest/command

Use this command to visualize genomic data with introns fixed at a specific length. It includes options for showing junction numbers and density plots from BAM files.

```bash
trackplot \
  --intron-scale 250  \
  -e 9:112225716-112333664 \
  -r ptbp3_ext.gtf.gz \
  --show-junction-num \
  --density bam_files.tsv \
  --raster \
  --height 2 \
  --width 20 \
  --font-size 14 \
  --transcripts-to-show PTBP3-201,PTBP3-202,PTBP3-203,PTBP3-204,PTBP3-205,PTBP3-206,PTBP3-207,PTBP3-208 \
  -o PTBP3_mod_specific_transcipts.log10.png
```

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

### Filter junction counts and show specific junctions

Source: https://trackplot.readthedocs.io/en/latest/command

Filter junctions based on minimum read counts using the `-t` flag and display specific junctions with the `--included-junctions` option.

```bash
# panel A, show all junctions

trackplot \
  -e chr9:112296343-112335026 \
  -r Homo_sapiens.GRCh38.101.chr.gtf.gz \
  --density bam.tsv \
  -o PTBP3.raw.pdf \
  --dpi 300 \
  --width 6 \
  --height 1 --show-junction-num

# panel B, show the junctions with more 10 counts.

trackplot \
  -e chr9:112296343-112335026 \
  -r Homo_sapiens.GRCh38.101.chr.gtf.gz \
  --density bam.tsv \
  -o PTBP3.filter.pdf \
  --dpi 300 \
  --width 6 \
  --height 1 --show-junction-num -t 10

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

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

### Domain Annotation Plot with Included Categories

Source: https://trackplot.readthedocs.io/en/latest/command

Generates a plot with domain information, including only specified categories like MOLECULE_PROCESSING and PTM. Use to focus on specific types of protein features.

```bash
trackplot \
  -e 7:107830089-107832297 \
  -r example/Article_figures/FigS1/A/Homo_sapiens.GRCh37.87.gtf.sorted.gz \
  -o domain.include.pdf \
  --dpi 300 \
  --width 6 \
  --height 1 --show-junction-num -t 10 --domain --domain-include MOLECULE_PROCESSING:PTM,CARBOHYD
```

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

### Generate plot with customized junctions

Source: https://trackplot.readthedocs.io/en/latest/command

Use the `--customized-junction` flag to specify a file containing custom junction data for plotting.

```bash
trackplot \
  -e chr1:1270656-1284730:+ \
  -r example/example.sorted.gtf.gz \
  --density example/density_list.tsv \
  --customized-junction example/custome_junction.tsv \
  --output example.pdf
```

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

### add_density Method Signature

Source: https://trackplot.readthedocs.io/en/latest/interactive

This is the signature for the add_density method, outlining all available parameters for customizing density plots. Use this to understand the various options for input files, density calculation, and plot appearance.

```python
def add_density(self,
                path: str,
                category: str = "bam",
                size_factor=None,

                # file loading parameters
                label: Union[str, List[str]] = "",
                title: str = "",
                barcode: str = "",
                barcode_groups: Dict[str, Set[str]] = None,
                barcode_tag: str = "BC",
                umi_tag: str = "UB",
                library: str = "fru",
                density_by_strand: bool = False,

                # plotting parameters
                color="blue",
                font_size: int = 8,
                show_junction_number: bool = True,
                junction_number_font_size: int = 5,
                n_y_ticks: int = 4,
                show_y_label: bool = True,
                y_label: str = "",
                theme: str = "ticks_blank",
                log_trans: Optional[str] = None,

                # site plot parameters
                show_site_plot: bool = False,
                strand_choice: Optional[str] = None,

                only_customized_junction: bool = False
                )

```

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

### set_annotation

Source: https://trackplot.readthedocs.io/en/latest/interactive

Adds transcripts to the track with various customization options for domains, intervals, and display.

```APIDOC
## set_annotation

### Description
Adds transcripts to the track with various customization options for domains, intervals, and display.

### Method
```python
def set_annotation(self, gtf: str, add_domain: bool = False, local_domain: Optional[str] = False, domain_include: Optional[str] = False, domain_exclude: Optional[str] = False, interval: Optional[str] = None, interval_label: Optional[str] = None, transcripts: Optional[List[str]] = None, remove_empty_transcripts: bool = False, choose_primary: bool = False, color: Optional[str] = "black", font_size: int = 5, show_gene: bool = False, show_id: bool = False, exon_width: float = .3, show_exon_id: bool = False, theme: str = "blank")
```

### Parameters
#### Path Parameters
- **gtf** (str) - Required - Path to gtf file.
- **add_domain** (bool) - Optional - Whether to add domain. Defaults to False.
- **local_domain** (Optional[str]) - Optional - Whether to add domain information into annotation track. Defaults to False.
- **domain_include** (Optional[str]) - Optional - Which domain will be included in annotation plot.
- **domain_exclude** (Optional[str]) - Optional - Which domain will be excluded in annotation plot.
- **interval** (Optional[str]) - Optional - Path to list of interval files in bed format, 1st column is path to file, 2nd column is the label. Defaults to None.
- **interval_label** (Optional[str]) - Optional - The label of added interval.
- **transcripts** (Optional[List[str]]) - Optional - The list of name or ids of transcripts to draw. Defaults to None.
- **remove_empty_transcripts** (bool) - Optional - Whether to remove transcripts without any exons. Defaults to False.
- **choose_primary** (bool) - Optional - Whether to choose primary transcript to plot. Defaults to False.
- **color** (Optional[str]) - Optional - The color of exons. Defaults to "black".
- **font_size** (int) - Optional - The size of transcript id, name. Defaults to 5.
- **show_gene** (bool) - Optional - Whether to show gene name/id. Defaults to False.
- **show_id** (bool) - Optional - Show gene id or gene name. Defaults to False.
- **exon_width** (float) - Optional - The height of exons. Defaults to 0.3.
- **show_exon_id** (bool) - Optional - Whether to show exon id. Defaults to False.
- **theme** (str) - Optional - The build-in theme, including `blank`, `ticks`, `ticks_blank`. Defaults to "blank".
```

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

### Trackplot Scaling Features

Source: https://trackplot.readthedocs.io/en/latest/command

This snippet demonstrates how to use Trackplot's scaling features for exons and introns to adjust visualization. Intron scale values less than 1 are relative.

```bash
--exon-scale 20 \
  --intron-scale 0.10  \
```
Tokens:
Raw