dash_bio.Pileup Examples and Reference

see Pileup in action.

Graph

An example of a default Pileup component without any extra properties.

import dash
import dash_bio as dashbio
import dash_core_components as dcc
import dash_html_components as html
from dash.dependencies import Input, Output

app = dash.Dash(__name__)

HOSTED_GENOME_DICT = [
    {'value': 'mm10', 'label': 'Mouse (GRCm38/mm10)'},
    {'value': 'hg19', 'label': 'Human (GRCh37/hg19)'}
]

HOSTED_GENOME_TRACKS = {
    'mm10': {
        'range': {
            'contig': 'chr17',
            'start': 7512284,
            'stop': 7512644
        },
        'reference': {
            'label': 'mm10',
            'url': 'https://hgdownload.cse.ucsc.edu/goldenPath/mm10/bigZips/mm10.2bit'
        },
        'tracks': [
            {
                'viz': 'scale',
                'label': 'Scale'
            },
            {
                'viz': 'location',
                'label': 'Location'
            }]
    },
    'hg19': {
        'range': {
            'contig': 'chr17',
            'start': 7512284,
            'stop': 7512644
        },
        'reference': {
            'label': 'hg19',
            'url': 'https://hgdownload.cse.ucsc.edu/goldenPath/hg19/bigZips/hg19.2bit'
        },
        'tracks': [{
            'viz': 'scale',
            'label': 'Scale'
        },
            {
                'viz': 'location',
                'label': 'Location'
            },
            {
                'viz': 'genes',
                'label': 'genes',
                'source': 'bigBed',
                'sourceOptions': {'url': 'https://www.biodalliance.org/datasets/ensGene.bb'}
            }]
    }
}

app.layout = html.Div([
    dcc.Loading(id='default-pileup-container'),
    html.Hr(),
    html.P('Select the genome to display below.'),
    dcc.Dropdown(
        id='default-pileup-genome-select',
        options=HOSTED_GENOME_DICT,
        value='hg19'
    )
])


# Return the Pileup component with the selected genome.
@app.callback(
    Output('default-pileup-container', 'children'),
    Input('default-pileup-genome-select', 'value')
)
def return_pileup(genome):
    if HOSTED_GENOME_TRACKS.get(genome) is None:
        raise Exception("No tracks for genome %s" % genome)

    return (
        html.Div([
            dashbio.Pileup(
                id='pileup-default',
                range=HOSTED_GENOME_TRACKS[genome]['range'],
                reference=HOSTED_GENOME_TRACKS[genome]['reference'],
                tracks=HOSTED_GENOME_TRACKS[genome]['tracks']
            )
        ])
    )


if __name__ == '__main__':
    app.run_server(debug=True)

Select the genome to display below.

Customization

Genome

Select a genome by specifying a reference label (e.g. “hg19”, “mm10”), and a url pointing to a TwoBit data file. TwoBit files can be found in the UCSC Genome Browser, or can be remotely staged elsewhere.The Pileup component also requires a genomic range object that specifies the contig, start, and end position to be visualized.

import dash_bio as dashbio

dashbio.Pileup(
    id='pileup-genome',
    range={
        'contig': 'chr8',
        'start': 65869361,
        'stop': 65869511
    },
    reference={
        'label': 'mm10',
        'url': 'https://hgdownload.cse.ucsc.edu/goldenPath/mm10/bigZips/mm10.2bit'
    }
)

Tracks

Add tracks with the tracks property of a Pileup component to view additional data types and sources. Tracks can display genomic coverage, features, variants, and reads.
Each track in a Pileup component requires a visualization type (viz) and a data source (source).

Pileup Data Sources

Each data source has its own set of required keys. Below, we enumerate the available data source types:
- bam : requires 'sourceOptions': {'url':, URL.bam 'indexUrl': URL.bam.bai}
- alignmentJson : requires 'sourceOptions': {GA4GH_JSON_STRING}
- variantJson : requires 'sourceOptions': {GA4GH_JSON_STRING}
- featureJson : requires 'sourceOptions': {GA4GH_JSON_STRING}
- idiogramJson : requires 'sourceOptions': {JSON_STRING}
- vcf : requires 'sourceOptions': {'url':, URL.vcf }
- bigBed : requires 'sourceOptions': {'url':, URL.bb }

Pileup Visualization Types

The Pileup component supports the following visualizations:
- coverage : requires alignmentJson, bam, or featureJson source
- genes : requires bigBed source
- features : requires featureJson or bigBed source
- variants : requires a vcf or variantJson data source
- genotypes : requires a vcf or variantJson data source
- pileup : requires a bam or alignmentJson data source
- idiogram : requires idiogramJson data source
- location : does not require a data source
- scale : does not require a data source

