d3ndro

Interactive Hierarchical Clustering Vizualization Using D3 & R.

Outline

Features
Installation
Demonstration
Usage
Configuration
- Options
- Events
Citing

Features

Collapsible d3ndrogram (see Configuration)
Colored leaf nodes (per datum via callback)
Colored text labels
Quick Scrolling Navigation
Simple Integration with R's hclust function

Installation

Installing is as simple as including this in your html document:

<script src="https://cdn.jsdelivr.net/npm/d3ndro@1.0.0/dist/d3ndro.js"></script>

Alternatively, if you use npm, you can install it using the following command:

npm install d3ndro

Demonstration

You can see a demonstration of this library by cloning the repo and running any simple webserver in the root directory. I personally prefer python's SimpleHTTPServer.

python -m SimpleHTTPServer 8888

Then open http://localhost:8888/demo in your favorite web browser.

Usage

This visualization tool is meant to be used in conjunction with R's hclust function. See src/hclust2json.R for an hclust2json function that exports d3ndro-compatible JSON.

Once you have generated the JSON from R, you'll need to bring it into your web page using d3. If you aren't using d3 elsewhere in your project, you can use d3ndro.d3 to access d3's functions. See the demo source code for an example.

Configuration

Options

The d3ndro package offers easy configuration options available through d3ndro.options. To set, just edit the global d3ndro.options object before calling any other functions. I recommend placing configuration options in the same script tag that you use to include d3ndro if you use a script tag to include d3ndro.

Here is a table of all of the options for d3ndro. To see default functiond definitions, look at src/options.js.

Option	Description	Default
d3ndro.options.backgroundColor	Function returning the background color for the d3ndrogram plot. Function can take parsedJSON as a parameter.	See src/options.js
d3ndro.options.collapsible	Determines whether internal tree nodes should collapse children into them when clicked (and uncollapse when clicked again).	`undefined // (false)`
d3ndro.options.fontSize	Font size for leaf labels and axes text.	`16`
d3ndro.options.highlightOnHover	Determines whether the path through the tree to the current leaf node should be highlighted when the mouse is over the leaf node	`undefined // (false)`
d3ndro.options.internalNodeRadius	Size of the internal (non-leaf) nodes in the tree.	`4`
d3ndro.options.itemColor	Function to determine color of leaf nodes. Can take datum (d) as an argument. See the demo for more deatils.	See src/options.js
d3ndro.options.labelSpace	Function returning space allocated for each leaf node/label in pixels. Function can take parsedJSON as a parameter.	See src/options.js
d3ndro.options.leafNodeRadius	Radius of the leaf node circles in pixels.	`5`
d3ndro.options.mergeColor	Function returning the color of internal (non-leaf) nodes and connections in the tree. Function can take a merge node datum and index as arguments.	See src/options.js
d3ndro.options.padding	Number of pixels to offset the dendrogram from the edge.	`24`
d3ndro.options.spacing	Space to put between each leaf node/label.	`24`
d3ndro.options.svgHeight	Height of the SVG element conaining the d3ndrogram.	`400`
d3ndro.options.svgOverflow	Function returning the CSS Policy for when the d3ndrogram is larger than the width. See this tutorial for more information. Function can take parsedJSON as a parameter.	See src/options.js
d3ndro.options.textColor	Function returning the color for label text. Function can take a leaf datum as an argument.	See src/options.js

Events

The d3ndro package also exposes events using jQuery for convenience of integration. See the demo for an example on how to listen to events. For your reference, a list of all exposed d3ndro events has been given below:

Event	Description	Location
`d3ndro:leaf:click`	When a leaf node is clicked.	src/interaction/collapse.js
`d3ndro:collapse`	When an internal node is collapsed.	src/interaction/collapse.js
`d3ndro:uncollapse`	When a collapsed internal node is expanded.	src/interaction/collapse.js
`d3ndro:highlight`	When a path to a leaf node is highlighted.	src/interaction/highlight.js
`d3ndro:flash`	When a path to a leaf node is emboldened temporarily through animation.	src/interaction/highlight.js
`d3ndro:unhighlight`	When highlighting is removed from a path to a leaf node.	src/interaction/highlight.js
`d3ndro:groupHighlight`	When group highlighting is toggled on an internal (non-leaf) node.	src/interaction/highlight.js
`d3ndro:scroll`	When automatic scrolling to a leaf node is invoked.	src/interaction/scroll.js

Citing

If you find this useful, please consider citing the work which inspired it:

Baker, F.N. and Porollo, A., 2018. CoeViz: A Web-Based Integrative Platform for Interactive Visualization of Large Similarity and Distance Matrices. Data, 3(1), p.4. https://doi.org/10.3390/data3010004

frazierbaker / d3ndro