Documentation - adamlabadorf/d3po GitHub Wiki

Table of contents:

Core functionality

d3po.chart (opts)

The main function of the library, makes a chart. The chart has the following "methods":

Each of these methods accepts two arguments: data and opts. The data argument must be an array of objects with at least the fields x and y, e.g.:

[{x:0,y:0},{x:3,:y:4}]

opts is an object that configures the entire chart, the following options are accepted, with defaults:

option default description
width 600 width of chart in pixels, or fill will set the width equal to the containing element
height 600 height of chart in pixels, or fill will set the width equal to the containing element
margin {top:40, left:40, right:40, bottom:40} space around exterior of chart area, in pixels
target body target DOM element to put chart into, should be a selector compatible with d3.select
name chart_X name of chart, if not supplied assigned chart_X where X is a number incremented with d3po.chartcount, should be unique within current document
background #eee background color of charting area, should be #RGB, #RRGGBB, or a named color
axis true true or false, whether to draw an axis on the plot
axis_opts {} options for the axis, see chart.axis
padding normal padding between chart frame and plotted content, one of normal, tight, or none (e.g. use none for heatmap)
zoom false adds d3.behavior.zoom to chart
zoom_opts {} options for zoom behavior, see chart.zoom
databox true enable databoxes on hover over scatter points
databox_opts {} options for databox behavior, see chart.databox
controls true add HTML based chart controls, see chart.controls
chart.axis

Not directly callable, but sets the chart to draw an d3.axis on the current chart when axis=true in d3po.chart, axis options passed as axis_opts:

option default description
aspect none aspect ratio of axis, equal makes axis have 1:1
xLabel none text for x axis label
yLabel none text for y axis label
tickSize 4 size of ticks in pixels
chart.zoom

Not directly callable, but sets the chart to use d3.behavior.zoom when zoom=true in d3po.chart, zoom options passed as zoom_opts:

option default description
geometric false geometric zoom will scale scatter plot shapes with zoom, true or false
chart.databox

Draw a box with scatter point data in text on mouse hover when databox=true in d3po.chart. The box will contain text of key:value pairs of fields passed with each data point. Options passed as databox_opts:

option default description
offset 10 offset from scatter point in pixels to draw box origin
ignore ['fill', 'stroke', 'w','h', 'shape', 'alpha'] do not draw data fields with these names, draw any others
only undefined if defined as list, only draw these data fields in data boxes
chart.controls

Add HTML controls to the chart. The following are appended to the container indicated by target:

control effect
Reset return the zoom location to fit all plotted data
Zoom turn zoom behavior on and off
chart.lines (data,opts)

Draw line segments between the points specified, in order. Only x and y fields in objects are considered.

option default description
color black stroke color, should be #RGB, #RRGGBB,or a named color
stroke_width 1 stroke width in pixels
extend_edges false extend lines from extreme points on either end of data set to the edges of the chart, useful for plotting lines of infinite length
chart.scatter (data,opts)

Draw scatter shapes at the points specified. Each data point is plotted at the x and y fields, plus additional properties:

property default description
fill blue scatter shape fill color, should be #RGB, #RRGGBB,or a named color
alpha none fill-opacity of shape, in range [0,1]
size 30 relative size of shape, [min,max] of size is scaled to [30,300]. If not specified, all points are the same size
shape circle shape of scatter point, one of d3po.shapes
chart.boxes (data,opts)

Draw boxes, a primitive for drawing heatmaps. Each data point is plotted at the x and y fields, plus additional properties:

property default description
fill blue box fill color, should be #RGB, #RRGGBB,or a named color
stroke none stroke color, should be #RGB, #RRGGBB,or a named color
alpha none fill-opacity of shape, in range [0,1]
w 1 width of box in [x,y] coordinate system
h 1 height of box in [x,y] coordinate system

opts may have the following:

option default description
anchor origin

how to position the box in relation to [x,y]:

  • origin: bottom left corner of box is at [x,y]
  • center: center of box is at [x,y]
chart.heatmap (data,opts)

Draw a heatmap, using chart.boxes. Each data point is plotted at the x and y fields, plus required property v, indicating the value. Options:

option default description
colors ['white', '#410'] color scale for heatmap values v, first color value is min, second color value is max

Other functionality

d3po.shapes

shapes available for use in scatter plot, values:

['circle', 'cross', 'triangle-up', 'triangle-down', 'diamond','square']
d3po.colors

some colors available in `named colors`_, values:

['red','blue','cyan','green','orange','black','purple']
d3po.randomScatter
Generates a random scatter dataset with various locations, shapes, sizes, colors, alphas, etc.
d3po.randomLine
Generates a random line of 15 points with the x values sorted ascending.
d3po.randomBoxes
Generates a bunch of random boxes with various locations, shapes, sizes, colors, alphas, strokes, etc.
d3po.randomBoxGrid
Like d3po.randomBoxes but with positions on a regular integer grid.

Miscellaneous

d3po.chartcount
global variable incremented whenever d3po.chart is called
d3po.counter

A generic counter object used to keep track of things that need to be counted, works like:

var counter = d3po.counter(),
    newChartID = counter.inc('charts'), # 0
    nextChartID = counter.inc('charts'); # 1
d3po.css
CSS used by various charting elements. Appended as a style tag to the end of the first head element found on the page.
d3po.util

Object with utility functions:

d3po.util.transform (obj,elem)
Wrapper around d3.transform useful for manipulating the transform attribute on elements. obj is an object with any of rotate, translate, skew, scale fields. elem is an optional element that will have its transform attribute extracted and modified according to obj. The function returns the transform string (d3.transform.toString).
d3po.version
You guessed it, current version of d3po.
⚠️ **GitHub.com Fallback** ⚠️