inst/htmlwidgets/lib/d4/docs/d4-doc.md
In yutannihilation/DfouR:
d4 -0.9.3
base.js
axesbuilderclonefeaturesmarginmixinmixoutouterHeightouterWidthusingappendOncebaseChartbuilderchartcreateAccessorProxyextendfeatureflattenfunctorisArrayisContinuousScaleisDateisDefinedisFunctionisObjectisOrdinalScaleisNotFunctionisNotNullisNullisUndefinedmergeparser
helpers.js
scales.js
column.js
donut.js
grouped-column.js
grouped-row.js
line.js
row.js
scatter.js
stacked-column.js
stacked-row.js
waterfall.js
arc-labels.js
arc-series.js
arrow.js
brush.js
column-labels.js
grid.js
grouped-column-series.js
line-series-labels.js
line-series.js
reference-line.js
stacked-column-connectors.js
stacked-labels.js
stacked-shapes-series.js
trend-line.js
waterfall-connectors.js
x-axis.js
y-axis.js
nested-group.js
nested-stack.js
waterfall.js
base.js
axes
This function returns the internal axes object as a parameter to the
supplied function.
Arguments
funct(Function) -- function which will perform the modifcation.
Returns
(Function) -chart instance
builder
Specifies an object, which d4 uses to initialize the chart with. By default
d4 expects charts to return a builder object, which will be used to
configure defaults for the chart. Typically this means determining the
the default value for the various axes. This accessor allows you to
override the existing builder provided by a chart and use your own.
Examples
myChart.builder = function(chart, data){
return {
link: function(chart, data) {
configureScales.bind(this)(chart, data);
}
};
};
Arguments
funct(Function) -- function which returns a builder object.
Returns
(Function) -chart instance
clone
This function creates a deep copy of the current chart and returns it.
This is useful if you have to create several charts which have a variety
of shared features but deviate from each other in a small number of ways.
Examples
var chart = d4.charts.column();
var clone = chart.clone();
Returns
(Function) -a copy of the current chart
features
To see what features are currently mixed into your chart you can use
this method. This function cannot be chained.
Examples
// Mixout the yAxis which is provided as a default
var chart = d4.charts.column()
.mixout('yAxis');
// Now test that the feature has been removed.
console.log(chart.features());
// => ["bars", "barLabels", "xAxis"]
Returns
(Array) -An array of features.
margin
To adjust the chart's margins supply either an object or a function that returns
an object to this method.
Examples
// set the margin this using an object:
chart.margin({ top: 10, right: 10, bottom: 10, left: 10 });
// set using a function:
chart.margin(function(){
return { top: 10, right: 10, bottom: 10, left: 10 };
});
// since JavaScript is a pass by reference language you can also
// set portions of the margin this way:
chart.margin().left = 20;
// there are also accessor method for each property of the margin
// object:
chart.marginLeft(20);
chart.marginLeft() // => 20;
Arguments
funct(*) -- an object or a function that returns an object.
Returns
(Function) -chart instance
mixin
Specifies a feature to be mixed into a given chart.
The feature is an object where the key represents the feature name, and a
value which is a function that when invoked returns a d4 feature object.
Examples
// Mix in a single feature at a specific depth
chart.mixin({ name : 'grid', feature : d4.features.grid, index: 0 })
// Mix in multiple features at once.
chart.mixin([
{ name : 'zeroLine', feature : d4.features.referenceLine },
{ name : 'grid', feature : d4.features.grid, index: 0 }
])
Arguments
features(*) -- an object or array of objects describing the feature to mix in.
Returns
(Function) -chart instance
mixout
Specifies an existing feature of a chart to be removed (mixed out).
Examples
// Mixout the yAxis which is provided as a default
var chart = d4.charts.column()
.mixout('yAxis');
// Now test that the feature has been removed.
console.log(chart.features());
=> ["bars", "barLabels", "xAxis"]
Arguments
name(String) -- accessor name for chart feature.
Returns
(Function) -chart instance
outerHeight
Returns or sets the outerHeight of the chart.
Arguments
height(Number) -
Returns
(Function) -chart instance
outerWidth
Returns or sets the outerWidth of the chart.
Arguments
width(Number) -
Returns
(Function) -chart instance
using
The heart of the d4 API is the using function, which allows you to
contextually modify attributes of the chart or one of its features.
Examples
chart.mixin({ 'zeroLine': d4.features.referenceLine })
.using('zeroLine', function(zero) {
zero
.x1(function() {
return this.x(0);
})
});
Arguments
name(String) -- accessor name for chart feature.funct(Function) -- function which will perform the modifcation.
Returns
(Function) -chart instance
appendOnce
This function conditionally appends a SVG element if it doesn't already
exist within the parent element.
Examples
// this will create a svg element, with the id of chart and apply two classes "d4 and chart"
d4.appendOnce(selection, 'svg#chart.d4.chart')
Arguments
Selection}(D3) -- parent DOM element-(String) -string to use as the dom selector
Returns
(D3) -Selection} selection
baseChart
This function creates a d4 chart object. It is only used when creating a
new chart factory.
Examples
var chart = d4.baseChart({
builder: myBuilder,
config: {
axes: {
x: {
scale: 'linear'
},
y: {
scale: 'ordinal'
}
}
}
});
Arguments
options(Object) -- object which contains an optional config and /or
Returns
(Function) -chart instance
builder
This function allows you to register a reusable chart builder with d4.
Arguments
name(String) -- accessor name for chart builder.funct(Function) -- function which will instantiate the chart builder.
Returns
(Function) -a reference to the chart builder
chart
This function allows you to register a reusable chart with d4.
Arguments
name(String) -- accessor name for chart.funct(Function) -- function which will instantiate the chart.
Returns
(Function) -a reference to the chart function
createAccessorProxy
This function allows create proxy accessor to other objects. This is most
useful when you need a feature to transparently control a component of a
d3 object. Consider the example of the yAxis feature. It allows you to control
a d3 axis object. To the user the d4 axis feature and the d3 axis object are
one in the same, and they will expect that they can interact with an d4 axis
feature in the same way they could with a d3 axis object. Therefore before
the feature is created we first use this function to create a transparent
proxy that links the two.
Examples
d4.feature('yAxis', function(name) {
var axis = d3.svg.axis();
var obj = { accessors : {} };
d4.createAccessorProxy(obj, axis);
return obj;
});
// Then when using the feature you can transparently access the axis properties
chart.using('yAxis', function(axis){
// => 0
axis.ticks();
});
Arguments
proxy(Object) -- The proxy object, which masks the target.target(Object) -- The target objet, which is masked by the proxyprefix(String) -- Optional prefix to add to the method names, which helps avoid naming collisions on the proxy.
extend
Helper method to extend one object with the attributes of another.
Examples:
var opts = d4.extend({
margin: {
top: 20,
right: 20,
bottom: 40,
left: 40
},
width: 400
}, config);
Arguments
obj(Object) -- the object to extendoverrides(Object) -- the second object who will extend the first.
Returns
(Object) -the first object which has now been extended;
feature
This function allows you to register a reusable chart feature with d4.
Arguments
name(String) -- accessor name for chart feature.funct(Function) -- function which will instantiate the chart feature.
Returns
(Function) -a reference to the chart feature
flatten
Helper method to flatten a multi-dimensional array into a single array.
Arguments
arr(Array) -- array to be flattened.
Returns
(Array) -flattened array.
functor
Based on D3's own functor function.
If the specified value is a function, returns the specified value. Otherwise,
returns a function that returns the specified value. This method is used
internally as a lazy way of upcasting constant values to functions, in
cases where a property may be specified either as a function or a constant.
For example, many D3 layouts allow properties to be specified this way,
and it simplifies the implementation if we automatically convert constant
values to functions.
Arguments
funct(*) -- An function or other variable to be wrapped in a function
Returns
(Function) -
isArray
Helper method to determine if a supplied argument is an array
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isContinuousScale
Helper method to determine if the supplied scale wants continuous as
opposed to ordinal values.
isDate
Helper method to determine if a supplied argument is a date
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isDefined
Helper method to determine if a supplied argument is defined
Arguments
value(*) -- the argument to test
Returns
(Boolean) -
isFunction
Helper method to determine if a supplied argument is a function
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isObject
Helper method to determine if a supplied argument is not an object
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isOrdinalScale
Helper method to determine if the supplied scale wants ordinal as
opposed to continuous values.
isNotFunction
Helper method to determine if a supplied argument is not a function
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isNotNull
Helper method to determine if a supplied argument is not null
Arguments
value(*) -- the argument to test
Returns
(Boolean) -
isNull
Helper method to determine if a supplied argument is null
Arguments
value(*) -- the argument to test
Returns
(Boolean) -
isUndefined
Helper method to determine if a supplied argument is undefined
Arguments
value(*) -- the argument to test
Returns
(Boolean) -
merge
Helper method to merge two objects together into a new object. This will leave
the two orignal objects untouched. The overrides object will replace any
values which also occur in the options object.
Examples:
var opts = d4.merge({
margin: {
top: 20,
right: 20,
bottom: 40,
left: 40
},
width: 400
}, config);
Arguments
options(Object) -- the first objectoverrides(Object) -- the second object to merge onto the top.
Returns
(Object) -newly merged object;
parser
This function allows you to register a reusable data parser with d4.
Arguments
name(String) -- accessor name for data parser.funct(Function) -- function which will instantiate the data parser.
Returns
(*) -a reference to the data parser
helpers.js
scales.js
linearScaleForNestedData
Creates a linear scale for a dimension of a given chart.
Arguments
d4(Object) -chart objectdata(Array) -arraystring(string) -represnting a dimension e.g. `x`,`y`.
Returns
(Object) -Chart scale object
timeScaleForNestedData
Creates a time scale for a dimension of a given chart.
Arguments
d4(Object) -chart objectdata(Array) -arraystring(string) -represnting a dimension e.g. `x`,`y`.
Returns
(Object) -Chart scale object
ordinalScaleForNestedData
Creates an ordinal scale for a dimension of a given chart.
Arguments
d4(Object) -chart objectdata(Array) -arraystring(string) -represnting a dimension e.g. `x`,`y`.
Returns
(Object) -Chart scale object
column.js
column
The column chart has two axes (x and y). By default the column chart expects
linear values for the y and ordinal values on the x. The basic column chart
has four default features:
Features
bars - series bars
barLabels - data labels above the bars
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ x: '2010', y:-10 },
{ x: '2011', y:20 },
{ x: '2012', y:30 },
{ x: '2013', y:40 },
{ x: '2014', y:50 },
];
var chart = d4.charts.column();
d3.select('#example')
.datum(data)
.call(chart);
By default d4 expects a series object, which uses the following format: { x : '2010', y : 10 }.
The default format may not be desired and so we'll override it:
var data = [
['2010', -10],
['2011', 20],
['2012', 30],
['2013', 40],
['2014', 50]
];
var chart = d4.charts.column()
.x(function(x) {
x.key(0)
})
.y(function(y){
y.key(1);
});
d3.select('#example')
.datum(data)
.call(chart);
donut.js
donut
The donut chart
Features
arcs - The arc series
arcLabels - The data labels linked to the arcs
radius - The total radius of the chart
arcWidth - The width of the arc
Example Usage
var generateData = function() {
var data = [];
var names = ['Clay Hauck', 'Diego Hickle', 'Heloise Quitzon',
'Hildegard Littel', 'Janiya Legros', 'Karolann Boehm',
'Lilyan Deckow IV', 'Lizeth Blick', 'Marlene O\'Kon', 'Marley Gutmann'
],
pie = d3.layout.pie()
.sort(null)
.value(function(d) {
return d.unitsSold;
});
d4.each(names, function(name) {
data.push({
unitsSold: Math.max(10, Math.random() * 100),
salesman: name
});
});
return pie(data);
};
var chart = d4.charts.donut()
.outerWidth($('#pie').width())
.margin({
left: 0,
top: 0,
right: 0,
bottom: 0
})
.radius(function() {
return this.width / 8;
})
.arcWidth(50)
.using('arcLabels', function(labels) {
labels.text(function(d) {
return d.data.salesman;
})
})
.using('arcs', function(slices) {
slices.key(function(d) {
return d.data.salesman;
});
});
var redraw = function() {
var data = generateData();
d3.select('#pie')
.datum(data)
.call(chart);
};
(function loop() {
redraw();
setTimeout(loop, 4500);
})();
grouped-column.js
groupedColumn
The grouped column chart is used to compare a series of data elements grouped
along the xAxis. This chart is often useful in conjunction with a stacked column
chart because they can use the same data series, and where the stacked column highlights
the sum of the data series across an axis the grouped column can be used to show the
relative distribution.
Features
bars - series bars
barLabels - data labels above the bars
groupsOf - an integer representing the number of columns in each group
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold:-100, salesman : 'Bob' },
{ year: '2011', unitsSold:200, salesman : 'Bob' },
{ year: '2012', unitsSold:300, salesman : 'Bob' },
{ year: '2013', unitsSold:400, salesman : 'Bob' },
{ year: '2014', unitsSold:500, salesman : 'Bob' },
{ year: '2010', unitsSold:100, salesman : 'Gina' },
{ year: '2011', unitsSold:100, salesman : 'Gina' },
{ year: '2012', unitsSold:-100, salesman : 'Gina' },
{ year: '2013', unitsSold:500, salesman : 'Gina' },
{ year: '2014', unitsSold:600, salesman : 'Gina' },
{ year: '2010', unitsSold:400, salesman : 'Average' },
{ year: '2011', unitsSold:0, salesman : 'Average' },
{ year: '2012', unitsSold:400, salesman : 'Average' },
{ year: '2013', unitsSold:400, salesman : 'Average' },
{ year: '2014', unitsSold:400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedGroup()
.x('year')
.y('unitsSold')
.value('unitsSold')(data);
var chart = d4.charts.groupedColumn()
.width($('#example').width())
.x.$key('year')
.y.$key('unitsSold')
.groupsOf(parsedData.data[0].values.length);
d3.select('#example')
.datum(parsedData.data)
.call(chart);
grouped-row.js
groupedRow
The grouped row chart is used to compare a series of data elements grouped
along the xAxis. This chart is often useful in conjunction with a stacked row
chart because they can use the same data series, and where the stacked row highlights
the sum of the data series across an axis the grouped row can be used to show the
relative distribution.
Features
bars - series bars
barLabels - data labels above the bars
groupsOf - an integer representing the number of rows in each group
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold:-100, salesman : 'Bob' },
{ year: '2011', unitsSold:200, salesman : 'Bob' },
{ year: '2012', unitsSold:300, salesman : 'Bob' },
{ year: '2013', unitsSold:400, salesman : 'Bob' },
{ year: '2014', unitsSold:500, salesman : 'Bob' },
{ year: '2010', unitsSold:100, salesman : 'Gina' },
{ year: '2011', unitsSold:100, salesman : 'Gina' },
{ year: '2012', unitsSold:-100, salesman : 'Gina' },
{ year: '2013', unitsSold:500, salesman : 'Gina' },
{ year: '2014', unitsSold:600, salesman : 'Gina' },
{ year: '2010', unitsSold:400, salesman : 'Average' },
{ year: '2011', unitsSold:0, salesman : 'Average' },
{ year: '2012', unitsSold:400, salesman : 'Average' },
{ year: '2013', unitsSold:400, salesman : 'Average' },
{ year: '2014', unitsSold:400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedGroup()
.x('year')
.y('unitsSold')
.value('unitsSold')(data);
var chart = d4.charts.groupedRow()
.width($('#example').width())
.x.$key('year')
.y.$key('unitsSold')
.groupsOf(parsedData.data[0].values.length);
d3.select('#example')
.datum(parsedData.data)
.call(chart);
line.js
line
The line series chart is used to compare a series of data elements grouped
along the xAxis.
Features
lineSeries - series lines
lineSeriesLabels - data labels beside the lines
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold:-100, salesman : 'Bob' },
{ year: '2011', unitsSold:200, salesman : 'Bob' },
{ year: '2012', unitsSold:300, salesman : 'Bob' },
{ year: '2013', unitsSold:400, salesman : 'Bob' },
{ year: '2014', unitsSold:500, salesman : 'Bob' },
{ year: '2010', unitsSold:100, salesman : 'Gina' },
{ year: '2011', unitsSold:100, salesman : 'Gina' },
{ year: '2012', unitsSold:-100, salesman : 'Gina' },
{ year: '2013', unitsSold:500, salesman : 'Gina' },
{ year: '2014', unitsSold:600, salesman : 'Gina' },
{ year: '2010', unitsSold:400, salesman : 'Average' },
{ year: '2011', unitsSold:0, salesman : 'Average' },
{ year: '2012', unitsSold:400, salesman : 'Average' },
{ year: '2013', unitsSold:400, salesman : 'Average' },
{ year: '2014', unitsSold:400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedGroup()
.x(function(){
return 'year';
})
.nestKey(function(){
return 'salesman';
})
.y(function(){
return 'unitsSold';
})
.value(function(){
return 'unitsSold';
})(data);
var chart = d4.charts.line()
.width($('#example').width())
.x.$key('year')
.y.$key('unitsSold');
d3.select('#example')
.datum(parsedData.data)
.call(chart);
row.js
row
The row chart has two axes (x and y). By default the column chart expects
linear scale values for the x and ordinal scale values on the y. The basic column chart
has four default features:
Features
bars - series bars
barLabels - data labels to the right of the bars
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ y: '2010', x:-10 },
{ y: '2011', x:20 },
{ y: '2012', x:30 },
{ y: '2013', x:40 },
{ y: '2014', x:50 },
];
var chart = d4.charts.row();
d3.select('#example')
.datum(data)
.call(chart);
scatter.js
scatterPlot
The scatter plot has three axes (x, y and z). By default the scatter
plot expects linear scale values for all axes. The basic scatter plot chart
has these default features:
Features
circles - series of circles
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ age: 12, unitsSold: 0, month: 1 },
{ age: 22, unitsSold: 200, month: 2 },
{ age: 42, unitsSold: 300, month: 3 },
{ age: 32, unitsSold: 400, month: 4 },
{ age: 2 , unitsSold: 400, month: 2 }
];
var chart = d4.charts.scatterPlot()
.x(function(x){
x.min(-10)
x.key('age');
})
.y(function(y){
y.key('month');
})
.z(function(z){
z.key('unitsSold');
});
d3.select('#example')
.datum(data)
.call(chart);
stacked-column.js
stackedColumn
The stacked column chart has two axes (x and y). By default the stacked
column expects continious scale for the y axis and a discrete scale for
the x axis. The stacked column has the following default features:
Features
bars - series of rects
barLabels - individual data values inside the stacked rect
connectors - visual lines that connect the various stacked columns together
columnTotals - column labels which total the values of each stack.
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold: 200, salesman : 'Bob' },
{ year: '2011', unitsSold: 200, salesman : 'Bob' },
{ year: '2012', unitsSold: 300, salesman : 'Bob' },
{ year: '2013', unitsSold: -400, salesman : 'Bob' },
{ year: '2014', unitsSold: -500, salesman : 'Bob' },
{ year: '2010', unitsSold: 100, salesman : 'Gina' },
{ year: '2011', unitsSold: 100, salesman : 'Gina' },
{ year: '2012', unitsSold: 200, salesman : 'Gina' },
{ year: '2013', unitsSold: -500, salesman : 'Gina' },
{ year: '2014', unitsSold: -600, salesman : 'Gina' },
{ year: '2010', unitsSold: 400, salesman : 'Average' },
{ year: '2011', unitsSold: 100, salesman : 'Average' },
{ year: '2012', unitsSold: 400, salesman : 'Average' },
{ year: '2013', unitsSold: -400, salesman : 'Average' },
{ year: '2014', unitsSold: -400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedStack()
.x(function(){
return 'year';
})
.y(function(){
return 'salesman';
})
.value(function(){
return 'unitsSold';
})(data);
var chart = d4.charts.stackedColumn()
.x(function(x){
x.key('year');
})
.y(function(y){
y.key('unitsSold');
})
d3.select('#example')
.datum(parsedData.data)
.call(chart);
stacked-row.js
stackedRow
The stacked row chart has two axes (x and y). By default the stacked
row expects continious scale for the x axis and a discrete scale for
the y axis. The stacked row has the following default features:
Features
bars - series of rects
barLabels - individual data values inside the stacked rect
connectors - visual lines that connect the various stacked columns together
columnTotals - column labels which total the values of each stack.
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold: 200, salesman : 'Bob' },
{ year: '2011', unitsSold: 200, salesman : 'Bob' },
{ year: '2012', unitsSold: 300, salesman : 'Bob' },
{ year: '2013', unitsSold: -400, salesman : 'Bob' },
{ year: '2014', unitsSold: -500, salesman : 'Bob' },
{ year: '2010', unitsSold: 100, salesman : 'Gina' },
{ year: '2011', unitsSold: 100, salesman : 'Gina' },
{ year: '2012', unitsSold: 200, salesman : 'Gina' },
{ year: '2013', unitsSold: -500, salesman : 'Gina' },
{ year: '2014', unitsSold: -600, salesman : 'Gina' },
{ year: '2010', unitsSold: 400, salesman : 'Average' },
{ year: '2011', unitsSold: 200, salesman : 'Average' },
{ year: '2012', unitsSold: 400, salesman : 'Average' },
{ year: '2013', unitsSold: -400, salesman : 'Average' },
{ year: '2014', unitsSold: -400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedStack()
.x(function(){
return 'year';
})
.y(function(){
return 'salesman';
})
.value(function(){
return 'unitsSold';
})(data);
var chart = d4.charts.stackedRow()
.x(function(x){
x.key('unitsSold');
})
.valueKey('unitsSold')
.y(function(y){
y.key('year');
});
d3.select('#example')
.datum(parsedData.data)
.call(chart);
waterfall.js
waterfall
The waterfall chart visually tallies the cumulative result of negative and
positive values over a data series. In addition to specifying the normal
positive and negative values d4's also lets you designate a column as a subtotal
column by passing in an "e" as the value key, which may be a familiar convention
if you have used think-cell.
The waterfall chart has two axes (x and y). By default the stacked
column expects continious scale for the y axis and a discrete scale for
the x axis. This will render the waterfall chart vertically. However,
if you swap the scale types then the waterfall will render horizontally.
Features
bars - series of rects
connectors - visual lines that connect the various stacked columns together
columnLabels - column labels which total the values of each rect.
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ 'category': 'Job', 'value': 27 },
{ 'category': 'Groceries', 'value': -3 },
{ 'category': 'Allowance', 'value': 22 },
{ 'category': 'Subtotal', 'value': 'e' },
{ 'category': 'Videos', 'value': -22 },
{ 'category': 'Coffee', 'value': -4 },
{ 'category': 'Total', 'value': 'e' }
];
var parsedData = d4.parsers.waterfall()
.x(function() {
return 'category';
})
.y(function() {
return 'value';
})
.nestKey(function() {
return 'category';
})(data);
var chart = d4.charts.waterfall()
.width($('#example').width())
.x(function(x){
x.key('category');
})
.y(function(y){
y.key('value');
});
d3.select('#example')
.datum(parsedData.data)
.call(chart);
arc-labels.js
arcLabels
Arc labels are used to annotate arc series, for example those created by pie and donut charts.
Many of the accessors of this feature proxy directly to D3's arc object:
https://github.com/mbostock/d3/wiki/SVG-Shapes#arc
Accessors
centroid - proxied accessor to the navtive d3 function
classes - classes assigned to the arc label.
duration - time in milliseconds for the transition to occur.
endAngle - proxied accessor to the navtive d3 function
innerRadius - proxied accessor to the navtive d3 function
key - unique identifier used for linking the element during d3's transition process
outerRadius - proxied accessor to the navtive d3 function
startAngle - proxied accessor to the navtive d3 function
text - value to display in the label.
x - position across the x axis
y - position across the y axis
arc-series.js
arcSeries
Arc series is a collection of arcs suitable for those needed by pie and donut charts.
Many of the accessors of this feature proxy directly to D3's arc object:
https://github.com/mbostock/d3/wiki/SVG-Shapes#arc
Accessors
centroid - proxied accessor to the navtive d3 function
classes - classes assigned to the arc label.
duration - time in milliseconds for the transition to occur.
endAngle - proxied accessor to the navtive d3 function
innerRadius - proxied accessor to the navtive d3 function
key - unique identifier used for linking the element during d3's transition process
outerRadius - proxied accessor to the navtive d3 function
startAngle - proxied accessor to the navtive d3 function
x - position across the x axis
y - position across the y axis
arrow.js
arrow
The arrow feature is a convienient way to visually draw attention to a portion
of a chart by pointing an arrow at it.
brush.js
column-labels.js
columnLabels
The columnLabels feature is used to affix data labels to column series.
grid.js
grid
This feature allows you to specify a grid over a portion or the entire chart area.
grouped-column-series.js
groupedColumnSeries
This feature is specifically designed to use with the groupedColumn and groupedRow charts.
line-series-labels.js
lineSeriesLabels
Approach based off this example:
http://bl.ocks.org/mbostock/3902569
line-series.js
@name lineSeries
reference-line.js
referenceLine
The reference line feature is helpful when you want to apply a line to a chart
which demarcates a value within the data. For example a common use of this
feature is to specify the zero value across an axis.
stacked-column-connectors.js
stackedColumnConnectors
Column connectors helpful when displaying a stacked column chart.
A connector will not connect positve and negative columns. This is because
in a stacked column a negative column may move many series below its previous
location. This creates a messy collection of crisscrossing lines.
stacked-labels.js
stackedLabels
The stackedLabels are appropriate for use with the stacked shape series.
stacked-shapes-series.js
circleSeries
This feature is useful for displaying charts which need stacked circles.
Note: Many of the d4 charts use the stacked series as the base, and simply
renders only one series, if there is nothing to stack.
Accessors
classes - classes assigned to each circle in the series
cx - placement on the chart's x axis
cy - placement on the chart's y axis
r - radius of the circle
ellipseSeries
This feature is useful for displaying charts which need stacked ellipses.
Note: Many of the d4 charts use the stacked series as the base, and simply
renders only one series, if there is nothing to stack.
Accessors
classes - classes assigned to each ellipse in the series
cx - placement on the chart's x axis
cy - placement on the chart's y axis
rx - radius of the ellipse on the x axis
ry - radius of the ellipse on the y axis
rectSeries
This feature is useful for displaying charts which need stacked rects.
Note: Many of the d4 charts use the stacked series as the base, and simply
renders only one series, if there is nothing to stack.
Accessors
classes - classes assigned to each rect in the series
height - height of the rect
rx - rounding of the corners against the x dimension
ry - rounding of the corners against the y dimension
width - width of the rect
x - placement on the chart's x axis
y - placement on the chart's y axis
trend-line.js
trendLine
A trendline allows you to associate a line with a numerical value.
waterfall-connectors.js
waterfallConnectors
Waterfall connectors are orthogonal series connectors which visually join
column series together by spanning the top or bottom of adjacent columns.
Accessors
x - Used in placement of the connector lines.
y - Used in placement of the connector lines.
span - calculates the length of the connector line
classes - applies the class to the connector lines.
x-axis.js
xAxis
This feature creates an xAxis for use within d4. There are a variety of
accessors described below which modify the behavior and apperance of the axis.
Accessors
axis - The d3 axis object itself.
innerTickSize - see: https://github.com/mbostock/d3/wiki/SVG-Axes#innerTickSize
orient - see: https://github.com/mbostock/d3/wiki/SVG-Axes#orient
outerTickSize- see: https://github.com/mbostock/d3/wiki/SVG-Axes#outerTickSize
scale - see: https://github.com/mbostock/d3/wiki/SVG-Axes#scale
stagger - (true | false) determines if the axis should stagger overlapping text (true by default)
tickFormat - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickFormat
tickPadding - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickPadding
tickSize - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickSize
tickSubdivide- see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickSubdivide
tickValues - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickValues
ticks - see: https://github.com/mbostock/d3/wiki/SVG-Axes#ticks
var chart = d4.charts.groupedColumn()
.using('yAxis', function(axis){
// adjust the number of tick marks based on the height of the chart
axis.ticks($('#example').height()/20);
// set the inner and outer tick sizes
axis.tickSize(10,5);
// adjust the tick padding
axis.tickPadding(5);
})
.using('xAxis', function(axis){
// position the tickmarks on the top of the axis line
axis.orient('top');
// move the axis to the top of the chart.
axis.align('top');
})
y-axis.js
yAxis
This feature creates an xAxis for use within d4. There are a variety of
accessors described below which modify the behavior and apperance of the axis.
Accessors
axis - The d3 axis object itself.
innerTickSize - see: https://github.com/mbostock/d3/wiki/SVG-Axes#innerTickSize
orient - see: https://github.com/mbostock/d3/wiki/SVG-Axes#orient
outerTickSize- see: https://github.com/mbostock/d3/wiki/SVG-Axes#outerTickSize
scale - see: https://github.com/mbostock/d3/wiki/SVG-Axes#scale
stagger - (true | false) determines if the axis should stagger overlapping text (true by default)
tickFormat - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickFormat
tickPadding - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickPadding
tickSize - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickSize
tickSubdivide- see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickSubdivide
tickValues - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickValues
ticks - see: https://github.com/mbostock/d3/wiki/SVG-Axes#ticks
Examples
var chart = d4.charts.groupedColumn()
.using('yAxis', function(axis){
// adjust the number of tick marks based on the height of the chart
axis.ticks($('#example').height()/20);
// set the inner and outer tick sizes
axis.tickSize(10,5);
// adjust the tick padding
axis.tickPadding(5);
})
.using('xAxis', function(axis){
// position the tickmarks on the top of the axis line
axis.orient('top');
// move the axis to the top of the chart.
axis.y(-20);
})
nested-group.js
nestedGroup
The nested group parser is useful for grouped column charts where multiple
data items need to appear relative to the axis value, for example grouped
column charts or multi-series line charts.
_____________________
| _ |
| _ _ | |_ |
| | | | | | | |
----------------------
This module makes use of the d3's "nest" data structure layout
https://github.com/mbostock/d3/wiki/Arrays#-nest
Approach
Just like D3, this parser uses a chaining declaritiave style to build up
the necessary prerequistes to create the waterfall data. Here is a simple
example. Given a data item structure like this: {"category" : "Category One", "value" : 23 }
var parser = d4.parsers.nestedGroup()
.x('category')
.y('value')
.value('value');
var groupedColumnData = parser(data);
Keep reading for more information on these various accessor functions.
Accessor Methods
x - A function which returns a key to access the x values in the data array
y - A function which returns a key to access the y values in the data array
value - A function which returns a key to access the values in the data array.
data - An array of objects with their dimensions specified like this:
var data = [
{"year" : "2010", "category" : "Category One", "value" : 23 },
{"year" : "2010", "category" : "Category Two", "value" : 55 },
{"year" : "2010", "category" : "Category Three", "value" : -10 },
{"year" : "2010", "category" : "Category Four", "value" : 5 }]
nested-stack.js
nestedStack
The nested stack parser is useful for charts which take a data series
and wants to sort them across a dimension and then display the results.
The most common usecase would be a stacked column chart like this:
_____________________
| _ |
| | | _ |
| |-| | | _ |
| |-| |-| |-| |
| | | |-| |-| |
----------------------
This module makes use of the d3's "nest" data structure, and "stack" layout
Approach
Just like D3, this parser uses a chaining declaritiave style to build up
the necessary prerequistes to create the stacked data. Here is a simple
example:
var parser = d4.parsers.nestedStack()
.x(function() {
return 'title';
})
.y(function(){
return 'group';
})
.value(function() {
return 'values';
});
var stackedData = parser(data);
Keep reading for more information on these various accessor functions.
Benefits
- Supports negative and positive stacked data series.
Limitations
- The parser expects the stack will occur on the yAxis, which means it is only suitable for column charts presently.
Accessor Methods
x : - function which returns a key to access the x values in the data array
y : - function which returns a key to access the y values in the data array
value : - function which returns a key to access the values in the data array.
data : array - An array of objects with their dimensions specified like this:
var data = [{ "title": "3 Years", "group" : "one", "value": 30 },
{ "title": "3 Years", "group" : "two", "value": 20 },
{ "title": "3 Years", "group" : "three", "value": 10 },
{ "title": "5 Years", "group" : "one", "value": 3 },
{ "title": "5 Years", "group" : "two", "value": 2 },
{ "title": "5 Years", "group" : "three", "value": 1 }]
Example Usage
Given the example data and dimension variables above you can use this module
in the following way:
var parser = d4.parsers.nestedStack()
.x(function() {
return 'title';
})
.y(function(){
return 'group';
})
.value(function() {
return 'value';
})
.call(data);
The parser variable will now be an object containing the following structure:
{
data: Array
value: {
key: string,
values: Array
},
x: {
key: string,
values: Array
},
y: {
key: string,
values: Array
}
}
waterfall.js
waterfall
The waterfall parser is useful for waterfall charts where data items need to account
for the position of earlier values:
_____________________
| _ _______ |
| |_|___ | | | | |
| |_|__|_| | | |
| |_| |
----------------------
This module makes use of the d3's "nest" data structure, and "stack" layout
https://github.com/mbostock/d3/wiki/Arrays#-nest
https://github.com/mbostock/d3/wiki/Stack-Layout
Approach:
Just like D3, this parser uses a chaining declaritiave style to build up
the necessary prerequistes to create the waterfall data. Here is a simple
example. Given a data item structure like this: {"category" : "Category One", "value" : 23 }
var parser = d4.parsers.waterfall()
.x(function() {
return 'category';
})
.y(function(){
return 'value';
})
.value(function() {
return 'value';
});
var waterfallData = parser(data);
Keep reading for more information on these various accessor functions.
Benefits:
Supports horizontal or vertical waterfalls
Supports totaling series using a special "e" value in a data item.
Limitations:
Does not support stacked waterfalls.
Accessors:
x : - function which returns a key to access the x values in the data array
y : - function which returns a key to access the y values in the data array
value : - function which returns a key to access the values in the data array.
data : array - An array of objects with their dimensions specified
like this:
var data = [
{"category" : "Category One", "value" : 23 },
{"category" : "Category Two", "value" : 55 },
{"category" : "Category Three", "value" : -10 },
{"category" : "Category Four", "value" : 5 },
{"category" : "Category Five", "value" : "e" }]
SPECIAL NOTE:
Waterfalls charts typically have the ability to display subtotals at any point.
In order to use this feature simply set the value of your subtotal column to "e."
Example Usage:
Given the example data and dimension variables above you can use this module
in the following way:
var parser = d4.parsers.nestedStack()
.dimensions(dimensions)
.call(data);
The `parser` variable will now be an object containing the following structure:
{
data: Array
value: {
key: string,
values: Array
},
x: {
key: string,
values: Array
},
y: {
key: string,
values: Array
}
}
yutannihilation/DfouR documentation built on May 4, 2019, 7:45 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
d4 -0.9.3
base.js
axesbuilderclonefeaturesmarginmixinmixoutouterHeightouterWidthusingappendOncebaseChartbuilderchartcreateAccessorProxyextendfeatureflattenfunctorisArrayisContinuousScaleisDateisDefinedisFunctionisObjectisOrdinalScaleisNotFunctionisNotNullisNullisUndefinedmergeparser
helpers.js
scales.js
column.js
donut.js
grouped-column.js
grouped-row.js
line.js
row.js
scatter.js
stacked-column.js
stacked-row.js
waterfall.js
arc-labels.js
arc-series.js
arrow.js
brush.js
column-labels.js
grid.js
grouped-column-series.js
line-series-labels.js
line-series.js
reference-line.js
stacked-column-connectors.js
stacked-labels.js
stacked-shapes-series.js
trend-line.js
waterfall-connectors.js
x-axis.js
y-axis.js
nested-group.js
nested-stack.js
waterfall.js
base.js
axes
This function returns the internal axes object as a parameter to the supplied function.
Arguments
funct(Function) -- function which will perform the modifcation.
Returns
(Function) -chart instance
builder
Specifies an object, which d4 uses to initialize the chart with. By default d4 expects charts to return a builder object, which will be used to configure defaults for the chart. Typically this means determining the the default value for the various axes. This accessor allows you to override the existing builder provided by a chart and use your own.
Examples
myChart.builder = function(chart, data){
return {
link: function(chart, data) {
configureScales.bind(this)(chart, data);
}
};
};
Arguments
funct(Function) -- function which returns a builder object.
Returns
(Function) -chart instance
clone
This function creates a deep copy of the current chart and returns it. This is useful if you have to create several charts which have a variety of shared features but deviate from each other in a small number of ways.
Examples
var chart = d4.charts.column();
var clone = chart.clone();
Returns
(Function) -a copy of the current chart
features
To see what features are currently mixed into your chart you can use this method. This function cannot be chained.
Examples
// Mixout the yAxis which is provided as a default
var chart = d4.charts.column()
.mixout('yAxis');
// Now test that the feature has been removed.
console.log(chart.features());
// => ["bars", "barLabels", "xAxis"]
Returns
(Array) -An array of features.
margin
To adjust the chart's margins supply either an object or a function that returns an object to this method.
Examples
// set the margin this using an object:
chart.margin({ top: 10, right: 10, bottom: 10, left: 10 });
// set using a function:
chart.margin(function(){
return { top: 10, right: 10, bottom: 10, left: 10 };
});
// since JavaScript is a pass by reference language you can also
// set portions of the margin this way:
chart.margin().left = 20;
// there are also accessor method for each property of the margin
// object:
chart.marginLeft(20);
chart.marginLeft() // => 20;
Arguments
funct(*) -- an object or a function that returns an object.
Returns
(Function) -chart instance
mixin
Specifies a feature to be mixed into a given chart. The feature is an object where the key represents the feature name, and a value which is a function that when invoked returns a d4 feature object.
Examples
// Mix in a single feature at a specific depth
chart.mixin({ name : 'grid', feature : d4.features.grid, index: 0 })
// Mix in multiple features at once.
chart.mixin([
{ name : 'zeroLine', feature : d4.features.referenceLine },
{ name : 'grid', feature : d4.features.grid, index: 0 }
])
Arguments
features(*) -- an object or array of objects describing the feature to mix in.
Returns
(Function) -chart instance
mixout
Specifies an existing feature of a chart to be removed (mixed out).
Examples
// Mixout the yAxis which is provided as a default
var chart = d4.charts.column()
.mixout('yAxis');
// Now test that the feature has been removed.
console.log(chart.features());
=> ["bars", "barLabels", "xAxis"]
Arguments
name(String) -- accessor name for chart feature.
Returns
(Function) -chart instance
outerHeight
Returns or sets the outerHeight of the chart.
Arguments
height(Number) -
Returns
(Function) -chart instance
outerWidth
Returns or sets the outerWidth of the chart.
Arguments
width(Number) -
Returns
(Function) -chart instance
using
The heart of the d4 API is the using function, which allows you to
contextually modify attributes of the chart or one of its features.
Examples
chart.mixin({ 'zeroLine': d4.features.referenceLine })
.using('zeroLine', function(zero) {
zero
.x1(function() {
return this.x(0);
})
});
Arguments
name(String) -- accessor name for chart feature.funct(Function) -- function which will perform the modifcation.
Returns
(Function) -chart instance
appendOnce
This function conditionally appends a SVG element if it doesn't already exist within the parent element.
Examples
// this will create a svg element, with the id of chart and apply two classes "d4 and chart" d4.appendOnce(selection, 'svg#chart.d4.chart')
Arguments
Selection}(D3) -- parent DOM element-(String) -string to use as the dom selector
Returns
(D3) -Selection} selection
baseChart
This function creates a d4 chart object. It is only used when creating a new chart factory.
Examples
var chart = d4.baseChart({
builder: myBuilder,
config: {
axes: {
x: {
scale: 'linear'
},
y: {
scale: 'ordinal'
}
}
}
});
Arguments
options(Object) -- object which contains an optional config and /or
Returns
(Function) -chart instance
builder
This function allows you to register a reusable chart builder with d4.
Arguments
name(String) -- accessor name for chart builder.funct(Function) -- function which will instantiate the chart builder.
Returns
(Function) -a reference to the chart builder
chart
This function allows you to register a reusable chart with d4.
Arguments
name(String) -- accessor name for chart.funct(Function) -- function which will instantiate the chart.
Returns
(Function) -a reference to the chart function
createAccessorProxy
This function allows create proxy accessor to other objects. This is most useful when you need a feature to transparently control a component of a d3 object. Consider the example of the yAxis feature. It allows you to control a d3 axis object. To the user the d4 axis feature and the d3 axis object are one in the same, and they will expect that they can interact with an d4 axis feature in the same way they could with a d3 axis object. Therefore before the feature is created we first use this function to create a transparent proxy that links the two.
Examples
d4.feature('yAxis', function(name) {
var axis = d3.svg.axis();
var obj = { accessors : {} };
d4.createAccessorProxy(obj, axis);
return obj;
});
// Then when using the feature you can transparently access the axis properties
chart.using('yAxis', function(axis){
// => 0
axis.ticks();
});
Arguments
proxy(Object) -- The proxy object, which masks the target.target(Object) -- The target objet, which is masked by the proxyprefix(String) -- Optional prefix to add to the method names, which helps avoid naming collisions on the proxy.
extend
Helper method to extend one object with the attributes of another.
Examples:
var opts = d4.extend({
margin: {
top: 20,
right: 20,
bottom: 40,
left: 40
},
width: 400
}, config);
Arguments
obj(Object) -- the object to extendoverrides(Object) -- the second object who will extend the first.
Returns
(Object) -the first object which has now been extended;
feature
This function allows you to register a reusable chart feature with d4.
Arguments
name(String) -- accessor name for chart feature.funct(Function) -- function which will instantiate the chart feature.
Returns
(Function) -a reference to the chart feature
flatten
Helper method to flatten a multi-dimensional array into a single array.
Arguments
arr(Array) -- array to be flattened.
Returns
(Array) -flattened array.
functor
Based on D3's own functor function.
If the specified value is a function, returns the specified value. Otherwise, returns a function that returns the specified value. This method is used internally as a lazy way of upcasting constant values to functions, in cases where a property may be specified either as a function or a constant. For example, many D3 layouts allow properties to be specified this way, and it simplifies the implementation if we automatically convert constant values to functions.
Arguments
funct(*) -- An function or other variable to be wrapped in a function
Returns
(Function) -
isArray
Helper method to determine if a supplied argument is an array
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isContinuousScale
Helper method to determine if the supplied scale wants continuous as opposed to ordinal values.
isDate
Helper method to determine if a supplied argument is a date
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isDefined
Helper method to determine if a supplied argument is defined
Arguments
value(*) -- the argument to test
Returns
(Boolean) -
isFunction
Helper method to determine if a supplied argument is a function
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isObject
Helper method to determine if a supplied argument is not an object
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isOrdinalScale
Helper method to determine if the supplied scale wants ordinal as opposed to continuous values.
isNotFunction
Helper method to determine if a supplied argument is not a function
Arguments
obj(*) -- the argument to test
Returns
(Boolean) -
isNotNull
Helper method to determine if a supplied argument is not null
Arguments
value(*) -- the argument to test
Returns
(Boolean) -
isNull
Helper method to determine if a supplied argument is null
Arguments
value(*) -- the argument to test
Returns
(Boolean) -
isUndefined
Helper method to determine if a supplied argument is undefined
Arguments
value(*) -- the argument to test
Returns
(Boolean) -
merge
Helper method to merge two objects together into a new object. This will leave the two orignal objects untouched. The overrides object will replace any values which also occur in the options object.
Examples:
var opts = d4.merge({
margin: {
top: 20,
right: 20,
bottom: 40,
left: 40
},
width: 400
}, config);
Arguments
options(Object) -- the first objectoverrides(Object) -- the second object to merge onto the top.
Returns
(Object) -newly merged object;
parser
This function allows you to register a reusable data parser with d4.
Arguments
name(String) -- accessor name for data parser.funct(Function) -- function which will instantiate the data parser.
Returns
(*) -a reference to the data parser
helpers.js
scales.js
linearScaleForNestedData
Creates a linear scale for a dimension of a given chart.
Arguments
d4(Object) -chart objectdata(Array) -arraystring(string) -represnting a dimension e.g. `x`,`y`.
Returns
(Object) -Chart scale object
timeScaleForNestedData
Creates a time scale for a dimension of a given chart.
Arguments
d4(Object) -chart objectdata(Array) -arraystring(string) -represnting a dimension e.g. `x`,`y`.
Returns
(Object) -Chart scale object
ordinalScaleForNestedData
Creates an ordinal scale for a dimension of a given chart.
Arguments
d4(Object) -chart objectdata(Array) -arraystring(string) -represnting a dimension e.g. `x`,`y`.
Returns
(Object) -Chart scale object
column.js
column
The column chart has two axes (x and y). By default the column chart expects
linear values for the y and ordinal values on the x. The basic column chart
has four default features:
Features
bars - series bars
barLabels - data labels above the bars
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ x: '2010', y:-10 },
{ x: '2011', y:20 },
{ x: '2012', y:30 },
{ x: '2013', y:40 },
{ x: '2014', y:50 },
];
var chart = d4.charts.column();
d3.select('#example')
.datum(data)
.call(chart);
By default d4 expects a series object, which uses the following format: { x : '2010', y : 10 }.
The default format may not be desired and so we'll override it:
var data = [
['2010', -10],
['2011', 20],
['2012', 30],
['2013', 40],
['2014', 50]
];
var chart = d4.charts.column()
.x(function(x) {
x.key(0)
})
.y(function(y){
y.key(1);
});
d3.select('#example')
.datum(data)
.call(chart);
donut.js
donut
The donut chart
Features
arcs - The arc series
arcLabels - The data labels linked to the arcs
radius - The total radius of the chart
arcWidth - The width of the arc
Example Usage
var generateData = function() {
var data = [];
var names = ['Clay Hauck', 'Diego Hickle', 'Heloise Quitzon',
'Hildegard Littel', 'Janiya Legros', 'Karolann Boehm',
'Lilyan Deckow IV', 'Lizeth Blick', 'Marlene O\'Kon', 'Marley Gutmann'
],
pie = d3.layout.pie()
.sort(null)
.value(function(d) {
return d.unitsSold;
});
d4.each(names, function(name) {
data.push({
unitsSold: Math.max(10, Math.random() * 100),
salesman: name
});
});
return pie(data);
};
var chart = d4.charts.donut()
.outerWidth($('#pie').width())
.margin({
left: 0,
top: 0,
right: 0,
bottom: 0
})
.radius(function() {
return this.width / 8;
})
.arcWidth(50)
.using('arcLabels', function(labels) {
labels.text(function(d) {
return d.data.salesman;
})
})
.using('arcs', function(slices) {
slices.key(function(d) {
return d.data.salesman;
});
});
var redraw = function() {
var data = generateData();
d3.select('#pie')
.datum(data)
.call(chart);
};
(function loop() {
redraw();
setTimeout(loop, 4500);
})();
grouped-column.js
groupedColumn
The grouped column chart is used to compare a series of data elements grouped along the xAxis. This chart is often useful in conjunction with a stacked column chart because they can use the same data series, and where the stacked column highlights the sum of the data series across an axis the grouped column can be used to show the relative distribution.
Features
bars - series bars
barLabels - data labels above the bars
groupsOf - an integer representing the number of columns in each group
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold:-100, salesman : 'Bob' },
{ year: '2011', unitsSold:200, salesman : 'Bob' },
{ year: '2012', unitsSold:300, salesman : 'Bob' },
{ year: '2013', unitsSold:400, salesman : 'Bob' },
{ year: '2014', unitsSold:500, salesman : 'Bob' },
{ year: '2010', unitsSold:100, salesman : 'Gina' },
{ year: '2011', unitsSold:100, salesman : 'Gina' },
{ year: '2012', unitsSold:-100, salesman : 'Gina' },
{ year: '2013', unitsSold:500, salesman : 'Gina' },
{ year: '2014', unitsSold:600, salesman : 'Gina' },
{ year: '2010', unitsSold:400, salesman : 'Average' },
{ year: '2011', unitsSold:0, salesman : 'Average' },
{ year: '2012', unitsSold:400, salesman : 'Average' },
{ year: '2013', unitsSold:400, salesman : 'Average' },
{ year: '2014', unitsSold:400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedGroup()
.x('year')
.y('unitsSold')
.value('unitsSold')(data);
var chart = d4.charts.groupedColumn()
.width($('#example').width())
.x.$key('year')
.y.$key('unitsSold')
.groupsOf(parsedData.data[0].values.length);
d3.select('#example')
.datum(parsedData.data)
.call(chart);
grouped-row.js
groupedRow
The grouped row chart is used to compare a series of data elements grouped along the xAxis. This chart is often useful in conjunction with a stacked row chart because they can use the same data series, and where the stacked row highlights the sum of the data series across an axis the grouped row can be used to show the relative distribution.
Features
bars - series bars
barLabels - data labels above the bars
groupsOf - an integer representing the number of rows in each group
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold:-100, salesman : 'Bob' },
{ year: '2011', unitsSold:200, salesman : 'Bob' },
{ year: '2012', unitsSold:300, salesman : 'Bob' },
{ year: '2013', unitsSold:400, salesman : 'Bob' },
{ year: '2014', unitsSold:500, salesman : 'Bob' },
{ year: '2010', unitsSold:100, salesman : 'Gina' },
{ year: '2011', unitsSold:100, salesman : 'Gina' },
{ year: '2012', unitsSold:-100, salesman : 'Gina' },
{ year: '2013', unitsSold:500, salesman : 'Gina' },
{ year: '2014', unitsSold:600, salesman : 'Gina' },
{ year: '2010', unitsSold:400, salesman : 'Average' },
{ year: '2011', unitsSold:0, salesman : 'Average' },
{ year: '2012', unitsSold:400, salesman : 'Average' },
{ year: '2013', unitsSold:400, salesman : 'Average' },
{ year: '2014', unitsSold:400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedGroup()
.x('year')
.y('unitsSold')
.value('unitsSold')(data);
var chart = d4.charts.groupedRow()
.width($('#example').width())
.x.$key('year')
.y.$key('unitsSold')
.groupsOf(parsedData.data[0].values.length);
d3.select('#example')
.datum(parsedData.data)
.call(chart);
line.js
line
The line series chart is used to compare a series of data elements grouped along the xAxis.
Features
lineSeries - series lines
lineSeriesLabels - data labels beside the lines
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold:-100, salesman : 'Bob' },
{ year: '2011', unitsSold:200, salesman : 'Bob' },
{ year: '2012', unitsSold:300, salesman : 'Bob' },
{ year: '2013', unitsSold:400, salesman : 'Bob' },
{ year: '2014', unitsSold:500, salesman : 'Bob' },
{ year: '2010', unitsSold:100, salesman : 'Gina' },
{ year: '2011', unitsSold:100, salesman : 'Gina' },
{ year: '2012', unitsSold:-100, salesman : 'Gina' },
{ year: '2013', unitsSold:500, salesman : 'Gina' },
{ year: '2014', unitsSold:600, salesman : 'Gina' },
{ year: '2010', unitsSold:400, salesman : 'Average' },
{ year: '2011', unitsSold:0, salesman : 'Average' },
{ year: '2012', unitsSold:400, salesman : 'Average' },
{ year: '2013', unitsSold:400, salesman : 'Average' },
{ year: '2014', unitsSold:400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedGroup()
.x(function(){
return 'year';
})
.nestKey(function(){
return 'salesman';
})
.y(function(){
return 'unitsSold';
})
.value(function(){
return 'unitsSold';
})(data);
var chart = d4.charts.line()
.width($('#example').width())
.x.$key('year')
.y.$key('unitsSold');
d3.select('#example')
.datum(parsedData.data)
.call(chart);
row.js
row
The row chart has two axes (x and y). By default the column chart expects
linear scale values for the x and ordinal scale values on the y. The basic column chart
has four default features:
Features
bars - series bars
barLabels - data labels to the right of the bars
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ y: '2010', x:-10 },
{ y: '2011', x:20 },
{ y: '2012', x:30 },
{ y: '2013', x:40 },
{ y: '2014', x:50 },
];
var chart = d4.charts.row();
d3.select('#example')
.datum(data)
.call(chart);
scatter.js
scatterPlot
The scatter plot has three axes (x, y and z). By default the scatter
plot expects linear scale values for all axes. The basic scatter plot chart
has these default features:
Features
circles - series of circles
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ age: 12, unitsSold: 0, month: 1 },
{ age: 22, unitsSold: 200, month: 2 },
{ age: 42, unitsSold: 300, month: 3 },
{ age: 32, unitsSold: 400, month: 4 },
{ age: 2 , unitsSold: 400, month: 2 }
];
var chart = d4.charts.scatterPlot()
.x(function(x){
x.min(-10)
x.key('age');
})
.y(function(y){
y.key('month');
})
.z(function(z){
z.key('unitsSold');
});
d3.select('#example')
.datum(data)
.call(chart);
stacked-column.js
stackedColumn
The stacked column chart has two axes (x and y). By default the stacked
column expects continious scale for the y axis and a discrete scale for
the x axis. The stacked column has the following default features:
Features
bars - series of rects
barLabels - individual data values inside the stacked rect
connectors - visual lines that connect the various stacked columns together
columnTotals - column labels which total the values of each stack.
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold: 200, salesman : 'Bob' },
{ year: '2011', unitsSold: 200, salesman : 'Bob' },
{ year: '2012', unitsSold: 300, salesman : 'Bob' },
{ year: '2013', unitsSold: -400, salesman : 'Bob' },
{ year: '2014', unitsSold: -500, salesman : 'Bob' },
{ year: '2010', unitsSold: 100, salesman : 'Gina' },
{ year: '2011', unitsSold: 100, salesman : 'Gina' },
{ year: '2012', unitsSold: 200, salesman : 'Gina' },
{ year: '2013', unitsSold: -500, salesman : 'Gina' },
{ year: '2014', unitsSold: -600, salesman : 'Gina' },
{ year: '2010', unitsSold: 400, salesman : 'Average' },
{ year: '2011', unitsSold: 100, salesman : 'Average' },
{ year: '2012', unitsSold: 400, salesman : 'Average' },
{ year: '2013', unitsSold: -400, salesman : 'Average' },
{ year: '2014', unitsSold: -400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedStack()
.x(function(){
return 'year';
})
.y(function(){
return 'salesman';
})
.value(function(){
return 'unitsSold';
})(data);
var chart = d4.charts.stackedColumn()
.x(function(x){
x.key('year');
})
.y(function(y){
y.key('unitsSold');
})
d3.select('#example')
.datum(parsedData.data)
.call(chart);
stacked-row.js
stackedRow
The stacked row chart has two axes (x and y). By default the stacked
row expects continious scale for the x axis and a discrete scale for
the y axis. The stacked row has the following default features:
Features
bars - series of rects
barLabels - individual data values inside the stacked rect
connectors - visual lines that connect the various stacked columns together
columnTotals - column labels which total the values of each stack.
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ year: '2010', unitsSold: 200, salesman : 'Bob' },
{ year: '2011', unitsSold: 200, salesman : 'Bob' },
{ year: '2012', unitsSold: 300, salesman : 'Bob' },
{ year: '2013', unitsSold: -400, salesman : 'Bob' },
{ year: '2014', unitsSold: -500, salesman : 'Bob' },
{ year: '2010', unitsSold: 100, salesman : 'Gina' },
{ year: '2011', unitsSold: 100, salesman : 'Gina' },
{ year: '2012', unitsSold: 200, salesman : 'Gina' },
{ year: '2013', unitsSold: -500, salesman : 'Gina' },
{ year: '2014', unitsSold: -600, salesman : 'Gina' },
{ year: '2010', unitsSold: 400, salesman : 'Average' },
{ year: '2011', unitsSold: 200, salesman : 'Average' },
{ year: '2012', unitsSold: 400, salesman : 'Average' },
{ year: '2013', unitsSold: -400, salesman : 'Average' },
{ year: '2014', unitsSold: -400, salesman : 'Average' }
];
var parsedData = d4.parsers.nestedStack()
.x(function(){
return 'year';
})
.y(function(){
return 'salesman';
})
.value(function(){
return 'unitsSold';
})(data);
var chart = d4.charts.stackedRow()
.x(function(x){
x.key('unitsSold');
})
.valueKey('unitsSold')
.y(function(y){
y.key('year');
});
d3.select('#example')
.datum(parsedData.data)
.call(chart);
waterfall.js
waterfall
The waterfall chart visually tallies the cumulative result of negative and positive values over a data series. In addition to specifying the normal positive and negative values d4's also lets you designate a column as a subtotal column by passing in an "e" as the value key, which may be a familiar convention if you have used think-cell.
The waterfall chart has two axes (x and y). By default the stacked
column expects continious scale for the y axis and a discrete scale for
the x axis. This will render the waterfall chart vertically. However,
if you swap the scale types then the waterfall will render horizontally.
Features
bars - series of rects
connectors - visual lines that connect the various stacked columns together
columnLabels - column labels which total the values of each rect.
xAxis - the axis for the x dimension
yAxis - the axis for the y dimension
Example Usage
var data = [
{ 'category': 'Job', 'value': 27 },
{ 'category': 'Groceries', 'value': -3 },
{ 'category': 'Allowance', 'value': 22 },
{ 'category': 'Subtotal', 'value': 'e' },
{ 'category': 'Videos', 'value': -22 },
{ 'category': 'Coffee', 'value': -4 },
{ 'category': 'Total', 'value': 'e' }
];
var parsedData = d4.parsers.waterfall()
.x(function() {
return 'category';
})
.y(function() {
return 'value';
})
.nestKey(function() {
return 'category';
})(data);
var chart = d4.charts.waterfall()
.width($('#example').width())
.x(function(x){
x.key('category');
})
.y(function(y){
y.key('value');
});
d3.select('#example')
.datum(parsedData.data)
.call(chart);
arc-labels.js
arcLabels
Arc labels are used to annotate arc series, for example those created by pie and donut charts. Many of the accessors of this feature proxy directly to D3's arc object: https://github.com/mbostock/d3/wiki/SVG-Shapes#arc
Accessors
centroid - proxied accessor to the navtive d3 function
classes - classes assigned to the arc label.
duration - time in milliseconds for the transition to occur.
endAngle - proxied accessor to the navtive d3 function
innerRadius - proxied accessor to the navtive d3 function
key - unique identifier used for linking the element during d3's transition process
outerRadius - proxied accessor to the navtive d3 function
startAngle - proxied accessor to the navtive d3 function
text - value to display in the label.
x - position across the x axis
y - position across the y axis
arc-series.js
arcSeries
Arc series is a collection of arcs suitable for those needed by pie and donut charts. Many of the accessors of this feature proxy directly to D3's arc object: https://github.com/mbostock/d3/wiki/SVG-Shapes#arc
Accessors
centroid - proxied accessor to the navtive d3 function
classes - classes assigned to the arc label.
duration - time in milliseconds for the transition to occur.
endAngle - proxied accessor to the navtive d3 function
innerRadius - proxied accessor to the navtive d3 function
key - unique identifier used for linking the element during d3's transition process
outerRadius - proxied accessor to the navtive d3 function
startAngle - proxied accessor to the navtive d3 function
x - position across the x axis
y - position across the y axis
arrow.js
arrow
The arrow feature is a convienient way to visually draw attention to a portion of a chart by pointing an arrow at it.
brush.js
column-labels.js
columnLabels
The columnLabels feature is used to affix data labels to column series.
grid.js
grid
This feature allows you to specify a grid over a portion or the entire chart area.
grouped-column-series.js
groupedColumnSeries
This feature is specifically designed to use with the groupedColumn and groupedRow charts.
line-series-labels.js
lineSeriesLabels
Approach based off this example: http://bl.ocks.org/mbostock/3902569
line-series.js
@name lineSeries
reference-line.js
referenceLine
The reference line feature is helpful when you want to apply a line to a chart which demarcates a value within the data. For example a common use of this feature is to specify the zero value across an axis.
stacked-column-connectors.js
stackedColumnConnectors
Column connectors helpful when displaying a stacked column chart. A connector will not connect positve and negative columns. This is because in a stacked column a negative column may move many series below its previous location. This creates a messy collection of crisscrossing lines.
stacked-labels.js
stackedLabels
The stackedLabels are appropriate for use with the stacked shape series.
stacked-shapes-series.js
circleSeries
This feature is useful for displaying charts which need stacked circles. Note: Many of the d4 charts use the stacked series as the base, and simply renders only one series, if there is nothing to stack.
Accessors
classes - classes assigned to each circle in the series
cx - placement on the chart's x axis
cy - placement on the chart's y axis
r - radius of the circle
ellipseSeries
This feature is useful for displaying charts which need stacked ellipses. Note: Many of the d4 charts use the stacked series as the base, and simply renders only one series, if there is nothing to stack.
Accessors
classes - classes assigned to each ellipse in the series
cx - placement on the chart's x axis
cy - placement on the chart's y axis
rx - radius of the ellipse on the x axis
ry - radius of the ellipse on the y axis
rectSeries
This feature is useful for displaying charts which need stacked rects. Note: Many of the d4 charts use the stacked series as the base, and simply renders only one series, if there is nothing to stack.
Accessors
classes - classes assigned to each rect in the series
height - height of the rect
rx - rounding of the corners against the x dimension
ry - rounding of the corners against the y dimension
width - width of the rect
x - placement on the chart's x axis
y - placement on the chart's y axis
trend-line.js
trendLine
A trendline allows you to associate a line with a numerical value.
waterfall-connectors.js
waterfallConnectors
Waterfall connectors are orthogonal series connectors which visually join column series together by spanning the top or bottom of adjacent columns.
Accessors
x - Used in placement of the connector lines.
y - Used in placement of the connector lines.
span - calculates the length of the connector line
classes - applies the class to the connector lines.
x-axis.js
xAxis
This feature creates an xAxis for use within d4. There are a variety of accessors described below which modify the behavior and apperance of the axis.
Accessors
axis - The d3 axis object itself.
innerTickSize - see: https://github.com/mbostock/d3/wiki/SVG-Axes#innerTickSize
orient - see: https://github.com/mbostock/d3/wiki/SVG-Axes#orient
outerTickSize- see: https://github.com/mbostock/d3/wiki/SVG-Axes#outerTickSize
scale - see: https://github.com/mbostock/d3/wiki/SVG-Axes#scale
stagger - (true | false) determines if the axis should stagger overlapping text (true by default)
tickFormat - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickFormat
tickPadding - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickPadding
tickSize - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickSize
tickSubdivide- see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickSubdivide
tickValues - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickValues
ticks - see: https://github.com/mbostock/d3/wiki/SVG-Axes#ticks
var chart = d4.charts.groupedColumn()
.using('yAxis', function(axis){
// adjust the number of tick marks based on the height of the chart
axis.ticks($('#example').height()/20);
// set the inner and outer tick sizes
axis.tickSize(10,5);
// adjust the tick padding
axis.tickPadding(5);
})
.using('xAxis', function(axis){
// position the tickmarks on the top of the axis line
axis.orient('top');
// move the axis to the top of the chart.
axis.align('top');
})
y-axis.js
yAxis
This feature creates an xAxis for use within d4. There are a variety of accessors described below which modify the behavior and apperance of the axis.
Accessors
axis - The d3 axis object itself.
innerTickSize - see: https://github.com/mbostock/d3/wiki/SVG-Axes#innerTickSize
orient - see: https://github.com/mbostock/d3/wiki/SVG-Axes#orient
outerTickSize- see: https://github.com/mbostock/d3/wiki/SVG-Axes#outerTickSize
scale - see: https://github.com/mbostock/d3/wiki/SVG-Axes#scale
stagger - (true | false) determines if the axis should stagger overlapping text (true by default)
tickFormat - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickFormat
tickPadding - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickPadding
tickSize - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickSize
tickSubdivide- see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickSubdivide
tickValues - see: https://github.com/mbostock/d3/wiki/SVG-Axes#tickValues
ticks - see: https://github.com/mbostock/d3/wiki/SVG-Axes#ticks
Examples
var chart = d4.charts.groupedColumn()
.using('yAxis', function(axis){
// adjust the number of tick marks based on the height of the chart
axis.ticks($('#example').height()/20);
// set the inner and outer tick sizes
axis.tickSize(10,5);
// adjust the tick padding
axis.tickPadding(5);
})
.using('xAxis', function(axis){
// position the tickmarks on the top of the axis line
axis.orient('top');
// move the axis to the top of the chart.
axis.y(-20);
})
nested-group.js
nestedGroup
The nested group parser is useful for grouped column charts where multiple data items need to appear relative to the axis value, for example grouped column charts or multi-series line charts.
_____________________
| _ |
| _ _ | |_ |
| | | | | | | |
----------------------
This module makes use of the d3's "nest" data structure layout
https://github.com/mbostock/d3/wiki/Arrays#-nest
Approach
Just like D3, this parser uses a chaining declaritiave style to build up the necessary prerequistes to create the waterfall data. Here is a simple example. Given a data item structure like this: {"category" : "Category One", "value" : 23 }
var parser = d4.parsers.nestedGroup()
.x('category')
.y('value')
.value('value');
var groupedColumnData = parser(data);
Keep reading for more information on these various accessor functions.
Accessor Methods
x - A function which returns a key to access the x values in the data array
y - A function which returns a key to access the y values in the data array
value - A function which returns a key to access the values in the data array.
data - An array of objects with their dimensions specified like this:
var data = [
{"year" : "2010", "category" : "Category One", "value" : 23 },
{"year" : "2010", "category" : "Category Two", "value" : 55 },
{"year" : "2010", "category" : "Category Three", "value" : -10 },
{"year" : "2010", "category" : "Category Four", "value" : 5 }]
nested-stack.js
nestedStack
The nested stack parser is useful for charts which take a data series and wants to sort them across a dimension and then display the results. The most common usecase would be a stacked column chart like this:
_____________________
| _ |
| | | _ |
| |-| | | _ |
| |-| |-| |-| |
| | | |-| |-| |
----------------------
This module makes use of the d3's "nest" data structure, and "stack" layout
Approach
Just like D3, this parser uses a chaining declaritiave style to build up the necessary prerequistes to create the stacked data. Here is a simple example:
var parser = d4.parsers.nestedStack()
.x(function() {
return 'title';
})
.y(function(){
return 'group';
})
.value(function() {
return 'values';
});
var stackedData = parser(data);
Keep reading for more information on these various accessor functions.
Benefits
- Supports negative and positive stacked data series.
Limitations
- The parser expects the stack will occur on the yAxis, which means it is only suitable for column charts presently.
Accessor Methods
x : - function which returns a key to access the x values in the data array
y : - function which returns a key to access the y values in the data array
value : - function which returns a key to access the values in the data array.
data : array - An array of objects with their dimensions specified like this:
var data = [{ "title": "3 Years", "group" : "one", "value": 30 },
{ "title": "3 Years", "group" : "two", "value": 20 },
{ "title": "3 Years", "group" : "three", "value": 10 },
{ "title": "5 Years", "group" : "one", "value": 3 },
{ "title": "5 Years", "group" : "two", "value": 2 },
{ "title": "5 Years", "group" : "three", "value": 1 }]
Example Usage
Given the example data and dimension variables above you can use this module in the following way:
var parser = d4.parsers.nestedStack()
.x(function() {
return 'title';
})
.y(function(){
return 'group';
})
.value(function() {
return 'value';
})
.call(data);
The parser variable will now be an object containing the following structure:
{
data: Array
value: {
key: string,
values: Array
},
x: {
key: string,
values: Array
},
y: {
key: string,
values: Array
}
}
waterfall.js
waterfall
The waterfall parser is useful for waterfall charts where data items need to account for the position of earlier values:
_____________________
| _ _______ |
| |_|___ | | | | |
| |_|__|_| | | |
| |_| |
----------------------
This module makes use of the d3's "nest" data structure, and "stack" layout https://github.com/mbostock/d3/wiki/Arrays#-nest https://github.com/mbostock/d3/wiki/Stack-Layout
Approach:
Just like D3, this parser uses a chaining declaritiave style to build up the necessary prerequistes to create the waterfall data. Here is a simple example. Given a data item structure like this: {"category" : "Category One", "value" : 23 }
var parser = d4.parsers.waterfall()
.x(function() {
return 'category';
})
.y(function(){
return 'value';
})
.value(function() {
return 'value';
});
var waterfallData = parser(data);
Keep reading for more information on these various accessor functions.
Benefits:
Supports horizontal or vertical waterfalls Supports totaling series using a special "e" value in a data item.
Limitations:
Does not support stacked waterfalls.
Accessors:
x : - function which returns a key to access the x values in the data array
y : - function which returns a key to access the y values in the data array
value : - function which returns a key to access the values in the data array.
data : array - An array of objects with their dimensions specified
like this:
var data = [
{"category" : "Category One", "value" : 23 },
{"category" : "Category Two", "value" : 55 },
{"category" : "Category Three", "value" : -10 },
{"category" : "Category Four", "value" : 5 },
{"category" : "Category Five", "value" : "e" }]
SPECIAL NOTE:
Waterfalls charts typically have the ability to display subtotals at any point. In order to use this feature simply set the value of your subtotal column to "e."
Example Usage:
Given the example data and dimension variables above you can use this module in the following way:
var parser = d4.parsers.nestedStack()
.dimensions(dimensions)
.call(data);
The `parser` variable will now be an object containing the following structure:
{
data: Array
value: {
key: string,
values: Array
},
x: {
key: string,
values: Array
},
y: {
key: string,
values: Array
}
}
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.