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. callback is used to return an api variable which can be used to access HiGlass events.

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

Arguments:	element (Object) – DOM element the HiGlass component should be associated to. viewConfig (Object\|String) – Dictionary or URL of a view config. options (Object) – Dictionary of public options.
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

shareViewConfigAsLink(url)¶

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)¶

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

Examples:

// Absolute coordinates
hgApi.zoomTo('view1', 1000000, 1000000, 2000000, 2000000, 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

shareViewConfigAsLink(url)¶

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); })

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);