datagovsg-plottable-charts

datagovsg-plottable-charts

Motivation

Generating a chart is easy, making it looks beautiful requires much more effort. Numerous charting libraries have been written to solves the basic problem of converting data to chart objects. Regardless of the library you choose, out-of-the-box defaults hardly produces the look you want.

Charts on Data.gov.sg are rendered using the Plottable library. Based on D3, it is highly flexible and gives you many low level controls to fine-tune every single detail. However, this power comes at the price of additional configurations. We want to abstract away these configurations by creating wrappers that pre-apply all the styles we want on our component. That's why we created this library.

What it does for you

Tooltips

Pie chart labels

Automatically downsample tick marks

And many more...

How to use

Dependencies

• D3
• Plottable
• JQuery (optional, only if you require tooltip)

Use with bundler (Webpack, Rollup etc)

npm install --save datagovsg-plottable-charts

<!-- html -->
<link rel="stylesheet" href="lib/plottable.css">
<link rel="stylesheet" href="lib/datagovsg-charts.css">
<!-- ... -->
<script src="lib/d3.min.js"></script>
<script src="lib/plottable.min.js"></script>

/* js */
import {SimplePie} from 'datagovsg-plottable-charts'

// Instantiate the chart component
const pie = new SimplePie(props)

// Mount component
pie.mount(document.getElementById('ctn'))

// Update chart
pie.update(newProps)

Using plugins

import {
  highlightOnHover,
  setupOuterLabel
} from 'datagovsg-plottable-charts/dist/plugins'

highlightOnHover(pie)
setupOuterLabel(pie)

Use without a bundler

<!-- html -->
<script src="lib/datagovsg-charts.min.js"></script>

/* js */
const {SimplePie, plugins} = window.DatagovsgCharts
const {highlightOnHover, setupOuterLabel} = plugins

const pie = new SimplePie(props)
highlightOnHover(pie)
setupOuterLabel(pie)

Full Component List

Pre-styled

• DatagovsgSimplePie
• DatagovsgSimpleBar
• DatagovsgHorizontalBar
• DatagovsgGroupedBar
• DatagovsgStackedBar
• DatagovsgLine

Unstyled

• SimplePie
• SimpleBar
• GroupedBar
• StackedBar
• MultipleLine

Full Plugin List

• highlightOnHover
• setupTooltip
• setupPopover
• setupPopoverOnGuideLine
• setupShadowWithPopover
• customizeTimeAxis
• removeInnerPadding
• downsampleTicks

Useful helpers

• DATAGOVSG_COLORS
• getScale
• getCategoryScale
• getColorScale
• getSingleColorScale
• getTimeScale

PivotTable

Example usage

import {DatagovsgLine} from 'datagovsg-plottable-charts'
import PivotTable, {
  filterItems,
  filterGroups,
  groupItems,
  aggregate
} from 'datagovsg-plottable-charts/dist/PivotTable'

const pivotTable = new PivotTable(data)

pivotTable.push(
  filterItems('income', {type: 'exclude', values: ['-', 'na']}),
  groupItems('gender'),
  filterGroups('gender', {type: 'exclude', values: ['Total']})
  aggregate('year', 'income')
)

const processedData = pivotTable.transform()

const series = processedData.map(g => ({
  label: g._group.gender,
  series: g._summaries[0].series
}))

const chart = new DatagovsgLine({data: series})
chart.mount(document.getElementById('chart'))

How it works

Original data

year	gender	income
2006	Total	2042
2016	Total	3250
2017	Total	-
2006	Male	2213
2016	Male	3500
2006	Female	1875
2016	Female	2979

Transform into custom data structure

pivotTable.transform()
// returns
[
  {
    _group: {},
    _items: [
      {year: 2006, gender: 'Total', income: 2042},
      {year: 2016, gender: 'Total', income: 3250},
      {year: 2016, gender: 'Total', income: '-'},
      {year: 2006, gender: 'Male', income: 2213},
      {year: 2016, gender: 'Male', income: 3500},
      {year: 2006, gender: 'Female', income: 1875},
      {year: 2016, gender: 'Female', income: 2979}
    ],
    _summaries: []
  }
]

