Ideogram API reference

March 7, 2024 ยท View on GitHub

Ideogram.js is a JavaScript library for chromosome visualization. Ideogram supports drawing and animating genome-wide datasets. Its API consists of configuration options and methods. You can see examples of almost all these options and methods -- as well as their actual effect -- in the many live examples. Simply "View source" in any example page.

Installation

See the main README for installation instructions.

Configuration

To start, you need to instantiate the Ideogram class. Configuration options -- which organism's genome to display, in what orientation, with which annotation data, etc. -- are passed into the Ideogram constructor as a JavaScript object.

For example:

var ideogram = new Ideogram({
  organism: 'human',
  annotations: [{
    name: 'BRCA1',
    chr: '17',
    start: 43044294,
    stop: 43125482
  }]
});

Options

accessToken

String. Optional. OAuth 2.0 access token. Enables authentication and authorization. This can be useful for controlling access to private annotation data.

ancestors

Object. Optional. A map associating ancestor labels to colors. Used to color chromosomes from different ancestors in polyploid genomes. Example in Ploidy, recombination.

annotations

Array. Optional. A list of annotation objects. Each annotation object has at least a chromosome name (chr), start coordinate (start), and stop coordinate (stop). Annotation objects can also have a name, color, shape, track index and placement. Positive placement brings the annotations to the bottom/left of the chromosome, whilst negative placement brings it to the top/right. Example in Annotations, basic.

See also annotationsPath.

annotationHeight

Number. Optional. The height of each annotation. Example in Annotations, tracks.

annotationsColor

String. Optional. Default: "#F00" (i.e., red). The color of each annotation. Example in Multiple, primates.

annotationsLayout

String. Optional. Default: "tracks".

The layout of this ideogram's annotations. One of "tracks", "heatmap", "histogram", or "overlay".

annotationsLayout: 'span'

Lay out annotations in spanning tracks beside each chromosome. There can be more than one track, which is useful for displaying annotations by category (e.g. pathogenic, unknown significance, benign). Example in Annotations, span.

annotationsLayout: 'tracks'

Lay out annotations in tracks beside each chromosome. There can be more than one track, which is useful for displaying annotations by category (e.g. pathogenic, unknown significance, benign). Example in Annotations, tracks.

annotationsLayout: 'heatmap'

Lay out annotations in heatmap beside each chromosome. Plot individual annotations like annotationsLayout: 'tracks', with the scalability of annotationsLayout: 'histogram'. Each chromosome can have one or more heatmap tracks. Use with the heatmaps configuration option. Example in Annotations, heatmap.

annotationsLayout: 'heatmap-2d'

Lay out annotations in a two-dimensional zheatmap beside a single chromosome. Enables visualizing raw data summarized in annotationsLayout: 'heatmap'. Example in Annotations, 2D heatmap.

annotationsLayout: 'histogram'

Lay out annotations in a histogram. This clusters annoatations by location, such that each cluster or bin is shown as a bar. The height of the bar represent the number of annotations in that genomic range. This option is useful for summarizing the distribution of many (1000+) features througout the genome. Example in Annotations, histogram.

annotationsLayout: 'overlay'

Lay out annotations directly over chromosomes. This is the most space-efficient annotation layout option. Example in Annotations, overlaid.

annotationsPath

String. Optional. An absolute or relative URL to a JSON file containing annotation objects. Example in Annotations, overlaid.

See also annotations.

annotationTracks

Array. Optional. A list of objects with metadata for each track, e.g. DOM id, display name, color, shape, placement. Example in Annotations, tracks. If placement is not specified, it is assigned the trackIndex by default. Positive placement brings the annotations to the bottom/left of the chromosome, whilst negative placement brings it to the top/right. The placement of the histogram should have the largest number (either positive or negative) to avoid overlapping of tracks. Example in Annotations, spanning heatmap and histogram.

assembly

