gobierto-vizzs

Shared data visualizations for Gobierto projects

Usage no npm install needed!

<script type="module">
  import gobiertoVizzs from 'https://cdn.skypack.dev/gobierto-vizzs';
</script>

README

gobierto-vizzs

Reusable visualizations used in Gobierto. Check out the demo!

API

BeeSwarm

import { BeeSwarm } from "gobierto-vizzs"

const bee = new BeeSwarm(chart, data, options)

// ...update data
bee.setData(newData)

chart (HTMLElement): DOM node where put the visualization

data (Array): Elements to display

options (Object): To custom the defaults presets. Optional. All properties come with setters, that is, once you have the object you can change any property using setPROP(VALUE), i.e. setX("prop"), setMargin({ left: 30 }), setOnClick(() => {}) etc...

name type default description
x String "date" Property name of the X-axis. It must contain a date-like value.
y String "group" Property name of the Y-axis. Categories to be grouped by.
value String "value" Property name of the radius. Quantitative value.
id String "id" Property name of the id or title. Better if unique.
relation String - Property name of the relationship. In order to display some internal relationships between circles of different categories. Only make sense on mouse over.
margin Object { top: 50, bottom: 50, left: 120, right: 30 } Set the margin around the chart. You can pass the properties you want.
locale String window.navigator.language 4-letters specification of the locale.
minBlockSize Number 100 Height of each category. If there are many elements, it's strongly recommended it to increase this value.
circleSize Array [2, 20] Minimum and maximum circle radius size, respectively.
onClick Function - Circle click callback handler. It receives the event and the datum.
tooltip Function 1 Custom HTML content to render in the tooltip on mouseenter. 

defaultTooltip(d) {
  return `
    <div class="beeswarm-tooltip-id">${d[this.idProp]}</div>
    <div class="beeswarm-tooltip-values">
      <span class="beeswarm-tooltip-date">${d[this.xAxisProp].toLocaleDateString()}</span>
      &nbsp;
      <span class="beeswarm-tooltip-radius">${d[this.rAxisProp].toLocaleString()}</span>
    </div>
    `;
}

BeeSwarm examples

If your data array have the expected keys, you can simply do:

import { BeeSwarm } from "gobierto-vizzs"

const chart = document.body
const data = [
  {
    "date": "2020-10-26T13:04:51.746Z",
    "value": 8600,
    "group": "Mayotte",
    "relation": "Ford",
    "id": 0
  },
  {
    "date": "2021-04-03",
    "value": 169,
    "group": "Rwanda",
    "relation": "Polestar",
    "id": 1
  },
  ...
]
const bee = new BeeSwarm(chart, data)

But if not, you can easily parse them using the options setup:

import { BeeSwarm } from "gobierto-vizzs"

const chart = document.body
const data = [
  {
    "imported_date": "2020-10-26T13:04:51.746Z",
    "amount": 8600,
    "category": "Mayotte",
    "event": "Ford",
    "title": 0
  },
  {
    "imported_date": "2021-04-03",
    "amount": 169,
    "category": "Rwanda",
    "event": "Polestar",
    "title": 1
  },
  ...
]
const bee = new BeeSwarm(chart, data, {
  x: "imported_date",
  y: "category",
  value: "amount",
  relation: "event",
  id: "title"
})

Tooltip can be configured with a custom function. The return will be parsed as HTML. Function argument is the current element data.

const tooltip = (data) => `<strong>${data.title}</strong>`
const bee = new BeeSwarm(chart, data, { tooltip })

Set a custom callback when clicking into the circles

const bee = new BeeSwarm(chart, data, { onClick: (event, datum) => /* custom function */ })

If your dataset is quite large and the groups are too close each other, try to increase the minBlockSize property. Similarly, you can change the maximum/minimum size of the circles.

const bee = new BeeSwarm(chart, data, { minBlockSize: 200, circleSize: [3, 30] })

In order to render the chart locale-sensitive stuff, enforce the graph language (List of available locales)

const bee = new BeeSwarm(chart, data, { locale: "it-IT" })

TreeMap

import { TreeMap } from "gobierto-vizzs"

const tree = new TreeMap(chart, data, options)

// ...update data
tree.setData(newData)

chart (HTMLElement): DOM node where put the visualization

data (Array): Elements to display

