# igv.js notebook module
[](https://mybinder.org/v2/gh/igvteam/igv-notebook/main?filepath=examples) _**Jupyter Notebook**_
[](https://mybinder.org/v2/gh/igvteam/igv-notebook/main?urlpath=lab/tree/examples) _**JupyterLab**_
[](https://colab.research.google.com/drive/1-4P_r07Dq-WxaOVUevlbHvVhC9Y11FWC?usp=sharing) _**Google Colab**_
[](https://pypi.org/project/igv-notebook/)
============
igv-notebook is a Python package which wraps [igv.js](https://github.com/igvteam/igv.js) for embedding in an IPython notebook.
Both Jupyter and Google Colab platforms are supported.
### Related projects
Other projects enabling embedding igv.js in notebooks include
* [igv-jupyter](https://github.com/g2nb/igv-jupyter) (wrapper around igv-notebook that adds g2nb integration)
* [igv-jupyterlab](https://github.com/epi2me-labs/igv-jupyterlab)
* [ipyigv](https://github.com/QuantStack/ipyigv)
The main differences between igv-notebook and these other projects are:
* igv-notebook is a Python package, while the projects listed above are Jupyter extensions;
* igv-notebook works with Google Colab, in addition to Jupyter and JupyterLab; and
* igv-notebook supports loading data files from any location on the local or mounted file system when used with Jupyter Notebook or
Google Colab. **_NOTE_**: General local file paths do not work with JupyterLab, for JupyterLab the files must be in the JupyterLab file tree.
### Examples
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](https://github.com/igvteam/igv-notebook/archive/master.zip). Notebooks are available in the
"examples" directory.
## Usage
Typical usage proceeds as follow
1. Install igv-notebook
2. Initialize igv-notebook
3. Create igv "browser" object
4. Add tracks to browser
5. Navigate to loci of interest
**Installation**
```bash
pip install igv-notebook
```
**Initialization**
After installing, import and intialize igv_notebook as follows.
```python
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.
`
### Browser creation
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](https://github.com/igvteam/igv.js/wiki/Browser-Configuration-2.0).
**Example:**
```python
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)"
}
]
}
)
```
### URLS and paths
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:
* loading data in a Colab notebook from the local Colab file system or a mounted Google Drive; and
* loading data in Jupyter Notebook from the local file system that is outside the Jupyter file tree.
**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.
### Tracks
To load a track, pass a track configuration object to ```igv_browser.load_track()```. Track configuration
objects are described in the [igv.js documentation](https://github.com/igvteam/igv.js/wiki/Tracks-2.0), 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
```python
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
```python
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```.
```python
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.
```python
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.
```python
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"
})
```
### API
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 browser post-creation. These are described below
#### Load a track**
To load a track
```
igv_browser.load_track(track_config)
```
See example track configurations above. Also [igv.js wiki](https://github.com/igvteam/igv.js/wiki/Tracks-2.0)
Example:
```python
igv_browser.load_track(
{
"name": "Local BAM",
"url": "data/gstt1_sample.bam",
"indexURL": "data/gstt1_sample.bam.bai",
"format": "bam",
"type": "alignment"
})
```
#### Load regions of interest** (version >= 0.4.0)
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])
```
#### Navigation
Jump to a specific genomic range
```python
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](https://s3.amazonaws.com/igv.org.genomes/genomes.json). To customize the search, load a non-indexed annotation
track with the "searchable" property set to true (see [igv.js documentation](https://github.com/igvteam/igv.js/wiki/Annotation-Track#configuration-options)).
```python
igv_browser.search('myc')
```
Zoom in by a factor of 2
```python
igv_browser.zoom_in()
```
Zoom out by a factor of 2
```python
igv_browser.zoom_out()
```
### SVG conversion - Jupyter Notebook only
To convert the current igv view to a static SVG image
```python
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.**
#### Version
To verify the currently installed igv-notebook version (versions >= 0.3.1 only)
```python
igv_notebook.version()
```
To verify the current version of igv.js (igv-notebook versions >= 0.4.0 only)
```python
igv_notebook.igv_version()
```
## Development
requires python >= 3.9.1
### Development install
```bash
pip install -e .
```
### Build
```bash
python setup.py build
```
### Updating igv.js version
1. Edit VERSION_IGV - enter igv.js version with no line feed. Visit [npmjs.com](https://www.npmjs.com/package/igv) to find latest version
2. Run ```python updateIGV.py```
## Release Notes
**0.5.1**
* Update igv.js version to 2.15.7
**0.5.0**
* Add support for loading an igv session
* Generate links to igv-web
**0.4.5**
* Fix path/url problems when using JupyterLab
**0.4.4**
* Add missing requirements to setup.py
* Update igv.js version to 2.13.10
**0.4.3**
* Fix file-not-found error with version() and igv_version() functions
**0.4.1**
* Update documentation
**0.4.0**
* Add support for regions-of-interest
* Add ```igv_notebook.igv_version()``` function.
**0.3.1**
* Update ```browser.to_svg()``` function to support Python 3.6.
* Add ```igv_notebook.version()``` function.
**0.3.0**
* Add ```browser.to_svg()``` function to convert igv instance to static SVG image (Jupyter Notebook only).
Raw data
{
"_id": null,
"home_page": "https://github.com/igvteam/igv-notebook",
"name": "igv-notebook",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "igv,bioinformatics,genomics,visualization,ipython,jupyter",
"author": "Jim Robinson",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/b9/44/1aa19a667476e69bd25c091f29207f656e15aa837abfba788b789004bc6d/igv-notebook-0.5.1.tar.gz",
"platform": null,
"description": "# igv.js notebook module\n\n[](https://mybinder.org/v2/gh/igvteam/igv-notebook/main?filepath=examples) _**Jupyter Notebook**_\n\n[](https://mybinder.org/v2/gh/igvteam/igv-notebook/main?urlpath=lab/tree/examples) _**JupyterLab**_\n\n[](https://colab.research.google.com/drive/1-4P_r07Dq-WxaOVUevlbHvVhC9Y11FWC?usp=sharing) _**Google Colab**_\n\n[](https://pypi.org/project/igv-notebook/)\n\n============\n\nigv-notebook is a Python package which wraps [igv.js](https://github.com/igvteam/igv.js) for embedding in an IPython notebook.\nBoth Jupyter and Google Colab platforms are supported. \n\n### Related projects\n\nOther projects enabling embedding igv.js in notebooks include\n\n* [igv-jupyter](https://github.com/g2nb/igv-jupyter) (wrapper around igv-notebook that adds g2nb integration)\n* [igv-jupyterlab](https://github.com/epi2me-labs/igv-jupyterlab)\n* [ipyigv](https://github.com/QuantStack/ipyigv)\n\nThe main differences between igv-notebook and these other projects are: \n\n* igv-notebook is a Python package, while the projects listed above are Jupyter extensions;\n* igv-notebook works with Google Colab, in addition to Jupyter and JupyterLab; and \n* igv-notebook supports loading data files from any location on the local or mounted file system when used with Jupyter Notebook or \nGoogle Colab. **_NOTE_**: General local file paths do not work with JupyterLab, for JupyterLab the files must be in the JupyterLab file tree.\n\n\n### Examples\n\nExample notebooks are available in the github repository, and can be run from the Binder and Colab links above. \nTo download examples without cloning the repository use this \n[link](https://github.com/igvteam/igv-notebook/archive/master.zip). Notebooks are available in the\n\"examples\" directory.\n\n## Usage\n\nTypical usage proceeds as follow\n\n1. Install igv-notebook\n2. Initialize igv-notebook\n3. Create igv \"browser\" object\n4. Add tracks to browser \n5. Navigate to loci of interest\n\n**Installation**\n\n```bash\npip install igv-notebook\n```\n\n**Initialization**\n\nAfter installing, import and intialize igv_notebook as follows. \n\n```python\nimport igv_notebook\nigv_notebook.init()\n```\nFor a Jupyter notebook this should be done once per notebook. Colab notebooks display output in a sandboxed iFrame \nfor each cell, so initialization must be repeated for each cell in which igv-notebook is used.\n`\n\n### Browser creation\n\nThe Browser initializer takes a configuration dictionary which is converted to JSON and passed to the igv.js\ncreateBrowser function. The configuration options are described in the\n[igv.js documentation](https://github.com/igvteam/igv.js/wiki/Browser-Configuration-2.0).\n\n**Example:**\n\n```python\nimport igv_notebook\nigv_notebook.init()\nigv_browser= igv_notebook.Browser(\n {\n \"genome\": \"hg19\",\n \"locus\": \"chr22:24,376,166-24,376,456\",\n \"tracks\": [{\n \"name\": \"BAM\",\n \"url\": \"https://s3.amazonaws.com/igv.org.demo/gstt1_sample.bam\",\n \"indexURL\": \"https://s3.amazonaws.com/igv.org.demo/gstt1_sample.bam.bai\",\n \"format\": \"bam\",\n \"type\": \"alignment\"\n }],\n \"roi\": [\n {\n \"name\": \"ROI set 1\",\n \"url\": \"https://s3.amazonaws.com/igv.org.test/data/roi/roi_bed_1.bed\",\n \"indexed\": False,\n \"color\": \"rgba(94,255,1,0.25)\"\n }\n ]\n }\n)\n```\n\n### URLS and paths\n\nConfiguration objects for igv.js have properties to specify URLs to files for data and indexes. These properties are \nsupported in igv-notebook, however igv-notebook also provides equivalent ```path``` properties for specfiying paths to \nlocal files when used with Jupyter Notebook or Colab. (_**Note**_: The ```path``` properties cannot be used with JupyterLab, however local files can\nbe loaded by URL if they are in the Jupyter file tree). The ```path``` properties are useful for:\n\n* loading data in a Colab notebook from the local Colab file system or a mounted Google Drive; and\n* loading data in Jupyter Notebook from the local file system that is outside the Jupyter file tree. \n\n**URL and Path properties**\n| igv.js url property | igv-notebook path property |\n| --------- | ----------- |\n | url | path |\n | indexURL | indexPath |\n | fastaURL | fastaPath |\n | cytobandURL | cytobandPath |\n | aliasURL | aliasPath | \n\n\nFor Jupyter servers (Notebook and Lab), local files can be also be loaded via the url property if the file is in the Jupyter \nstartup directory tree. This will usually yield better performance than using ```path``` properties. URL paths \nthat begin with a \"/\" are relative to the Jupyter server startup directory, i.e. the directory from where you \nstarted Jupyter Notebook or JupyterLab. For Jupyter Notebook, URL paths without a leading slash can be used and are \nassumed to be relative to the notebook directory. See below for examples. You can also use the \"download url\" for \nthe file, obtainable through the JupyterLab UI, as the URL for igv.\n\n### Tracks\n\nTo load a track, pass a track configuration object to ```igv_browser.load_track()```. Track configuration\nobjects are described in the [igv.js documentation](https://github.com/igvteam/igv.js/wiki/Tracks-2.0), however\nsee the note on _URLs and paths_ above. The configuration object will be converted to JSON and passed to the igv.js browser instance.\n\nData for the track can be loaded by URL, file path, or passed directly as an array of JSON objects.\n\n\n**Examples:** \n\nLocal file - Jupyter. URL relative to the location of the notebook \n\n```python\nigv_browser.load_track(\n {\n \"name\": \"Local BAM\",\n \"url\": \"data/gstt1_sample.bam\",\n \"indexURL\": \"data/gstt1_sample.bam.bai\",\n \"format\": \"bam\",\n \"type\": \"alignment\"\n })\n\n```\n\nLocal file - Jupyter. URL relative to root of Jupyter file tree\n\n```python\nigv_browser.load_track(\n {\n \"name\": \"Local BAM\",\n \"url\": \"/examples/data/gstt1_sample.bam\",\n \"indexURL\": \"/examples/data/gstt1_sample.bam.bai\",\n \"format\": \"bam\",\n \"type\": \"alignment\"\n })\n\n```\n\nLocal file - Jupyter. Absolute file path, potentially outside the Jupyter file tree. Note the use of ```path``` and ```indexPath```.\n\n```python\nigv_browser.load_track(\n {\n \"name\": \"Local BAM\",\n \"path\": \"/any_path_you_like/data/gstt1_sample.bam\",\n \"indexPath\": \"/any_path_you_like/data/gstt1_sample.bam.bai\",\n \"format\": \"bam\",\n \"type\": \"alignment\"\n })\n\n```\n\n\n\nLocal file - Colab. In Colab files are loaded by file path.\n\n```python\nigv_browser.load_track(\n {\n \"name\": \"Local BAM\",\n \"path\": \"/content/igv-notebook/examples/data/gstt1_sample.bam\",\n \"indexPath\": \"/content/igv-notebook/examples/data/gstt1_sample.bam.bai\",\n \"format\": \"bam\",\n \"type\": \"alignment\"\n })\n```\n\nRemote file - Jupyter. \n\n```python\nigv_browser.load_track(\n {\n \"name\": \"BAM\",\n \"url\": \"https://s3.amazonaws.com/igv.org.demo/gstt1_sample.bam\",\n \"indexURL\": \"https://s3.amazonaws.com/igv.org.demo/gstt1_sample.bam.bai\",\n \"format\": \"bam\",\n \"type\": \"alignment\"\n })\n\n```\n\n\n### API\n\nMost 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 browser post-creation. These are described below\n\n#### Load a track**\n\nTo load a track\n\n```\nigv_browser.load_track(track_config)\n```\n\nSee example track configurations above. Also [igv.js wiki](https://github.com/igvteam/igv.js/wiki/Tracks-2.0)\n\n\nExample:\n\n```python\nigv_browser.load_track(\n {\n \"name\": \"Local BAM\",\n \"url\": \"data/gstt1_sample.bam\",\n \"indexURL\": \"data/gstt1_sample.bam.bai\",\n \"format\": \"bam\",\n \"type\": \"alignment\"\n })\n\n```\n\n#### Load regions of interest** (version >= 0.4.0)\n\nRegions-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.\n\n```\nigv_browser.loadROIs([roi_configs])\n```\n\n\n#### Navigation\n\nJump to a specific genomic range\n\n```python\nigv_browser.search('chr1:3000-4000')\n\n```\n\nJump to a specific gene. This uses the IGV search web service, which currently supports a limited number of \n[genomes](https://s3.amazonaws.com/igv.org.genomes/genomes.json). To customize the search, load a non-indexed annotation\ntrack with the \"searchable\" property set to true (see [igv.js documentation](https://github.com/igvteam/igv.js/wiki/Annotation-Track#configuration-options)).\n\n\n```python\nigv_browser.search('myc')\n\n```\n\nZoom in by a factor of 2\n\n```python\nigv_browser.zoom_in()\n```\n\nZoom out by a factor of 2\n\n```python\nigv_browser.zoom_out()\n```\n\n### SVG conversion - Jupyter Notebook only\n\nTo convert the current igv view to a static SVG image \n\n```python\nigv_browser.to_svg()\n```\n\nThis action can also be invoked with the \"To SVG\" button on the igv.js command bar. This is useful when converting \nthe notebook to formats such as HTML and PDF. \n\n\n**Note: This action is not reversible.**\n\n\n#### Version\n\nTo verify the currently installed igv-notebook version (versions >= 0.3.1 only)\n\n```python\nigv_notebook.version()\n```\n\nTo verify the current version of igv.js (igv-notebook versions >= 0.4.0 only)\n\n```python\nigv_notebook.igv_version()\n```\n\n## Development \n\nrequires python >= 3.9.1\n\n### Development install\n\n```bash\npip install -e .\n```\n\n### Build \n```bash\npython setup.py build \n```\n\n### Updating igv.js version\n\n1. Edit VERSION_IGV - enter igv.js version with no line feed. Visit [npmjs.com](https://www.npmjs.com/package/igv) to find latest version\n2. Run ```python updateIGV.py``` \n\n## Release Notes\n\n**0.5.1**\n\n* Update igv.js version to 2.15.7\n\n**0.5.0**\n\n* Add support for loading an igv session\n* Generate links to igv-web\n\n**0.4.5**\n\n* Fix path/url problems when using JupyterLab\n\n**0.4.4**\n\n* Add missing requirements to setup.py\n* Update igv.js version to 2.13.10\n\n**0.4.3**\n\n* Fix file-not-found error with version() and igv_version() functions\n\n**0.4.1**\n\n* Update documentation\n\n**0.4.0**\n\n* Add support for regions-of-interest\n* Add ```igv_notebook.igv_version()``` function.\n\n**0.3.1**\n\n* Update ```browser.to_svg()``` function to support Python 3.6.\n* Add ```igv_notebook.version()``` function.\n\n**0.3.0**\n\n* Add ```browser.to_svg()``` function to convert igv instance to static SVG image (Jupyter Notebook only).\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Package for embedding the igv.js genome visualization in IPython notebooks",
"version": "0.5.1",
"project_urls": {
"Homepage": "https://github.com/igvteam/igv-notebook"
},
"split_keywords": [
"igv",
"bioinformatics",
"genomics",
"visualization",
"ipython",
"jupyter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "052af9b4d2c30e635c8ff2fa6c70df2b46334304d2cd85966464f975cc572424",
"md5": "e03fb0694e87a72389c8727594b83a42",
"sha256": "16682c675f5f77321b11a9d4b84b9caa27eb92f9489d3ee77b04ecdd6e7b3e2e"
},
"downloads": -1,
"filename": "igv_notebook-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e03fb0694e87a72389c8727594b83a42",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 302438,
"upload_time": "2023-05-08T02:51:23",
"upload_time_iso_8601": "2023-05-08T02:51:23.472858Z",
"url": "https://files.pythonhosted.org/packages/05/2a/f9b4d2c30e635c8ff2fa6c70df2b46334304d2cd85966464f975cc572424/igv_notebook-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b9441aa19a667476e69bd25c091f29207f656e15aa837abfba788b789004bc6d",
"md5": "3d75ee24af3bbdd75b334e86bb112c23",
"sha256": "d3f93e8e965becd9832a7bad00bcc0acb8d55fad1ea7857011b8c11892c7a5be"
},
"downloads": -1,
"filename": "igv-notebook-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "3d75ee24af3bbdd75b334e86bb112c23",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 304643,
"upload_time": "2023-05-08T02:51:25",
"upload_time_iso_8601": "2023-05-08T02:51:25.707936Z",
"url": "https://files.pythonhosted.org/packages/b9/44/1aa19a667476e69bd25c091f29207f656e15aa837abfba788b789004bc6d/igv-notebook-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-08 02:51:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "igvteam",
"github_project": "igv-notebook",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "igv-notebook"
}
JSON
