igv-jupyter is an extension for Jupyter Notebook which wraps igv.js. With this extension you can render igv.js in a cell and call its API from the notebook. The extension exposes a python API that mimics the igv.js Browser creation and control APIs. Dictionaries are used for browser and track configuration objects. Track data can be loaded from local or remote URLs, or supplied directly as lists of objects.
Requirements:
- python >= 3.6.4
- jupyterlab >= 3.0
pip install igv-jupyter
# To install to configuration in your home directory
jupyter serverextension enable --py igv
jupyter labextension enable --py igv
jupyter nbextension install --py igv
jupyter nbextension enable --py igv
# If using a virtual environment
jupyter serverextension enable --py igv --sys-prefix
jupyter labextension enable --py igv --sys-prefix
jupyter nbextension install --py igv --sys-prefix
jupyter nbextension enable --py igv --sys-prefix
Example notebooks are available in the github repository. To download without cloning the repository use this link. Notebooks are available in the "examples" directory.
To insert an IGV instance into a cell:
(1) create an igv.Browser object,and (2) call showBrowser on the instance.
Example:
import igv
b = igv.Browser({"genome": "hg19"})
The igv.Browser initializer takes a configuration object which is converted to JSON and passed to the igv.js createBrowser function. The configuration object is described in the igv.js documentation.
To instantiate the client side IGV instance in a cell call show()
b.show()
To load a track pass a track configuration object to load_track(). Track configuration objects are described in the igv.js documentation. The configuration object will be converted to JSON and passed to the igv.js browser instance.
Data for the track can be loaded by URL or passed directly as an array of JSON objects.
b.load_track(
{
"name": "Segmented CN",
"url": "https://data.broadinstitute.org/igvdata/test/igv-web/segmented_data_080520.seg.gz",
"format": "seg",
"indexed": False
})
b.load_track(
{
"name": "Local VCF",
"url": "data/example.vcf",
"format": "vcf",
"type": "variant",
"indexed": False
})
Features can also be passed directly to tracks.
b.load_track({
"name": "Copy number",
"type": "seg",
"displayMode": "EXPANDED",
"height": 100,
"isLog": True,
"features": [
{
"chr": "chr20",
"start": 1233820,
"end": 1235000,
"value": 0.8239,
"sample": "TCGA-OR-A5J2-01"
},
{
"chr": "chr20",
"start": 1234500,
"end": 1235180,
"value": -0.8391,
"sample": "TCGA-OR-A5J3-01"
}
]
})
Zoom in by a factor of 2
b.zoom_in()
Zoom out by a factor of 2
b.zoom_out()
Jump to a specific locus
b.search('chr1:3000-4000')
Jump to a specific gene. This uses the IGV search web service, which currently supports a limited number of genomes: hg38, hg19, and mm10. To configure a custom search service see the igv.js documentation
b.search('myc')
Saving the current IGV view as an SVG image requires two calls.
b.get_svg()
b.display_svg()
Note: This is an experimental feature.
def locuschange(data):
b.locus = data
b.on("locuschange", locuschange)
b.zoom_in()
return b.locus
To build and install from source:
python setup.py build
pip install -e .
jupyter labextension develop . --overwrite
jupyter nbextension install --py igv --symlink
jupyter nbextension enable --py igv
After source changes, the extension can be rebuilt using:
jupyter labextension build .
Creating a conda environment
conda create -n test python=3.7.1
conda activate test
conda install pip
conda install jupyter