options (Object): To custom the defaults presets. Optional. All properties come with setters, that is, once you have the object you can change any property using setPROP(VALUE), i.e. setGroup("another_group"), setMargin({ bottom: 0 }), setTooltip(() => {}), etc...

name type default description
group String, Array<String> "group" Property/ies name/s of the different levels of the tree.
value String - Property name of the aggregator. The tree will be adding such value for each item in each category. If none is passed, the treemap will group by number of children.
id String "id" Property name to build the tree object. It works as a title for the different groups.
rootTitle String "root" Display name of the first level of the tree.
margin Object { top: 30, bottom: 0, left: 0, right: 0 } Set the margin around the chart. You can pass the properties you want.
locale String window.navigator.language 4-letters specification of the locale.
onLeafClick Function - Leaf (no children node) click callback handler. It receives the event and the datum.
tooltip Function 1 Custom HTML content to render in the tooltip on mouseenter.
breadcrumb Function 2 Custom HTML content to render in the breadcrumb. It's clickable to change groups.
itemTemplate Function 3 Custom HTML content to render in the item. 

defaultTooltip(d) {
  return d.children && d.data.children.map(x => `
    <div class="treemap-tooltip-block">
      ${[
        `<div class="treemap-tooltip-id">${x[this.idProp]}</div>`,
        x[this.valueProp] && `<div class="treemap-tooltip-values">${x[this.valueProp].toLocaleString()}</div>`
      ].join("")}
    </div>
  `).join("");
}


defaultBreadcrumb(d) {
  return d.map((pathName) => `<span>${pathName}</span>`).join("&nbsp;/&nbsp;");
}


defaultItemTemplate(d) {
  return [
    `<div><strong>${d.data[this.idProp]}</strong></div>`,
    `<div>${d.value.toLocaleString()}</div>`,
    d.children && `<div>${d.children?.length}</div>`,
  ].join("");
}

TreeMap examples

If your data array have the expected keys, you can simply do to display a one level depth treemap, arranged by group property

import { TreeMap } from "gobierto-vizzs"

const chart = document.body
const data = [
  {
    "id": "id nobis possimus incidunt dolorum",
    "group": "Lebanon",
  },
  {
    "id": "adipisci fugiat quidem alias molestiae",
    "group": "Ireland",
  },
  ...
]
const tree = new TreeMap(chart, data)

Instead of the children, if you want to sum the values of a different property, you can set the value prop accordingly

import { TreeMap } from "gobierto-vizzs"

const chart = document.body
const data = [
  {
    "id": "id nobis possimus incidunt dolorum",
    "group": "Lebanon",
    "population": 6e6
  },
  {
    "id": "adipisci fugiat quidem alias molestiae",
    "group": "Ireland",
    "population": 5e6
  },
  ...
]
const tree = new TreeMap(chart, data, { value: "population" })

But if you want more depth levels, and use different keys, try this instead

import { TreeMap } from "gobierto-vizzs"

const chart = document.body
const data = [
  {
    "amount": 8600,
    "category": "Mayotte",
    "category1": "Madagascar",
    "category2": "Mozambique",
    "category3": "Ford",
    "title": 0
  },
  {
    "amount": 169,
    "category": "Rwanda",
    "category1": "Madagascar",
    "category2": "Mozambique",
    "category3": "Polestar",
    "title": 1
  },
  ...
]
const tree = new TreeMap(chart, data, {
  group: ["category", "category1", "category2", "category3"],
  value: "amount",
  id: "title"
})

Tooltip, breadcrumb and item template can be configured with a custom functions. The return will be parsed as HTML.

  • In the tooltip, the argument is the current tree data.
  • In the breadcrumb, the argument is the array of id selected (path names).
  • In the item template, the argument is the current tree data.
const tooltip = (data) => `<strong>${data.title}</strong>`
const breadcrumb = (data) => data.map(d => `<em>${d.id}</em>`).join(">")
const itemTemplate = (data) => `<div>${d.value.toLocaleString()}</div>`
const tree = new TreeMap(chart, data, { tooltip, breadcrumb, itemTemplate })

Set a custom callback when clicking into a leaf (a node with no children)

const tree = new TreeMap(chart, data, { onClick: (event, datum) => /* custom function */ })

Instead of display root as the first item, you may edit the text

const tree = new TreeMap(chart, data, { rootTitle: "Entities" })

