JavaScript API reference

The JavaScript library, geneviewer 0.3.11: newChart(), the chart spec, the chart's methods and events. The spec's options are generated from the JSON Schema in the repository; names may still change until 1.0.

The R and Python packages have their own references: R reference, Python reference.

• newChart()
• Other functions
• The chart spec
• Per-cluster settings
• Components: align, annotation, cluster, clusterFooter, clusterLabel, clusterTitle, color, coordinates, elementStyle, events, genes, grid, labels, legend, links, pattern, scale, scaleBar, sequence, theme, title, toolbar, tooltip, trackMouse, transcript, zoom
• Chart methods
• Events
• Builds
• Versions

newChart()

geneviewer.newChart(target, spec, options?) → Chart

Argument	Type	Description
target	string or Element	A CSS selector or the element to draw in. The chart takes its size.
spec	object	What to draw: see the chart spec.
options.on	object	Event handlers by name, added before the first draw, so they also get its events.
options.saveAs	function	Called as saveAs(blob, filename) instead of the browser's download.
options.injectStyles	boolean	Default true: the library adds its stylesheet to the page once. Turn off where a Content-Security-Policy blocks it, and load geneviewer.css.
options.server	boolean	For the R and Python packages: events go to a server that may draw the chart again.

Other functions

Name	Description
geneviewer.compile(spec)	The render model a spec gives: clusters split, per-cluster settings applied, theme resolved. For tests and debugging; its shape is internal and may change in any version.
geneviewer.themes	The built-in themes and their settings, by name. The names are those of theme; the settings use the renderer's names and are not part of spec v1.
geneviewer.palettes	The built-in colour palettes: arrays of colours, by the names theme.palette takes.
geneviewer.version	The library's version.

The chart spec

A chart is one plain object, which can be written as JSON. Its keys mirror the R package's functions: GC_labels() becomes labels, and arguments become camelCase options.

Key	Type	Default	Description
version	1	1	The spec version. Optional: a spec without one is version 1.
data	table		The genes: an array of rows, or columns (an object of equal-length arrays), as R and Python send them.
fields	object		The columns of data that hold each gene's position, cluster, group and strand.
width	number or string	"100%"	Width of the chart: pixels, or a CSS length such as "100%".
height	number or string	"400px"	Height of the chart: pixels, or a CSS length such as "400px".
style	style object		CSS styles of the chart's element, e.g. { backgroundColor: "white" }.

fields

Option	Type	Default	Description
start	column name	"start"	Column with the start position of each gene.
end	column name	"end"	Column with the end position of each gene.
cluster	column name		Column that splits the genes into clusters. Default: one cluster.
group	column name		Column that groups the genes, which sets their colours and the legend.
strand	column name		Column with the strand of each gene: 1, "forward", "sense" or "+" for forward; -1, 0, "reverse", "antisense", "complement" or "-" for reverse. Default: a column named strand if the data has one; otherwise a gene with start less than end is forward and any other gene is reverse.

Per-cluster settings

Most components can be an array of entries. Entries apply in order; an entry with clusters applies only to those clusters, by name or by 1-based position:

labels: [
  { label: "name" },                      // every cluster
  { clusters: ["dbophA"], show: false },  // then hide the labels of dbophA
]

Components

align

Aligns the clusters on one gene: each cluster's scale is set so the gene is at the same place in every cluster. One object.

Option	Type	Default	Description
idColumn	column name		Column that identifies the gene to align on.
id	string or number		The value of idColumn of the gene to align on; one gene per cluster.
align	"left" | "center" | "right"	"left"	The side of the gene the clusters align on.

annotation

Annotations drawn in the clusters: text, lines, arrows, symbols and more. One entry, or an array of entries applied in order.

