Skip to main content

Package for embedding the juicebox.js hic visualization in IPython notebooks

Project description

juicebox notebook module

Binder Jupyter Notebook

Binder JupyterLab

Open In Colab


juicebox-notebook is an module for Jupyter and Colab notesbooks which exposes a python API that enables creation and interaction with a juicebox.js instance in a cell.

Examples

Example notebooks are available in the github repository in the "examples" directory of the github repository.

Installation

Requirements:

  • python >= 3.6.4
  • jupyter >= 4.2.0
pip install juicebox-notebook

Initialization

After installing import and intialize igv_notebook as follows.

import juicebox_notebook
juicebox_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 these steps must be repeated for each cell in which juicebox-notebook is used.

Browser creation

The juicebox_notebook.Browser constructor takes a configuration object which is converted to JSON and passed to the juicebox.js createBrowser function. The configuration object is described in the juicebox.js documentation. To open an empty "browser" to dynamically load maps pass an empty dictionary.

Example:

import juicebox_notebook
juicebox_notebook.init()
b = juicebox_notebook.Browser(
    {
        "name": "GM12878",
        "url": "https://www.encodeproject.org/files/ENCFF179HVU/@@download/ENCFF179HVU.hic",
        "tracks": [
            {
                "url": "https://www.encodeproject.org/files/ENCFF000ARJ/@@download/ENCFF000ARJ.bigWig",
                "name": "CTCF",
                "color": "rgb(22, 129, 198)"
            }
        ]
    }

)

Dynamically loading maps and tracks

Typically maps and tracks are loaded in the initial juicebox.Browser creation. However its also possible to load them post creation using the b.load_map(config and b.load_track functions.

Maps

To load a map into an existing browser pass a hic file configuration object to the load_map function

import juicebox_notebook
juicebox_notebook.init()
b = juicebox_notebook.Browser({})
b.load_map(
    {
         "url": "https://hicfiles.s3.amazonaws.com/hiseq/gm12878/in-situ/primary.hic"
    }
)

Tracks

To load a track pass a track configuration object to load_track. Track configuration objects are described in the juicebox.js documentation. The configuration object will be converted to JSON and passed to the juicebox.js browser instance.

import juicebox_notebook
juicebox_notebook.init()
b = juicebox_notebook.Browser({
        "name": "GM12878",
        "url": "https://www.encodeproject.org/files/ENCFF179HVU/@@download/ENCFF179HVU.hic"
    }
)

b.load_track({
    "url": "https://www.encodeproject.org/files/ENCFF000ARJ/@@download/ENCFF000ARJ.bigWig",
    "name": "CTCF",
    "color": "#ff8802"
  }
)

URLS and paths

Configuration objects for juicebox.js maps (.hic files) and tracks have properties to specify URLs to files for data and indexes. These properties are supported in juicebox-notebook, however juicebox-notebook also provides equivalent path properties for specfiying paths to local files when used with Jupyter Notebook or Colab.
The path properties are useful for

  1. Loading data in a Colab notebook from the local Colab file system or a mounted Google Drive
  2. Loading data in Jupyter Notebook from the local file system that is outside the Jupyter file tree.

URL and Path properties

juicebox.js url property juicebox-notebook path property notes
url path
indexURL indexPath Used in some track configurations. See igv.js

(Note: The path properties cannot be used with JupyterLab, however local files can be loaded by URL).

For Jupyter servers (Notebook and Lab) local files can be also be loaded via the url property if the file is in Jupyter directory tree. This will usually yield better performance than using path properties. URLs that begin with a "/" are relative to the Jupyter server startup directory, that is the directory from where you started Jupyter Notebook or JupyterLab. URL paths without a leading slash are assumed to be relative to the notebook directory.
See below for examples. You can also use the JupyterLab "download url" for the file, obtainable through the JupyterLab UI, as the URL for juicebox.

Examples:


Jupyter Notebook and Colab. Local files using absolute file paths, potentially outside the Jupyter file tree. Note the use of path instead of url.

import juicebox_notebook

juicebox_notebook.init()
b = juicebox_notebook.Browser(
    {
        "name": "GM12878",
        "path": "/TestData/juicebox/HCT-116_Untreated.hic",
        "tracks": [
            {
                "path": "/TestData/juicebox/CTCF_Untreated.bw",
                "type": "wig",
                "name": "CTCF",
                "color": "rgb(22, 129, 198)"
            }
        ]
    }
)

Jupyter Notebook and JupyterLab. Local files using urls relative to the startup directory of the Jupyter server.

import juicebox_notebook

juicebox_notebook.init()
b = juicebox_notebook.Browser(
    {
        "name": "GM12878",
        "url": "/TestData/juicebox/HCT-116_Untreated.hic",
        "tracks": [
            {
                "url": "/TestData/juicebox/CTCF_Untreated.bw",
                "type": "wig",
                "name": "CTCF",
                "color": "rgb(22, 129, 198)"
            }
        ]
    }
)

Jupyter Notebook and Lab. Local files using urls relative to the directory of the notebook.

import juicebox_notebook

juicebox_notebook.init()
b = juicebox_notebook.Browser(
    {
        "name": "GM12878",
        "url": "TestData/juicebox/HCT-116_Untreated.hic",
        "tracks": [
            {
                "path": "TestData/juicebox/CTCF_Untreated.bw",
                "type": "wig",
                "name": "CTCF",
                "color": "rgb(22, 129, 198)"
            }
        ]
    }
)

All platforms. Remote files using urls.

import juicebox_notebook
juicebox_notebook.init()
b = juicebox_notebook.Browser(
    {
        "name": "GM12878",
        "url": "https://www.encodeproject.org/files/ENCFF179HVU/@@download/ENCFF179HVU.hic",
        "tracks": [
            {
                "url": "https://www.encodeproject.org/files/ENCFF000ARJ/@@download/ENCFF000ARJ.bigWig",
                "name": "CTCF",
                "color": "rgb(22, 129, 198)"
            }
        ]
    }

)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

juicebox-notebook-0.2.1.tar.gz (168.3 kB view details)

Uploaded Source

Built Distribution

juicebox_notebook-0.2.1-py3-none-any.whl (167.7 kB view details)

Uploaded Python 3

File details

Details for the file juicebox-notebook-0.2.1.tar.gz.

File metadata

  • Download URL: juicebox-notebook-0.2.1.tar.gz
  • Upload date:
  • Size: 168.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.0 CPython/3.9.1

File hashes

Hashes for juicebox-notebook-0.2.1.tar.gz
Algorithm Hash digest
SHA256 b31a239823902b718bbc38515dca084c9de4b4fb4dbbfe3a7cf52c39506cace0
MD5 9a61a04f4a785e16b4bb4f4adc1fe65a
BLAKE2b-256 21d4dd0ee0ff3ce19fb9bef66d83e2b1837d6bb3e04ab8c8cc82ef05aff4f3c8

See more details on using hashes here.

File details

Details for the file juicebox_notebook-0.2.1-py3-none-any.whl.

File metadata

File hashes

Hashes for juicebox_notebook-0.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 afe1b4f026a4af2b285b01e3104bb5014eff7051f9b6a9fecbc79b535f421e18
MD5 c233a576147a7fab72ef3eb7856e0c6c
BLAKE2b-256 b1ee6743e82631e0ab65fdb82412801c08f5c8f32ba79c522bd0c23262d9bb98

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page