Deprecated: How to Embed Next-Generation Clustered Heat Maps

ngchm

Next-Generation Clustered Heat Maps (NG-CHMs) can now be embedded in an HTML page.

This page describes a deprecated implementation of embeddable maps.

New embeddings should use the new implementation.

What are Embedded Next-Generation Clustered Heat Maps?

Figure 1: Heatmap of Gene Expression for TCGA ACC.

When the HTML page is opened, a thumbnail image is displayed as a placeholder, as shown in Figure 1. When the user hovers over the thumbnail, an Expand Map graphic is superimposed on the thumbnail image. Clicking on the expand map graphic will load the NG-CHM into the browser, expand the thumbnail into a large, interactive NG-CHM that the user can explore as they would any other NG-CHM. Clicking the Collapse Map button on the top-left will hide the NG-CHM and redisplay the thumbnail.

The author of the web page decides where to include the thumbnail/heatmap, the image to use for the thumbnail, and the size of the thumbnail. The size and position of the NG-CHM can be tailored to the page using CSS styling.

What you need

  1. One or more standalone NG-CHMs. The interactive web builder, the Galaxy NG-CHM builder, and the NG-CHM package for R can all directly generate a standalone NG-CHM. Alternatively, you save any NG-CHM by selecting Save Heat Map Changes from the hamburger menu, perhaps after changing various display parameters (such as the color scheme, etc.).

  2. A copy of ngchmWidget-min.js, at least version 2.5.2. By default it is expected to reside in the same directory/folder as the HTML page, but with a little extra effort it can be loaded from anywhere (including directly from the previous link).

  3. A thumbnail image for the NG-CHM.

Basic Embedding

This section describes the minimum steps required to embed an NG-CHM. It requires that the HTML page have a simple structure and that the NG-CHM, the thumbnail, and ngchmWidget-min.js all reside in the same directory/folder as the HTML page. Also, the NG-CHM file should have extension .ngchm and the thumbnail’s file is the same with .ngchm replaced by .png.

  1. Include ngchmWidget-min.js in the page header: 

    <script type='text/Javascript' src='ngchmWidget-min.js'></script>

  2. Create a DIV element in the page with id “NGCHM”: 

    <DIV id='NGCHM'></DIV>

  3. After the DIV element has been defined, call NgChm.UTIL.embedExpandableMap: 

    <script type='text/Javascript'>
NgChm.UTIL.embedExpandableMap({ ngchm: 'NGCHM-file-name.ngchm' })
</script>
    The function takes as its only parameter a structure that contains a single mandatory field “ngchm”, the value of which is the URL for downloading the standalone NG-CHM to be displayed. (Replace the value above with a URL for your NG-CHM.)

An HTML template containing these elements is available for download.

Specifying the thumbnail URL

The URL for the thumbnail image is obtained by replacing “.ngchm” with “.png”. Alternatively, you can specify a different URL by including the optional field “thumbnail”: 

<script type='text/Javascript'>
NgChm.UTIL.embedExpandableMap({ ngchm: 'NGCHM-file-name.ngchm', thumbnail: 'some-other-path.png' })
</script>

Specifying the thumbnail width and height

The width of the thumbnail image defaults to 150px. A different width can be specified by the optional field “thumbnailWidth”. 

<script type='text/Javascript'>
NgChm.UTIL.embedExpandableMap({ ngchm: 'NGCHM-file-name.ngchm', thumbnailWidth: '200px' })
</script>

The height of the thumbnail image defaults to its width. A different height can be specified by the optional field “thumbnailHeight”.

Specifying the DIV element to use

The id of the DIV element in which to insert the NG-CHM defaults to “NGCHM”. You can specify a different id with the optional field “divId”: 

<script type='text/Javascript'>
NgChm.UTIL.embedExpandableMap({ ngchm: 'NGCHM-file-name.ngchm', divId: 'mydiv' })
</script>

Embedding multiple NG-CHMs in a page

You can include multiple embedded NG-CHMs in a page by including multiple divs with different ids.

Including ngchmWidget-min.js from a different location

When an embeddded NG-CHM is expanded, it must include ngchmWidget-min.js from a known location, which by default is the same directory/folder as the HTML page. If you include ngchmWidget-min.js from another location, you must also inform the NG-CHM system of that location.

You can set that location for a single NG-CHM with the optional field “ngchmWidget”.

Alternatively, you can set the default location using NgChm.UTIL.setNgchmWidget: 

<script type='text/Javascript'>
NgChm.UTIL.setNgchmWidget('url-for-ngchm-Widget-min.js');
</script>
The specified URL will be used for all subsequent calls to embedExpandableMap.

Controlling the appearance of the expanded NG-CHM

The default appearance of the expanded NG-CHM is fairly basic. You can modify its appearance using CSS styling. The embedded NG-CHM and thumbnail are included inside an iframe element. When the iframe element is displaying the thumbnail it has class “ngchmThumbnail”. When it is displaying an expanded NG-CHM it has class “ngchm”.

This page uses CSS rules for these classes similar to the following: 

.ngchm {
    position: fixed;
    top: 0;
    left: 0;
    padding: 0.5em;
    background-color: white;
}



.ngchmThumbnail {
    padding: 0.25em;
}

Authors