❤
npm
Sign UpSign In

d3-ez

3.3.15 • Public • Published

d3-ez

D3 Easy Reusable Charts Library

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.

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:

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.v5.min.js"></script> 
   <script src="https://raw.githack.com/jamesleesaunders/d3-ez/master/build/d3-ez.min.js"></script> 
   <link rel="stylesheet" type="text/css" href="https://raw.githack.com/jamesleesaunders/d3-ez/master/build/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 }
    ]
};

Declare the chart and components component: chart, legend and title:

var chart = d3.ez.chart.barChartVertical()
    .colors(['#00c41d', '#ffa500', '#800080', '#ffe714']);
 
var legend = d3.ez.component.legend()
    .title("Fruit Type");
 
var title = d3.ez.component.title()
    .mainText("Super Fruit Survey")
    .subText("Which fruit do you like?");

Construct chart base from the above components:

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

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");

Components and Charts

As described above, d3-ez charts are made up of three components: chart, legend and title. For more information see the API Reference.

Chart

The following charts are currently supported:

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

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);

Legend

The title component has the following options:

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

Title

The title component has the following options:

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

All of the components above support the following options:

  • colors()

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.

Single Series Data

Used by charts such as a single series bar chart, 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: 9, x: 1, y: 2, z: 5 },
        /* ... */
        { key: "Bananas", value: 7, x: 6, y: 3, z: 8 }
    ]
};

Multi Series Data

Used by charts such as the multi series scatter plot, the multi series data structure is simply an array of the single series data objects above.

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).

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

Readme

Keywords

Package Sidebar

Install

npm i d3-ez

Repository

github.com/jamesleesaunders/d3-ez

Homepage

d3-ez.net

Weekly Downloads

129

Version

3.3.15

License

GPL-2.0

Unpacked Size

13.8 MB

Total Files

284

Last publish

Collaborators

  • jamesleesaunders
Try on RunKit
Report malware