Javascript API

Overview

Embedding HiGlass in web page

HiGlass can be included in any web page by including the relevant javascript and css files:

<link rel="stylesheet" href="https://unpkg.com/higlass@1.2.6/dist/hglib.css" type="text/css">
<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" type="text/css">


<script crossorigin src="https://unpkg.com/react@16/umd/react.development.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/pixi.js/4.8.1/pixi.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react-bootstrap/0.32.1/react-bootstrap.min.js"></script>

<script src="https://unpkg.com/higlass@1.2.6/dist/hglib[.min].js"></script>

External tracks should be included before the hglib.js import:

<script src="https://unpkg.com/higlass-multivec@0.1.10/dist/higlass-multivec.js"></script>

Instructions for instantiating the component and interacting with it are in the Public API section.

Available endpoints

import { HiGlassComponent, ChromosomeInfo, viewer } from 'higlass';

HiGlass exports three endpoints for your convenience. viewer is the main endpoint to create a new HiGlass component. HiGlassComponent can be used to integrate HiGlass in your React application. ChromosomeInfo is a class for converting absolute coordinates to chromosome coordinates. It’s used internally and made available to convert absolute range selection into chromosome range selections.

Creating an inline HiGlass component

const hgv = hglib.viewer(element, config, options);

Create a new HiGlass viewer within a web page. This initializes a HiGlassComponent inside the element element with a viewconfig passed in as config. If config is a string, it is interpreted as a url and used to try to fetch a remote viewconfig.

The options parameter can currently only specify the bounded property which tells the HiGlass component to fill all the space in the containing element. Note that if bounded is set to true, then element must have a fixed height.

The function returns an instance of the public API of a HiGlass component.

A full example of an inline HiGlass component can be found in the HiGlass GitHub repository.

Example

const hgv = hglib.viewer(
  document.getElementById('development-demo'),
  testViewConfig,
  { bounded: true },
);

Creating a HiGlass component in your React app

<HiGlassComponent
  options={options}
  viewConfig={viewConfig}
>

Use the HiGlassComponent to create a HiGlass instance in react. The options prop is the same as explained above.

Example

import { HiGlassComponent } from 'higlass';

const HiGlass = props => <HiGlassComponent
  ref={props.onRef}
  options={props.options}
  viewConfig={props.viewConfig}
>

export default HiGlass;

Obtaining ordered chromosome info

HiGlass provides an API for obtaining information about chromosomes and the order they are listed in a chromSizes file:

import { ChromosomeInfo } from 'higlass';

const chromInfo = ChromosomeInfo(
  'http://higlass.io/api/v1/chrom-sizes/?id=Ajn_ttUUQbqgtOD4nOt-IA',
  (chromInfo) => { console.log('chromInfo:', chromInfo); });

This will return a data structure with information about the chromosomes listed:

{
  chrPositions: {
    chr1 : {id: 0, chr: "chr1", pos: 0},
    chr2 : {id: 1, chr: "chr2", pos: 249250621} ,
    ...
  },
  chromLengths: {
    chr1: "249250621",
    chr2: "243199373",
    ...
  },
  cumPositions: [
    {id: 0, chr: "chr1", pos: 0},
    {id: 1, chr: "chr2", pos: 249250621},
    ...
   ]
}

Convert absolute to chromosomal coordinates:

absPos = 257893;
chromPos = chromInfo.absToChr(absPos);

API Functions

viewer(element, viewConfig, options)

Create a HiGlass component.

In addition to the parameters below, a number of extra options can be passed using the options parameter:

  • authToken (string) - An auth token to be included with every tile request (e.g. JWT xyz)
  • bounded (bool) - A boolean specifying whether the component should be sized to fit within the enclosing div [default=false]. If it is false, then the component will grow as needed to fit the tracks within it.
  • editable (bool) - Can the layout be changed? If false, the view headers will be hidden. This can also be specified in the viewconfig using the editable option. The value passed here overrides the value in the viewconf. [default=true]
Arguments:
  • element (Object) – DOM element the HiGlass component should be attached to.
  • viewConfig (Object|String) – The viewconfig to load. If this parameter is a string it will be interpreted as a url from which to retrieve the viewconf. If it is a dictionary it will be loaded as is.
  • options (Object) – Dictionary of public options. See the description above for a list of available values.
