Skip to main content
Version: 0.11.0

Composition

Gosling visualizations are composed from tracks and views.

A track is a unit building block in Gosling which can be represented as a bar chart, a line chart, or an ideogram. Multiple tracks can be grouped into together into a view. A view defines the genomic location for all the tracks it contains, and the tracks define the data to be visualized.

In Gosling, you can compose multiple tracks and views in diverse ways using the following properties:

  1. You can display genomic positions of a view either in Cartesian coordinates (linear) or in polar coordinates (circular) using the layout property.
  2. You can determine to either overlay or stack multiple tracks when composing them into a view using a alignment property.
  3. You use juxtapose multiple views in four different ways (i.e., parallel, serial, vertical, horizontal) using the arrangement property.
{
"arrangement": "parallel", // how to arrange multiple views
"views": [
{
// a single view can contain multiple tracks
"layout": "circular", // specify the layout of a view
"alignment": "stack", // specify how to align several tracks
"tracks": [
{/** track 1 **/},
{/** track 2 **/},
...
]
},
{
/** another view **/
},
...
]
}

Specify the View Layout

In each view, genomic coordinate can be represented in either a circular or linear layout.

In the following figure the upper track is using a linear layout while the bottom one is a circular layout.

linear vs circular

Users can either specify the layout of all views in the root level

{
"layout": "linear", //specify the layout of all views
"views":[...]
}

or specify/override the layout of a certain view in its own definition

{
"layout": "linear", //specify the layout of all tracks in this view
"tracks":[...]
}

To enable an easy switch, both linear and circular layout can be specified through width and height.
Note: the meaning of height is different in circular and linear layout.
A linear layout is controlled by the following properties:

propertytypedescription
widthnumberwidth (in pixel) of the view
heightnumberheight (in pixel) of the view

A circular layout is controlled by the following properties:

propertytypedescription
widthnumberwidth (in pixel) of the view
heightnumberyou need to specify the height of each track to control the ratio of their ticknesses
centerRadiusnumberradius of the center white space / radius of the whole view. default = 0.3

Align Multiple Tracks in One View

The alignment propoerty allow users to either "overlay" or "stack" several tracks.

When setting alignment as "overlay", multiple tracks are overlaid on top of others. When setting alignment as "stack", multiple tracks are vertically concantenated. The default value of alignment is "stack".

alignment of multiple tracks

Multiple tracks can compose one single view, which has the following properties:

propertytypedescription
layoutstringspecify the layout type of all tracks, either "linear" or "circular"
alignmentstringspecify how to align tracks, either "stack" or "overlay". default="stack"
spacingnumberspecify the space between tracks in pixels (if layout is linear) or in percentage ranging from 0 to 100 (if layout is circular)
staticbooleanwhether to disable Zooming and Panning, default=false.
assemblystringcurrently support "hg38", "hg19", "hg18", "hg17", "hg16", "mm10", "mm9"
linkingIdstringspecify an ID for linking multiple views
centerRadiusnumberspecify the proportion of the radius of the center white space. A number between [0,1], default=0.3
widthnumberrequired when setting alignment: overlay
heightnumberrequired when setting alignment: overlay

Arrange Multiple Views

Goslings supports multi-view visualizations. Users can specify the visualizations in "views" and arrange them through the arrangement property.

{
"arrangement": "parallel",
"views": [
// one view is composed of tracks that share the same layout property (linear or circular)
{
"layout": "linear",
"tracks": [...]
},
// One view can have a hierarchical structure.
// For example, the view below is composed of two sub-views
{
"arrangement": "serial",
"views": [
{
"tracks": [...]
},
{
"tracks": [...]
}
]
}
]
}

Gosling supports four types of arrangemet: "parallel", "serial", "vertical", "horizontal".

arrangement of multiple views

Below are the properties that are supported in a multi-view gosling visualization

property type description

views

array

Required. An array of view specifications

zoomLimits

array

yOffset

number

Specify the y offset of views in the unit of pixels

yDomain

DomainInterval | DomainChrInterval | DomainChr

Specify the visible region of genomic y-axis

xOffset

number

Specify the x offset of views in the unit of pixels

xDomain

DomainInterval | DomainChrInterval | DomainChr

Specify the visible region of genomic x-axis

style

Style

Define the style of multive views. Will be overwritten by the style of children elements (e.g., view, track).

static

boolean

Whether to disable Zooming and Panning, Default: false.

spacing

number

The size of the gap (1) between tracks, (2) between views, and (3) of the origin of circular tracks. The effect of this property depends on where on the spec you specify the spacing. In a linear layout, this value is used in pixels, while in a circular layout, this value is used relative to the height of the tracks or views.

orientation

string

One of "horizontal", "vertical". Specify the orientation.

linkingId

string

Specify an ID for linking multiple views

layout

string

One of "linear", "circular". Specify the layout type of all tracks.

id

string

The ID of a view that is maintained for the use of JS API functions, e.g., positions of a view

centerRadius

number

Proportion of the radius of the center white space. Default: 0.3

assembly

string | array

A string that specifies the genome builds to use. Currently support "hg38", "hg19", "hg18", "hg17", "hg16", "mm10", "mm9", and "unknown". Note:: with "unknown" assembly, genomic axes do not show chrN: in labels.

arrangement

string

One of "parallel", "serial", "horizontal", "vertical". Specify how multiple views are arranged.

Inherit Property in Nested Structure

Both view and track supports nested structures: One view can have several children views, and one track can have several children tracks. Properties can be inherited from upper-level specifications or overwritten locally.

// nested structures in views
{
"arrangement": "parallel",
"views": [
{/** a single view **/ },
{
// a view with children views
"arrangement": "parallel",
"views": [...]
}
]
}
// nested structures in tracks
{
"alignment":"overlay",
"views":[{
"tracks": [{
// the parent track
"data": ... , // specify data
"x": ...,
"y": ...,
"color":...,
"alignment": "overlay",
"tracks": [
// the children tracks
// point mark and line mark have the same data, x, y, color encoding
{
"mark": "line",
},
{
"mark": "point",
// specify the size of point mark
"size": {"field": "peak", "type": "quantitative", "range": [0, 6]}
}
]
}]
}]
}

Use the nested structure if you want to use overlaid tracks inside stacked tracks.

Try examples in the online editor:

Line chart (line + point)

Ideogram (text + rect + triangle)