Option	Type	Default	Description
type	"text" | "textMarker" | "line" | "arrow" | "symbol" | "rectangle" | "promoter" | "terminator" | "arc"	"text"	The kind of annotation.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
x	number or array of number		Position along the scale (text, symbol, promoter, terminator); an array draws one per position; an array draws one per value.
y	number or array of number		Vertical position, from 1 to 100 (text, symbol, promoter, terminator); an array draws one per value.
text	string or number or array of string or number		The text (text, textMarker, arc); an array draws one per value.
x1	number or array of number		Start position along the scale (line, arrow, textMarker, arc); an array draws one per value.
x2	number or array of number		End position along the scale (line, arrow, textMarker, arc); an array draws one per value.
y1	number or array of number		Start height, from 1 to 100 (line, arrow, textMarker, arc); an array draws one per value.
y2	number or array of number		End height, from 1 to 100 (line, arrow, textMarker, arc); an array draws one per value.
position	any		textMarker: the position along the scale; rectangle: corners [[x1, y1], [x2, y2]], or an array of them.
labelX	number or array of number		Horizontal offset of the text, in pixels (textMarker, arc); an array draws one per value.
labelY	number or array of number		Vertical offset of the text, in pixels (textMarker, arc); an array draws one per value.
showArrow	boolean		Whether the textMarker has an arrowhead.
arrowSize	number or array of number		Size of the arrowhead, in pixels (arrow, textMarker); an array draws one per value.
symbol	string or array of string		Symbol: circle, cross, diamond, square, star, triangle or wye.
size	number or array of number		Size of the symbol, in square pixels; an array draws one per value.
rotation	number or array of number		Rotation, in degrees (symbol, rectangle, promoter, terminator); an array draws one per value.
direction	"forward" | "reverse"		Direction of a promoter or terminator.
scale	number or array of number		Size factor of a promoter or terminator; an array draws one per value.
midY	number or array of number		Height of the arc's middle, from 1 to 100; an array draws one per value.
stroke	string or array of string		Line colour of an arc.
strokeWidth	number or array of number		Line width of an arc, in pixels; an array draws one per value.
style	style object		Style of the annotation (text, line, symbol, rectangle, promoter, terminator).
textStyle	style object		Style of the text (textMarker, arc).
arrowStyle	style object		Style of the arrowhead (arrow, textMarker).
lineStyle	style object		Style of the line (arrow, textMarker, arc).

Other options are passed to the renderer as they are.

cluster

Layout of the genes in a cluster: strands on separate rows, overlapping genes on separate tracks, and the cluster's style. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
separateStrands	boolean		Whether forward and reverse genes go on separate rows.
strandSpacing	number		Space between the forward and reverse rows, with separateStrands.
preventGeneOverlap	boolean or "nested"		Overlapping genes go on separate tracks: true for all overlapping genes, "nested" only for genes that lie inside another gene. The track of each gene is in its geneTrack field.
overlapMin	number or string		How much two genes must overlap to go on separate tracks: base pairs, or a share of the shorter gene such as "10%". Default: any overlap.
overlapSpacing	number		Space between tracks, with preventGeneOverlap.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
style	style object		CSS styles of the cluster's element.
margin	margins		Margins of the cluster, in pixels.
width	number or string		Width of the cluster.
height	number or string		Height of the cluster.

Other options are passed to the renderer as they are.

clusterFooter

Footer below each cluster: a title and subtitle. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
title	string or number or array of string or number		Title of each footer; an array is recycled over the clusters.
subtitle	string or number or array of string or number		Subtitle of each footer.
show	boolean or array of boolean	true	Whether to show the footer.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
subtitleFont	style object		Font options of the subtitle.
titleFont	style object		Font options of the title.
align	"left" | "center" | "right" or array of "left" | "center" | "right"		Alignment of the title and subtitle; x moves them from there. Default: the theme's, otherwise "left".
spacing	number or array of number		Pixels between the title and subtitle. Default: the theme's, otherwise 12.
x	number		Horizontal offset of the footer, in pixels.
y	number		Vertical offset of the footer, in pixels.

Other options are passed to the renderer as they are.

clusterLabel

Label in the left or right margin of each cluster. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
title	string or number or array of string or number		Text of the label; an array is recycled over the clusters.
show	boolean	true	Whether to show the label.
width	number or string		Width of the label, which sets the cluster's margin on that side. Default: a margin set with grid, otherwise the theme's, otherwise "100px".
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
position	"left" | "right"		Side of the label. Default: the theme's, otherwise "left".
align	"left" | "center" | "right" or array of "left" | "center" | "right"		Alignment of the label's lines in its margin; x moves it from there. Default: the theme's, otherwise "center".
wrapLabel	boolean		Whether long labels wrap over several lines. Default: the theme's, otherwise true.
wrapOptions	object		Options for wrapping the label.
subtitle	string or number or array of string or number		A second line below the title, e.g. the species.
subtitleFont	style object		Font options of the subtitle. Default: 11px, not bold.
spacing	number or array of number		Pixels between the middle of the title's last line and the subtitle. Default: the theme's, otherwise 1.2 times the mean font size of the two.
x	number		Horizontal offset of the label, in pixels.
y	number		Vertical offset of the label, in pixels.
fontSize	number or string		Font size, e.g. "12px".
fontStyle	string		Font style, e.g. "italic".
fontWeight	number or string		Font weight, e.g. "bold".
fontFamily	string		Font family.
cursor	string		Mouse cursor over it.

