Welcome to pyGenomeTracks’s documentation!¶

Standalone program and library to plot beautiful genome browser tracks¶

pyGenomeTracks aims to produce high-quality genome browser tracks that are highly customizable. Currently, it is possible to plot:

bigwig

bed/gtf (many options)

bedgraph

bedgraph matrices (like TAD-separation scores)

epilogos

narrow peaks

links (represented as arcs, triangles or squares)

Hi-C matrices (as triangle or squares)

fasta

maf (multiple alignment format)

Here is a scheme which describe how pyGenomeTracks is working (graphical abstract of Lopez-Delisle et al. 2020):

pyGenomeTracks can make plots with or without Hi-C data. The following is an example output of pyGenomeTracks from Ramírez et al. 2017.

There are 3 ways for using pyGenomeTracks:

Galaxy usage – the public European Galaxy server let’s you use pyGenomeTracks within the familiar Galaxy framework without the need to master the command line
command line usage – simply download and install the tool (see Installation and Usage)

Table of content¶

Installation¶

Remember – pyGenomeTracks is available for command line usage as well as for integration into Galaxy servers!

Requirements
Command line installation using conda
Command line installation using conda and mamba
Command line installation using pip
Command line installation without pip
Galaxy installation
- Installation via Galaxy API (recommended)
- Installation via web browser

Requirements ¶

Python dependencies:

Python >= 3.7
numpy >= 1.20
intervaltree >= 2.1.0
pyBigWig >= 0.3.16
hicmatrix >= 15
pysam >= 0.14
matplotlib >= 3.1.1,<= 3.6.2
gffutils >= 0.9
pybedtools >= 0.8.1
tqdm >= 4.20
bx-python >=0.8.13
pyfaidx >= 0.1.3

External dependencies:

BEDTools

Command line installation using `conda`¶

We encourage users to use conda installation to install pygenometracks. All of the requirements for pyGenomeTracks can be installed via Anaconda with:

$ conda create -n pygenometracks -c bioconda -c conda-forge pygenometracks python=3.7

To get a specific version, one can specify it. For example:

$ conda create -n pygenometracks -c bioconda -c conda-forge pygenometracks=3.5 python=3.7

Command line installation using `conda` and `mamba`¶

However, we noticed that conda installation can be quite slow so using mamba can help. You first need to create the environment and install mamba:

$ conda create -n pygenometracks -c bioconda -c conda-forge mamba python=3.7

Then activate the environment and install pygenometracks with mamba:

$ conda activate pygenometracks
$ mamba install -c conda-forge -c bioconda pygenometracks

or if you want a specific version:

$ conda create -n pygenometracks -c bioconda -c conda-forge mamba python=3.7
$ conda activate pygenometracks
$ mamba install -c conda-forge -c bioconda pygenometracks=3.5

Command line installation using `pip`¶

Install pyGenomeTracks using the following command:

$ pip install pyGenomeTracks

All python requirements should be automatically installed.

Since version 3.5, pyGenomeTracks require BEDTools, do not forget to install it or load it into your environment.

If you need to specify a specific path for the installation of the tools, make use of pip install’s numerous options:

$ pip install --install-option="--prefix=/MyPath/Tools/pyGenomeTracks" git+https://github.com/deeptools/pyGenomeTracks.git

Command line installation without `pip`¶

You are highly recommended to use conda install rather than the following complicated steps.

Install the requirements listed above in the “requirements” section. This is done automatically by pip (except BEDTools).

2. Download source code

$ git clone https://github.com/deeptools/pyGenomeTracks.git

or if you want a particular release, choose one from https://github.com/deeptools/pygenometracks/releases:

$ wget https://github.com/deeptools/pyGenomeTracks/archive/3.1.tar.gz
$ tar -xzvf

3. install the source code (if you don’t have root permission, you can set a specific folder using the --prefix option)

$ python setup.py install --prefix /User/Tools/pyGenomeTracks3.1

Galaxy installation ¶

pyGenomeTracks can be easily integrated into a local Galaxy. The wrapper and its dependencies are available in the Galaxy Tool Shed.

Installation via Galaxy API (recommended)¶

First generate an API Key for your admin user and run the the installation script:

$ python ./scripts/api/install_tool_shed_repositories.py \
        --api YOUR_API_KEY -l http://localhost/ \
        --url http://toolshed.g2.bx.psu.edu/ \
        -o iuc -r <revision> --name pygenometracks \
        --tool-deps --repository-deps --panel-section-name plots

The -r argument specifies the version of pygenometracks.

You can watch the installation status under: Top Panel –> Admin –> Manage installed tool shed repositories

Installation via web browser ¶

go to the admin page
select Search and browse tool sheds
Galaxy tool shed –> Visualization –> pygenometracks
install pygenometracks

Starting usage ¶

To run pyGenomeTracks a configuration file describing the tracks is required.

In a configuration file, each track is defined as a block of parameters starting with its name [track name] and continues with the parameters for that track such as the file location, its title, height, color etc.

The tracks are then plotted in the order of the configuration file from top to bottom.

The easiest way to create this file is using the program make_tracks_file which creates a configuration file with defaults that can be easily changed. make_tracks_file uses the file ending to guess the file type. Then, a region can be plotted using pyGenomeTracks. Both programs are described below:

make_tracks_file ¶

Facilitates the creation of a configuration file for pyGenomeTracks. The program takes a list of files and does the boilerplate for the configuration file.

usage: make_tracks_file --trackFiles <bigwig file> <bed file> etc. -o tracks.ini

Named Arguments ¶

--trackFiles, -f: Files to use in for the tracks. The ending of the file is used to define the type of track. E.g. .bw for bigwig, .bed for bed etc. For a arcs or links file, the file ending recognized is .arcs or .links
--out, -o: File to save the tracks
--version: show program’s version number and exit

pyGenomeTracks ¶

Plots genomic tracks on specified region(s). Citations : Ramirez et al. High-resolution TADs reveal DNA sequences underlying genome organization in flies. Nature Communications (2018) doi:10.1038/s41467-017-02525-w Lopez-Delisle et al. pyGenomeTracks: reproducible plots for multivariate genomic datasets. Bioinformatics (2020) doi:10.1093/bioinformatics/btaa692

usage: pyGenomeTracks --tracks tracks.ini --region chr1:1000000-4000000 -o image.png

Named Arguments ¶

--tracks

File containing the instructions to plot the tracks. The tracks.ini file can be genarated using the make_tracks_file program.

--region

Region to plot, the format is chr:start-end

--BED

Instead of a region, a file containing the regions to plot, in BED format, can be given. If this is the case, multiple files will be created. It will use the value of –outFileName as a template and put the coordinates between the file name and the extension.

--width

figure width in centimeters (default is 40)

--plotWidth

width in centimeters of the plotting (central) part

--height

Figure height in centimeters. If not given, the figure height is computed based on the heights of the tracks. If given, the track height are proportionally scaled to match the desired figure height.

--title, -t

Plot title

--outFileName, -out

File name to save the image, file prefix in case multiple images are stored

--fontSize

Font size for the labels of the plot (default is 0.3 * figure width)

--dpi

Resolution for the image in case the ouput is a raster graphics image (e.g png, jpg) (default is 72)

--trackLabelFraction

By default the space dedicated to the track labels is 0.05 of the plot width. This fraction can be changed with this parameter if needed.

--trackLabelHAlign

Possible choices: left, right, center

By default, the horizontal alignment of the track labels is left. This alignemnt can be changed to right or center.

--decreasingXAxis

By default, the x-axis is increasing. Use this option if you want to see all tracks with a decreasing x-axis.

--version

show program’s version number and exit

Citation¶

If you use pyGenomeTracks in your analysis, you can cite the following papers:

Fidel Ramírez, Vivek Bhardwaj, Laura Arrigoni, Kin Chung Lam, Björn A. Grüning, José Villaveces, Bianca Habermann, Asifa Akhtar & Thomas Manke. High-resolution TADs reveal DNA sequences underlying genome organization in flies. Nature Communications (2018) doi:10.1038/s41467-017-02525-w.

Lopez-Delisle L, Rabbani L, Wolff J, Bhardwaj V, Backofen R, Grüning B, Ramírez F, Manke T. pyGenomeTracks: reproducible plots for multivariate genomic data sets. Bioinformatics. 2020 Aug 3:btaa692. doi: 10.1093/bioinformatics/btaa692. Epub ahead of print. PMID: 32745185.

All available tracks and types¶

bed¶

Description¶

A track for all bed-like files (with first column chromosome, second start and third end). If the other columns fit the requirement as defined in UCSC additional fields can be used. For example, the 5th and 9th column can be used to change the color of intervals, the 6th column indicate the strand… By default, intervals without strand are displayed as rectangle and for intervals with strand an arrow is added at the extremity (not included in the interval). In case of BED12 format, the introns are displayed into another color. But other styles are available.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
fontsize: 12 (default) or any float above 0
orientation: by default this option is not set but you can also put: inverted.
line_width: 0.5 (default) or any float above 0
color: #1f78b4 (default)
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
border_color: black (default)
prefered_name: transcript_name (default)
merge_transcripts: false (default) or true.
labels: true (default) or false.
style: flybase (default) or UCSC or tssarrow.
display: stacked (default) or collapsed, triangles, interleaved or squares.
max_labels: 60 (default) or any integer above 0
merge_overlapping_exons: false (default) or true.
global_max_row: false (default) or true.
gene_rows: by default this option is not set but you can also put: any integer above 0
arrow_interval: 2 (default) or any integer above 1
arrowhead_included: false (default) or true.
arrowhead_fraction: 0.004 (default) or any float above 0
color_utr: grey (default)
color_backbone: black (default)
height_utr: 1 (default) or any float above 0 below 1
arrow_length: by default this option is not set but you can also put: any integer above 0
all_labels_inside: false (default) or true.
labels_in_margin: false (default) or true.
fontstyle: normal (default) or italic or oblique.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# If the bed file contains a column for color (column 9), then this color can be used by
# setting:
#color = bed_rgb
# if color is a valid colormap name (like RbBlGn), then the score (column 5) is mapped
# to the colormap.
# In this case, the the min_value and max_value for the score can be provided, otherwise
# the maximum score and minimum score found are used.
#color = RdYlBu
#min_value=0
#max_value=100
# If the color is simply a color name, then this color is used and the score is not considered.
color = darkblue
# optional: line_width
#line_width = 0.5
# optional: border_color
# default is black.
# To remove the border, simply set 'border_color' to none
# Not used in tssarrow style
#border_color = black
# the display parameter defines how the bed file is plotted.
# Default is 'stacked' where regions are plotted on different lines so
# we can see all regions and all labels.
# The other options are ['collapsed', 'interleaved', 'triangles', 'squares']
# These 2 options assume that the regions do not overlap.
# `collapsed`: The bed regions are plotted one after the other in one line.
# `interleaved`: The bed regions are plotted in two lines, first up, then down, then up etc.
# If the bed file contains the exon
# structure (bed 12) then this is plotted. Otherwise
# a region **with direction** is plotted.
# style to plot the genes when the display is 'stacked', 'collapsed' or 'interleaved'
#style = UCSC
#style = flybase
#style = tssarrow
# maximum number of gene rows to be plotted. This
# field is useful to limit large number of close genes
# to be printed over many rows. When several images want
# to be combined this must be set to get equal size
# otherwise, on each image the height of each gene changes
#gene_rows = 10
# by default the ymax is the number of
# rows occupied by the genes in the region plotted. However,
# by setting this option, the global maximum is used instead.
# This is useful to combine images that are all consistent and
# have the same number of rows.
#global_max_row = true
# whether printing the labels
labels = false
# optional:
# by default the labels are not printed if you have more than 60 features.
# to change it, just increase the value:
#max_labels = 60
# optional: font size can be given to override the default size
fontsize = 10
# If you want to plot all labels inside the plotting region:
#all_labels_inside = true
# If you want to display the name of the gene which goes over the plotted
# region in the right margin put:
#labels_in_margin = true
# If you want to use italic for your labels:
#fontstyle = italic
# if you use UCSC style, you can set the relative distance between 2 arrows on introns
# default is 2
#arrow_interval = 2
# if you use tssarrow style, you can choose the length of the arrow in bp
# (default is 4% of the plotted region)
#arrow_length = 5000
# if you use flybase or tssarrow style, you can choose the color of non-coding intervals:
#color_utr = grey
# as well as the proportion between their height and the one of coding
# (by default they are the same height):
#height_utr = 1
# if you use flybase or UCSC style, you can choose the color of the backbone
#color_backbone = red
# By default, for oriented intervals in flybase style,
# or bed files with less than 12 columns, the arrowhead is added
# outside of the interval.
# If you want that the tip of the arrow correspond to
# the extremity of the interval use:
#arrowhead_included = true
# By default the size of this arrow is 0.4% of the plotted region.
# This size is also used to put space between the bed regions and
# their labels.
# To increase it:
#arrowhead_fraction = 0.01
# The two other display options are really different and no label can be display:
# `triangles` display each region as a triangle, can be useful to overlay with a hic_matrix
# `squares` display each region as a square along the diagonal, can be useful to overlay with a hic_matrix_square
# optional. If not given is guessed from the file ending.
file_type = bed
    

