blackHole.js

Introduce

This library is child of two projects:

• WorldBank Contract Awards
• GitHub Visualizer

The main objective of this library is the visualization of data that change over time. Suitable for the visualization of such data as:

• Commits history (GitHub Visualizer)
• Economic Indicators (Distribution of Russian budget 2013, LuckyLunch)
• Network attacks (NetMonitor)
• And etc.

Depends on D3js

Structure

• Quick Example
• Documentation
  • Properties
  • Settings
  • Methods
  • Realtime Mode
  • Node object
    • Parent node
    • Child node
  • Category object
• For developers

## Quick Examples

For fast look Example I

We have data (generated by script):

[
  {
    "key": 119,
    "category": "nemo,",
    "parent": {
      "name": "cumque5",
      "key": 5
    },
    "date": "2014-01-29T15:39:45.340Z"
  },
  {
    "key": 96,
    "category": "nemo,",
    "parent": {
      "name": "cumque5",
      "key": 5
    },
    "date": "2014-01-29T19:56:18.885Z"
  },
  {
    "key": 125,
    "category": "nemo,",
    "parent": {
      "name": "cumque5",
      "key": 5
    },
    "date": "2014-01-30T01:00:53.648Z"
  },
  {
    "key": 51,
    "category": "nemo,",
    "parent": {
      "name": "eveniet1",
      "key": 1
    },
    "date": "2014-01-30T06:46:51.531Z"
  },
  {
    "key": 237,
    "category": "nemo,",
    "parent": {
      "name": "cumque5",
      "key": 5
    },
    "date": "2014-01-30T12:25:14.810Z"
  },
  //...
]

And code:

<div id="canvas"></div>
<script src="http://d3js.org/d3.v3.min.js"></script>
<script src="http://lib.artzub.com/js/blackhole.js/blackhole.js"></script>
<script>
var data = rawData.map(function(d) {
        d.date = new Date(d.date);
        return d;
    })
    , stepDate = 864e5
    , d3bh = d3.blackHole("#canvas")
    ;

d3bh.setting.drawTrack = true;

d3bh.on('calcRightBound', function(l) {
        return +l + stepDate;
    })
    .start(data)
    ;
</script>

## Documentation

For creation instance of the blackHole object, need call method of the d3js object

var bh = d3.blackHole('#canvas');

d3.blackHole([node])

node — or a selector, or a dom node, or a d3 node (default: document.body)
returning the blackHole object

Next describe the properties and methods of the blackHole object.

Properties

• bh.setting.version — the version of library
• bh.setting.setting — object with fields of settings

Settings

All fields can change dynamic.

For try how to work setting look this example II
also try this dataset

• Items

  • bh.setting.alpha — uses for calculation cluster (default: 0.025)
  • bh.setting.childLife — number of ticks of life a child node (default: 255)
  • bh.setting.parentLife — number of ticks of life a parent node, after the death of all children (default: 255)
  • bh.setting.rateOpacity — rate of decrease of opacity (default: .5)
  • bh.setting.rateFlash — rate of decrease of flash effect (default: 2.5)
  • bh.setting.padding — padding of parent (default: 25)

• Behavior

  • bh.setting.skipEmptyDate — skips empty dates (default: true).

    if after filtering data, an array is empty then it steps on next date.

  • bh.setting.realtime — indicates that need work in mode realtime (default: false).

    more info realtime mode
    This parameters must be initialized before starting visualization.

  • bh.setting.asyncParsing — parsing data in async mode (default: false).

    If param is true, then will work method .on('parsing')
    This parameters must be initialized before starting visualization.

  • bh.setting.speed — sets milliseconds for setInterval of method filtering data (default: 1000)

    This parameters must be initialized before starting visualization.
    After need use speed method

  • bh.setting.increaseChildWhenCreated — increase children nodes when they are created (default: false)

  • bh.setting.increaseChild — should children nodes increase size (default: true)

  • bh.setting.createNearParent — create children nodes near they parents (default: false)