Returns:

Object – Newly created HiGlass component.

Examples:

const hgv = hglib.viewer(
 document.getElementById('development-demo'),
 testViewConfig,
 { bounded: true },
);
reload()

Reload all of the tiles

setViewConfig(newViewConfig)

Set a new view config to define the layout and data of this component

Arguments:
  • newViewConfig (obj) – A JSON object that defines the state of the HiGlassComponent
Returns:

Promise – dataLoaded A promise that resolves when all of the data for this viewconfig is loaded

Examples:

const p = hgv.setViewConfig(newViewConfig);
p.then(() => {
  // the initial set of tiles has been loaded
});
getMinMaxValue(viewId, trackId, ignoreOffScreenValues=false, ignoreFixedScale=false)

Get the minimum and maximum visible values for a given track.

Arguments:
  • viewId (string) – The id of the view containing the track.
  • trackId (string) – The id of the track to query.
  • ignoreOffScreenValues (bool) – If true only truly visible values are considered. Otherwise the values of visible tiles are used. Not that considering only the truly visible values results in a roughly 10x slowdown (from 0.1 to 1 millisecond).
  • ignoreFixedScale (bool) – If true potentially fixed scaled values are ignored. I.e., if the absolute range is [1, 18] but you have fixed the output range to [4, 5] you would normally retrieve [4, 5]. Having this option set to true retrieves the absolute [1, 18] range.
Returns:

Array – The minimum and maximum value

Examples:

const [minVal, maxVal] = hgv.getMinMaxValue('myView', 'myTrack');
getRangeSelection()

Get the current range selection

Returns:Array – The current range selection