bedgraph¶

Description¶

A track for bedgraph files.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
color: #a6cee3 (default)
alpha: 1 (default) or any float above 0 below 1
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
use_middle: false (default) or true.
show_data_range: true (default) or false.
type: fill (default)
negative_color: by default this option is not set
nans_to_zeros: false (default) or true.
summary_method: by default this option is not set but you can also put: mean, average, max, min, stdev, dev, coverage, cov or sum.
number_of_bins: 700 (default) or any integer above 1
transform: no (default) or log, log1p, -log, log2 or log10.
log_pseudocount: 0 (default) or any float
y_axis_values: transformed (default) or original.
second_file*: by default this option is not set
operation*: file (default)
grid: false (default) or true.
rasterize: false (default) or true.

* While pyGenomeTracks can convert coverage tracks on the fly, this might be a time-consuming step, especially on large files and if you want to replot many times. In this situation, we recommend using the deepTools suite to convert your files in advance. For example bamCoverage or bamCompare

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

color = green
# To use a different color for negative values
#negative_color = red
# To use transparency, you can use alpha
# default is 1
# alpha = 0.5
# the default for min_value and max_value is 'auto' which means that the scale will go
# roughly from the minimum value found in the region plotted to the maximum value found.
min_value = 0
#max_value = auto
# to convert missing data (NaNs) into zeros. Otherwise, missing data is not plotted.
nans_to_zeros = true
# for type, the options are: line, points, fill. Default is fill
# to add the preferred line width or point size use:
# type = line:lw where lw (linewidth) is float
# similarly points:ms sets the point size (markersize (ms) to the given float
# type = line:0.5
# type = points:0.5
# If you want to plot a 4C track where you want to link
# the non-missing data (NaNs) together and only use the
# middle of the region instead of the region itself:
# Default is false.
# use_middle = true
# By default the bedgraph is plotted at the base pair
# resolution. This can lead to very large pdf/svg files
# If plotting large regions.
# If you want to decrase the size of your file.
# You can either rasterize the bedgraph profile by using:
# rasterize = true
# Or use a summary method on a given number of bin:
# The possible summary methods are given by pyBigWig:
# mean/average/stdev/dev/max/min/cov/coverage/sum
# summary_method = mean
# number_of_bins = 700
# set show_data_range to false to hide the text on the left showing the data range
show_data_range = true
# to compute operations on the fly on the file
# or between 2 bedgraph files
# operation will be evaluated, it should contains file or
# file and second_file,
# we advice to use nans_to_zeros = true to avoid unexpected nan values
#operation = 0.89 * file
#operation = - file
#operation = file - second_file
#operation = log2((1 + file) / (1 + second_file))
#operation = max(file, second_file)
#second_file = path for the second file
# To log transform your data you can also use transform and log_pseudocount:
# For the transform values:
# 'log1p': transformed_values = log(1 + initial_values)
# 'log': transformed_values = log(log_pseudocount + initial_values)
# 'log2': transformed_values = log2(log_pseudocount + initial_values)
# 'log10': transformed_values = log10(log_pseudocount + initial_values)
# '-log': transformed_values = log(log_pseudocount + initial_values)
# For example:
#tranform = log
#log_pseudocount = 2
# When a transformation is applied, by default the y axis
# gives the transformed values, if you prefer to see
# the original values:
#y_axis_values = original
# If you want to have a grid on the y-axis
#grid = true
file_type = bedgraph
    

bedgraph_matrix¶

Description¶

A track for file like bedgraph but with more than 4 columns, like the insulation score from hicPlotTADs

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
show_data_range: true (default) or false.
type: matrix (default) or lines.
rasterize: true (default) or false.
pos_score_in_bin: center (default) or block.
plot_horizontal_lines: false (default) or true.
colormap: viridis (default)
individual_color: grey (default)
summary_color: #1f77b4 (default)

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# a bedgraph matrix file is like a bedgraph, except that per bin there
# are more than one value separated by tab: E.g.
# This file type is produced by HiCExplorer tool hicFindTads and contains
# the TAD-separation score at different window sizes
# chrX	18279	40131	0.399113	0.364118	0.320857	0.274307
# chrX	40132	54262	0.479340	0.425471	0.366541	0.324736
#min_value = 0.10
#max_value = 0.70
# if type is set as lines, then the TAD score lines are drawn instead
# of the matrix otherwise a heatmap is plotted
type = lines
# by default individual lines are colored in grey:
individual_color = grey
# by default the summary line is colored in blue:
summary_color = #1f77b4
# If the type is not lines, you can choose to keep the matrix as not rasterized
# (only used if you use pdf or svg output format) by using:
# rasterize = false
# The different options for color maps can be found here:
# https://matplotlib.org/users/colormaps.html
# the default color map is viridis
# If you want your own colormap you can put the values of the color you want
# For example, colormap = ['blue', 'yellow', 'red']
# or colormap = ['white', (1, 0.88, .66), (1, 0.74, 0.25), (1, 0.5, 0), (1, 0.19, 0), (0.74, 0, 0), (0.35, 0, 0)]
#colormap = Reds
# pos_score_in_bin means 'position of score with respect to bin start and end'
# if the lines option is used, the y values can be put at the
# center of the bin (default) or they can be plot as 'block',
# which mean to plot the values as a line between the start and end of bin
pos_score_in_bin = center
show_data_range = true

# only when type lines is used. Adds horizontal lines
plot_horizontal_lines = false
file_type = bedgraph_matrix
    

bigwig¶

Description¶

A track for bigwig files.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
color: #33a02c (default)
alpha: 1 (default) or any float above 0 below 1
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
show_data_range: true (default) or false.
type: fill (default)
negative_color: by default this option is not set
nans_to_zeros: false (default) or true.
summary_method: mean (default) or average, max, min, stdev, dev, coverage, cov or sum.
number_of_bins: 700 (default) or any integer above 1
transform: no (default) or log, log1p, -log, log2 or log10.
log_pseudocount: 0 (default) or any float
y_axis_values: transformed (default) or original.
second_file*: by default this option is not set
operation*: file (default)
grid: false (default) or true.

* While pyGenomeTracks can convert coverage tracks on the fly, this might be a time-consuming step, especially on large files and if you want to replot many times. In this situation, we recommend using the deepTools suite to convert your files in advance. For example bamCoverage or bamCompare

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

color = #666666
# To use a different color for negative values
#negative_color = red
# To use transparency, you can use alpha
# default is 1
# alpha = 0.5
# the default for min_value and max_value is 'auto' which means that the scale will go
# roughly from the minimum value found in the region plotted to the maximum value found.
min_value = 0
#max_value = auto
# The number of bins takes the region to be plotted and divides it
# into the number of bins specified
# Then, at each bin the bigwig mean value is computed and plotted.
# A lower number of bins produces a coarser tracks
number_of_bins = 700
# to convert missing data (NaNs) into zeros. Otherwise, missing data is not plotted.
nans_to_zeros = true
# The possible summary methods are given by pyBigWig:
# mean/average/stdev/dev/max/min/cov/coverage/sum
# default is mean
summary_method = mean
# for type, the options are: line, points, fill. Default is fill
# to add the preferred line width or point size use:
# type = line:lw where lw (linewidth) is float
# similarly points:ms sets the point size (markersize (ms) to the given float
# type = line:0.5
# type = points:0.5
# set show_data_range to false to hide the text on the left showing the data range
show_data_range = true
# to compute operations on the fly on the file
# or between 2 bigwig files
# operation will be evaluated, it should contains file or
# file and second_file,
# we advice to use nans_to_zeros = true to avoid unexpected nan values
#operation = 0.89 * file
#operation = - file
#operation = file - second_file
#operation = log2((1 + file) / (1 + second_file))
#operation = max(file, second_file)
#second_file = path for the second file
# To log transform your data you can also use transform and log_pseudocount:
# For the transform values:
# 'log1p': transformed_values = log(1 + initial_values)
# 'log': transformed_values = log(log_pseudocount + initial_values)
# 'log2': transformed_values = log2(log_pseudocount + initial_values)
# 'log10': transformed_values = log10(log_pseudocount + initial_values)
# '-log': transformed_values = - log(log_pseudocount + initial_values)
# For example:
#tranform = log
#log_pseudocount = 2
# When a transformation is applied, by default the y axis
# gives the transformed values, if you prefer to see
# the original values:
#y_axis_values = original
# If you want to have a grid on the y-axis
#grid = true
file_type = bigwig
    

domains¶

Description¶

A track for bed files that you want to see as triangles.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
line_width: 0.5 (default) or any float above 0
color: #1f78b4 (default)
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
border_color: black (default)
prefered_name: transcript_name (default)
merge_transcripts: false (default) or true.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# If the bed file contains a column for color (column 9), then this color can be used by
# setting:
#color = bed_rgb
# if color is a valid colormap name (like RbBlGn), then the score (column 5) is mapped
# to the colormap.
# In this case, the the min_value and max_value for the score can be provided, otherwise
# the maximum score and minimum score found are used.
#color = RdYlBu
#min_value=0
#max_value=100
# If the color is simply a color name, then this color is used and the score is not considered.
color = darkblue
# optional: line_width
#line_width = 0.5
# optional, default is black. To remove the border, simply set 'border_color' to none
#border_color = black
# optional. If not given it is guessed from the file ending.
file_type = domains
    

epilogos¶

Description¶

A track for epilogos files.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
categories_file: by default this option is not set
orientation: by default this option is not set but you can also put: inverted.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# The categories file should contain the color information for each category id
# A categories file should look like:
# {
# "categories":{
#           "1":["Active TSS","#ff0000"],
#           "2":["Flanking Active TSS","#ff4500"],
#           "3":["Transcr at gene 5" and 3"","#32cd32"],
#           "4":["Strong transcription","#008000"],
#           "5":["Weak transcription","#006400"]
# 	}
#}
categories_file = <path to json categories file>
# optional. If not given, it is guessed from the file ending.
file_type = epilogos
    

fasta¶

Description¶

A track to display sequences from fasta files.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

gtf¶

Description¶

A track for gtf files.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
fontsize: 12 (default) or any float above 0
orientation: by default this option is not set but you can also put: inverted.
line_width: 0.5 (default) or any float above 0
color: #1f78b4 (default)
border_color: black (default)
prefered_name: transcript_name (default)
merge_transcripts: false (default) or true.
labels: true (default) or false.
style: flybase (default) or UCSC or tssarrow.
display: stacked (default) or collapsed, triangles or interleaved.
max_labels: 60 (default) or any integer above 0
merge_overlapping_exons: false (default) or true.
global_max_row: false (default) or true.
gene_rows: by default this option is not set but you can also put: any integer above 0
arrow_interval: 2 (default) or any integer above 1
arrowhead_included: false (default) or true.
arrowhead_fraction: 0.004 (default) or any float above 0
color_utr: grey (default)
color_backbone: black (default)
height_utr: 1 (default) or any float above 0 below 1
arrow_length: by default this option is not set but you can also put: any integer above 0
all_labels_inside: false (default) or true.
labels_in_margin: false (default) or true.
fontstyle: normal (default) or italic or oblique.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# By default the transcript_name is used.
# If you want to use the gene_name:
prefered_name = gene_name
# By default, the gtf is transformed to transcripts
# If you want to use see only one structure per gene
# merge_transcripts = true
# Sometimes merging transcripts without merging overlapping
# exons may give unexpected output especially when
# multiple 3' exons overlap. We recommand to use:
# merge_overlapping_exons = true
# You can change the color of coding sequences by:
color = darkblue
# height of track in cm
height = 5
# whether printing the labels
labels = false
# optional:
# by default the labels are not printed if you have more than 60 features.
# to change it, just increase the value:
#max_labels = 60
# optional: font size can be given to override the default size
fontsize = 10
# optional: line_width
#line_width = 0.5
# the display parameter defines how the gtf file is plotted.
# Default is 'stacked' where regions are plotted on different lines so
# we can see all regions and all labels.
# The other options are ['collapsed', 'interleaved', 'triangles']
# These options assume that the regions do not overlap.
# `collapsed`: The gtf regions are plotted one after the other in one line.
# `interleaved`: The gtf regions are plotted in two lines, first up, then down, then up etc.
# optional, default is black. To remove the border, simply set 'border_color' to none
# Not used in tssarrow style
#border_color = black
# style to plot the genes when the display is not triangles
#style = UCSC
#style = flybase
#style = tssarrow
# maximum number of gene rows to be plotted. This
# field is useful to limit large number of close genes
# to be printed over many rows. When several images want
# to be combined this must be set to get equal size
# otherwise, on each image the height of each gene changes
#gene_rows = 10
# by default the ymax is the number of
# rows occupied by the genes in the region plotted. However,
# by setting this option, the global maximum is used instead.
# This is useful to combine images that are all consistent and
# have the same number of rows.
#global_max_row = true
# If you want to plot all labels inside the plotting region:
#all_labels_inside = true
# If you want to display the name of the gene which goes over the plotted
# region in the right margin put:
#labels_in_margin = true
# If you want to use italic for your labels:
#fontstyle = italic
# if you use UCSC style, you can set the relative distance between 2 arrows on introns
# default is 2
#arrow_interval = 2
# if you use tssarrow style, you can choose the length of the arrow in bp
# (default is 4% of the plotted region)
#arrow_length = 5000
# if you use flybase or tssarrow style, you can choose the color of non-coding intervals:
#color_utr = grey
# as well as the proportion between their height and the one of coding
# (by default they are the same height):
#height_utr = 1
# if you use flybase or UCSC style, you can choose the color of the backbone
#color_backbone = red
# By default, for oriented intervals in flybase style,
# or bed files with less than 12 columns, the arrowhead is added
# outside of the interval.
# If you want that the tip of the arrow correspond to
# the extremity of the interval use:
#arrowhead_included = true
# By default the size of this arrow is 0.4% of the plotted region.
# This size is also used to put space between the bed regions and
# their labels.
# To increase it:
#arrowhead_fraction = 0.01
# optional. If not given is guessed from the file ending.
file_type = gtf
    

