A utility script to manage local docker instances of HiGlass
Branch: master
Clone or download
Type Name Latest commit message Commit time
Failed to load latest commit information.
.bumpversion.cfg Bump version: 0.4.0 → 0.5.0 Feb 4, 2019
.gitignore Add new failing subprocess call, and check all subprocess calls Oct 17, 2018
CHANGELOG Removed print statements Oct 31, 2018
COMMANDS Added version update command Jul 10, 2018
LICENSE Create LICENSE Jul 10, 2018



Manage HiGlass Instances

This utility script helps manage local HiGlass instances


To use this utility, you will require:


higlass-manage can be installed using pip

pip install higlass-manage


HiGlass wraps the Docker commands for starting, stopping, listing and populating local higlass instances.


To run the tests, first get the test data:


And then run the tests:

python test.py

Quickly viewing a dataset

The simplest way to get started is to open and view a dataset. The higlass-manage view command will automatically start a new instance if one isn’t already running, add the given dataset and display it in a browser. Currently, the higlass-manage view command only works with cooler, bigWig, chromsizes and gene-annotation files.

wget https://s3.amazonaws.com/pkerp/public/hic-resolutions.cool
higlass-manage view hic-resolutions.cool

Starting a HiGlass instance

Start a local higlass instance using the default data and temporary directories: ~/hg-data and /tmp/higlass-docker. All of the data ingested into the instance will be placed into the data directory. Alternate data and temp directory can be specified using --data-dir and --temp-dir parameters.

higlass-manage start

If you want to make your instance accessible to the outside world, you need to specify the host URL that it will be available through using the --site-url parameter:

higlass-manage start --site-url higlass.io

These commands will start an instance running on the default port of 8989. An alternate port can be specified using the --port parameter.

Setting default client options

To the default options for newly created tracks, use the --default-track-options parameter to pass in a JSON file containing either track-specific or general default track options:

$cat default_options.json
    "all": {
        "showTooltip": "true"

$ ./higlass_manage.py start --default-track-options default_options.json

Ingesting data

Use the ingest command to add new data. Generally data requires a filetype and a datatype. This can sometimes (i.e. in the case of cooler and bigwig files) be inferred from the file itself.

higlass-manage ingest my_data.mcool

In other, more ambiguous cases, it needs to be explicitly specified:

higlass-manage ingest my_file.bed --filetype bedfile --datatype bedlike --assembly hg19

Note that bedfiles don't store chromosome sizes so they need to be passed in using either the --assembly or --chromsizes-filename parameters.

Listing available datasets

pete@twok:~/projects/higlass-manage$ higlass-manage list_data
VlWKy6ofT6qMFGf-uG_5pQ | beddb | bedlike | GSE93955_CHIP_DMC1_B6_peaks.bed.multires
LAXFhHhASa2zDgJRRS67cw | cooler | matrix | H3K27me3_HiChIP_1.multi.cool

Starting a shell

For debugging purposes it can be useful to run a shell within the Docker container hosting the higlass instance. This can accomplished using the shell command:

higlass-manage shell

Getting the error log

When errors occur they are usually on the higlass-server end. To output the log use the log command:

higlass-manage log

Stopping a HiGlass instance

To stop a running instance, use the stop command:

higlass-manage stop


The following is a list of handy commands when developing HiGlass:

  • Start locally built docker image: The locally built image must be named image-default. Usually built using higlass-docker.
    higlass-manage start --version local


The code in this repository is provided under the MIT License.