Other options are passed to the renderer as they are.

clusterTitle

Title and subtitle above each cluster. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
title	string or number or array of string or number		Title of each cluster; an array is recycled over the clusters.
subtitle	string or number or array of string or number		Subtitle of each cluster; an array is recycled over the clusters.
subtitleFont	style object		Font options of the subtitle.
titleFont	style object		Font options of the title.
show	boolean	true	Whether to show the title.
height	number or string		Height of the title, e.g. "40px".
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
align	"left" | "center" | "right" or array of "left" | "center" | "right"		Alignment of the title and subtitle; x moves them from there. Default: the theme's, otherwise "center".
spacing	number or array of number		Pixels between the title and subtitle. Default: the theme's, otherwise 20.
x	number		Horizontal offset of the title, in pixels.
y	number		Vertical offset of the title, in pixels.

Other options are passed to the renderer as they are.

color

Colours of the gene groups, for the genes and the legend. One object.

Option	Type	Default	Description
colorScheme	string		Name of a colour scheme: a D3 scheme such as "schemeTableau10", or a geneviewer palette such as "okabeIto".
customColors	colours		Colours of the groups: an array recycled over the groups, or an object of colours by group. Groups left out keep the colours of colorScheme, the theme's palette or the defaults.

coordinates

Start and end positions written at the genes. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
show	boolean or array of boolean	true	Whether to show the coordinates.
tickValuesTop	array of number		Positions written above the cluster, in place of the genes' own.
tickValuesBottom	array of number		Positions written below the cluster, in place of the genes' own.
ticksFormat	string		D3 number format of the positions. Default: ",.0f".
tickStyle	style object		Styles of the ticks.
textStyle	style object		Styles of the text.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
groupStyle	styles by group		Styles by group, for the coordinates of every gene of that group: show = false leaves them out, tick styles their ticks, the rest their text.
styleBy	column name		Column whose values groupStyle matches. Default: fields.group.
rotate	number	-45	Rotation of the coordinates, in degrees.
yPositionTop	number	53	Vertical position of the coordinates above the genes, from 1 (bottom) to 100 (top) of the cluster.
yPositionBottom	number	48	Vertical position of the coordinates below the genes, from 1 (bottom) to 100 (top) of the cluster.
overlapThreshold	number	20	Distance in pixels below which coordinates of neighbouring genes go on the other side.

Other options are passed to the renderer as they are.

elementStyle

Overrides for single elements: a gene, label or coordinate, a title or subtitle, a legend label or marker, a scale bar or axis. Each entry is one element; later entries for the same element add to earlier ones. One entry, or an array of entries applied in order.

Option	Type	Default	Description
component	"genes" | "labels" | "coordinates" | "clusterTitle" | "clusterFooter" | "clusterLabel" | "legend" | "title" | "scaleBar" | "scale"	"genes"	The component of the element.
rowID	number		For genes, labels and coordinates: the gene's rowID, as reported in select and dblclick events.
cluster	cluster		For cluster titles, footers, labels, scale bars and axes: the cluster's name or 1-based position.
part	"title" | "subtitle" | "label" | "marker"		For titles, footers and cluster labels: "title" or "subtitle"; for the legend: "label" or "marker".
end	"start" | "end"		For coordinates: the start or end coordinate. Default: both.
group	string		For the legend: the group's original value, as reported in events.

Other options are passed to the renderer as they are.

events

Which interactions the chart reports, and whether parts are clickable. One object.

Option	Type	Default	Description
click	boolean	true	Whether clicks are reported, in a spec with an events key; a spec without one reports nothing.
highlight	boolean	false	Whether the part under the mouse is outlined, to show what a click selects.
rendered	boolean	false	Whether each finished draw is reported as a rendered event.
renderId	string or number		Identifies this draw in the rendered event. A new value also restarts the zoom at its range. Default: a new unique id for each draw.
dblclick	boolean	false	Whether double-clicks are reported, for editing.
select	boolean	false	Whether elements can be selected.
legendClick	boolean	true	Whether clicks on the legend are reported.
drag	boolean	false	Whether labels, titles, scale bars, axes and legend items can be dragged. Moves can be undone and redone.
zoom	boolean	false	Whether the zoom window is reported, on the first draw and after every change.