hic_matrix¶

Description¶

A track for matrix files. Only cool format and h5 format from HiCExplorer are supported. For other format, please first convert to a supported format, for example with hicConvertFormat <https://hicexplorer.readthedocs.io/en/latest/content/tools/hicConvertFormat.html#hicconvertformat>.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: If you do not set it, the height will be adjusted so that each bin is a square, else you can choose any float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
transform: no (default) or log, log1p or -log.
rasterize: true (default) or false.
colormap: RdYlBu_r (default)
depth: 100000 (default) or any integer above 1
show_masked_bins: false (default) or true.
scale_factor: 1 (default) or any float

Output of `make_tracks_file`:¶

# The different options for color maps can be found here:
# https://matplotlib.org/users/colormaps.html
# the default color map is RdYlBu_r (_r) stands for reverse
# If you want your own colormap you can put the values of the color you want
# For example, colormap = ['blue', 'yellow', 'red']
# or colormap = ['white', (1, 0.88, .66), (1, 0.74, 0.25), (1, 0.5, 0), (1, 0.19, 0), (0.74, 0, 0), (0.35, 0, 0)]
#colormap = RdYlBu_r
# height of track (in cm) can be given.
# Otherwise, the height is computed such that the proportions of the
# hic matrix are kept (e.g. the image does not appear shrink or extended)
# height = 10
# min_value and max_value refer to the contacts in the matrix.
#min_value =2.8
#max_value = 3.0
# the matrix can be transformed using the log1p (or log or -log, but zeros could be problematic)
transform = log1p
# show masked bins plots as white lines
# those bins that were not used during the correction
# the default is to extend neighboring bins to
# obtain an aesthetically pleasant output
show_masked_bins = false
# optional if the values in the matrix need to be scaled the
# following parameter can be used. This is useful to plot multiple hic-matrices on the same scale
# scale_factor = 1
# You can choose to keep the matrix as not rasterized
# (only used if you use pdf or svg output format) by using:
# rasterize = false
    
# depth is the maximum distance that should be plotted.
# If it is more than 125% of the plotted region, it will
# be adjsted to this maximum value.
depth = 100000
file_type = hic_matrix
    

hic_matrix_square¶

Description¶

A track for matrix files in ‘square’ (not rotated 45°). Only cool format and h5 format from HiCExplorer are supported. For other format, please first convert to a supported format, for example with hicConvertFormat <https://hicexplorer.readthedocs.io/en/latest/content/tools/hicConvertFormat.html#hicconvertformat>.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
region2: by default this option is not set
transform: no (default) or log, log1p or -log.
rasterize: true (default) or false.
colormap: RdYlBu_r (default)
show_masked_bins: false (default) or true.
scale_factor: 1 (default) or any float

Output of `make_tracks_file`:¶

# The different options for color maps can be found here:
# https://matplotlib.org/users/colormaps.html
# the default color map is RdYlBu_r (_r) stands for reverse
# If you want your own colormap you can put the values of the color you want
# For example, colormap = ['blue', 'yellow', 'red']
# or colormap = ['white', (1, 0.88, .66), (1, 0.74, 0.25), (1, 0.5, 0), (1, 0.19, 0), (0.74, 0, 0), (0.35, 0, 0)]
#colormap = RdYlBu_r
# height of track (in cm) can be given.
# Otherwise, the height is computed such that the proportions of the
# hic matrix are kept (e.g. the image does not appear shrink or extended)
# height = 10
# min_value and max_value refer to the contacts in the matrix.
#min_value =2.8
#max_value = 3.0
# the matrix can be transformed using the log1p (or log or -log, but zeros could be problematic)
transform = log1p
# show masked bins plots as white lines
# those bins that were not used during the correction
# the default is to extend neighboring bins to
# obtain an aesthetically pleasant output
show_masked_bins = false
# optional if the values in the matrix need to be scaled the
# following parameter can be used. This is useful to plot multiple hic-matrices on the same scale
# scale_factor = 1
# You can choose to keep the matrix as not rasterized
# (only used if you use pdf or svg output format) by using:
# rasterize = false
    
# region2 is the region that should be plotted on the y axis.
# Default is the region on the x-axis
# By default the top is the start and the bottom is the end
# If orientation=inverted is used it is the contrary.
#region2 = X:3000000-3500000
file_type = hic_matrix_square
    

hlines¶

Description¶

A track to add horizontal lines to your tracks with overlay_previous = share-y or just to separate group of tracks.

Parameters¶

Necessary:¶

y_values

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
line_width: 0.5 (default) or any float above 0
line_style: solid (default) or dashed, dotted or dashdot.
color: black (default)
alpha: 1 (default) or any float above 0 below 1
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
show_data_range: true (default) or false.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# color of the lines
color = black
# To use transparency, you can use alpha
# default is 1
# alpha = 0.5
# the default for min_value and max_value is 'auto' which means that the scale will go
# roughly from the minimum value found in the region plotted to the maximum value found.
min_value = 0
#max_value = auto
# line width:
# line_width = 0.5
# options for line_style are 'solid', 'dashed', 'dotted', and 'dashdot'
#line_style = solid
# y values where horizontal lines should be plotted separated by comma:
y_values = 10, 200
# set show_data_range to false to hide the text on the upper-left showing the data range
show_data_range = true
file_type = hlines
    

links¶

Description¶

A track for pairs of intervalls, the supported format is (tab separated): chr1 start1 end1 chr2 start2 end2 (score …) The score field is optional and fields after the score are ignored.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
links_type: arcs (default) or triangles, loops or squares.
line_width: by default this option is not set but you can also put: any float above 0
line_style: solid (default) or dashed, dotted or dashdot.
color: blue (default)
alpha: 0.8 (default) or any float above 0 below 1
max_value: by default this option is not set but you can also put: any float
min_value: by default this option is not set but you can also put: any float
ylim: by default this option is not set but you can also put: any float above 0
compact_arcs_level: 0 (default) or 1 or 2.
use_middle: false (default) or true.
region2: by default this option is not set

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# the file format for links is (tab separated)
#   chr1 start1 end1 chr2 start2 end2 (score ...)
# The score field is optional
# The fields after the score field will be ignored
# for example:
#   chr1 100 200 chr1 250 300 0.5
# depending on the value of links_type either 'arcs' or 'triangles' or 'loops'
# or 'squares' can be plotted.
# If arcs, an arc will be drawn linking the beginning of the first region (chr1: 100),
# to the end of the other region (chr1: 300) except if use_middle is set to true.
# If triangles, the vertix of the triangle will be drawn at the center between the two points
# (also the extremity of each position is used)
# If loops, a diamond highlighting the intersection between the 2 regions will be shown
# the triangles, and loops options are convenient to overlay over a
# Hi-C matrix to highlight the matrix pixel of the highlighted link.
# If squares, a rectangle highlighting the intersection between the 2 regions will be shown
# In this case the y axis represent region2 which can be specified
# By default it is the same as the region of the x-axis
#region2 = X:3000000-3500000
# For these tracks do not hesitate to put large line_width like 5 or 10.
links_type = arcs
# For triangles and arcs, by default the extremities coordinates are used
# To use the middle of start1 and end1 and the middle of start2 and end2
#use_middle = true
# color of the lines
color = red
# if color is a valid colormap name (like RdYlGn),
# then the score is mapped to the colormap.
#color = RdYlGn
# To set the minimum and maximum value of the colormap:
#min_value = 0
#max_value = 1.2
# To use transparency, you can use alpha
# default is 0.8
# alpha = 0.5
# if line_width is not given, the score is used to set the line width
# using the following formula (0.5 * square root(score)
#line_width = 0.5
# options for line_style are 'solid', 'dashed', 'dotted', and 'dashdot'
line_style = solid
# If you want to compact the arcs (when you have both long and short arcs)
# You can choose a compact level of
# 1 (the height is proportional to the square root of the distance)
# 2 (the height is the same for all distances)
# (default is 0 proportional to distance)
#compact_arcs_level = 2
# To be able to see small arcs when big arcs exists, you can set
# the upper y limit.
# The unit is bp. This corresponds to the longest arc you will see.
# This option is incompatible with compact_arcs_level = 2
#ylim = 100000
file_type = links
    

maf¶

Description¶

A track for MAF (multiple alignment format). See the format description from UCSC.

Parameters¶

Necessary:¶

file
reference

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
line_width: 0.5 (default) or any float above 0
file_index: by default this option is not set
color_identical: black (default)
color_mismatch: grey (default)
color_gap: lightgrey (default)
species_order: by default this option is not set
species_labels: by default this option is not set
species_order_only: false (default) or true.
display_ref_seq: false (default) or true.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# In addition to the maf file the reference genome is required:
# For example
#reference = mm10
# To speed the access to specific region
# The maf file needs an index.
# The default is the file
# followed by '.index'. Alternatively another
# file can be specified.
# If it does not exists it will be created:
#file_index =
# Set colors
#color_identical = black
#color_mismatch = grey
#color_gap = lightgrey
# Set line_width
#line_width = 0.5
# optional: the species order
#species_order = hg18 panTro2
# optional if species_order is specified (don't use space in names)
#species_labels = human chimpanzee
# optional if species_order is specified and they are the only one you want:
#species_order_only = true
# optional if you want to see the DNA sequence of the ref
#display_ref_seq = true
# optional: If not given is guessed from the file ending.
file_type = maf
    

narrow_peak¶

Description¶

A track for ENCODE narrowPeak format.

Parameters¶

Necessary:¶

file

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
orientation: by default this option is not set but you can also put: inverted.
line_width: 1 (default) or any float above 0
color: #FF000080 (default)
max_value: by default this option is not set but you can also put: any float
show_data_range: true (default) or false.
show_labels: true (default) or false.
use_summit: true (default) or false.
width_adjust: 1.5 (default) or any float above 0
type: peak (default) or box.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

color = #FF000080
#max_value = 0.70
show_data_range = true
show_labels = true
# the narrowPeak format provides the information of the
# peak summit. By default this information is used
# although some peaks may look crooked.
use_summit = true
# type of plot: either box or peak
# box will plot a rectangle of the peak width
# peak will plot the shape of the peak, whose height is the
# narrowPeak file signal value (usually peak coverage)
type = peak
# if the peaks look too thin, the can be adjusted
width_adjust = 1.5
# optional: line_width
#line_width = 0.5
file_type = narrow_peak
    

scalebar¶

Description¶

A track to put scalebar like in the UCSC browser or put highlight a distance between two coordinates.

Parameters¶

Necessary:¶

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.
where: left (default) or right, top or bottom.
fontsize: 12 (default) or any float above 0
line_width: 0.5 (default) or any float above 0
color: black (default)
alpha: 1 (default) or any float above 0 below 1
x_center: by default this option is not set but you can also put: any integer above 0
size: by default this option is not set but you can also put: any integer above 0
scalebar_start_position: by default this option is not set but you can also put: any integer above 0
scalebar_end_position: by default this option is not set but you can also put: any integer above 0

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

