/# igv.js notebook module
Jupyter Notebook
JupyterLab
Google Colab
============
igv-notebook is a Python package which wraps igv.js for embedding in an IPython notebook. Both Jupyter and Google Colab platforms are supported.
Other projects enabling embedding igv.js in notebooks include
The main differences between igv-notebook and these other projects are:
Example notebooks are available in the github repository, and can be run from the Binder and Colab links above. To download examples without cloning the repository use this link. Notebooks are available in the "examples" directory.
Typical usage proceeds as follow
Installation
pip install igv-notebook
Initialization
After installing, import and intialize igv_notebook as follows.
import igv_notebook
igv_notebook.init()
For a Jupyter notebook this should be done once per notebook. Colab notebooks display output in a sandboxed iFrame for each cell, so initialization must be repeated for each cell in which igv-notebook is used. `
The Browser initializer takes a configuration dictionary which is converted to JSON and passed to the igv.js createBrowser function. The configuration options are described in the igv.js documentation.
Example:
import igv_notebook
igv_notebook.init()
igv_browser= igv_notebook.Browser(
{
"genome": "hg19",
"locus": "chr22:24,376,166-24,376,456",
"tracks": [{
"name": "BAM",
"url": "https://s3.amazonaws.com/igv.org.demo/gstt1_sample.bam",
"indexURL": "https://s3.amazonaws.com/igv.org.demo/gstt1_sample.bam.bai",
"format": "bam",
"type": "alignment"
}],
"roi": [
{
"name": "ROI set 1",
"url": "https://s3.amazonaws.com/igv.org.test/data/roi/roi_bed_1.bed",
"indexed": False,
"color": "rgba(94,255,1,0.25)"
}
]
}
)
Configuration objects for igv.js have properties to specify URLs to files for data and indexes. These properties are
supported in igv-notebook, however igv-notebook also provides equivalent path properties for specfiying paths to
local files when used with Jupyter Notebook or Colab. (Note: The path properties cannot be used with JupyterLab, however local files can
be loaded by URL if they are in the Jupyter file tree). The path properties are useful for:
URL and Path properties
| igv.js url property | igv-notebook path property |
|---|---|
| url | path |
| indexURL | indexPath |
| fastaURL | fastaPath |
| cytobandURL | cytobandPath |
| aliasURL | aliasPath |
For Jupyter servers (Notebook and Lab), local files can be also be loaded via the url property if the file is in the Jupyter
startup directory tree. This will usually yield better performance than using path properties. URL paths
that begin with a "/" are relative to the Jupyter server startup directory, i.e. the directory from where you
started Jupyter Notebook or JupyterLab. For Jupyter Notebook, URL paths without a leading slash can be used and are
assumed to be relative to the notebook directory. See below for examples. You can also use the "download url" for
the file, obtainable through the JupyterLab UI, as the URL for igv.
To load a track, pass a track configuration object to igv_browser.load_track(). Track configuration
objects are described in the igv.js documentation, however
see the note on URLs and paths above. 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, file path, or passed directly as an array of JSON objects.
Examples:
Local file - Jupyter. URL relative to the location of the notebook
igv_browser.load_track(
{
"name": "Local BAM",
"url": "data/gstt1_sample.bam",
"indexURL": "data/gstt1_sample.bam.bai",
"format": "bam",
"type": "alignment"
})
Local file - Jupyter. URL relative to root of Jupyter file tree
igv_browser.load_track(
{
"name": "Local BAM",
"url": "/examples/data/gstt1_sample.bam",
"indexURL": "/examples/data/gstt1_sample.bam.bai",
"format": "bam",
"type": "alignment"
})
Local file - Jupyter. Absolute file path, potentially outside the Jupyter file tree. Note the use of path and indexPath.
igv_browser.load_track(
{
"name": "Local BAM",
"path": "/any_path_you_like/data/gstt1_sample.bam",
"indexPath": "/any_path_you_like/data/gstt1_sample.bam.bai",
"format": "bam",
"type": "alignment"
})
Local file - Colab. In Colab files are loaded by file path.
igv_browser.load_track(
{
"name": "Local BAM",
"path": "/content/igv-notebook/examples/data/gstt1_sample.bam",
"indexPath": "/content/igv-notebook/examples/data/gstt1_sample.bam.bai",
"format": "bam",
"type": "alignment"
})
Remote file - Jupyter.
igv_browser.load_track(
{
"name": "BAM",
"url": "https://s3.amazonaws.com/igv.org.demo/gstt1_sample.bam",
"indexURL": "https://s3.amazonaws.com/igv.org.demo/gstt1_sample.bam.bai",
"format": "bam",
"type": "alignment"
})
Most IGV options can be specified in the initial browser configuration, including specifying genome, locus, tracks, and regions-of-interest. Additional methods are provided to perform actions on the IGV browser post-creation. These are described below
To load a track
igv_browser.load_track(track_config)
See example track configurations above. Also igv.js wiki
Example:
igv_browser.load_track(
{
"name": "Local BAM",
"url": "data/gstt1_sample.bam",
"indexURL": "data/gstt1_sample.bam.bai",
"format": "bam",
"type": "alignment"
})
Regions-of-interest are overlays marking genomic ranges of interest. They are defined by track configurations, often backed by a "bed" file, and usually with a translucent color. These can be specified at browser creation with the "roi" property, or loaded afterwards with the ```loadROIs`` function. This function takes an array of track configuration objects. See the notebook examples/ROI.ipynb for example usage.
igv_browser.loadROIs([roi_configs])
Jump to a specific genomic range
igv_browser.search('chr1:3000-4000')
Jump to a specific gene. This uses the IGV search web service, which currently supports a limited number of genomes. To extend or customize the search, load a non-indexed annotation track with the "searchable" property set to true (see igv.js documentation).
igv_browser.search('myc')
Zoom in by a factor of 2
igv_browser.zoom_in()
Zoom out by a factor of 2
igv_browser.zoom_out()
To convert the current igv view to a static SVG image
igv_browser.to_svg()
This action can also be invoked with the "To SVG" button on the igv.js command bar. This is useful when converting the notebook to formats such as HTML and PDF. Note: This action is not reversible.
To verify the currently installed igv-notebook version (versions >= 0.3.1 only)
igv_notebook.version()
To verify the current version of igv.js (igv-notebook versions >= 0.4.0 only)
igv_notebook.igv_version()
requires python >= 3.9.1
pip install -e .
python setup.py build
python updateIGV.py0.5.2
0.5.1
0.5.0
0.4.5
0.4.4
0.4.3
0.4.1
0.4.0
igv_notebook.igv_version() function.0.3.1
browser.to_svg() function to support Python 3.6.igv_notebook.version() function.0.3.0
browser.to_svg() function to convert igv instance to static SVG image (Jupyter Notebook only).FAQs
Package for embedding the igv.js genome visualization in IPython notebooks
We found that igv-notebook demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.