genes

The gene markers. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
group	column name		Column that groups the genes for their colours. Default: fields.group.
marker	"arrow" | "boxarrow" | "box" | "cbox" | "rbox"		Shape of the markers.
markerSize	"small" | "medium" | "large"		Size of the markers.
show	boolean	true	Whether to show the genes.
colorScheme	string		Colour scheme of the groups. Default: the colours of the color component.
customColors	colours		Colours of the groups: an array recycled over the groups, or an object by group.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
itemStyle	item styles		Styles of single genes, by their 0-based index in the cluster.
groupStyle	styles by group		Styles by group, for every gene of that group. A gene's itemStyle takes precedence.
styleBy	column name		Column whose values groupStyle matches, or "geneTrack" for the track of each gene. Default: group.
cornerRadius	number		Radius in pixels of the markers' corners. Default: sharp, and 5 for "rbox".
x	number		Horizontal offset of the genes, in pixels.
y	number	50	Vertical position of the genes, from 1 (bottom) to 100 (top) of the cluster.
stroke	colour		Outline colour of the genes.
strokeWidth	number	1	Outline width of the genes, in pixels.
cursor	string	"default"	Mouse cursor over a gene.
arrowheadWidth	number		Width of the arrowhead, in pixels. Default: from markerSize.
arrowheadHeight	number		Height of the arrowhead, in pixels. Default: from markerSize.
markerHeight	number		Height of the gene body, in pixels. Default: from markerSize.

Other options are passed to the renderer as they are.

grid

Size and margins of each cluster, and the direction clusters are laid out in. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
margin	margins		Margins of the cluster in pixels.
width	number or string		Width of the cluster; a number is a percentage.
height	number or string		Height of the cluster.
direction	"column" | "row"	"column"	Clusters below each other ("column") or side by side ("row").
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.

labels

Labels of the genes. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
label	column name		Column with the label of each gene. Default: fields.group.
show	boolean	true	Whether to show the labels.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
itemStyle	item styles		Styles of single labels, by their 0-based index in the cluster.
groupStyle	styles by group		Styles by group, for the labels of every gene of that group.
styleBy	column name		Column whose values groupStyle matches, e.g. the label column, or "geneTrack". Default: fields.group.
x	number		Horizontal offset of the labels, in pixels.
y	number	55	Vertical position of the labels, from 1 (bottom) to 100 (top) of the cluster.
dx	number or string		Horizontal shift of each label, e.g. "0.5em".
dy	number or string		Vertical shift of each label, e.g. "-1em".
rotate	number	0	Rotation of the labels, in degrees.
start	number		Position where the labels start; labels of genes before it are not drawn.
end	number		Position where the labels end; labels of genes after it are not drawn.
adjustLabels	boolean or "hide" | "spread"	true	Overlapping labels: true moves them apart, "hide" hides them, "spread" spreads them out with leader lines, false leaves them.
spreadPosition	"bottom" | "top"	"bottom"	With adjustLabels "spread": the side of the genes the labels go to.
leaderLine	false or style object		Style of the lines to spread labels (stroke, strokeWidth, length in pixels); false draws none.
textAnchor	"start" | "middle" | "end"	"middle"	Text alignment of each label at its gene.
labelAdjustment	style object		How overlapping labels are moved: rotation, offsetX, offsetY, dx, dy.
fontSize	number or string		Font size, e.g. "12px".
fontStyle	string		Font style, e.g. "italic".
fontWeight	number or string		Font weight, e.g. "bold".
fontFamily	string		Font family.
cursor	string		Mouse cursor over it.

Other options are passed to the renderer as they are.

legend

The legend of the gene groups. One object.