# color of the scalebar
color = black
# To use transparency, you can use alpha
# default is 1
# alpha = 0.5
# line width:
# line_width = 0.5
# To set the position and the size of the scale bar
# 4 parameters can be set:
# x_center, scalebar_start_position, scalebar_end_position, size
# scalebar_start_position need to be smaller than x_center smaller than scalebar_end_position
# x_center: coordinate where the scale bar should be plotted (center)
# if not set and cannot be deduce from other parameters
# it will be in the middle of the plotted area
#x_center = 3100000
# size: in bp the length of the scale bar
# if not set and cannot be deduced from other parameters
# it will be like in UCSC:
# the higher number that begins with 1, 2 or 5 followed by 0s
# that is less than half the plotted area
#size = 100000
# Another example:
#scalebar_start_position = 2900000
#scalebar_end_position = 3100000
# where: where the size of the scale bar should
# appear among left, right, top, bottom
# default is left
#where = right
# fontsize: default is 12
#fontsize = 10
file_type = scalebar
    

spacer¶

Description¶

A track to include a space between tracks. To use it you can either put file_type = spacer or call your section [spacer]

Parameters¶

Necessary:¶

Optional:¶

title: Put here a title which will apprear on the right.
height: 0.5 (default) or float above 0.
overlay_previous: no (default) or yes or share-y.

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

vhighlight¶

Description¶

This type is not really a track as it does not occupy a horizontal space. It will go over all tracks plotted in the vertical orientation. It can be defined multiple times and will plot vertical rectangle corresponding to the intervals of a bed file.

Parameters¶

Necessary:¶

type: vhighlight
file

Optional:¶

line_width: 0.5 (default) or any float above 0
color: yellow (default)
alpha: 0.5 (default) or any float above 0 below 1
border_color: none (default)
zorder: -100 (default) or any float

Output of `make_tracks_file`:¶

# Mandatory:
# bed file with regions to highlight
file = regions.bed
# type:
type = vhighlight
# Optional:
# line width
#line_width = 0.5
# border_color of the line (put none to have no border):
#border_color = black
# color of the rectangle:
#color = yellow
# transparency:
#alpha = 0.3
# zorder, choose high values (10 or 100) to put on top
# and low values to put behind (0 or negative values)
#zorder = -100
    

vlines¶

Description¶

This type is not really a track as it does not occupy a horizontal space. It will go over all tracks plotted in the vertical orientation. It can be defined multiple times and will plot vertical vertical lines corresponding to the beginning of intervals of a bed file.

Parameters¶

Necessary:¶

type: vlines
file

Optional:¶

line_width: 0.5 (default) or any float above 0
line_style: dashed (default) or solid, dotted or dashdot.
color: black (default)
alpha: 0.7 (default) or any float above 0 below 1
zorder: 10 (default) or any float

Output of `make_tracks_file`:¶

# Mandatory:
# bed file with positions to plot (only start are used)
file = tads.bed
# type:
type = vlines
# Optional:
# line width
#line_width = 0.5
# color of the line:
#color = black
# transparency:
#alpha = 0.7
# zorder, choose positive value (above) to put on top
# and null or negative values to put behind
#zorder = 10
# line style choose among 'solid', 'dashed', 'dashdot' or 'dotted'
# line_style = 'dashed'
    

x_axis¶

Description¶

A track to include a x axis. To use it you can either put file_type = x_axis or call your section [x-axis]

Parameters¶

Necessary:¶

Optional:¶

title: Put here a title which will apprear on the right.
height: If you do not set it, the height will be fontsize / 8, else you can choose any float above 0.
overlay_previous: no (default) or yes or share-y.
where: bottom (default) or top.
fontsize: 15 (default) or any float above 0

Output of `make_tracks_file`:¶

# title of track (plotted on the right side)
title =
# height of track in cm (ignored if the track is overlay on top the previous track)
height = 2
# if you want to plot the track upside-down:
# orientation = inverted
# if you want to plot the track on top of the previous track. Options are 'yes' or 'share-y'.
# For the 'share-y' option the y axis values is shared between this plot and the overlay plot.
# Otherwise, each plot use its own scale
#overlay_previous = yes

Examples¶

These examples and the input data for these examples can found in the examples/ or test_data/ folders of the github repository.

Basic Examples
Examples with bed and gtf
Examples with 4C-seq
Examples with peaks
Example with horizontal lines
Examples with Epilogos
Examples with multiple options
Examples with multiple options for bigwig tracks
Examples with Hi-C data
Log transform and Operation Examples

Basic Examples ¶

A minimal example of a configuration file with a single bigwig track looks like this:

[bigwig file test]
file = bigwig.bw
# height of the track in cm (optional value)
height = 4
title = bigwig
min_value = 0
max_value = 30

$ pyGenomeTracks --tracks bigwig_track.ini --region X:2,500,000-3,000,000 -o bigwig.png

Now, let’s add the genomic location and some genes:

[bigwig file test]
file = bigwig.bw
# height of the track in cm (optional value)
height = 4
title = bigwig
min_value = 0
max_value = 30

[spacer]
# this simply adds an small space between the two tracks.

[genes]
file = genes.bed.gz
height = 7
title = genes
fontsize = 10
file_type = bed
gene_rows = 10

[x-axis]
fontsize=10

$ pyGenomeTracks --tracks bigwig_with_genes.ini --region X:2,800,000-3,100,000 -o bigwig_with_genes.png

Now, we will add some vertical lines across all tracks. The vertical lines should be in a bed format.

[bigwig file test]
file = bigwig.bw
# height of the track in cm (optional value)
height = 4
title = bigwig
min_value = 0
max_value = 30

[spacer]
# this simply adds an small space between the two tracks.

[genes]
file = genes.bed.gz
height = 7
title = genes
fontsize = 10
file_type = bed
gene_rows = 10

[x-axis]
fontsize=10

[vlines]
file = domains.bed
type = vlines

$ pyGenomeTracks --tracks bigwig_with_genes_and_vlines.ini --region X:2,800,000-3,100,000 -o bigwig_with_genes_and_vlines.png

_images/bigwig_with_genes_and_vlines.png

You can also overlay bigwig with or without transparency.

[test bigwig]
file = bigwig2_X_2.5e6_3.5e6.bw
color = blue
height = 7
title = No alpha: (bigwig color=blue 2000 bins) overlaid with (bigwig color = (0.6, 0, 0) max over 300 bins) overlaid with (bigwig mean color = green 200 bins)
number_of_bins = 2000
min_value = 0
max_value = 30

[test bigwig max]
file = bigwig2_X_2.5e6_3.5e6.bw
color = (0.6, 0, 0)
summary_method = max
number_of_bins = 300
overlay_previous = share-y

[test bigwig mean]
file = bigwig2_X_2.5e6_3.5e6.bw
color = green
type = fill
number_of_bins = 200
overlay_previous = share-y

[spacer]

[test bigwig]
file = bigwig2_X_2.5e6_3.5e6.bw
color = blue
height = 7
title = alpha (bigwig color = blue 2000 bins) overlaid with (bigwig color = (0.6, 0, 0) alpha = 0.5 max over 300 bins) overlaid with (bigwig mean color = green alpha = 0.5 200 bins)
number_of_bins = 2000
min_value = 0
max_value = 30

[test bigwig max]
file = bigwig2_X_2.5e6_3.5e6.bw
color = (0.6, 0, 0)
alpha = 0.5
summary_method = max
number_of_bins = 300
overlay_previous = share-y

[test bigwig mean]
file = bigwig2_X_2.5e6_3.5e6.bw
color = green
alpha = 0.5
type = fill
number_of_bins = 200
overlay_previous = share-y

[spacer]

[test bigwig]
file = bigwig2_X_2.5e6_3.5e6.bw
height = 7
title = alpha for lines/points: (bigwig color=(0.6, 0, 0) alpha = 0.5 max) overlaid with (bigwig mean color = green alpha = 0.5 line:2) overlaid with (bigwig min color = blue alpha = 0.5 points:2)
color = (0.6, 0, 0)
alpha = 0.5
summary_method = max
number_of_bins = 300
min_value = 0
max_value = 30

[test bigwig mean]
file = bigwig2_X_2.5e6_3.5e6.bw
color = green
type = line:2
alpha = 0.5
summary_method = mean
number_of_bins = 300
overlay_previous = share-y

[test bigwig min]
file = bigwig2_X_2.5e6_3.5e6.bw
color = blue
summary_method = min
number_of_bins = 1000
type = points:3
alpha = 0.5
overlay_previous = share-y

[x-axis]

$ pyGenomeTracks --tracks alpha.ini --region X:2700000-3100000 --trackLabelFraction 0.2 --dpi 130 -o master_alpha.png

Examples with bed and gtf ¶

Here is an example to explain the parameters for bed and gtf:

[x-axis]
where = top
title = where =top

[spacer]
height = 0.05

[genes 2]
file = dm3_genes.bed.gz
height = 7
title = genes (bed12) style = UCSC; fontsize = 10
style = UCSC
fontsize = 10

[genes 2bis]
file = dm3_genes.bed.gz
height = 7
title = genes (bed12) style = UCSC; arrow_interval=10; fontsize = 10
style = UCSC
arrow_interval = 10
fontsize = 10

[spacer]
height = 1

[test bed6]
file = dm3_genes.bed6.gz
height = 7
title = bed6 border_color = black; gene_rows=10; fontsize=7; color=Reds (when a color map is used for the color (e.g. coolwarm, Reds) the bed score column mapped to a color)
fontsize = 7
file_type = bed
color = Reds
border_color = black
gene_rows = 10

[spacer]
height = 1

[test bed4]
file = dm3_genes.bed4.gz
height = 10
title = bed4 fontsize = 10; line_width = 1.5; global_max_row = true (global_max_row sets the number of genes per row as the maximum found anywhere in the genome, hence the white space at the bottom)
fontsize = 10
file_type = bed
global_max_row = true
line_width = 1.5

[spacer]
height = 1

[test gtf]
file = dm3_subset_BDGP5.78_gtf.dat
height = 10
title = gtf from ensembl (with dat extension)
fontsize = 12
file_type = gtf

[spacer]
height = 1

[test bed]
file = dm3_subset_BDGP5.78_asbed_sorted.bed.gz
height = 10
title = gtf from ensembl in bed12
fontsize = 12
file_type = bed

[spacer]
height = 1

[test gtf collapsed]
file = dm3_subset_BDGP5.78.gtf.gz
height = 10
title = gtf from ensembl one entry per gene
merge_transcripts = true
prefered_name = gene_name
fontsize = 12
file_type = gtf

[spacer]
height = 1

[x-axis]
fontsize = 30
title = fontsize = 30

$ pyGenomeTracks --tracks bed_and_gtf_tracks.ini --region X:3000000-3300000 --trackLabelFraction 0.2 --width 38 --dpi 130 -o master_bed_and_gtf.png

By default, when bed are displayed and interval are stranded, the arrowhead which indicates the direction is plotted outside of the interval. Here is an example to show how to put it inside:

[x-axis]
where = top
title = where =top

[spacer]
height = 0.05

[genes 2]
file = dm3_genes.bed.gz
height = 3
title = genes (bed12) style = UCSC; fontsize = 10
style = UCSC
fontsize = 10

[genes 2bis]
file = dm3_genes.bed.gz
height = 3
title = genes (bed12) style = UCSC; arrow_interval=10; fontsize = 10
style = UCSC
arrow_interval = 10
fontsize = 10

[spacer]
height = 1

[test bed6]
file = dm3_genes.bed6.gz
height = 3
title = bed6 border_color = black; fontsize=8; color=red
fontsize = 8
file_type = bed
color = red
border_color = black

[spacer]
height = 1

[test bed6 arrowhead_included]
file = dm3_genes.bed6.gz
height = 3
title = bed6 border_color = black; fontsize=8; color=red; arrowhead_included = true
fontsize = 8
file_type = bed
color = red
border_color = black
arrowhead_included = true

[spacer]
height = 1

[test bed4]
file = dm3_genes.bed4.gz
height = 3
title = bed4 fontsize = 10; line_width = 1.5
fontsize = 10
file_type = bed
line_width = 1.5

[spacer]
height = 1

[test bed]
file = dm3_subset_BDGP5.78_asbed_sorted.bed.gz
height = 8
title = gtf from ensembl in bed12
fontsize = 12
file_type = bed

[spacer]
height = 1

[test bed]
file = dm3_subset_BDGP5.78_asbed_sorted.bed.gz
height = 8
title = gtf from ensembl in bed12; arrowhead_included = true
fontsize = 12
file_type = bed
arrowhead_included = true

[spacer]
height = 1

[x-axis]
fontsize = 30
title = fontsize = 30

[vlines]
type = vlines
file = dm3_genes.bed4.gz
line_style = dotted

[second_vlines]
type = vlines
file = dm3_genes_end.bed
line_width = 1
color = orange
zorder = -100

$ pyGenomeTracks --tracks bed_arrow_tracks.ini --region X:3130000-3140000 --trackLabelFraction 0.2 --width 38 --dpi 130 -o master_bed_arrow_zoom.png

