Skip to main content
Version: 0.11.0

JavaScript API

GoslingComponent

A React component which takes a Gosling specification and generates the visualization defined by it.

import { GoslingComponent} from 'gosling.js';

<GoslingComponent spec = {/**your gosling spec**/} />
ParameterTypeDescription
specobjectThe Gosling specification the component will create a visualization from
paddingnumberPadding around the component
marginnumberMargin around the component
borderstringBorder style of the component
idstringId of the component
classNamestringCSS class to apply to the component
themeobjectSee themes
urlToFetchOptionsobjectEach object follows the form "{[url: string]: RequestInit}" where RequestInit is also an object. When fetching data from URL which matches a key in this object, Gosling will use the corresponding RequestInit when making the fetch request.

GoslingComponent ref

GoslingComponent can take a Ref which exposes an API which can be used to control or respond to changes in the component.

import React, { useRef, useEffect } from "react";
import { GoslingComponent} from 'gosling.js';

const gosRef = useRef(null)

<GoslingComponent
ref = {gosRef}
spec = {/**your gosling spec**/}
/>

if (gosRef.current) {
// then you can use any Gosling API you want
gosRef.current.api.exportPdf();
}

To find an working example, please visit gosling-lang/gosling-react.

zoomTo

This function makes a view navigate to a specific genomic position with the animated transition.

gosRef.current.zoomTo(viewId: string, position: string, padding?: number, duration?: number)

Parameters

ParameterTypeDescription
viewIdstringThe ID of a view that you want to control. This ID is consistent to what you specify as track.id in your spec.
positionstringThe genomic position that your view should be navigated to. You can either specify chromosome (e.g., chr1) or a chromosome and range pair (e.g., chr1:1-10000).
padding?numberThis determines the padding around the specified position. The unit of this number is a base pair (Default: 0).
duration?numberA duration of the animated transition in ms (Default: 1000).

zoomToExtent

gosRef.current.api.zoomToExtend(viewId: string, duration?: number)

This function zooms out the specified view to see entire genome.

Parameters

ParameterTypeDescription
viewIdstringThe ID of a view that you want to control. This ID is consistent to what you specify as track.id in your spec.
duration?numberA duration of the animated transition in ms (Default: 1000).

zoomToGene

gosRef.current.zoomToGene(viewId: string, gene: string, padding?: number, duration?: number)

This function makes a view navigate to a certain gene with animated transition.

Parameters

ParameterTypeDescription
viewIdstringThe ID of a view that you want to control. This ID is consistent to what you specify as track.id in your spec.
genestringThe target gene symbol that your view should be navigated to (e.g., MYC).
padding?numberThis determines the padding around the specified position. The unit of this number is a base pair (Default: 0).
duration?numberA duration of the animated transition in ms (Default: 1000).

getViewIds

gosRef.current.getViewIds();

Return

Returns a list of IDs that are assigned to individual views. This function can be used prior to navigation functions to check whether certain view IDs exist.

exportPng

gosRef.current.exportPng(transparentBackground?: boolean)

Parameters

ParameterTypeDescription
transparentBackground?booleanDetermine if the background should be transparent or not (Default: false).

exportPdf

gosRef.current.exportPdf(transparentBackground?: boolean)

Parameters

ParameterTypeDescription
transparentBackground?booleanDetermine if the background should be transparent or not (Default: false).

getCanvas

gosRef.current.getCanvas(options?: { resolution?: number; transparentBackground?: boolean })

Parameters

ParameterTypeDescriptionDefault
options.resolution?numberRelative resolution of Gosling.js visualization4
options.transparentBackground?booleanDetermine if the background should be transparent or notfalse

Return Returns a canvas that renders Gosling.js visualization:

{
canvas: HTMLCanvasElement;
canvasWidth: number;
canvasHeight: number;
resolution: number;
}

subscribe

gosRef.current.subscribe(eventName:string, callback: (msg:string, eventData)=>void)

Subscribe the callback function to the specified event.

Parameters

ParameterTypeDescription
eventNamestringSpecify the event using its name. One of "mouseOver", "rangeSelect", "click", "rawData", "onNewTrack", "onNewView", "location".
callback(msg:string, eventData)=>voidA function that is subscribed to the specified event.
  • For "onNewTrack" and "onNewView", the eventData contains just the id of a track or view that has been added. These API functions can be useful if you want to know when certain tracks and views have been added.

    {
    id: string;
    }
  • For "rawData", the eventData stores columnar data that has been used internally in Gosling to display the view:

    {
    id: string,
    data: {[k:string]: number|string}[]
    }
  • For "mouseOver" or "Click", the eventData stores the genomic position of the event and the columnar data corresponding to the visual mark that is either clicked or mouse overed.

     {
    id: string,
    data: {[k:string]: number|string}[],
    genomicPosition: {chromosome: string, position: number}
    }
  • For "rangeSelect", the eventData stores the genomic range of the range select event and the columnar data corresponding to all selected visual marks that are within a range brush.

    {
    id: string,
    data: {[k:string]: number|string}[],
    genomicRange: [
    {chromosome: string, position: number},
    {chromosome: string, position: number}
    ]
    }
  • For "location", the eventData contains the genomic range of a track. Every time a track axis range changes, this API gets updated. For example, if a user zooms in to a track, the axis range changes, and the location API gets updated. If the axis starts before the first chromosome, the start of the genomic range will return the beginning of the first chromosome. If the axis ends after the last chromosome, the end of the genomic range will be the last position in the last chromosome.

    {
    id: string,
    genomicRange: [
    {chromosome: string, position: number},
    {chromosome: string, position: number}
    ]
    }

unsubscribe

gosRef.current.unsubscribe(eventName:string)

Unsubscribe the callback function from the specified event. Parameters

ParameterTypeDescription
eventNamestringName of the event. One of "mouseOver", "rangeSelect", "click", "rawData", "location".