Option	Type	Default	Description
group	column name		Column whose values the legend lists. Default: fields.group.
show	boolean	true	Whether to show the legend.
backgroundColor	colour		Background colour; style.backgroundColor takes precedence. Default: the theme's, otherwise transparent.
order	array of string		Order of the groups in the legend.
position	"top" | "bottom"		Above or below the clusters. Default: the theme's, otherwise "bottom".
align	"left" | "center" | "right"		Alignment of the legend items; each row on its own. Default: the theme's, otherwise "left".
style	style object		CSS styles of the legend's element.
markerStyle	style object		Options of the legend items (markers), such as cursor.
textStyle	style object		Options of the legend text, such as fontSize.
cornerRadius	number		Radius in pixels of the markers' corners. Default: square.
groupStyle	styles by group		Styles by group for the text of that group's entry; styles under marker go to its marker.
x	number		Horizontal offset of the legend, in pixels.
y	number		Vertical offset of the legend, in pixels.
width	number or string		Width of the legend. Default: the chart's width.
orientation	"horizontal" | "vertical"	"horizontal"	Entries side by side or below each other.
adjustHeight	boolean	true	Whether the legend's height follows its entries.

Other options are passed to the renderer as they are.

links

Links between genes of different clusters, drawn from a table of pairs. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
data	table		The links: one row per pair, made by R or Python (get_links) or by hand.
group	column name		The column the genes were matched on (R and Python: get_links). Its values pick the genes labelled with the measure; without it, links.data was given and labelPosition "gene" draws no labels.
value1	string or number or array of string or number		Values of group matched in the first cluster of each pair; only their genes are labelled with the measure.
value2	string or number or array of string or number		Values of group matched in the second cluster of each pair; only their genes are labelled with the measure.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
curve	boolean		Whether links are curved. Default: the theme's, otherwise true.
measure	"identity" | "similarity" | "none"	"identity"	The measure that sets the links' colour.
show	boolean	true	Whether to show the links.
label	boolean	true	Whether to write the measure on the links.
labelPosition	"gene" | "link"	"gene"	Where the measure goes: with the gene's label ("gene") or in the middle of the link ("link").
normalColor	colour		Colour of links. Default: the theme's, otherwise "#969696".
invertedColor	colour		Colour of inverted links. Default: the theme's, otherwise "#d62728".
lowColor	colour		Colour links fade to at a low measure. Default: the theme's, otherwise white.
vmin	number		Measure of the lightest colour, and the low end of the colour bar. Default: the theme's, otherwise 0.
vmax	number		Measure of the full colour, and the high end of the colour bar. Default: the theme's, otherwise 100.
useGroupColors	boolean	false	Whether links take the colour of their group.
colorBar	boolean		Whether to show the colour bar. Default: the theme's, otherwise true.
colorBarOptions	object		Options of the colour bar: position, orientation, labels, x, y, width, height, title and its styles.
linkWidth	number		Width of the links: 1 is the full width of the genes, 0 none.
linkStyle	style object		CSS styles of the links.
labelStyle	style object		CSS styles of the measure labels.
y	number	50	Vertical position of the links, from 1 (bottom) to 100 (top) of the cluster.
labelAdjustment	style object		How overlapping measures on the links are moved: rotation, offsetX, offsetY, dx, dy.

Other options are passed to the renderer as they are.

pattern

Pattern fills of the genes, exons and legend markers by group, e.g. for black and white figures. One object.

Option	Type	Default	Description
patterns	array of string or object		Pattern names: an array recycled over the groups, or an object by group (groups left out get none). Default: a pattern for each group in a fixed order.
color	colours	"black"	Colour of the pattern: one colour, an array recycled over the groups, or an object by group.
background	colours or null	"white"	Colour behind the pattern, in the same forms as color; null keeps the gene colours.
size	number	6	Width and height of one pattern tile in pixels.
strokeWidth	number	1	Width of the pattern lines in pixels.

scale

The position scale of each cluster: its range, axis and scale breaks. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
start	number or array of number		Start of the scale. Default: the first gene's start, less padding.
end	number or array of number		End of the scale. Default: the last gene's end, plus padding.
padding	number or string		Room on either side: a number, or a share such as "2%". Default: the theme's, otherwise 2.
hidden	boolean	false	Whether the axis is hidden.
breaks	array of break		Stretches of the scale left out, with break marks on the line, in the data's positions.
tickValues	array of number		Positions of the ticks. Default: chosen by D3.
reverse	boolean	false	Whether the scale runs from right to left.
axisPosition	"top" | "bottom"		Axis above or below the genes. Default: the theme's, otherwise "bottom".
axisType	"position" | "range"	"position"	Whether ticks show positions, or the range from the scale's start.
y	number		Vertical position of the axis, from 1 to 100.
autoBreaks	boolean	false	Whether to add scale breaks at large gaps between genes.
autoBreakThreshold	number	20	Gaps larger than this percentage of the cluster become scale breaks, with autoBreaks.
breakPadding	number or string	1	Room left on either side of a break: a percentage of the region shown, or base pairs as a string such as "500bp".
ticksCount	number		Number of ticks. Default: the theme's, otherwise 10.
ticksFormat	string		D3 number format of the ticks. Default: ",.0f" for positions, ".2s" for ranges.
tickStyle	style object		Styles of the ticks.
textStyle	style object		Styles of the tick text.
lineStyle	style object		Styles of the axis line.

