Permalink
Fetching contributors…
Cannot retrieve contributors at this time
209 lines (154 sloc) 6.98 KB

d3-ez

D3 Easy Reusable Charts

npm version Build Status Known Vulnerabilities

d3-ez is a library of reusable charts which use D3.js. Inspired by Mike Bostock's tutorial Towards Reusable Charts, the aim of the library is to harness the power of D3, whilst simplifying the process of creating charts and graph making with D3. d3-ez makes it easier for people who are still learning JavaScript or D3 to quickly produce data visualisations with minimal code.

Getting Started

The primary aim of d3-ez is to make is quick and easy to generate charts. The following example shows how, with minimal code, you can be up and running with a simple bar chart in no time!

Include the D3.js and d3-ez JS and CSS files in your page header:

<script src="d3.v5.min.js"></script>
<script src="d3-ez.min.js"></script>
<link rel="stylesheet" type="text/css" href="d3-ez.css" />

Add a 'chartholder' DIV to your page body:

<div id="chartholder"></div>

Generate some data: See the Data Structure section for more details.

var data = {
	"key": "Fruit",
	"values": [
		{"key": "Apples", "value": 9},
		{"key": "Oranges", "value": 3},
		{"key": "Grapes", "value": 5},
		{"key": "Bananas", "value": 7}
	]
};

Configure chart components, 'chart', 'legend' & 'title': See the Chart Components section for more details.

var title = d3.ez.component.title()
	.mainText("Super Fruit Survey")
	.subText("Which fruit do you like?");

var chart = d3.ez.chart.barChartVertical()
	.colors(['#00c41d', '#ffa500', '#800080', '#ffe714']);

var legend = d3.ez.component.legend()
	.title("Fruit Type");

Construct chart base from the above components: See the Chart Base for more details.

var myChart = d3.ez.base()
	.width(750)
	.height(400)
	.chart(chart)
	.legend(legend)
	.title(title);

Attach data and chart to 'chartholder' DIV:

d3.select("#chartholder")
	.datum(data)
	.call(myChart);

Chart Base

The chart base has 3 components:

  • Title
  • Legend
  • Chart

Chart Components

As described in the Chart Base section a d3-ez chart is made up of 3 components:

Title

The title component has the following options:

  • mainText() The main title.
  • subText() The sub title. Example:
var title = d3.ez.component.title()
	.mainText("Super Fruit Survey")
	.subText("Which fruit do you like?");

Legend

The title component has the following options:

  • title() The legend title.
var legend = d3.ez.component.legend()
	.title("Fruit Type");

Chart

The following charts are currently supported:

  • barChartClustered()
  • barChartStacked()
  • barChartHorizontal()
  • barChartVertical()
  • barChartCircular()
  • bubbleChart()
  • donutChart()
  • heatMapTable()
  • heatMapRadial()
  • candleChart()
  • lineChart()
  • polarAreaChart()
  • punchCard()
  • radarChart()
  • roseChart()

All of the above support the following options:

  • colors()

All the above charts can also be used stand-alone without having to attach them to a chart base. This can be useful should you just want the main chart but not a legend or title, or you may wish to insert the chart into your own custom D3 project.

var myChart = d3.ez.chart.discreteBar()
	.width(750)
	.height(400)
	.colors(['#00c41d', '#FFA500', '#800080', '#ffe714']);

d3.select("#chartholder")
	.datum(data)
	.call(myChart);

Data Structure

The format of the d3-ez data must be in key / value pairs.

Examples

Here are a few Blocks (Gists) examples demonstrating some of the d3-ez charts. One of the aims of d3-ez to make it easier to create visualizations with graphs which are clickable interact with each other, this is done though the use of D3's dispatch, please see the 'Showcase' link below for example:

What type of chart should I use?

What type of chart is best for different types of data?

  • Bar charts are good for quantitative data.
  • Pie charts for good to represent parts of a whole.
  • Histograms are good for showing distribution.
  • Line charts are good for showing time series data.
  • Circular heatmap is good for cyclic data (rolling hours, days, years).

For more information on which charts are good for different types of data see the Data Viz Project or Data Viz Catalogue

Alternatives to d3-ez

For reference here are a few other alternative D3 chart libraries which also follow the D3 reusable components pattern:

Credits