• Drawing

  • bh.setting.blendingLighter — if true, then sets the property compositeOperation of canvas in the 'lighter' value (default: true)
  • bh.setting.drawEdge — drawing edges (default: false)
  • bh.setting.drawChild — drawing children nodes (default: true)
  • bh.setting.drawChildLabel — drawing labels of children nodes (default: false)
  • bh.setting.drawParent — drawing parents nodes (default: true)
  • bh.setting.drawParentLabel — drawing labels of parents nodes (default: true)
  • bh.setting.drawPaddingCircle — drawing padding circles of parents nodes (default: false)
  • bh.setting.drawHalo — drawing the halo effect of children nodes (default: true)
  • bh.setting.drawTrack — drawing track of children nodes (default: false)
  • bh.setting.drawAsPlasma — drawing children nodes uses plasma effect (default: true)
  • bh.setting.drawParentImg — drawing images of parents nodes (default: true)
  • bh.setting.hasLabelMaxWidth — if true, then uses the maxWidth argument into the fillText method, in other words, text zooming based on the max width of canvas. (default: true)

• Colors

  • bh.setting.colorless — a color for bleaching (default: rgb(128, 128, 128))

  • bh.setting.colorlessFlash — a color for bleaching when using the flash effect (default: rgb(211, 211, 211))

  • bh.setting.parentColors — colors of parents nodes (default: d3.scale.category20b())

    it is a d3.scale.ordinal object, can initialised as d3.scale.ordinal.domain(['pie', 'roll', ...]).range(['red', 'blue', ...])
    more about d3 category

  • bh.setting.categoryColors — colors of children nodes categories (default: d3.scale.category20())

• Zoom and drag

  • bh.setting.zoomAndDrag — enable zooming and dragging canvas (default: true)
  • bh.setting.zoom — a function d3.zoom (default: generate when start visualization)
  • bh.setting.scaleExtent — scale extent for d3.zoom (default: [.1, 8])

  Following settings must be initialized before starting, after need using methods with the same names

  • bh.setting.scale — initial scale for d3.zoom (default: 1)
  • bh.setting.translate — initial translate for d3.zoom (default: [0, 0])

Methods

Most of the methods returning blackHole object in order to use chain.

• bh.start(inData [, width[, height[, reInitData[, callback]]]])

  running the dynamic visualization, also using for restart the visualization.

  inData {Array} — an array of source data
  width {Number} — width of canvas that will be created (default: parentNode.width)
  height {Number} — height of canvas that will be created (default: parentNode.height)
  reInitData {Boolean} — reinitializing source data
  callback {Function} — callback method. Mainly used if use start method when visualizing is ran

  return blackHole object

• bh.stop()

  Stop a running visualization
  After using this method resume will not work, need use start
  return blackHole object

• bh.pause()

  Pause a running visualization
  return blackHole object

• bh.resume()

  Resume a paused visualization
  return blackHole object

• bh.append(array)

  Append source data into visualization collection with using parsing. array {Array} — array of new source data
  This method is effective if realtime is true, but can used anytime
  more info realtime mode

  return backHole object

• bh.IsRun()

  Returning the true if a visualization is paused or running

• bh.IsPaused()

  Returning the true if a visualization is paused

---

• bh.selectNode([node])

  Gets or sets a selected node.
  node — node object
  If called without arguments then returns the selected node,
  else sets the selected node and returns blackHole object.

  If set the selected node, then colors of nodes will be colorless,
  if a category of a node is not equals a category of the selected node.

• bh.selectCategory([category])

  Gets or sets a selected category
  category — category object
  If called without arguments then returns the selected category,
  else sets the selected node and returns blackHole object.

  If set the selected category, then colors of nodes will be colorless,
  if a category of a node is not equals the selected category.

• bh.frozenCategory([category])

  Gets or sets a frozen category
  category — category object
  If called without arguments then returns the frozen category,
  else sets the frozen node and returns blackHole object.

  If set the frozen category, then nodes will be hidden,
  if a category of a node is not equals the frozen category.

---

• bh.parents([arg])

  Gets or sets d3_Map object of parents nodes
  arg — must be or hash object, or d3_Map object where a key is a key field of a parent node

  If called without arguments then returns the d3_Map object of patents nodes
  else sets patents nodes and returns blackHole object.