String. Optional. Default: latest RefSeq assembly for specified organism. The genome assembly to display. Takes assembly name (e.g. "GRCh37"), RefSeq accession (e.g. "GCF_000306695.2"), or GenBank accession (e.g. "GCA_000005005.5"). Example in Annotations, histogram.

barWidth

Number. Optional. Default: 3. The pixel width of bars drawn when annotationsLayout: 'histogram'. Example in Annotations, histogram.

brush

String. Optional. Default: null. Genomic coordinate range (e.g. "chr1:104325484-119977655") for a brush on a chromosome. Useful when ideogram consists of one chromosome and you want to be able to focus on a region within that chromosome, and create an interactive sliding window to other regions. Example in Brush.

chrBorderColor

String. Optional. Default: "#000". The color of the border for each chromosome.

chrFillColor

String or Object. Optional. Default: "#AAA". The color with which the chromosome is filled; its interior color. Customizes chromosome arm color if specified as string, e.g. chrFillColor: 'green'. Customizes chromosome arm and centromere colors if specified as object, e.g. chrFillColor: {arm: '#AEA', centromere: '#EEA '}. Example in Color, chromosomes.

chrHeight

Number. Optional. Default: 400. The pixel height of the tallest chromosome in the ideogram. Examples in Layout, small and Annotations, basic.

chrMargin

Number. Optional. Default: 10. The pixel space of the margin between each chromosome. Example in Multiple, primates.

chrWidth

Number. Optional. Default: 10. The pixel width of each chromosome. Example in Annotations, tracks.

chrLabelColor

String. Optional. Default: "#000". The color of the label for each chromosome.

chrLabelSize

Number. Optional. Default: 9. The pixel font size of chromosome labels. Example in Differential expression of genes.

chromosomes

Array. Optional. Default: all chromosomes in assembly. A list of the names of chromosomes to display. Useful for depicting a subset of the chromosomes in the genome, e.g. a single chromosome. Example in Annotations, basic.

chromosomeScale

String. Optional. Default: absolute. Either "absolute" or "relative". Used when comparing multiple genomes. If absolute, chromosomes will be scaled by base pairs in each genome. If relative, the first chromosme in each genome will be of equal length, and subsequent chromosomes will be scaled relative to the first chromosome.

container

String. Optional. Default: "body". CSS selector of the HTML element that will contain the ideogram. Example in Layout, small.

dataDir

String. Optional. Default: "../data/bands/native/". Absolute or relative URL of the directory containing data needed to draw banded chromosomes. Example in GeneExpressionAging/ideogram.

demarcateCollinearChromosomes

Boolean. Optional. Default: true. Whether to demarcate colllinear chromosomes. Puts a dark border around the perimeter of each track-chromosomes block in track sets for chromosomes arranged in collinear geometry. Example in Geometry, collinear.

geometry

String. Optional. Use "geometry: collinear" to arrange all chromosomes in one line, unlike the usual parallel view. Example in Geometry, collinear.

histogramScaling

String. Optional. Default: "absolute". One of "absolute" or "relative". The technique to use in scaling the height of histogram bars. The "absolute" value sets bar height relative to tallest bar in all chromosomes, while "relative" sets bar height relative to tallest bar in each chromosome.

heatmaps

Array. Optional. Array of heatmap objects. Each heatmap object has a key string and a thresholds array. The key property specifies the annotations key value to depict in the heatmap. The thresholds property specifies a list of two-element "threshold" lists, where the first element is the threshold value and the second is the threshold color. The threshold values are a list of ranges to use in coloring the heatmap. Threshold values are specified in ascending order. Example in Annotations, heatmap.

filterable

Boolean. Optional. Whether annotations should be filterable. Example in Annotations, histogram.

fontFamily

String. Optional. The font family to use for text in the ideogram, e.g. fontFamily: "'Montserrat', sans-serif".

fullChromosomeLabels

Boolean. Optional. Whether to include abbreviation species name in chromosome label. Example in Homology, interspecies.