Multiple tracks can be added to a Pileup component by passing in a list of dicts, each of which corresponds to an individual track.

import dash_bio as dashbio
import six.moves.urllib.request as urlreq
from dash_docs.utils import DatasetLoader

source_data = DatasetLoader().load(
    'https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/pileup.synth4.tumor.chr1.4930000-4950000.json').decode(
    'utf-8')

dashbio.Pileup(
    id='tracks-pileup',
    range={
        'contig': 'chr1',
        'start': 4930382,
        'stop': 4946898
    },
    reference={
        'label': 'hg19',
        'url': 'https://hgdownload.cse.ucsc.edu/goldenPath/hg19/bigZips/hg19.2bit'
    },
    tracks=[
        {
            'viz': 'coverage',
            'label': 'alignments',
            'source': 'alignmentJson',
            'sourceOptions': source_data
        },
        {
            'viz': 'pileup',
            'label': 'alignments',
            'source': 'alignmentJson',
            'sourceOptions': source_data
        }
    ]
)

Visualization Options

Depending on the visualization track, you can modify and set various visualization options. In this example, we set the option to view alignments as pairs by setting the value for viewAsPairs to True. Other vizOptions are as follows for each of the following track types:
- coverage and features : Set the track color by specifying a dict of RGB colors: { 'color': {'rgb': {'r': int, 'g': int, 'b': int, 'a': int}}}
- pileup : Included vizOptions are viewAsPairs: bool, colorByInsert: bool, colorByStrand: bool,hideAlignments: bool
- features : Collapse overlapping features by specifying {'collapse': True}

import dash_bio as dashbio
import six.moves.urllib.request as urlreq
from dash_docs.utils import DatasetLoader

source_data = DatasetLoader().load(
    'https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/pileup.synth4.tumor.chr1.4930000-4950000.json').decode(
    'utf-8')

dashbio.Pileup(
    id='viz-pileup',
    range={
        'contig': 'chr1',
        'start': 4930382,
        'stop': 4946898
    },
    reference={
        'label': 'hg19',
        'url': 'https://hgdownload.cse.ucsc.edu/goldenPath/hg19/bigZips/hg19.2bit'
    },
    tracks=[
        {
            'viz': 'pileup',
            'vizOptions': {'viewAsPairs': True},
            'label': 'alignments',
            'source': 'alignmentJson',
            'sourceOptions': source_data
        }
    ]
)

Features

The features visualization allows you to view any features that have a genomic location (a contig, start, and stop). You can specify vizOptions for features, including the track color whether to collapse overlapping features.

import dash_bio as dashbio
import six.moves.urllib.request as urlreq
from dash_docs.utils import DatasetLoader

source_data = DatasetLoader().load(
    'https://raw.githubusercontent.com/plotly/dash-bio-docs-files/master/pileup.features.ga4gh.chr1.120000-125000.chr17.7500000-7515100.json').decode(
    'utf-8')

dashbio.Pileup(
    id='features-pileup',
    range={
        'contig': 'chr1',
        'start': 120000,
        'stop': 125000
    },
    reference={
        'label': 'hg19',
        'url': 'https://hgdownload.cse.ucsc.edu/goldenPath/hg19/bigZips/hg19.2bit'
    },
    tracks=[
        {
            'viz': 'features',
            'vizOptions': {'color': {'rgb': {'r': 251, 'g': 62, 'b': 22, 'a': 1}},
                           'collapse': False},
            'label': 'features',
            'source': 'featureJson',
            'sourceOptions': source_data
        }
    ]
)

Pileup Properties

Access this documentation in your Python terminal with:
```python

help(dash_bio.Pileup)
```

Our recommended IDE for writing Dash apps is Dash Enterprise’s
Data Science Workspaces,
which has typeahead support for Dash Component Properties.
Find out if your company is using
Dash Enterprise
.

id (string; optional):
The ID of this component, used to identify dash components in
callbacks. The ID needs to be unique across all of the components in
an app.

className (string; optional):
className of the component div.

range (dict; optional):
Object defining genomic location. Of the format: {contig: ‘chr17’,
start: 7512384, stop: 7512544}.

range is a dict with keys:

reference (dict; optional):
Object defining genomic reference.

reference is a dict with keys:

style (dict; optional):
Generic style overrides on the plot div.

tracks (list of dicts; optional):
Array of configuration objects defining tracks initially displayed
when app launches. See
https://github.com/hammerlab/pileup.js#usage.

tracks is a list of dicts with keys:

Example Data