Skip to content

Latest commit

 

History

History
206 lines (158 loc) · 6.32 KB

README.md

File metadata and controls

206 lines (158 loc) · 6.32 KB
Raw

d3-ez

D3 Easy Reusable Charts Library

npm version 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.

Examples

Here are a few Observable 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:

Getting Started

Include d3.js and d3-ez.js and css files in the <head> section of your page:

<head>
	 <script src="https://d3js.org/d3.v7.min.js"></script>
	 <script src="https://raw.githack.com/jamesleesaunders/d3-ez/master/dist/d3-ez.min.js"></script>
	 <link rel="stylesheet" type="text/css" href="https://raw.githack.com/jamesleesaunders/d3-ez/master/dist/d3-ez.css"/>
</head>

Add a chartholder <div> and <script> tags to your page <body>:

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

Place the following code between the <script></script> tags:

Select chartholder:

var chartHolder = d3.select("#chartholder");

Generate some data:

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

Create chart component:

var myChart = d3.ez.chart.barChartVertical()
	.width(750)
	.height(400)
	.colors(["#00C41d", "#FFA500", "#800080", "#FFE714"]);

Attach chart and data to the chartholder:

chartHolder
	.datum(myData)
	.call(myChart);

That's all there is to it! View the page in your browser, and you should see a basic bar chart.

Install from NPM

If your project is using ES6 modules you can also import d3-ez, for example from NPM:

npm install --save d3-ez

Then in your project:

let d3Ez = require("d3-ez");

Chart Types

The following charts are currently supported:

  • barChartCircular()
  • barChartHorizontal()
  • barChartVertical()
  • bubbleChart()
  • candlestickChart()
  • donutChart()
  • heatMap()
  • heatMapRadial()
  • lineChart()
  • polarAreaChart()
  • punchCard()
  • radarChart()
  • roseChart()

For more information see the API Reference.

Data Structures

At its most basic description, the format of the d3-ez data is a series of key / value pairs. Depending on whether the chart is a single series or multi series chart the data structure differs slightly.

The data structure is an object with the following structure:

  • key {string} - The series name
  • values {array} - An array of objects containing: * key {string} - The value name * value {number} - The value * x {number} - X axis value* * y {number} - Y axis value*

*optional, x & y values are used for cartesian coordinate type graphs such as the bubble chart.

var myData = [
	{
		key: "UK",
		values: [
			{ key: "Apples", value: 2 },
			/* ... */
			{ key: "Bananas", value: 3 }
		]
	},
	/* ... */
	{
		key: "France",
		values: [
			{ key: "Apples", value: 5 },
			/* ... */
			{ key: "Bananas", value: 9 }
		]
	}
];

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).
  • Radar charts are used to compare two or more items or group features or characteristics.

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

Alternatives

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

Credits