filterItems( )

pivotTable.push(
  filterItems('income', {type: 'exclude', values: ['-', 'na']})
)
pivotTable.transform()
// returns
[
  {
    _group: {},
    _items: [
      {year: 2006, gender: 'Total', income: 2042},
      {year: 2016, gender: 'Total', income: 3250},
      {year: 2006, gender: 'Male', income: 2213},
      {year: 2016, gender: 'Male', income: 3500},
      {year: 2006, gender: 'Female', income: 1875},
      {year: 2016, gender: 'Female', income: 2979}
    ],
    _summaries: []
  }
]

groupItems( )

pivotTable.push(
  filterItems('income', {type: 'exclude', values: ['Total']}),
  groupItems('gender')
)
pivotTable.transform()
// returns
[
  {
    _group: {gender: 'Total'},
    _items: [
      {year: 2006, gender: 'Total', income: 2042},
      {year: 2016, gender: 'Total', income: 3250},
    ],
    _summaries: []
  },
  {
    _group: {gender: 'Male'},
    _items: [
      {year: 2006, gender: 'Male', income: 2213},
      {year: 2016, gender: 'Male', income: 3500},
    ],
    _summaries: []
  },
  {
    _group: {gender: 'Female'},
    _items: [
      {year: 2006, gender: 'Female', income: 1875},
      {year: 2016, gender: 'Female', income: 2979}
    ],
    _summaries: []
  }
]

filterGroups( )

pivotTable.push(
  filterItems('income', {type: 'exclude', values: ['-', 'na']}),
  groupItems('gender'),
  filterGroups('gender', {type: 'exclude', values: ['Total']})
)
pivotTable.transform()
// returns
[
  {
    _group: {gender: 'Male'},
    _items: [
      {year: 2006, gender: 'Male', income: 2213},
      {year: 2016, gender: 'Male', income: 3500},
    ],
    _summaries: []
  },
  {
    _group: {gender: 'Female'},
    _items: [
      {year: 2006, gender: 'Female', income: 1875},
      {year: 2016, gender: 'Female', income: 2979}
    ],
    _summaries: []
  }
]

aggregate( )

pivotTable.push(
  filterItems('income', {type: 'exclude', values: ['-', 'na']}),
  groupItems('gender'),
  filterGroups('gender', {type: 'exclude', values: ['Total']})
  aggregate('year', 'income')
)
pivotTable.transform()
// returns
[
  {
    _group: {gender: 'Male'},
    _items: [
      {year: 2006, gender: 'Male', income: 2213},
      {year: 2016, gender: 'Male', income: 3500},
    ],
    _summaries: [
      {
        labelField: 'year',
        valueField: 'income',
        series: [
          {label: 2006, value: 2213},
          {label: 2016, value: 3500}
        ]
      }
    ]
  },
  {
    _group: {gender: 'Female'},
    _items: [
      {year: 2006, gender: 'Female', income: 1875},
      {year: 2016, gender: 'Female', income: 2979}
    ],
    _summaries: [
      {
        labelField: 'year',
        valueField: 'income',
        series: [
          {label: 2006, value: 1875},
          {label: 2016, value: 2979}
        ]
      }
    ]
  }
]

Using without bundler

<!-- html -->
<script src="lib/pivot-table.min.js"></script>

/* js */
const PivotTable = window.PivotTable
const {filterItems, groupItems, filterGroups, aggregate} = PivotTable

Debugging guide

1. Clone the datagovsg/datagovsg-plottable-charts repo
2. cd to the cloned repo
3. Run npm install
4. Change main field in the package.json to "main": "src/index.js"
5. Delete module field in the package.json
6. Set up a symlink sudo npm link
7. cd to your working directory
8. Run npm link datagovsg-plottable-charts