dash_bio.Pileup Examples and Reference

Pileup

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

Select the genome to display below.

import dash_bio as dashbio
from dash import Dash, dcc, html, Input, Output, callback

app = Dash()

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.
@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(debug=True)

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 urllib.request as urlreq



source_data = urlreq.urlopen(
    'https://git.io/pileup-synth4.json'
).read().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 urllib.request as urlreq



source_data = urlreq.urlopen(
    'https://git.io/pileup-synth4.json'
).read().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 urllib.request as urlreq


source_data = urlreq.urlopen(
    'https://git.io/pileup-ga4gh.json'
).read().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.

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

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:

contig (string; optional):
Name of contig to display. (ie. chr17).
start (number; optional):
Start location to display.
stop (number; optional):
Stop location to display.

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

reference is a dict with keys:

label (string; optional):
Label to display by reference.
url (string; optional):
Url of 2bit file.
https://genome.ucsc.edu/goldenPath/help/twoBit.html.

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:

label (string; optional):
Label to display by track.
source (a value equal to: ‘bam’, ‘alignmentJson’, ‘variantJson’, ‘featureJson’, ‘idiogramJson’, ‘cytoBand’, ‘vcf’, ‘twoBit’, ‘bigBed’, ‘GAReadAlignment’, ‘GAVariant’, ‘GAFeature’ or ‘GAGene’; optional):
Data source to visualize. Must be one of (bam, vcf,
alignmentJson, variantJson, featureJson, idiogramJson, cytoBand,
vcf, twoBit, bigBed, GAReadAlignment, GAVariant, GAFeature,
GAGene). For more info on data source types supported
by pileup.js see
https://github.com/hammerlab/pileup.js/blob/master/src/main/pileup.js.
sourceOptions (optional):
Options that define data source. Options depend on the
source selected.
viz (a value equal to: ‘coverage’, ‘genome’, ‘genes’, ‘features’, ‘idiogram’, ‘location’, ‘scale’, ‘variants’, ‘genotypes’ or ‘pileup’; optional):
Name of visualization. Must be one of (coverage,
genome, genes, features, idiogram, location, scale,
variants, genotypes, or pileup). For more info on visualization
types supported by pileup.js see
https://github.com/akmorrow13/pileup.js/blob/master/src/main/pileup.js.
vizOptions (optional):
Options that define viz details. Options depend on the
viz type selected.

loading_state (dict; optional):
Object that holds the loading state object coming from dash-renderer.

loading_state is a dict with keys:

component_name (string; optional):
Holds the name of the component that is loading.
is_loading (boolean; optional):
Determines if the component is loading or not.
prop_name (string; optional):
Holds which property is loading.