Skip to content

SmokeChart Usage Guide

Jump to bottom
asergeyev edited this page Apr 10, 2012 · 9 revisions

This is a version that's not even a "beta," please do not expect API to be same in further releases.

See examples at dyninc.github.com/d3-smokechart/

Basic Usage

var smoke = new SmokeChart('#mydiv',svg_width,svg_height,x_value_count,max_y_value);
smoke.addLine('traffic', mydata, "#900", "#999")
   .addGuide('zero', 0, '#000')
   .addGuide('capacity', 160000, '#f00')
   .showLabels(['6:00', '12:00', '18:00', '0:00']);

Idea is simple: ask for a chart, put some lines, labels and guidelines. You may also dynamically change your chart content using functions described below.

Constructor

new SmokeChart(dom_locator,svg_width,svg_height,x_value_count,max_y_value)
new FlameChart(dom_locator,svg_width,svg_height,x_value_count,max_y_value)

Creates empty SVG chart inside of DOM element:

  • dom_locator defines DOM container to put div and svg (div is needed just to know a container with single SVG as a child, it really can help for exporting images and other tasks that are a little harder to do without div around svg)
  • svg_width and svg_height define size of SVG image
  • x_value_count is a number of data points to put on a chart, defines abscissa scale
  • max_y_value value that represents top edge of the chart, everything above it would be not visible

Property

smoke.parentNode

Adding Lines

smoke.addLine(line_class,data,line_color,smoke_color)
smoke.updateLine(line_class,data)

Puts a line on the chart or updates data for an existing line:

  • line_class sets class for path created for the path that represents bold line, class "line" is always added to "line_class".
  • data defines table of info to draw the chart (see below)
  • line_color sets color for the line on chart
  • smoke_color sets that elements further from line would gradient to smoke_color when they are drawn

How data element works:

  1. Data is always 2-dimensional table, each row defines a set of values for a point on x-scale equal to an index of this row.
  2. First element of the row - absolute value of the lowest point on the chart, every other column represents difference to a previous value.
  3. Top point on a chart always represents a sum of the row values.
  4. Line on FlameChart drawn at the lowest point, transparency and the saturation of the elements closest to the line is lower than those further from it. Line on SmokeChart drawn at the level representing median element of the row cumulative summaries (could match sum of the half elements or be between sum of half-length and sum of half-length+1 elements of the row)

Note: to draw a line without smoke or flame you would need a 2-dimensional array with a single column. Data written as "d3.transpose([y_values_vector])" is useful when you have 1-dimensional data.

Note: you may add more than one line to same chart but you cannot use flame line and smoke line on same chart so far.

Adding More To The Chart

smoke.addGuide(name,number,color)
smoke.updateGuide(name,number)

Adds or updates flat guide-line with class "line guide name". It's recommended to set CSS opacity for ".guide" class to not obstruct view of real data.

smoke.showLabels(labels)

Spreads labels equally on an X-scale and writes text labels at the bottom edge of the chart.

smoke.showMarkers(x_value_list)

Shows red dot markers at the given X-coordinates, putting more than one in a column if given value presents more than once in x_value_list

smoke.showAvailability(percent_list,box_height)

Shows boxes at the bottom of the chart, expanding SVG to the svg_height+box_height width. Each box split to upper and lower half where lower represents "available" state, and proportional to given "percent" value from percent_list. Boxes shown in width svg_width/length(percent_list)

Other Methods

smoke.yaxis(orientation,padding,ticks)

Adds yaxis at the right of the chart, adding "padding" pixels space for labels. ticks correspond to labels printed next to them according to orientation

smoke.selectAll(locator)

Helper function that does d3 locator selection on svg element created by constructor

smoke.height(svg_height)

Increases or decreases svg height without affecting chart drawing, space at the bottom of the chart could be useful for various markings. There is currently no way to change space above the chart.

smoke.stretch(svg_height,new_max_y_value)

Changes initialization parameters for SVG and scale, stretching or compressing chart vertically. Useful to update chart if it does not fit to the pre-determined max_y_value. There is currently no way to do horizontal stretching and/or automatic stretch upon detecting max value of all the lines combined.

Clone this wiki locally