Other options are passed to the renderer as they are.

scaleBar

A scale bar in each cluster. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
show	boolean	true	Whether to show the scale bar.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
lineStyle	style object		Styles of the bar's line.
tickStyle	style object		Styles of the bar's ticks.
labelStyle	style object		Styles of the bar's label.
title	string	"1 kb"	Text of the scale bar.
unit	number	1000	Length of the scale bar, in base pairs.
x	number		Horizontal offset of the scale bar, in pixels.
y	number		Vertical offset of the scale bar, in pixels.
textPadding	number	0	Space between the text and the bar, in pixels.

Other options are passed to the renderer as they are.

sequence

The line the genes sit on, with marks at scale breaks. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
show	boolean	true	Whether to show the line.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
y	number		Vertical position of the line. Default: the theme's, otherwise 50.
lineStyle	style object		Styles of the line.
markerStyle	style object		Styles of the break marks, plus markerHeight, tiltAmount and gap.
start	number		Position where the line starts. Default: the scale's start.
end	number		Position where the line ends. Default: the scale's end.

Other options are passed to the renderer as they are.

theme

The default look of every part of the chart. A built-in theme's name, or an object that starts from one and changes it. Options set in the other components take precedence. A built-in theme's name, or an object.

Option	Type	Default	Description
base	theme name		The built-in theme to start from; R's list of theme settings is the theme object itself. Default: the current theme.
textScale	number		Text size as a factor of the default font sizes.
fontFamily	string		Font family of all text.
textColor	colour		Colour of all text.
lineColor	colour		Colour of the lines: sequence, axis, coordinates, scale bar and leader lines.
background	colour		Background colour of the chart, also the fill of UTRs.
palette	string or array of colour		Gene colours: a colour scheme's name or an array of colours, in the order of the groups.
pattern	object or false		Patterns, with the properties of the pattern component; false removes the theme's patterns.

Other options are passed to the renderer as they are.

title

The chart's title and subtitle. One object.

Option	Type	Default	Description
title	string		The title.
subtitle	string		The subtitle.
style	style object		CSS styles of the title's element.
subtitleFont	style object		Font options of the subtitle.
titleFont	style object		Font options of the title.
show	boolean	true	Whether to show the title.
height	number or string		Height of the title. Default: the theme's, otherwise 50 pixels with a subtitle and 40 without.
align	"left" | "center" | "right"		Alignment of the title and subtitle. Default: the theme's, otherwise "center".
spacing	number		Pixels between the title and subtitle. Default: the theme's, otherwise 20.
x	number		Horizontal offset of the title, in pixels.
y	number		Vertical offset of the title, in pixels.

Other options are passed to the renderer as they are.

toolbar

The chart's own buttons: undo, redo, reset, reset zoom and save. One object.

Option	Type	Default	Description
show	"hover" | "always" | "never"		When the toolbar shows. Default: "hover".
position	"topright" | "topleft" | "bottomright" | "bottomleft"		The corner of the toolbar. Default: "topright".
buttons	array of "undo" | "redo" | "reset" | "zoom" | "save"		The buttons, in their order. Default: all.
size	number		Size of the icons in pixels. Default: 20.
color	colour		Colour of the icons. Default: "#D3D3D3".
hoverColor	colour		Colour of an icon under the mouse. Default: "#555555".
tooltipBackground	colour		Background of the tooltips and the save menu. Default: "#333333".
tooltipColor	colour		Text colour of the tooltips and the menu. Default: "white".
tooltipBorder	string		CSS border of the tooltips and the menu. Default: none.
tooltipRadius	number or string		Corner radius of the tooltips and the menu. Default: 3.
tooltipShadow	string		CSS box shadow of the tooltips and the menu. Default: none.
fontFamily	string		Font of the tooltips and the menu. Default: Arial.
icons	object		Icons by button, as Font Awesome names, e.g. { save: "camera" }. Buttons left out keep theirs.