Generate a sharable link to the current view config. The url parameter should contain the API endpoint used to export the view link (e.g. ‘http://localhost:8989/api/v1/viewconfs’). If it is not provided, the value is taken from the exportViewUrl value of the viewconf.

Arguments:
  • url (string) – Custom URL that should point to a higlass server’s view config endpoint, i.e., http://my-higlass-server.com/api/v1/viewconfs/.
Returns:

Object – Promise resolving to the link ID and URL.

Examples:

hgv.shareViewConfigAsLink('http://localhost:8989/api/v1/viewconfs')
.then((sharedViewConfig) => {
  console.log(`Shared view config (ID: ${sharedViewConfig.id}) is available at ${sharedViewConfig.url}`)
})
.catch((err) => { console.error('Something did not work. Sorry', err); })
zoomToDataExtent(viewUid)

Zoom so that the entirety of all the datasets in a view are visible. The passed in viewUid should refer to a view which is present. If it doesn’t, an exception will be thrown. Note that if this function is invoked directly after a HiGlass component is created, the information about the visible tilesets will not have been retrieved from the server and zoomToDataExtent will not work as expected. To ensure that the visible data has been loaded from the server, use the setViewConfig function and place zoomToDataExtent in the promise resolution.

Arguments:
  • viewUid (string) – The view uid of the view to zoom

Examples:

const p = hgv.setViewConfig(newViewConfig);
p.then(() => {
    hgv.zoomToDataExtent('viewUid');
});
setViewConfig(newViewConfig)

Set a new view config to define the layout and data of this component

Arguments:
  • newViewConfig (obj) – A JSON object that defines the state of the HiGlassComponent
Returns:

Promise – dataLoaded A promise that resolves when all of the data for this viewconfig is loaded

Examples:

const p = hgv.setViewConfig(newViewConfig);
p.then(() => {
  // the initial set of tiles has been loaded
});
zoomTo(viewUid, start1Abs, end1Abs, start2Abs, end2Abs, animateTime)

Change the current view port to a certain data location. When animateTime is greater than 0, animate the transition. If working with genomic data, a chromosome info file will need to be used in order to calculate “data” coordinates from chromosome coordinates. “Data” coordinates are simply the coordinates as if the chromosomes were placed next to each other.

Arguments:
  • viewUid (string) – The identifier of the view to zoom
  • start1Abs (Number) – The x start position
  • end1Abs (Number) – The x end position
  • start2Abs (Number) – (optional) The y start position. If not specified start1Abs will be used.
  • end2Abs (Number) – (optional) The y end position. If not specified end1Abs will be used
  • animateTime (Number) – The time to spend zooming to the specified location

Examples:

// Absolute coordinates
hgApi.zoomTo('view1', 1000000, 1100000, 2000000, 2100000, 500);
// Chromosomal coordinates
hglib
  // Pass in the URL of your chrom sizes
  .ChromosomeInfo('//s3.amazonaws.com/pkerp/data/hg19/chromSizes.tsv')
  // Now we can use the chromInfo object to convert
  .then((chromInfo) => {
    // Go to PTEN
    hgApi.zoomTo(
      viewConfig.views[0].uid,
      chromInfo.chrToAbs(['chr10', 89596071]),
      chromInfo.chrToAbs(['chr10', 89758810]),
      chromInfo.chrToAbs(['chr10', 89596071]),
      chromInfo.chrToAbs(['chr10', 89758810]),
      2500  // Animation time
    );
  });
  // Just in case, let us catch errors
  .catch(error => console.error('Oh boy...', error))
exportAsSvg()

Get the current view as an SVG. Relies on all the tracks implementing their respective exportAsSVG methods.

Returns:string – An SVG string of the current view.
exportAsPng()

Get the current view as a Data URI

Returns:string – A data URI describing the current state of the canvas
exportAsViewConfString()

Export the current view as a Viewconf.

Returns:string – A stringified version of the current viewconf

Generate a sharable link to the current view config. The url parameter should contain the API endpoint used to export the view link (e.g. ‘http://localhost:8989/api/v1/viewconfs’). If it is not provided, the value is taken from the exportViewUrl value of the viewconf.

Arguments:
  • url (string) – Custom URL that should point to a higlass server’s view config endpoint, i.e., http://my-higlass-server.com/api/v1/viewconfs/.
Returns:

Object – Promise resolving to the link ID and URL.

Examples:

hgv.shareViewConfigAsLink('http://localhost:8989/api/v1/viewconfs')
.then((sharedViewConfig) => {
  console.log(`Shared view config (ID: ${sharedViewConfig.id}) is available at ${sharedViewConfig.url}`)
})
.catch((err) => { console.error('Something did not work. Sorry', err); })
api.on(event, callback, viewId)

Subscribe to events

HiGlass exposes the following event, which one can subscribe to via this method:

  • location
  • rangeSelection
  • viewConfig
  • mouseMoveZoom

Event types

location: Returns an object describing the visible region

{
    xDomain: [1347750580.3773856, 1948723324.787681],
    xRange: [0, 346],
    yDomain: [1856870481.5391564, 2407472678.0075483],
    yRange: [0, 317]
}

rangeSelection: Returns a BED- (1D) or BEDPE (1d) array of the selected data and genomic range (if chrom-sizes are available)

// Global output
{
  dataRange: [...]
  genomicRange: [...]
}

// 1D data range
[[1218210862, 1528541001], null]

// 2D data range
[[1218210862, 1528541001], [1218210862, 1528541001]]

// 1D or BED-like array
[["chr1", 249200621, "chrM", 50000], null]

// 2D or BEDPE-like array
[["chr1", 249200621, "chr2", 50000], ["chr3", 197972430, "chr4", 50000]]

viewConfig: Returns the current view config.

mouseMoveZoom: Returns the raw data around the mouse cursors screen location and the related genomic location.

{
  data, // Raw Float32Array
  dim,  // Dimension of the lens (the lens is squared)
  toRgb,  // Current float-to-rgb converter
  center,  // BED array of the cursors genomic location
  xRange,  // BEDPE array of the x genomic range
  yRange,  // BEDPE array of the y genomic range
  rel  // If true the above three genomic locations are relative
}
Arguments:
  • event (string) – One of the events described below
  • callback (function) – A callback to be called when the event occurs
  • viewId (string) – The view ID to listen to events

Examples:

let locationListenerId;
hgv.on(
  'location',
  location => console.log('Here we are:', location),
  'viewId1',
  listenerId => locationListenerId = listenerId
);

const rangeListenerId = hgv.on(
  'rangeSelection',
  range => console.log('Selected', range)
);

const viewConfigListenerId = hgv.on(
  'viewConfig',
  range => console.log('Selected', range)
);

 const mmz = event => console.log('Moved', event);
 hgv.on('mouseMoveZoom', mmz);