When genes are displayed with the default style (flybase), the color and the height of UTR can be set:

[x-axis]
where = top

[spacer]
height = 0.05

[genes 0]
file = dm3_genes.bed.gz
height = 7
title = genes (bed12) style = flybase; fontsize = 10
style = flybase
fontsize = 10

[spacer]
height = 1

[genes 1]
file = dm3_genes.bed.gz
height = 7
title = genes (bed12) style = flybase; fontsize = 10; color_utr = red
style = flybase
fontsize = 10
color_utr = red

[spacer]
height = 1

[genes 2]
file = dm3_genes.bed.gz
height = 7
title = genes (bed12) style = flybase; fontsize = 10; height_utr = 0.7
style = flybase
fontsize = 10
height_utr = 0.7

[spacer]
height = 1

[genes 3]
file = dm3_genes.bed.gz
height = 7
title = genes (bed12) style = flybase; fontsize = 5; arrowhead_fraction = 0.03
style = flybase
fontsize = 5
arrowhead_fraction = 0.03
all_labels_inside = true

$ pyGenomeTracks --tracks bed_flybase_tracks.ini --region X:3000000-3300000 --trackLabelFraction 0.2 --width 38 --dpi 130 -o master_bed_flybase.png

Examples with 4C-seq ¶

The output file of some 4C-seq pipeline are bedgraph where the coordinates are the coordinates of the fragment. In these cases, it can be interesting to remove the regions absent from the file and just link the middle of the fragments together instead of plotting a rectangle for each fragment. Here is an example of the option use_middle

[x-axis]
where = top

[spacer]
height = 0.05

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = blue
height = 5
title = bedgraph rasterize = true
rasterize = true
max_value = 10

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = blue
height = 5
title = bedgraph
max_value = 10

[test bedgraph use middle]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = blue
height = 5
title = bedgraph with use_middle = true
max_value = 10
use_middle = true

[genes]
file = HoxD_cluster_regulatory_regions_mm10.bed
height = 3
title = HoxD genes and regulatory regions

We can generate two zooms using a bed instead of regions:

track type=bed name=regions_to_plot
chr2	73800000	75744000
chr2	74000000	74800000

$ pyGenomeTracks --tracks bedgraph_useMid.ini --BED regions_imbricated_chr2.bed --trackLabelFraction 0.2 --width 38 --dpi 130  -o master_bedgraph_useMid.png

_images/master_bedgraph_useMid_chr2-73800000-75744000.png

_images/master_bedgraph_useMid_chr2-74000000-74800000.png

Examples with peaks ¶

pyGenomeTracks has an option to plot peaks using MACS2 narrowPeak format.

The following is an example of the output in which the peak shape is drawn based on the start, end, summit and height of the peak.

[narrow]
file = test2.narrowPeak
height = 4
max_value = 40
line_width = 0.1
title = max_value = 40;line_width = 0.1

[narrow 2]
file = test2.narrowPeak
height = 2
show_labels = false
show_data_range =  false
color = #00FF0080
use_summit = false
title = show_labels = false; show_data_range = false; use_summit = false; color = #00FF0080

[spacer]

[narrow 3]
file = test2.narrowPeak
height = 2
show_labels = false
color = #0000FF80
use_summit = false
width_adjust = 4
title = show_labels = false; use_summit = false; width_adjust = 4

[spacer]

[narrow 4]
file = test2.narrowPeak
height = 3
type = box
color = blue
line_width = 2
title = type = box; color = blue; line_width = 2

[spacer]

[narrow 5]
file = test2.narrowPeak
height = 3
type = box
color = blue
use_summit = false
title = type = box; color = blue; use_summit = false

[x-axis]

$ pyGenomeTracks --tracks narrow_peak2.ini --region X:2760000-2802000 --trackLabelFraction 0.2 --dpi 130 -o master_narrowPeak2.png

Example with horizontal lines ¶

[test hlines]
color = red
line_width = 2
line_style = dashed
y_values = 10, 200
min_value = 0
show_data_range = true
height = 5
title = hlines: color = red; line_width = 2; line_style = dashed; y_values = 10, 200
file_type = hlines

[spacer]

[test bigwig fill]
file = bigwig2_X_2.5e6_3.5e6.bw
color = gray
height = 2
type = fill
title = bigwig: gray fill overlayed with hlines at 10 and 200 blue dotted
max_value = 50

[test hlines ovelayed]
color = blue
line_style = dotted
y_values = 10, 200
overlay_previous = share-y
file_type = hlines

[spacer]

[x-axis]

$ pyGenomeTracks --tracks hlines.ini --region X:2700000-3100000 --trackLabelFraction 0.2 --dpi 130 -o master_hlines.png

Examples with Epilogos ¶

pyGenomeTracks can be used to visualize epigenetic states (for example from chromHMM) as epilogos. For more information see: https://epilogos.altiusinstitute.org/