legend

Array. Optional. List of objects describing annotations. Example in Annotations, tracks.

onBrushMove

Function. Optional. Callback function to invoke when brush moves. Example in Brush.

onDidRotate

Function. Optional. Callback function to invoke after chromosome has rotated.

onDrawAnnots

Function. Optional. Callback function to invoke when annotations are drawn. This is useful for when loading and drawing large annotation datsets. Example in web-tests.js.

onLoad

Function. Optional. Callback function to invoke when chromosomes are loaded, i.e. rendered on the page. Example in Annotations, external data.

onLoadAnnots

Function. Optional. Callback function to invoke when annotations are downloaded and ready for data transformation.

onWillShowAnnotTooltip

Function. Optional. Callback function to invoke immediately before annotation tooltip is shown. The tooltip shows the genomic range and, if available, name of the annotation. This option can be useful to e.g. enhance the displayed annotation name, say by transforming a gene name into a hyperlink to a gene record web page. Example in Annotations, external data.

organism

String or number or array. Required. Organism(s) to show chromosomes for. Supply organism's name as a string (e.g. "human") or organism's NCBI Taxonomy ID (taxid, e.g. 9606) to display chromosomes from a single organism, or an array of organisms' names or taxids to display chromosomes from multiple species or other taxa. Example in Human.

orientation

String. Optional. Default: vertical. The orientation of chromosomes on the page. Example in Mouse.

perspective

String. Optional. Use perspective: 'comparative' to enable annotations between two chromosomes, either within the same organism or different organisms. Examples in Homology, basic and Homology, interspecies.

ploidy

Number. Optional. Default: 1. The ploidy, i.e. number of chromosomes to depict for each chromosome set. Useful for more biologically accurate rendering of genomes that are diploid, triploid, etc. Example in Ploidy, basic.

ploidyDesc

Array. Optional. Description of ploidy in each chromosome set in terms of ancestry composition. Example in Ploidy, recombination.

rangeSet

Array. Optional. List of objects describing segments of recombination among chromosomes in a chromosome set. Example in Ploidy, recombination.

resolution

Number. Optional. Default: highest resolution available for specified genome assembly. The resolution of cytogenetic bands to show for each chromosome. The quantity refers to approximate value in bands per haploid set (bphs). One of 400, 550, or 850. Example in Layout, small.

See also: showFullyBanded.

rotatable

Boolean. Optional. Default: true. Whether chromosomes are rotatable upon clicking them. Example in Layout, small.

rows

Number. Optional. Default: 1. Number of rows to arrange chromosomes into. Useful for putting ideogram into a small container, or when dealing with genomes that have many chromosomes. Example in Layout, small.

sex

String. Optional. Default: male. The biological sex of the organism. Useful for omitting chromosome Y in female mammals. Currently only supported for organisms that use XY sex-determination. Examples in Ploidy, basic.

showBandLabels

Boolean. Optional. Default: false. Whether to show cytogenetic band labels, e.g. 1q21. Example in Annotations, basic.

showChromosomeLabels

Boolean. Optional. Defaut: true. Whether to show chromosome labels, e.g. 1, 2, 3, X, Y. Example in Annotations, basic.

showAnnotTooltip

Boolean. Optional. Default: true. Whether to show a tooltip upon mousing over an annotation. Example in Multiple, trio SV.

showFullyBanded

Boolean. Optional. Default: true. Whether to show fully banded chromosomes for genomes that have sufficient data. Useful for showing simpler chromosomes of cytogenetically well-characterized organisms, e.g. human, beside chromosomes of less studied organisms, e.g. chimpanzee. Example in Multiple, primates.

See also: resolution.

showNonNuclearChromosomes

Boolean. Optional. Default: false. Whether to show non-nuclear chromosomes, e.g. for mitochondrial (MT) and chloroplast (CP) DNA. Example in Eukaryotes: Sus scrofa.