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.
See the main README for installation instructions.
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
}]
});
String. Optional. OAuth 2.0 access token. Enables authentication and authorization. This can be useful for controlling access to private annotation data.
Object. Optional. A map associating ancestor labels to colors. Used to color chromosomes from different ancestors in polyploid genomes. Example in Ploidy, recombination.
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, and track index. Example in Annotations, basic.
See also annotationsPath.
Number. Optional. The height of each annotation. Example in Annotations, tracks.
String. Optional. Default: “#F00” (i.e., red). The color of each annotation. Example in Multiple, primates.
String. Optional. Default: “tracks”.
The layout of this ideogram’s annotations. One of “tracks”, “heatmap”, “histogram”, or “overlay”.
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.
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.
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.
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.
Lay out annotations directly over chromosomes. This is the most space-efficient annotation layout option. Example in Annotations, overlaid.
String. Optional. An absolute or relative URL to a JSON file containing annotation objects. Example in Annotations, overlaid.
See also annotations.
Array. Optional. A list of objects with metadata for each track, e.g. DOM id, display name, color, shape. Example in Annotations, tracks.
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.
Number. Optional. Default: 3. The pixel width of bars drawn when annotationsLayout: 'histogram'. Example in Annotations, histogram.
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.
String. Optional. Default: “#000”. The color of the border for each chromosome.
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.
Number. Optional. Default: 400. The pixel height of the tallest chromosome in the ideogram. Examples in Layout, small and Annotations, basic.
Number. Optional. Default: 10. The pixel space of the margin between each chromosome. Example in Multiple, primates.
Number. Optional. Default: 10. The pixel width of each chromosome. Example in Annotations, tracks.
String. Optional. Default: “#000”. The color of the label for each chromosome.
Number. Optional. Default: 9. The pixel font size of chromosome labels. Example in Differential expression of genes.
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.
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.
String. Optional. Default: “body”. CSS selector of the HTML element that will contain the ideogram. Example in Layout, small.
String. Optional. Default: “../data/bands/native/”. Absolute or relative URL of the directory containing data needed to draw banded chromosomes. Example in GeneExpressionAging/ideogram.
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.
String. Optional. Use “geometry: collinear” to arrange all chromosomes in one line, unlike the usual parallel view. Example in Geometry, collinear.
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.
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.
Boolean. Optional. Whether annotations should be filterable. Example in Annotations, histogram.
String. Optional. The font family to use for text in the ideogram, e.g. fontFamily: "'Montserrat', sans-serif".
Boolean. Optional. Whether to include abbreviation species name in chromosome label. Example in Homology, interspecies.
Array. Optional. List of objects describing annotations. Example in Annotations, tracks.
Function. Optional. Callback function to invoke when brush moves. Example in Brush.
Function. Optional. Callback function to invoke after chromosome has rotated.
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.
Function. Optional. Callback function to invoke when chromosomes are loaded, i.e. rendered on the page. Example in Annotations, external data.
Function. Optional. Callback function to invoke when annotations are downloaded and ready for data transformation.
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.
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.
String. Optional. Default: vertical. The orientation of chromosomes on the page. Example in Mouse.
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.
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.
Array. Optional. Description of ploidy in each chromosome set in terms of ancestry composition. Example in Ploidy, recombination.
Array. Optional. List of objects describing segments of recombination among chromosomes in a chromosome set. Example in Ploidy, recombination.
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.
Boolean. Optional. Default: true. Whether chromosomes are rotatable upon clicking them. Example in Layout, small.
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.
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.
Boolean. Optional. Default: false. Whether to show cytogenetic band labels, e.g. 1q21. Example in Annotations, basic.
Boolean. Optional. Defaut: true. Whether to show chromosome labels, e.g. 1, 2, 3, X, Y. Example in Annotations, basic.
Boolean. Optional. Default: true. Whether to show a tooltip upon mousing over an annotation. Example in Multiple, trio SV.
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.
Boolean. Optional. Default: false. Whether to show non-nuclear chromosomes, e.g. for mitochondrial (MT) and chloroplast (CP) DNA. Example in Eukaryotes: Sus scrofa.