• bh.children([arg])

  Gets or sets d3_Map object of children nodes
  arg — must be or hash object, or d3_Map object where a key is a key field of a child node

  If called without arguments then returns the d3_Map object of children nodes
  else sets children nodes and returns blackHole object.

• bh.categories([arg])

  Gets or sets d3_Map object of categories
  arg — must be or hash object, or d3_Map object where a key is a key field of a category

  If called without arguments then returns the d3_Map object of categories
  else sets categories and returns blackHole object.

---

• bh.sort([func])

  Gets or sets a sort function for source data
  func {Function} — function(a, b) {}, a and b are two source nodes value (default function)

  If called without arguments then returns a sort function
  else sets a sort function and returns blackHole object.

• bh.filter([func])

  Gets or sets a filter function for source data
  func {Function} — function(l, r) {}, l and r are the left and the right bounds of filtering (default function)

  If called without arguments then returns a filter function
  else sets a filter function and returns blackHole object.

---

• bh.speed([milliseconds])

  Gets or sets a speed of visualization on milliseconds
  milliseconds {Number}
  If called without arguments then returns current speed
  else sets a speed and returns blackHole object.

• bh.size([array])

  Gets and sets a size for canvas
  array {Array} — [w, h] the new size of canvas
  This method used for resizing canvas

  If called without arguments then returns current size
  else sets a size and returns blackHole object.

• bh.style(name [, value[, priority]])

  Wrapper for d3.style but apply only the main canvas node.

• bh.scale([scale])

  Gets and sets a scale for d3.zoom
  scale {Number}

  If called without arguments then returns current scale
  else sets a scale and returns blackHole object.

• bh.translate([array])

  Gets and sets a translate for d3.zoom
  array {Array} — [x, y] the coordinate of point for translate

  If called without arguments then returns current translate
  else sets a translate and returns blackHole object.

• bh.getCanvas()

  Returns the main canvas or null, if the visualization is not running.

---

Complex example using maps

• bh.on(key [, value])

  key — a string value form keys
  value — a function

  • Action signals

  key	value	description
  calcRightBound	function(leftBound)
  getChildLabel	function(sourceItem)
  getParentLabel	function(parentNodeItem)
  getSelectedColor	function(nodeItem)
  getVisibleByStep	function(nodeItem)
  getCreateNearParent	function(sourceItem, nodeItem)
  getCategoryKey	function(sourceItem)
  getCategoryName	function(sourceItem)
  getChildKey	function(sourceItem)
  getParent	function(sourceItem)
  getParentKey	function(sourceParentItem)
  getParentImage	function(sourceParentItem)
  getGroupBy	function(sourceItem)
  getValue	function(sourceItem)
  getParentRadius	function(parentNodeItem)
  getChildRadius	function(nodeItem)
  getParentPosition	function(sourceParentItem)
  getParentFixed	function(sourceParentItem)

  • Event signals

  key	value	description
  beforeParsing	function(sourceData)
  parsing	function(nodeItem)
  afterParsing	function(nodesCollection)
  processing	function(currentItems, leftBound, rightBound)
  processed	function(currentItems, leftBound, rightBound)
  stopped	function()
  finished	function(leftBound, rightBound)
  starting	function()
  started	function()
  mouseOverNode	function(nodeItem, d3event)
  mouseMove	function(nodeItem, d3event)
  mouseOutNode	function(nodeItem, d3event)
  particleAtTarget	function(nodeItem, parentNodeItem)

Realtime Mode

bh.setting.realtime bh.append(array)

Node object

Parent node

Child node

Category object

## For developers

If you want to modify blackHole.js, click the "Fork" button in the top-right corner of this page, and then clone your fork from the command line by replacing username with your GitHub username:

git clone git://github.com/username/blackhole.js.git

On the other hand, if you want to extend blackHole with new features, fix bugs, or run tests, you should fork the blackHole repository, and install Node.js (version 0.10.x or higher). From the root directory of this repository, you can then install blackHole's dependencies:

npm install

For make:

make full