tooltip

The tooltip shown over a gene. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
formatter	string	"<b>Start:</b> {start}<br><b>End:</b> {end}"	HTML of the tooltip; {column} is replaced by the gene's value.
show	boolean	true	Whether to show the tooltip.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
triggers	array of "markers" | "genes" | "labels" | "exons" | "introns" | "utrs"	["markers","genes","labels","exons","introns","utrs"]	The parts that show the tooltip.
opacity	number	0	Opacity of the tooltip when hidden.
position	string	"absolute"	CSS position of the tooltip.
pointerEvents	string	"none"	CSS pointer-events of the tooltip.
backgroundColor	colour		Background colour.
color	colour		Text colour.
padding	string		Padding, as CSS.
borderRadius	string		Corner radius, as CSS.
border	string		Border, as CSS.
boxShadow	string		Shadow, as CSS.
fontFamily	string		Font family.
fontSize	string		Font size, as CSS.
lineHeight	number or string		Line height, as CSS.
zIndex	number		Stacking order, as CSS.

Other options are passed to the renderer as they are.

trackMouse

Shows the position under the mouse, e.g. to place annotations. An array of entries applies them in order; an entry with clusters only to those clusters. One entry, or an array of entries applied in order.

Option	Type	Default	Description
show	boolean	true	Whether to show the position.
clusters	clusters		The clusters this entry applies to, by name or 1-based position. Default: all clusters.
cursor	string	"crosshair"	Mouse cursor over the clusters.
backgroundColor	colour		Background colour.
color	colour		Text colour.
padding	string		Padding, as CSS.
borderRadius	string		Corner radius, as CSS.
border	string		Border, as CSS.
boxShadow	string		Shadow, as CSS.
fontFamily	string		Font family.
fontSize	string		Font size, as CSS.
lineHeight	number or string		Line height, as CSS.
zIndex	number		Stacking order, as CSS.

Other options are passed to the renderer as they are.

transcript

Transcripts: exons, introns and UTRs. An array of entries applies them in order; an entry with selection only to those transcripts. One entry, or an array of entries applied in order.

Option	Type	Default	Description
transcript	column name		Column that groups the rows into transcripts.
type	column name		Column with the feature type of each row ("exon", "intron", "UTR").
strand	column name		Column with the strand of each transcript, read as fields.strand.
group	column name		Column that groups the transcripts for their colours.
selection	string or number or array of string or number		Only these transcripts are drawn.
show	boolean	true	Whether to show the transcripts.
colorScheme	string		Colour scheme of the groups. Default: the colours of the color component.
customColors	colours		Colours of the groups: an array recycled over the groups, or an object by group.
styleExons	style object		Styles of the exons.
styleIntrons	style object		Styles of the introns.
styleUTRs	style object		Styles of the UTRs.
itemStyleExons	item styles		Styles of single exons, by 0-based index.
itemStyleIntrons	item styles		Styles of single introns, by 0-based index.
itemStyleUTRs	item styles		Styles of single UTRs, by 0-based index.
groupStyleExons	styles by group		Styles by group, for every exon of that group.
groupStyleIntrons	styles by group		Styles by group, for every intron of that group.
groupStyleUTRs	styles by group		Styles by group, for every UTR of that group.
styleBy	column name		Column whose values the group styles match. Default: group.
labelOptions	style object		Options of the transcript labels.
x	number		Horizontal offset of the transcripts, in pixels.
y	number	50	Vertical position of the transcripts, from 1 (bottom) to 100 (top) of the cluster.

Other options are passed to the renderer as they are.

zoom

A slider below the clusters to zoom in on part of them. One object.

Option	Type	Default	Description
show	boolean	true	Whether to show the slider.
range	array of number or null		The window shown first, [start, end] in the units of mode. Default: everything.
mode	"relative" | "absolute"		"relative": every cluster shows the same share of its range; "absolute": the same base pairs. Default: "relative".
min	number		The narrowest window, in the units of mode. Default: 1% of the slider.
update	"live" | "release"		Draw while the slider moves, or when it is let go. Default: "live".
height	number		Height of the slider in pixels. Default: 24.
overview	boolean		Whether the slider shows the genes of each cluster. Default: true.
color	colour		One colour for the overview's genes in place of their group colours.
style	style object		CSS styles of the slider's track.
windowStyle	style object		CSS styles of the window.
handleStyle	style object		CSS styles of the two handles.

