Repository files navigation

Epigenomic data expresses a rich body of diverse patterns that help to identify regulatory elements like promoter, enhancers, etc. But finding these patterns reliably genome wide is challenging. Peax is a tool for interactive visual pattern search and exploration of epigenomic patterns based on unsupervised representation learning with convolutional autoencoders. The visual search is driven by manually labeled genomic regions for actively learning a classifier to reflect your notion of interestingness.

Citation: Lekschas et al.,Peax: Interactive Visual Pattern Search in Sequential Data Using Unsupervised Deep Representation Learning,Computer Graphics Forum, 2020, doi:10.1111/cgf.13971.

More Details:peax.lekschas.de

Requirements:

• Conda >= 4.8

Install:

git clone https://github.com/Novartis/peax&&cd peaxmake install

Do not fear,make install is just a convenience function for setting up conda and installing npm packages.

Notes:

• If you're a macOS user you might need tobrew installlibpng andopenssl for thepybbi package (seehere) andxz for pysam (if you see an error related tolzma.h).

Peax consists of three main parts:

1. A server application for serving genomic and autoencoded data on the web. [/server].
2. A user interface for exploring, visualizing, and interactively labeling genomic regions. [/ui].
3. A set of examples showing how to configure Peax and build your own. [/examples]

We provide 6 autoencoders trained on 3 kb, 12 kb, and 120 kb window sizes (with 25,100, and 1000 bp binning) on DNase-seq and histone mark ChIP-seq data (H3K4me1, H3K4me3, H3K27ac, H3K9ac, H3K27me3, H3K9me3, and H3K36me).

You can find detailed descriptions of the autoencoders atzenodo.org/record/2609763. When you follow theQuick Start instructions, you will automatically download the related autoencoders.

Peax comes with6 autoencoders for DNase-seq and histone markChIP-seq data and several example configurations for which we provideconvenience scripts to get you started as quickly as possible.

For instance, run one of the following commands to start Peax with a DNase-seqtrack for 3 kb, 12 kb, and 120 kb genomic windows.

Note: The first time Peax is started it will precompute the datasets forexploration. This can take a few minutes depending on your hardware. Also, these demoswill only prepare the above mentioned chromosomes, so don't try to search for patternson another chromosome. It won't work! For your own data you can freely configure thisof course.

The scripts will download test ENCODE tracks and use the matchingconfiguration to start the server. More examples are described in/examples.

In the following we describe how you can configure Peax for your own data.

Next, you need to configure Peax with your data to tell it which tracks you want to visualize in HiGlass and which of those tracks are encodable using an (auto)encoder.

The fastest way to get started is to copy the example config:

cp config.json.sample config.json

The config file has 10 top level properties:

The main parts to adjust areencoders anddatasets.encoders is a list of(auto)encoder definitions for different datatypes.T here are two ways toconfigure an (auto)encoder: (a) point to a pre-defined autoencoder or (b)configure from scratch.

Assuming you want to use predefined encoders all you have to do is to specify the path to the encoder configuration

Example:

{"encoders":"examples/encoders.json"}

The encoder configuration file is a dictionary with the top level keys actingas the identifier. Given the example from above the file could look like this:

{"histone-mark-chip-seq-3kb": {},"dnase-seq-3kb": {}}

See[encoders.json](encoders.json) for an example. The specific definition if anautoencoder is the same as described in the following.

To configure an autoencoder from scratch you need to provide a dictionary withthe following required format:

Note that if you have specified anautoencoder you do not need to provideseparateencoder anddecoder models.

Example:

{"encoder":"path/to/my-12kb-chip-seq-encoder.h5","decoder":"path/to/my-12kb-chip-seq-decoder.h5","content_type":"histone-mark-chip-seq","window_size":12000,"resolution":100,"channels":1,"input_dim":3,"latent_dim":12}

Datasets require the following format:

Example:

{"filepath":"data/chip-seq/my-fancy-gm12878-chip-seq-h3k27ac-fc-signal.bigWig","content_type":"histone-mark-chip-seq","uuid":"my-fancy-gm12878-chip-seq-h3k27c-track","name":"My Fancy GM12878 ChIP-Seq H3k27c Track"}

First, start the Peax server to serve your data.

Note: The first time you run Peax on a new dataset all the data will be prepared!Depending on your machine this can take some time. If you want to track the progressactivate the debugging mode using-d.

python start.py

Now go tohttp://localhost:5000.

Tostart.py script supports the following options:

usage: start.py [-h] [-c CONFIG] [--clear] [--clear-cache]                [--clear-cache-at-exit] [--clear-db] [-d] [--host HOST]                [--port PORT] [-v]Peak Explorer CLIoptional arguments:  -h, --help            show thishelp message andexit  -c CONFIG, --config CONFIG                        path to your JSON config file  -b BASE_DATA_DIR, --base-data-dir BASE_DATA_DIR                        base directory which the config file refers to  --clear               clears the cache and database on startup  --clear-cache         clears the cache on startup  --clear-cache-at-exit                        clear the cache on shutdown  --clear-db            clears the database on startup  -d, --debug           turn on debug mode  --host HOST           customize the hostname  --port PORT           customize the port  -v, --verbose         turn verbose logging on

Thehostname defaults tolocalhost and theport of the backend server defaultsto5000.

In order to speed up subsequend user interaction, Peax initially prepapres allthe data and caches that data under/cache. You can always remove thisdirectory manually or clear the cache on startup or at exist using the--clearas specified above.

Handy commands to keep in mind:

• make install installs the conda environment and npm packages and builds the UI
• make update updates the conda environment and npm packages and rebuilds the UI
• make build builds the UI
• python start.py starts the Flask server application for serving data
• [/ui]:npm install installs and updates all the needed packages for the frontend
• [/ui]:npm build creates the production built of the frontend
• [/ui]:npm start starts a dev server with hot reloading for the frontend

To start developing on the server and the ui in parallel, first start the backend serverapplication using./start.py and then start the frontend server application from./ui usingnpm start. Both server's watch the source code, so whenever you makechanges to the source code the servers will reload.

There are 2 types of configuration files. Thebackend server configurationdefines the datasets to explore and is described in detailabove.

Additionally, the frontend application can be configured to talk to a different backendserver and port if needed. Get started by copying the example configuration:

cd ui&& cp config.json.sample config.json

By default theserver is dynamically set to the hostname of the server running thefrontend application. I.e., it is assumed that the backend server application isrunning on the same host as the frontend application. Theport of the serverdefaults to5000.

For development the backend and frontend applications run as seperate serverapplications.

# Backend server./start.py --debug --config path/to/your/config.json# Frontend servercd ui&& npm start