In order to render the chart locale-sensitive stuff, enforce the graph language (List of available locales)

const tree = new TreeMap(chart, data, { locale: "it-IT" })

Gantt

import { Gantt } from "gobierto-vizzs"

const gantt = new Gantt(chart, data, options)

// ...update data
gantt.setData(newData)

chart (HTMLElement): DOM node where put the visualization

data (Array): Elements to display

options (Object): To custom the defaults presets. Optional. All properties come with setters, that is, once you have the object you can change any property using setPROP(VALUE), i.e. setX("prop"), setMargin({ left: 30 }), setOnClick(() => {}) etc...

name type default description
x String "phase" Property name of the categories along the X-axis. Legend will be depicted by these values
y String "group" Property name of the Y-axis. Categories to be grouped by.
from String "from" Property name of the initial range. Date-like value.
to String "to" Property name of the end range. Date-like value.
id String "id" Property name of the id or title. Better if unique.
margin Object { top: 30, bottom: 0, left: 0, right: 0 } Set the margin around the chart. You can pass the properties you want.
locale String window.navigator.language 4-letters specification of the locale.
barHeight Number 10 Height of each category.
onClick Function - Circle click callback handler. It receives the event and the datum.
tooltip Function 1 Custom HTML content to render in the tooltip on mouseenter. 

defaultTooltip(d) {
  return `
    <div class="gantt-tooltip-id">${d[this.yAxisProp]}</div>
    <div class="gantt-tooltip-values">
      <span>${d[this.xAxisProp]}:</span>
      <span>${d[this.fromProp].toLocaleDateString()} - ${d[this.toProp].toLocaleDateString()}</span>
    </div>
    `;
}

Gantt examples

If your data array have the expected keys, you can simply do:

import { Gantt } from "gobierto-vizzs"

const chart = document.body
const data = [
  {
    "id": "id nobis possimus incidunt dolorum",
    "group": "Lebanon",
    "phase": "Step 1",
    "from": "2020-01-01",
    "to": "2020-03-01",
  },
  {
    "id": "adipisci fugiat quidem alias molestiae",
    "phase": "Step 2",
    "group": "Lebanon",
    "from": "2020-03-01",
    "to": "2020-06-01",
  },
  ...
]
const gantt = new Gantt(chart, data)

But if not, you can easily parse them using the options setup:

import { BeeSwarm } from "gobierto-vizzs"

const chart = document.body
const data = [
  {
    "start_date": "2020-10-26T13:04:51.746Z",
    "end_date": "2020-12-26T13:04:51.746Z",
    "amount": 8600,
    "category": "Mayotte",
    "event": "#1",
    "title": 0
  },
  {
    "start_date": "2021-04-03",
    "end_date": "2021-04-03",
    "amount": 169,
    "category": "Mayotte",
    "event": "#2",
    "title": 1
  },
  ...
]
const gantt = new Gantt(chart, data, {
  from: "start_date",
  to: "end_date",
  x: "event",
  y: "category",
  id: "title"
})

Set a custom callback when clicking into a leaf (a node with no children)

const gantt = new Gantt(chart, data, { onClick: (event, datum) => /* custom function */ })

In order to render the chart locale-sensitive stuff, enforce the graph language (List of available locales)

const gantt = new Gantt(chart, data, { locale: "it-IT" })

Helpers

toJSON

Convenience method to transform a CSV text into a JSON structure, assuming the CSV separator is a comma ,

import { toJSON } from "gobierto-vizzs"

const data = toJSON(CSV_STRING)

You can use a different separator as well

import { toJSON } from "gobierto-vizzs"

const data = toJSON(CSV_STRING, ";")

Styling

All charts uses CSS custom variables to define the palette, you may overwrite them:

:root {
  --gv-color-1: #008e9c;
  --gv-color-2: #12365b;
  --gv-color-3: #ff776d;
  --gv-color-4: #f8b205;
  --gv-color-5: #a6cee3;
  --gv-color-6: #1f78b4;
  --gv-color-7: #b2df8a;
  --gv-color-8: #33a02c;
  --gv-color-9: #fb9a99;
  --gv-color-10: #e31a1c;
  --gv-color-11: #fdbf6f;
  --gv-color-12: #ff7f00;
}

Development

You can try the demos, running the examples:

cd examples
npm install
npm start