Chart methods

Method	Description
update(partial)	Merge a partial spec into the spec and draw again: objects merge key by key; arrays, other values and tables (data, links.data) replace. update({ theme: "dark" }) changes only the theme.
setSpec(spec)	Replace the spec and draw again.
getSpec()	A copy of the spec.
on(name, handler)	Call handler({ type, detail }) on each event of that name. Returns a function that stops it.
off(name, handler)	Stop calling a handler.
zoomTo([start, end])	Set the zoom window, in the units of zoom.mode; zoomTo(null) shows everything.
select(items)	Select elements, as a click does, and report select and selection when that changes the selection. An item gives a component and any of cluster, part and data; it selects every drawn element that matches all it gives, so { component: "genes", data: { rowID: 3 } } selects gene row 3, and the items of getSelection() select their elements again. select(null) or select([]) clears it. Needs events: { select: true }.
getSelection()	The selected elements, as the selection event reports them.
undo(), redo()	Undo or redo the last move, as the toolbar does (events: { drag: true }).
download(format, filename)	Save the chart as "svg" or "png", as the save menu does: through the saveAs option, or as a browser download. The name defaults to graph.svg or graph.png. A Promise.
toSVG()	The chart as SVG text.
toPNG()	The chart as a PNG Blob (a Promise).
resize()	Draw again at the element's size.
destroy()	Remove the chart and its listeners.

Events

Handlers get { type, detail }. Each event is also sent as a DOM event, geneviewer:<name>, on the chart's element; see the interactive example. events in the spec turns them on.

Event	When	Detail
click	An element was clicked (events.click).	The element (below).
dblclick	An element was double-clicked (events.dblclick).	The element.
select	The selected element changed (events.select).	The element selected last, or null when the selection is cleared.
selection	The list of selected elements changed.	An array of elements, in the order they were selected.
drag	An element was moved: dropped, nudged with the arrow keys, or moved by undo, redo or reset (events.drag).	The element, with position: { moveX, moveY }, its offset in pixels, and action: "drag", "nudge", "undo", "redo" or "reset".
dragmove	An element is being moved.	The element, with position.
moves	Several elements were moved in one step.	{ action, moves }: moves is an array of what drag reports.
zoom	The zoom window changed (events.zoom).	mode, start, end, zoomed, range (null when everything shows), clusters ({ cluster, start, end }, the base pairs each shows) and action: "drag", "keyboard", "reset", "set" (zoomTo()) or "render".
rendered	The chart was drawn (events.rendered).	id (events.renderId, or one made for each draw), chartId, width and height in pixels.

An element, as click, dblclick, select and selection report it:

Field	Description
component	The part of the chart: "genes", "transcript", "labels", "coordinates", "links", "legend", "scale", "scaleBar", "sequence", "title", "clusterTitle", "clusterFooter", "clusterLabel" or "annotations".
cluster	The cluster's name; null for the chart title, the legend and links between clusters.
data	The gene's row for genes, transcripts and labels, the link's row for links, the group for the legend; otherwise null.
part	"title" or "subtitle" of a title, cluster title, footer or label; "label" or "marker" in the legend.
style	How a selectable element is drawn, with the names of elementStyle options, so an editor can show the current values.

The TypeScript types give each event's detail: ChartEventDetails in geneviewer.d.ts.

Builds

File	Format	D3	For
geneviewer.min.js	Script tag, global geneviewer; minified, source map	included	CDNs and plain HTML pages
geneviewer.mjs	ES module (import ... from "geneviewer-js")	imported from npm	Bundlers
geneviewer.standalone.mjs	ES module (geneviewer-js/standalone), minified	included	Browser import, Jupyter
geneviewer.core.js	Script tag, not minified	the page's d3	The R package
geneviewer.css	Stylesheet		Pages that turn off injectStyles
geneviewer.d.ts, spec.d.ts	TypeScript types		Editors and TypeScript

Versions

• Library: semantic versioning from 1.0. While on 0.x, minor versions may change the API.
• Spec: the optional version key. A spec without one is version 1, the only version so far. A spec with a newer version than the library knows is drawn as far as possible, with a warning in the console.
• Not part of spec v1: the output of compile(), and the settings in geneviewer.themes. Theme and palette names are.