higlass-scalable-insets v0.1.0

Scalable Insets for HiGlass

Explore your beloved 2D annotations with Scalable Insets in HiGlass

Scalable Insets is a new technique for interactively exploring and navigating large numbers of annotated patterns in multiscale visual spaces such as gigapixel images, matrices, or maps. Our technique visualizes annotated patterns too small to be identifiable at certain zoom levels using insets, i.e., magnified thumbnail views of the patterns. Find out more at http://scalable-insets.lekschas.de and watch our <5min introductory video at https://youtu.be/7Bn4mNLl3WQ.

Note: This is the source code for the Scalable Insets tracks only! You might want to check out the following repositories as well if you want to know how Scalable Insets is integrated into HiGlass or use it with images or geographic maps:

• HiGlass viewer: https://github.com/hms-dbmi/higlass
• HiGlass server: https://github.com/hms-dbmi/higlass-server
• HiGlass image track: https://github.com/flekschas/higlass-image
• HiGlass GeoJSON track: https://github.com/flekschas/higlass-geojson

Installation

npm install higlass-scalable-insets

Usage

1. Make sure you load this track prior to hglib.js. For example:

<script src="higlass-scalable-insets.js"></script>
<script src="hglib.js"></script>
<script>
  ...
</script>

2. Configure the track in the view config.

{
  ...,
  tracks: {
    center: [
      {
        type: 'combined',
        options: {},
        contents: [
          // This tracks loads the Hi-C matrix
          {
            server: 'http://higlass.io/api/v1/',
            tilesetUid: 'CQMd6V_cRw6iCI_-Unl3PQ',  // Rao et al. 2014 GM12878
            type: 'heatmap',
          },
          // This track loads the annotated patterns
          {
              server: '//higlass.io/api/v1',
              tilesetUid: 'HunfK2D3R9iBdIq-YNYjiw',
              uid: 'anno-loops-1',
              type: '2d-rectangle-domains',
          },
          // This track is responsible for rendering the insets.
          {
            server: '//higlass.io/api/v1/',
            tilesetUid: 'CQMd6V_cRw6iCI_-Unl3PQ',
            uid: 'insets',
            type: 'insets',
            dataType: 'matrix',
          },
        ],
      },
    ],
    // You could also display the insets on the gallery of the matrix
    // gallery: {
    //   server: '//higlass.io/api/v1/',
    //   tilesetUid: 'CQMd6V_cRw6iCI_-Unl3PQ',
    //   type: 'insets',
    //   dataType: 'matrix',
    // },
    ...
  },
  metaTracks: {
    type: 'annotations-to-insets',
    insetsTrack: 'insets',
    options: {
      annotationTracks: ['ski-areas'],
    },
  }
}

Take a look at src/index.html for an example.

Configuration

Scalable Insets requires 2 tracks. An insets track, which handles the insets, and an annotations-to-insets track, which links all drawn annotations and compute the placement and clustering of insets.

Track: annotations-to-insets

Settings

Options

The following options let you adjust the trade-off between Details, Context, and Locality. Please see the paper for details.

*) Note This is the only mandatory option, I know it doesn't make sense semantically but it was the easiest way to implement given that HiGlass by default does not pass the entire track config to a track.

Track: insets

Settings

Options

Development

Installation

$ git clone https://github.com/flekschas/higlass-scalable-insets && higlass-scalable-insets
$ npm install

Commands

Developmental server: npm start

Production build: npm run build

Co-Development with HiGlass

If you need to work on HiGlass and Scalable Insets in parallel I recommend the following setup:

1. Link a local HiGlass instance:

git clone https://github.com/hms-dbmi/higlass && cd higlass && npm install
npm link
npm run build

2. Open another terminal, link the HiGlass instance and start the web server

cd higlass-scalable-insets
npm link higlass
npm start

Now, whenever you make changes to your local HiGlass instance it will be re-build and also trigger a re-build of the Scalable Insets track.