To plot epilogos a qcat file is needed. This file can be crated using the epilogos software (https://github.com/Altius/epilogos).

An example track file for epilogos looks like:

[epilogos]
file = epilog.qcat.bgz
height = 5
title = height=5; categories_file=epilog_cats.json

[x-axis]

$ pyGenomeTracks  --tracks epilogos_track.ini --region X:3100000-3150000 -o epilogos_track.png

The color of the bars can be set by using a json file. The structure of the file is like this

{
"categories":{
          "1":["Active TSS","#ff0000"],
          "2":["Flanking Active TSS","#ff4500"],
          "3":["Transcr at gene 5\" and 3\"","#32cd32"],
          "4":["Strong transcription","#008000"],
          "5":["Weak transcription","#006400"],
          "6":["Genic enhancers","#c2e105"],
          "7":["Enhancers","#ffff00"],
          "8":["ZNF genes & repeats","#66cdaa"],
          "9":["Heterochromatin","#8a91d0"],
          "10":["Bivalent/Poised TSS","#cd5c5c"],
          "11":["Flanking Bivalent TSS/Enh","#e9967a"],
          "12":["Bivalent Enhancer","#bdb76b"],
          "13":["Repressed PolyComb","#808080"],
          "14":["Weak Repressed PolyComb","#c0c0c0"],
          "15":["Quiescent/Low","#ffffff"]
	}
}

In the following examples the top epilogo has the custom colors and the one below is shown inverted.

[epilogos]
file = epilog.qcat.bgz
height = 5
title = epilogos with custom colors
categories_file = epilog_cats.json

[epilogos inverted]
file = epilog.qcat.bgz
height = 5
title = epilogos inverted
orientation = inverted

[x-axis]

$ pyGenomeTracks  --tracks epilogos_track2.ini --region X:3100000-3150000 -o epilogos_track2.png

Examples with multiple options ¶

A comprehensive example of pyGenomeTracks can be found as part of our automatic testing. Note, that pyGenomeTracks also allows the combination of multiple tracks into one using the parameter: overlay_previous = yes or overlay_previous = share-y. In the second option the y-axis of the tracks that overlays is the same as the track being overlay. Multiple tracks can be overlay together.

The configuration file for this image is:

[x-axis]
where = top
title = where=top

[spacer]
height = 0.05

[tads]
file = tad_classification.bed
title = TADs color = bed_rgb; border_color = black
file_type = domains
border_color = black
color = bed_rgb
height = 5

[tads 2]
file = tad_classification.bed
title = TADs orientation = inverted; color = #cccccc; border_color = red
file_type = domains
border_color = red
color = #cccccc
orientation = inverted
height = 3

[spacer]
height = 0.5

[tad state]
file = chromatinStates_kc.bed.gz
height = 1.2
title = bed display = interleaved; labels = false
display = interleaved
labels = false

[spacer]
height = 0.5

[tad state]
file = chromatinStates_kc.bed.gz
height = 0.5
title = bed display = collapsed; color = bed_rgb
labels = false
color = bed_rgb
display = collapsed

[spacer]
height = 0.5

[test bedgraph]
file = bedgraph_chrx_2e6_5e6.bg
color = blue
height = 1.5
title = bedgraph color = blue
max_value = 100

[test arcs]
file = test.arcs
title = links orientation = inverted
orientation = inverted
line_style = dashed
height = 2

[test bigwig]
file = bigwig2_X_2.5e6_3.5e6.bw
color = blue
height = 1.5
title = bigwig number_of_bins = 2000
number_of_bins = 2000

[spacer]

[test bigwig overlay]
file = bigwig2_X_2.5e6_3.5e6.bw
color = red
title = color:red; max_value = 50; number_of_bins = 100 (next track: overlay_previous = yes; max_value = 50; show_data_range = false; color = #0000FF80 (blue, with alpha 0.5))
min_value = 0
max_value = 50
height = 2
number_of_bins = 100

[test bigwig overlay]
file = bigwig_chrx_2e6_5e6.bw
color = #0000FF80
title =
min_value = 0
max_value = 50
show_data_range = false
overlay_previous = yes
number_of_bins = 100

[spacer]
height = 1

[tads 3]
file = tad_classification.bed
title = TADs color = #cccccc; border_color = red (next track: overlay_previous = share-y links_type = loops)
file_type = domains
border_color = red
color = #cccccc
height = 3

[test arcs overlay]
file = test.arcs
color = red
line_width = 10
links_type = loops
overlay_previous = share-y

[test arcs]
file = test.arcs
line_width = 3
color = RdYlGn
title = links line_width = 3 color RdYlGn
height = 3

[spacer]
height = 0.5
title = height = 0.5

[genes 2]
file = dm3_genes.bed.gz
height = 7
title = genes (bed12) style = flybase;fontsize = 10
style = flybase
fontsize = 10

[spacer]
height = 1

[test gene rows]
file = dm3_genes.bed.gz
height = 3
title = gene_rows = 3 (maximum 3 rows); style = UCSC
fontsize = 8
style = UCSC
gene_rows = 3

[spacer]
height = 1

[test bed6]
file = dm3_genes.bed6.gz
height = 7
title = bed6 border_color = black; gene_rows = 10; fontsize = 7; color = Reds (when a color map is used for the color (e.g. coolwarm, Reds) the bed score column mapped to a color)
fontsize = 7
file_type = bed
color = Reds
border_color = black
gene_rows = 10

[test bed6]
file = dm3_genes.bed6.gz
height = 10
title = bed6 fontsize = 10; line_width = 1.5; global_max_row = true (global_max_row sets the number of genes per row as the maximum found anywhere in the genome, hence the white space at the bottom)
fontsize = 10
file_type = bed
global_max_row = true
line_width = 1.5

[x-axis]
fontsize = 30
title = fontsize = 30

[vlines]
file = tad_classification.bed
type = vlines

$ pyGenomeTracks  --tracks browser_tracks.ini --region X:3000000-3500000 --trackLabelFraction 0.2 --width 38 --dpi 130  -o master_plot.png

Examples with multiple options for bigwig tracks ¶

The configuration file for this image is:

[test bigwig lines]
file = bigwig2_X_2.5e6_3.5e6.bw
color = gray
height = 2
type = line
title = orientation = inverted; show_data_range = false
orientation = inverted
show_data_range = false
max_value = 50

[test bigwig lines:0.2]
file = bigwig_chrx_2e6_5e6.bw
color = red
height = 2
type = line:0.2
title = type = line:0.2
min_value = auto
max_value = auto

[spacer]

[test bigwig points]
file = bigwig_chrx_2e6_5e6.bw
color = black
height = 2
min_value = 0
max_value = 100
type = points:0.5
title = type = point:0.5; min_value = 0; max_value = 100

[spacer]

[test bigwig nans to zeros]
file = bigwig_chrx_2e6_5e6.bw
color = red
height = 2
nans_to_zeros = true
title = nans_to_zeros = true

[spacer]

[test bigwig mean]
file = bigwig2_X_2.5e6_3.5e6.bw
color = gray
height = 5
title = gray:summary_method = mean; blue:summary_method = max; red:summary_method = min
type = line
summary_method = mean
max_value = 150
min_value = -5
show_data_range = false
number_of_bins = 300

[test bigwig max]
file = bigwig2_X_2.5e6_3.5e6.bw
#title = test
color = blue
type = line
summary_method = max
max_value = 150
min_value = -15
show_data_range = false
overlay_previous = share-y
number_of_bins = 300

[test bigwig min]
file = bigwig2_X_2.5e6_3.5e6.bw
color = red
type = line
summary_method = min
max_value = 150
min_value = -25
overlay_previous = share-y
number_of_bins = 300

[spacer]

[x-axis]

$ pyGenomeTracks  --tracks bigwig.ini --region X:2700000-3100000 --trackLabelFraction 0.2 --dpi 130 -o master_bigwig.png

Examples with Hi-C data ¶

The following is an example with Hi-C data overlay with topologically associating domains (TADs) and a bigwig file.

[x-axis]
where = top

[hic matrix]
file = hic_data.h5
title = Hi-C data
# depth is the maximum distance plotted in bp. In Hi-C tracks
# the height of the track is calculated based on the depth such
# that the matrix does not look deformed
depth = 300000
transform = log1p
file_type = hic_matrix

[tads]
file = domains.bed
display = triangles
border_color = black
color = none
# the tads are overlay over the hic-matrix
# the share-y options sets the y-axis to be shared
# between the Hi-C matrix and the TADs.
overlay_previous = share-y

[spacer]

[bigwig file test]
file = bigwig.bw
# height of the track in cm (optional value)
height = 4
title = ChIP-seq
min_value = 0
max_value = 30

$ pyGenomeTracks --tracks hic_track.ini -o hic_track.png --region chrX:2500000-3500000

Here is an example where the height was set or not set and the heatmap was rasterized (default) or not rasterized (the dpi was set very low just to show the impact of the parameter).

[hic matrix]
file = Li_et_al_2015.cool
title = depth = 200000; transform = log1p; min_value = 5; height = 5
depth = 200000
min_value = 5
transform = log1p
file_type = hic_matrix
show_masked_bins = false
height = 5

[hic matrix 2]
file = Li_et_al_2015.h5
title = same but orientation=inverted; no height
depth = 200000
min_value = 5
transform = log1p
file_type = hic_matrix
show_masked_bins = false
orientation = inverted

[spacer]
height = 0.5

[hic matrix 3]
file = Li_et_al_2015.h5
title = same rasterize = false
depth = 200000
min_value = 5
transform = log1p
file_type = hic_matrix
rasterize = false
show_masked_bins = false

[x-axis]

$ pyGenomeTracks --tracks browser_tracks_hic_rasterize_height.ini --region X:2500000-2600000 --trackLabelFraction 0.23 --width 38 --dpi 10 -o master_plot_hic_rasterize_height.pdf

The output is available here: master_plot_hic_rasterize_height.pdf.

This examples is where the overlay tracks are more useful. Notice that any track can be overlay over a Hi-C matrix. Most useful is to overlay TADs or to overlay links using the triangles option that will point in the Hi-C matrix the pixel with the link contact. When overlaying links and TADs is useful to set overlay_previous=share-y such that the two tracks match the positions. This is not required when overlying other type of data like a bigwig file that has a different y-scale.

The configuration file for this image is:

[hic matrix]
file = Li_et_al_2015.h5
title = depth = 200000; transform = log1p; min_value = 5
depth = 200000
min_value = 5
transform = log1p
file_type = hic_matrix
show_masked_bins = false

[hic matrix]
file = Li_et_al_2015.h5
title = depth = 250000; orientation = inverted; customized colormap; min_value = 5; max_value = 70
min_value = 5
max_value = 70
depth = 250000
colormap = ['white', (1, 0.88, .66), (1, 0.74, 0.25), (1, 0.5, 0), (1, 0.19, 0), (0.74, 0, 0), (0.35, 0, 0)]
file_type = hic_matrix
show_masked_bins = false
orientation = inverted

[spacer]
height = 0.5

[hic matrix]
file = Li_et_al_2015.h5
title = depth = 300000; transform = log1p; colormap Blues (TADs: overlay_previous = share-y; line_width = 1.5)
colormap = Blues
min_value = 10
max_value = 150
depth = 300000
transform = log1p
file_type = hic_matrix

[tads]
file = tad_classification.bed
#title = TADs color = none; border_color = black
file_type = domains
border_color = black
color = none
height = 5
line_width = 1.5
overlay_previous = share-y
show_data_range = false

[spacer]
height = 0.5

[hic matrix]
file = Li_et_al_2015.h5
title = depth = 250000; transform = log1p; colormap = bone_r (links: overlay_previous = share-y; links_type = triangles; color = darkred; line_style = dashed, bigwig: color = red)
colormap = bone_r
min_value = 15
max_value = 200
depth = 250000
transform = log1p
file_type = hic_matrix
show_masked_bins = false

[test arcs]
file = links2.links
title =
links_type = triangles
line_style = dashed
overlay_previous = share-y
line_width = 0.8
color = darkred
show_data_range = false


[test bigwig]
file = bigwig2_X_2.5e6_3.5e6.bw
color = red
height = 4
title =
overlay_previous = yes
min_value = 0
max_value = 50
show_data_range = false

[spacer]
height = 0.5

[hic matrix]
file = Li_et_al_2015.h5
title = depth = 200000; show_masked_bins = true; colormap = ['blue', 'yellow', 'red']; max_value = 150
depth = 200000
colormap = ['blue', 'yellow', 'red']
max_value = 150
file_type = hic_matrix
show_masked_bins = true

[spacer]
height = 0.1

[x-axis]

$ pyGenomeTracks  --tracks browser_tracks_hic.ini --region X:2500000-3500000 --trackLabelFraction 0.23 --width 38 --dpi 130 -o master_plot_hic.png

Log transform and Operation Examples ¶

With the parameter operation you can make operations between one or two files (here two bigwig files but this is also working with two bedgraph files). For example, difference, log ratio, scaling…

The configuration file for this image is:

[test bigwig1]
file = bigwig_chrx_2e6_5e6.bw
second_file = bigwig2_X_2.5e6_3.5e6.bw
color = blue
height = 4
title = first bw
min_value = 0
max_value = 30

[test bigwig2]
file = bigwig2_X_2.5e6_3.5e6.bw
color = red
height = 4
title = second bw
min_value = 0
max_value = 30
orientation = inverted

[spacer]
height = 0.5

[test bigwig dif]
file = bigwig_chrx_2e6_5e6.bw
second_file = bigwig2_X_2.5e6_3.5e6.bw
color = blue
negative_color = red
height = 8
title = operation = file - second_file
operation = file - second_file
min_value = -30
max_value = 30
nans_to_zeros = true

[spacer]
height = 0.5

[test bigwig op]
file = bigwig_chrx_2e6_5e6.bw
second_file = bigwig2_X_2.5e6_3.5e6.bw
color = blue
negative_color = red
height = 8
title = operation = log10((1 + file)/(1 + second_file))
operation = log10((1 + file)/(1 + second_file))
nans_to_zeros = true

[spacer]
height = 0.5

[test bigwig op2]
file = bigwig_chrx_2e6_5e6.bw
second_file = bigwig2_X_2.5e6_3.5e6.bw
color = red
height = 4
title = operation = 2 + second_file
operation = 2 + second_file
nans_to_zeros = true
max_value = 32
min_value = 0

[test bigwig op2bis]
file = bigwig_chrx_2e6_5e6.bw
second_file = bigwig2_X_2.5e6_3.5e6.bw
color = blue
height = 4
title = operation = 1 + 2 * file
operation = 1 + 2 * file
nans_to_zeros = true
max_value = 32
min_value = 0

[spacer]
height = 0.5

[test bigwig op3]
file = bigwig_chrx_2e6_5e6.bw
second_file = bigwig2_X_2.5e6_3.5e6.bw
color = green
height = 4
title = operation = max(file, second_file) in green overlayed with (file + second_file) / 2 in lime overlayed with min(file, second_file) in yellow
operation = max(file, second_file)
nans_to_zeros = true
max_value = 30
min_value = 0

[test bigwig op4]
file = bigwig_chrx_2e6_5e6.bw
second_file = bigwig2_X_2.5e6_3.5e6.bw
color = lime
operation = (file + second_file) / 2
nans_to_zeros = true
overlay_previous = share-y

[test bigwig op5]
file = bigwig_chrx_2e6_5e6.bw
second_file = bigwig2_X_2.5e6_3.5e6.bw
color = yellow
operation = min(file, second_file)
nans_to_zeros = true
overlay_previous = share-y

[spacer]
height = 0.5


[x-axis]

$ pyGenomeTracks --tracks operation.ini --region X:2700000-3100000 --trackLabelFraction 0.2 --dpi 130 -o master_operation.png

With the parameter transformation you can log transform your data and decide to put on the y axis either the transformed values or the original values:

The configuration file for this image is:

[test bigwig]
file = bigwig_chrx_2e6_5e6.bw
color = red
height = 5
transform = no
title = bigwig transform = no

[spacer]

[test bigwig log]
file = bigwig_chrx_2e6_5e6.bw
color = red
height = 5
transform = log1p
title = bigwig transform = log1p

[spacer]

[test bigwig log]
file = bigwig_chrx_2e6_5e6.bw
color = red
min_value = 0
height = 5
transform = log1p
title = bigwig transform = log1p min_value = 0 y_axis_values = original
y_axis_values = original

[x-axis]

$ pyGenomeTracks --tracks log1p.ini --region X:2700000-3100000 --trackLabelFraction 0.2 --dpi 130 -o master_log1p.png

With operation you can also do log transformation however nothing will be written on the left of the y axis:

The configuration file for this image is:

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = blue
height = 5
title = bedgraph color = blue transform = no
transform = no

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = blue
height = 5
title = bedgraph color = blue transform = log
transform = log

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = red
height = 5
title = bedgraph color = red transform = log min_value = 1
min_value = 1
transform = log

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = green
height = 5
title = bedgraph color = green transform = log log_pseudocount = 2 min_value = 0
transform = log
log_pseudocount = 2
min_value = 0

[test bedgraph with operation]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = green
height = 5
title = bedgraph color = green operation = log(2+file) min_value = 0.7
operation = log(2+file)
min_value = 0.7

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = black
height = 5
title = bedgraph color = black transform = log2 log_pseudocount = 1 min_value = 0
transform = log2
log_pseudocount = 1
min_value = 0

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = black
height = 5
title = bedgraph color = black operation = log2(1+file) min_value = 0
operation = log2(1+file)
min_value = 0

[test bedgraph]
file = GSM3182416_E12DHL_WT_Hoxd11vp.bedgraph.gz
color = black
height = 5
title = bedgraph color = black transform = log2 log_pseudocount = 1 min_value = 0 y_axis_values = original
transform = log2
log_pseudocount = 1
min_value = 0
y_axis_values = original

[x-axis]

$ pyGenomeTracks --tracks log.ini  --region chr2:73,800,000-75,744,000 --trackLabelFraction 0.2 --width 38 --dpi 130  -o master_log.png

Possible parameters¶

Here is a table to summarize which are the parameters that can be use for each of the file_type and which is the default value: Empty means this parameter is not used. not set means that by default the parameter is commented. This table is available as csv here.

parameter	x_axis	epilogos	links	domains	bed	gtf	narrow_peak	bigwig	bedgraph	bedgraph_matrix	hlines	hic_matrix	hic_matrix_square	maf	scalebar	vlines	vhighlight
overlay_previous	no	no	no	no	no	no	no	no	no	no	no	no	no	no	no
where	bottom														left
fontsize	15				12	12									12
categories_file		not set
orientation		not set	not set	not set	not set	not set	not set	not set	not set	not set	not set	not set	not set	not set
links_type			arcs
line_width			not set	0.5	0.5	0.5	1				0.5			0.5	0.5	0.5	0.5
line_style			solid								solid					dashed
color			blue	#1f78b4	#1f78b4	#1f78b4	#FF000080	#33a02c	#a6cee3		black				black	black	yellow
alpha			0.8					1	1		1				1	0.7	0.5
max_value			not set	not set	not set		not set	not set	not set	not set	not set	not set	not set
min_value			not set	not set	not set			not set	not set	not set	not set	not set	not set
ylim			not set
compact_arcs_level			0
use_middle			false						false
region2			not set										not set
border_color				black	black	black											none
prefered_name				transcript_name	transcript_name	transcript_name
merge_transcripts				false	false	false
labels					true	true
style					flybase	flybase
display					stacked	stacked
max_labels					60	60
merge_overlapping_exons					false	false
global_max_row					false	false
gene_rows					not set	not set
arrow_interval					2	2
arrowhead_included					false	false
arrowhead_fraction					0.004	0.004
color_utr					grey	grey
color_backbone					black	black
height_utr					1	1
arrow_length					not set	not set
all_labels_inside					false	false
labels_in_margin					false	false
fontstyle					normal	normal
show_data_range							true	true	true	true	true
show_labels							true
use_summit							true
width_adjust							1.5
type							peak	fill	fill	matrix
negative_color								not set	not set
nans_to_zeros								false	false
summary_method								mean	not set
number_of_bins								700	700
transform								no	no			no	no
log_pseudocount								0	0
y_axis_values								transformed	transformed
second_file*								not set	not set
operation*								file	file
grid								false	false
rasterize									false	true		true	true
pos_score_in_bin										center
plot_horizontal_lines										false
colormap										viridis		RdYlBu_r	RdYlBu_r
individual_color										grey
summary_color										#1f77b4
depth												100000
show_masked_bins												false	false
scale_factor												1	1
file_index														not set
color_identical														black
color_mismatch														grey
color_gap														lightgrey
species_order														not set
species_labels														not set
species_order_only														false
display_ref_seq														false
x_center															not set
size															not set
scalebar_start_position															not set
scalebar_end_position															not set
zorder																10	-100

* While pyGenomeTracks can convert coverage tracks on the fly, this might be a time-consuming step, especially on large files and if you want to replot many times. In this situation, we recommend using the deepTools suite to convert your files in advance. For example bamCoverage or bamCompare

Some parameters can take only discrete values.

They are summarized here:

overlay_previous:
- for x_axis, epilogos, links, domains, bed, gtf, narrow_peak, bigwig, bedgraph, bedgraph_matrix, hlines, hic_matrix, hic_matrix_square, maf, scalebar, fasta, spacer: no, yes, share-y
where:
- for x_axis: top, bottom
- for scalebar: left, right, top, bottom
orientation:
- for epilogos, links, domains, bed, gtf, narrow_peak, bigwig, bedgraph, bedgraph_matrix, hlines, hic_matrix, hic_matrix_square, maf: inverted, not set
links_type:
- for links: arcs, triangles, loops, squares
line_style:
- for links, hlines, vlines: solid, dashed, dotted, dashdot
compact_arcs_level:
- for links: 0, 1, 2
use_middle:
- for links, bedgraph: true, false
merge_transcripts:
- for domains, bed, gtf: true, false
style:
- for bed, gtf: flybase, UCSC, tssarrow
display:
- for bed: collapsed, triangles, interleaved, stacked, squares
- for gtf: collapsed, triangles, interleaved, stacked
fontstyle:
- for bed, gtf: normal, italic, oblique
labels:
- for bed, gtf: true, false
global_max_row:
- for bed, gtf: true, false
arrowhead_included:
- for bed, gtf: true, false
all_labels_inside:
- for bed, gtf: true, false
labels_in_margin:
- for bed, gtf: true, false
merge_overlapping_exons:
- for bed, gtf: true, false
type:
- for narrow_peak: peak, box
- for bedgraph_matrix: matrix, lines
show_data_range:
- for narrow_peak, bigwig, bedgraph, bedgraph_matrix, hlines: true, false
show_labels:
- for narrow_peak: true, false
use_summit:
- for narrow_peak: true, false
summary_method:
- for bigwig: mean, average, max, min, stdev, dev, coverage, cov, sum
- for bedgraph: mean, average, max, min, stdev, dev, coverage, cov, sum, not set
transform:
- for bigwig, bedgraph: no, log, log1p, -log, log2, log10
- for hic_matrix, hic_matrix_square: no, log, log1p, -log
y_axis_values:
- for bigwig, bedgraph: original, transformed
nans_to_zeros:
- for bigwig, bedgraph: true, false
grid:
- for bigwig, bedgraph: true, false
rasterize:
- for bedgraph, bedgraph_matrix, hic_matrix, hic_matrix_square: true, false
pos_score_in_bin:
- for bedgraph_matrix: center, block
plot_horizontal_lines:
- for bedgraph_matrix: true, false
show_masked_bins:
- for hic_matrix, hic_matrix_square: true, false
species_order_only:
- for maf: true, false
display_ref_seq:
- for maf: true, false

Adding new tracks¶

Adding new tracks to pyGenomeTracks only requires adding a new class to the pygenometracks/tracks folder. The name of the file must end with Track.py. The class must inherit the GenomeTrack (or other track class available) and must have a plot method. In order to work well with the config checker it should also have some global variable: - DEFAULTS_PROPERTIES is a dictionary where each key is a parameter and each value is the default value when it is not set or when something goes wrong. - NECESSARY_PROPERTIES is an array with all the parameters which are necessary for this track (usually ‘file’) - SYNONYMOUS_PROPERTIES is a dictionary where each key is a parameter, each value is a dictionnary where each key is a string that should be replaced by the value (for example, SYNONYMOUS_PROPERTIES = {'max_value': {'auto': None}}) - POSSIBLE_PROPERTIES is a dictionary where each key is a parameter, each value is an array with the only possible values for this parameter, if the value specified by the user is not part of them, it will be substituted by the default value. - BOOLEAN_PROPERTIES is an array with all parameters that should have a boolean value (a boolean value can be 0, 1, true, false, on, off) - STRING_PROPERTIES is an array with all parameters that have string values. It should always contains title and file_type. - FLOAT_PROPERTIES is a dictionnary where each key is a parameter, each value is an array with the min value (included) and the max value (included) that should have the parameter (You can use [- np.inf, np.inf] if there is no restriction). This dictionary should always contains 'height': [0, np.inf] - INTEGER_PROPERTIES same as FLOAT_PROPERTIES for integer values.

Additionally, some basic description should be added.

For example, to make a track that prints ‘hello world’ at a given location looks like this:

# -*- coding: utf-8 -*-
from . GenomeTrack import GenomeTrack
import numpy as np


class TextTrack(GenomeTrack):
    SUPPORTED_ENDINGS = ['.txt']  # this is used by make_tracks_file to guess the type of track based on file name
    TRACK_TYPE = 'text'
    OPTIONS_TXT = """
height = 3
title =
text =
# x position of text in the plot (in bp)
x position =
"""
    DEFAULTS_PROPERTIES = {'text': 'hello world'}
    NECESSARY_PROPERTIES = ['x_position']
    SYNONYMOUS_PROPERTIES = {}
    POSSIBLE_PROPERTIES = {}
    BOOLEAN_PROPERTIES = []
    STRING_PROPERTIES = ['text', 'title', 'file_type']
    FLOAT_PROPERTIES = {'height': [0, np.inf],
                        'x_position': [0, np.inf]}
    INTEGER_PROPERTIES = {}

    def plot(self, ax, chrom, region_start, region_end):
        """
        This example simply plots the given title at a fixed
        location in the axis. The chrom, region_start and region_end
        variables are not used.
        Args:
            ax: matplotlib axis to plot
            chrom_region: chromosome name
            start_region: start coordinate of genomic position
            end_region: end coordinate
        """
        # print text at position x = self.properties['x position'] and y = 0.5 (center of the plot)
        ax.text(self.properties['x_position'], 0.5, self.properties['text'])

The OPTIONS_TXT should contain the text to build a default configuration file. This information, together with the information about SUPPORTED_ENDINGS is used by the program make_tracks_file to create a default configuration file based on the endings of the files given.

The configuration file is:

[x-axis]
where = top

[new track]
file = 
height = 4
title = new pyGenomeTrack
file_type = text
text = hello world
x position = 3100000

$ pyGenomeTracks  --tracks new_track.ini --region X:3000000-3200000 -o new_track.png

Notice that the resulting track already includes a y-axis (to the left) and a label to the right. Those are the defaults that can be changed by adding a plot_y_axis and plot_label methods.

Another more complex example is the plotting of multiple bedgraph data as matrices. The output of HiCExplorer hicFindTADs produces a file whose data format is similar to a bedgraph but with more value columns. We call this a bedgraph matrix. The following track plot this bedgraph matrix:

# -*- coding: utf-8 -*-
import numpy as np
from . BedGraphTrack import BedGraphTrack
from . GenomeTrack import GenomeTrack


class BedGraphMatrixTrack(BedGraphTrack):
    # this track class extends a BedGraphTrack that is already part of
    # pyGenomeTracks. The advantage of extending this class is that
    # we can re-use the code for reading a bedgraph file
    SUPPORTED_ENDINGS = ['.bm', '.bm.gz']
    TRACK_TYPE = 'bedgraph_matrix'
    OPTIONS_TXT = GenomeTrack.OPTIONS_TXT + f"""
# a bedgraph matrix file is like a bedgraph, except that per bin there
# are more than one value (separated by tab). This file type is
# produced by the HiCExplorer tool hicFindTads and contains
# the TAD-separation score at different window sizes.
# E.g.
# chrX	18279	40131	0.399113	0.364118	0.320857	0.274307
# chrX	40132	54262	0.479340	0.425471	0.366541	0.324736
#min_value = 0.10
#max_value = 0.70
file_type = {TRACK_TYPE}
"""
    DEFAULTS_PROPERTIES = {'max_value': None,
                           'min_value': None,
                           'show_data_range': True,
                           'orientation': None}
    NECESSARY_PROPERTIES = ['file']
    SYNONYMOUS_PROPERTIES = {'max_value': {'auto': None},
                             'min_value': {'auto': None}}
    POSSIBLE_PROPERTIES = {'orientation': [None, 'inverted']}
    BOOLEAN_PROPERTIES = ['show_data_range']
    STRING_PROPERTIES = ['file', 'file_type', 'overlay_previous',
                         'orientation', 'title']
    FLOAT_PROPERTIES = {'max_value': [- np.inf, np.inf],
                        'min_value': [- np.inf, np.inf],
                        'height': [0, np.inf]}
    INTEGER_PROPERTIES = {}

    # In BedGraphTrack the method set_properties_defaults
    # has been adapted to a coverage track. Here we want to
    # go back to the initial method:
    def set_properties_defaults(self):
        GenomeTrack.set_properties_defaults(self)

    def plot(self, ax, chrom_region, start_region, end_region):
        """
        Args:
            ax: matplotlib axis to plot
            chrom_region: chromosome name
            start_region: start coordinate of genomic position
            end_region: end coordinate
        """
        start_pos = []
        matrix_rows = []

        # the BedGraphTrack already has methods to read files
        # in which the first three columns are chrom, start,end
        # here we used the interval_tree method inherited from the
        # BedGraphTrack class
        for region in sorted(self.interval_tree[chrom_region][start_region - 10000:end_region + 10000]):
            start_pos.append(region.begin)
            # the region.data contains all the values for a given region
            # In the following code, such list is converted to floats and
            # appended to a new list.
            values = list(map(float, region.data))
            matrix_rows.append(values)

        # using numpy, the list of values per line in the bedgraph file
        # is converted into a matrix whose columns contain
        # the bedgraph values for the same line (notice that
        # the matrix is transposed to achieve this)
        matrix = np.vstack(matrix_rows).T

        # using meshgrid we get x and y positions to plot the matrix at
        # corresponding positions given in the bedgraph file.
        x, y = np.meshgrid(start_pos, np.arange(matrix.shape[0]))

        # shading adds some smoothing to the pllot
        shading = 'gouraud'
        vmax = self.properties['max_value']
        vmin = self.properties['min_value']

        img = ax.pcolormesh(x, y, matrix, vmin=vmin, vmax=vmax, shading=shading)
        img.set_rasterized(True)

    def plot_y_axis(self, ax, plot_axis):
        """turn off y_axis plot"""
        pass

    def __del__(self):
        if self.tbx is not None:
            self.tbx.close()

Let’s create a track for this:

[bedgraph matrix]
file = tad_separation_score.bm.gz
file_type = bedgraph_matrix
title = bedgraph matrix
height = 5

[spacer]

[x-axis]

$ pyGenomeTracks  --tracks bedgraph_matrix.ini --region X:2000000-3500000 -o bedgraph_matrix.png

Although this image looks interesting another way to plot the data is a overlapping lines with the mean value highlighted. Using the bedgraph version of pyGenomeTracks the following image can be obtained:

Releases¶

3.8¶

Enhancement:¶

A new type was introduced in 3.7 (announcement has been forgotten): a vhighlight to be able to hightlight a whole region across all tracks.
Much more parameters for vhighlight and vlines
- ‘zorder’ to set it on top or behind.
- ‘line_width’, ‘color’, ‘alpha’, ‘border_color’ for vhighlight and ‘line_style’ for vlines
You can now set multiple vlines
For gtf, the output of make_tracks_file set prefered_name to gene_name instead of transcript_name.

Bugfix:¶

Support mcool files for hic_matrix_square. This solves #404
Works with gffutils version 0.11.0 where ValueError became gffutils.exceptions.EmptyInputError for empty gtf.
The installation instructions have been updated
Fixed a small bug in links track with “use_middle” enabled, where midpoints could have different ordering than start points (Thanks to @Jeff1995 ).
Fix a bug when plotting gtf in the middle of a large intron.
Fix plot genes with orientation = inverted
Support Numpy 1.24, drop support below 1.20

Relax version control on matplotlib:¶

Any version of matplotlib from 3.1.1 to 3.6.2 is now accepted.

3.7¶

Enhancements:¶

This release is full of new tracks and new parameters for existing tracks:

Brand new tracks:
- fasta: to display sequences with colored letters from a fasta file (Thanks @GDelevoye for his contribution).
- maf (multiple alignment format): to display conservation between species.
- hic_matrix_square: to display Hi-C matrices not in ‘triangle’ shape but in ‘square’ shape. This allow to display identical regions but also interactions between 2 different regions. This render plots close to hicPlotMatrix.
New parameters for existing tracks:
- Related to hic_matrix_square: we implemented a new display mode for bed and links_type for links: squares. This allow to overlay TADs or loops on these Hi-C maps.
- For bed and gtf:
  the fontstyle can be set to italic or oblique.
  
  the arrowhead_fraction which controls the size of the arrowhead in the flybase style can be adjusted.
  
  the color of the backbone when you use flybase or UCSC style can be changed with color_backbone.
- For gtf a new parameter merge_overlapping_exons = true help to get a better display when all transcripts are merged.
- For bedgraph_matrix: when type = lines is set the colors of individual lines can be set by individual_color and the summary line by summary_color

Minor enhancements:¶

pyGenomeTracks display better error message when rtf files are used.
the help message for BED has been improved to highlight the fact that the extension needs to be part of the output.
if the directory of the output file does not exists, it is created.

Drop support for python 3.6¶

The introduction of the new track for Maf forced us to drop support for python 3.6.

Relax version control on matplotlib:¶

Any version of matplotlib from 3.1.1 to 3.5.1 is now accepted.

Bugfixes:¶

The tick values for the x-axis are now accurate (see #333) and more informative.
The y values for tracks like bigwig are not restricted to one decimal. If needed, the scientific notation can be used.
pyGenomeTracks now allows to plot above chromosome size defined in bigwig or Hi-C matrices without raising an error.
pyGenomeTracks now works with gtf without exons.
pyGenomeTracks now closes figures after saving.
The plotting part does not modify the tracks anymore. This solves #393

3.6¶

Enhancements:¶

A new parameter for pyGenomeTracks allow to fix the width of the central part: --plotWidth
For scale bars, you can now define the position using 2 parameters among x_center, size, scalebar_start_position and scalebar_end_position.

Python dependency with conda:¶

Using conda which is the way we recommand installation it is now possible to use Python 3.8.

Relax version control on matplotlib:¶

Any version of matplotlib from 3.1.1 to 3.3.2 is now accepted.

Bugfixes:¶

When the --fontSize parameter was used it happened that the colorbar labels were not corresponding to the colorbar ticks. This bug has been fixed.
The colormap pink was not working because it was both the name of a color and a colormap. This bug has been fixed.
When setting min_value, max_value, if the track was empty these values were ignored. This bug has been fixed.
When using operation in bedgraph with a second_file, BEDTools is now used to intersect the second file. use_middle is now taken into account on the second file.
Different handling of string evaluation of color, colormap and operation.

3.5.1¶

Bugfixes:¶

Get a message when bedtools is installed instead of crashing without any message.
Always test if a bedgraph is tabix indexed without checking the extension
Fix a bug which was happening when operation or summary_method was used on bedgraph whereas the bedgraph had some missing intervals.
Enforcing version 15 of HiCMatrix. Version 14 had a bug concerning the application of the correction factors of cool files.

3.5¶

Enhancements:¶

pyGenomeTracks goes much faster:
- We now use bedtools to load only a portion of bed, gtf, bedgraph, narrowPeak, bedgraphMatrix, Epilogos, links. This speeds up the process dramatically especially for gtf files.
- When you use a cool matrix, only the plotted region is loaded, this speeds up the process. If multiple regions on different chromosomes are provided in a BED this option is not used.
- Unfortunately, it is not possible to speed the process with h5 matrices so you may want to convert them to cool with hicConvertFormat.
pyGenomeTracks does not require sorted bed anymore.
For coverage tracks (bedgraph and bigwig), there is a new parameter: grid which allows to display horizontal lines.
For links, you can choose to use the middle of start1 and end1 and the middle of start2 and end2 thanks to use_middle instead of the extremities coordinates.
For Hi-C matrices, mcool files are now supported.
For vlines, the line_width can now be set.

Minor enhancements:¶

Bedgraph with NA values in the 4-th column do not raise error anymore.
There is a progress bar for links.
For Hi-C matrices,
- there is no error when the plot goes over the chromosome size provided by the matrix.
- if the depth is smaller than binsize it makes an empty plot instead of raising errors.
When the overlay_previous is set in the first track it is ignored and a warning is given instead of giving an error with a not meaningful error message.
The color for negative values in coverage tracks (bigwig and bedgraph) is now part of the output of make_tracks_file.
Others output of make_tracks_file have been modified for better clarity.
Others code related enhancements which are transparent to the users.
The format of bed12 is more stringent (the blocks must span the chromStart and chromEnd).
Improve the documentation regarding the installation. We highly recommand to use conda.

Bugfixes:¶

For bed tracks when gene_rows or global_max_row was set the last row was very close to the bottom (sometimes even overlaying the next track). Now it is vertically centered and do not go over the track height.
Solve some bugs how non conventional bed files are handle.
Display more meaningful error messages.
Only plot scale bar when in the region of plot.
Do not show a warning when file_type is set for x_axis or spacer.
Solve some incompatibilities with python 3.8. However, python 3.8 is not officially supported by now as bioconda do not support it yet https://bioconda.github.io/user/versions.html#python.

3.4¶

Improved documentation:¶

fix url of test_data thanks to @sonnynguyen
Better documentation for pyGenomeTracks / makeTracksFile
Documentation of each track

Enhancements:¶

Different bed files format (BED3, BED4, BED5, BED6, BED8, BED9, BED12) is guessed based on the first line and rely not only on number of columns but on the type of each column (string/float etc.). This way, broadPeaks/gappedPeaks and other bed-like formats can be accepted as file_type = bed without preprocessing.
gtf has now its own file_type. Warning:file_type = bed for gtf will be no longer supported in a future version.
You can use a decreasing x-axis (from larger coordinates to smaller coordinates) with the option --decreasingXAxis in pyGenomeTracks.
For bedgraph and bigwig:
- logScale: To apply a log transformation to your data you can set transform to log1p, log, log2, log10, -log. For others than log1p, you can set a log_pseudocount. By default the y axis values will represent the transformed values and the transformation will be written on the left of the y axis but you can decide to keep the original values by setting y_axis_values = original.
- operation on files: You can plot the result of an operation on one or two files without preprocessing. To use it, put the operation in operation with the variable file or both variables file and second_file, for example operation = 0.89 * file or operation = max(file, second_file) or operation = file - second_file. In the two later cases, you need to put the path of the second file in second_file. However, this operation can be time consuming if you do it multiple times and you may prefer to convert your files in advance.
For more examples on these two new features, visit the examples.
Both type = line and type = lines are working in bedgraph_matrix

Bugfix:¶

In version 3.3, if you were using a colormap in bed the border_color and color_utr were ignored. Now each one can be set to different color/colormap/bed_rgb.

3.3¶

Release 3.3 adds:¶

a documentation on readthedocs: https://pygenometracks.readthedocs.io
progress bar for bed, gtf, bedgraph, narrowPeak, epilogos
all colors can be set as (r, g, b) with r, g, b values between 0 and 1.
all colormap can be set as an array of colors, for example [red, white, (0, 0, 0.5)]
the titles on the right can be align left, right or center with the argument --trackLabelHAlign
for the links track
- compact_arcs_level to be able to see both very long arcs and very small arcs.
- ylim to be able to zoom and see small arcs.
a new track type: file_type = scalebar which by default is close to the UCSC scale bar.
for the bed tracks
- a new gene type: tssarrow
- border_color and color_utr can be set to bed_rgb.
- all_labels_inside allow to put the name of the region on the left if it ends after the plotted region.
- labels_in_margin allow to put the name of the region in the margin if it ends after the plotted region.
line_width can now be set in the narrowPeak tracks.
colormap can now be set in bedgraphMatrix tracks.

bug fixes:¶

if a bed with no interval is provided, pgt no longer exit.
When an exon had both UTR start and UTR end within it, only the UTR start was considered.
alpha in links tracks was not used
qcat files with missing values are now working.

3.2.1¶

Small bug fix in parser when the parameter had spaces in the name and was a boolean (for example show data range instead of show_data_range).

Warning: In version 4.0 no parameter with space will be accepted.

3.2¶

This is a major release with a lot of new features but also some deprecations in preparation for a new 4.0 release.

During the years we have introduced several ways to enable/disable settings. We have used on/off, yes/no, 0/1, true/false. From now on we recommend to only use true/false so that we can unify our config files and make it more intuitive for all pgt-users.

We also removed all 2/3/4 words items and concatenate them now by _ #132. For example line width is now line_width. Thanks @LeilyR!

A few new features in this release:

Every config is now checked for syntax errors before anything is executed (@lldelisle)
Added the possibility to merge transcripts into one single gene representation when using gtf (@lldelisle)
Added the possibility to rasterize bedgraph plots (@lldelisle)
Added the possibility to use summary functions on bedgraphs (@lldelisle)
Generate an empty track if a requested region is not in the given track-files. Fixed #120 (@LeilyR)
Generate an empty track if a chromosome is missing in bedgraph files (@lldelisle)
Improved UCSC style for intron arrows (@lldelisle)
Flybase style now supports color_utr and height_uts (@lldelisle)
A new tracktype hlines was added (@lldelisle)
Allow to plot the arcs of the links with a color scale based on scores as proposed in #30 (@lldelisle)
Allow to plot rectangle on a heatmap for loops. Fixed #47 (@Phlya, @lldelisle)
A lot of HiC Matrix improvements (@lldelisle)
The alpha property can now be used nearly everywhere (@lldelisle)

Also checkout our updated readme).

Special thanks to @lldelisle & @LeilyR for such a feature-rich release.

Merry Xmas and a happy new year! Your PGT team!

3.1.2¶

change infos to warnings

3.1.1¶

small bug fix for summit usage (@lldelisle)
I added a vertical bar in the narrowPeaks when plotted as box to be able to see the summits (@lldelisle)

3.1¶

add the ability to control alpha of bedgraph tracks (thanks to @mikewolfe)
add GTF support (thanks to @lldelisle)
add support for various BED flavors (thanks to @lldelisle)
adopt codebase to lastest matplotlib changes (thanks to @lldelisle)
various new tests, code cleanups and smaller fixes all over

3.0¶

support for Python 2 has been removed.
regions smaller than 200000 can be plotted with a warning message for plotting TADs.
non existing chromosomes in some or all of the input files can be asked as regions to plot the tracks.

2.1¶

Support for epilogos #38
HiC improvements and migration to use HiCMatrix. Thanks to @joachimwolff for these changes.
Different coloring of negative and positive bigwig values is now possible. Thanks to @Phlya for this improvement.

2.0¶

This release makes it very easy to add new tracks! See the Readme for examples on how to do that.

Furthermore, this release:

Adds Hi-C tracks
Allows a track be plotted over the previous. There is not limit on the tracks that can be plotted on top of each other
Removed unnecessary empty space around the resulting image
Enlarged the README.md file with new examples and a mini-tutorial on how to add new tracks.
Added chromosome name and title to x-axis plot
Added option to plot links as ‘triangles’. This is useful to overlay links with Hi-C data to identify the contact pixel.
Added line width to bed track
Added ‘bed graph’ track
Added a track that can plot .narrowPeaks

1.0¶

This version added python3 compatibility to the code

Main changes in configuration files: Since v3.2:

there is no more space in the name of the parameters (line width become line_width)
all on/off, yes/no, 0/1 become true/false

Since v3.4:

gtf has its own file_type (file_type = gtf).

Warning in version 4.0 the old configuration files will not work anymore

FAQ¶

Why the scale of my Hi-C plot suddenly changed?
No output generated with version 3.5 installed with pip
My Hi-C plot looks like no correction was applied when using cool matrix

Why the scale of my Hi-C plot suddenly changed?¶

pyGenomeTracks is using HiCMatrix to read the matrix from h5 and cool format. From version 12 to version 13, a normalization step when reading cool file was removed. This normalization was mostly used when you were providing cool file from cooler balance.

If you want to keep the old scale you need to downgrade to HiCMatrix version 12 but version 13 also correct some bugs so we advice to change your max_value in your parameter file to adjust to the new scale.

No output generated with version 3.5 installed with pip ¶

If you used pyGenomeTracks version 3.5 and the last line you get is:

INFO:pygenometracks.tracksClass:initialize x. [xxxxx]

It is highly probable that BEDTools is not installed or not loaded in your environment.

My Hi-C plot looks like no correction was applied when using cool matrix ¶

pyGenomeTracks is using HiCMatrix to read the matrix from cool format. Unfortunately, a bug was introduced in version 14 ignoring the correction factors. This bug was fixed in version 15 so update HiCMatrix to last version should fix it.

Welcome to pyGenomeTracks’s documentation!¶

Standalone program and library to plot beautiful genome browser tracks¶

Table of content¶

Installation¶

Usage¶

Citation¶

All available tracks and types¶

bed¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

bedgraph¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

bedgraph_matrix¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

bigwig¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

domains¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

epilogos¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

fasta¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

gtf¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

hic_matrix¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

hic_matrix_square¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

hlines¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

links¶

Description¶

Parameters¶

Necessary:¶

Optional:¶

Output of make_tracks_file:¶

maf¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶

Output of `make_tracks_file`:¶