HDX Quick Charts use JSON configuration files to define the different kinds of charts to offer to users for HXL-tagged data. There are three related formats:

A bite, representing a single chart definition.
A recipe, representing a collection of bites from which the user can choose.
A cookbook, containing a selection of recipes.

Bites

A simple bite looks like this:

{
  "title": "Organisations",
  "type":"key figure",
  "ingredient": {
    "aggregateColumn": null,
    "valueColumn": "#org",
    "aggregateFunction": "distinct-count"
  },
  "unit": "orgs",
  "numberFormat": "us"
}

This will generate a key-figure chart showing the number of unique organisations mentioned in the first column with the HXL hashtag “#org”.

title	Chart title to display
type	Type of chart (“key figure”, “chart”, or “timeseries”).
ingredient	Definition of the data to use in the chart (see below).
unit	The label to place under the number for a key figure.
numberFormat	The format to use for numbers (“us” or “de”).

Fields in the “ingredient” object:

aggregateColumn
valueColumn
aggregateFunction	“sum”, “count”, “average”, or “distinct-count”
filtersWith
filtersWithout

Recipes

TODO

Cookbooks

TODO

Old content (ignore)

Each configuration file is a recipe consisting of a list of bites, individual blueprints for making charts from .

Here is an example of a simple bite to display a chart showing the number of unique administrative-level-one subdivisions (e.g. provinces) for each country in a dataset:

^{
^{"name": "Charts: Distinct count of values in value column by the aggregate column",}
^{"description": "",}
^{"type": "chart",}
^{"ingredients": {}
^{"aggregateFunctions": ["distinct-count"],}
^{"aggregateColumns": ["#country"],}
^{"valueColumns":["#adm1"]}

^}
^}

Properties of a bite

name (optional) — a short, generic description of the visualisation.

description (optional) — a longer, human-readable description of the visualisation.

type (required) — the type of visualisation to generate. The options include the following:

"chart" — display either a bar or pie chart, depending on the number of values to show.

"key figure" — display a single number (such as total people in need), optionally with units and description text.

"timeseries" — display the change in values over time.

ingredients (required) — a JSON object (dictionary) containing instructions for creating the visualisation. The object has the following properties:

(Is there a difference between aggregate-function used for an embedded viz and aggregate-functions used in bites.json? Ditto for value-columns vs value-column? What other differences are there between the JSON config for an embedded viz, and the JSON config for offering the user choices of viz?)

the json config file is more a bite generator, this means that we can specify more than one aggregated function. We could do a json bite definition for each aggregated function (count, disting-count or sum), but it is easier/simpler to put all of them there and let system to compute all possibilities. In specific cases (e.g 3w, HNOs, FTS) the recipe could be very simpe in order to generate a limited number of bites tailored for each file type.

aggregate-functions (required) — a JSON array of functions to use to generate summary (aggregate) data from the original dataset. HDX Quick Charts will offer each of these to the user as a separate option. The following functions are available:

"count" — display the total number of times each unique value appears (e.g. the number of activities for each prefecture in a 3W).

"distinct-count" — display the total number of unique values in a column listed in value-columns associated with each unique value in a column listed in aggregate-columns (e.g. the number of unique provinces in each country).

"sum" — add up figures in a column listed in value-columns for each unique value in a column listed in aggregate-columns (e.g. the total number of people in need in each country).

aggregate-columns (optional) — the columns that can be used to group the results (any given chart will use just one of the columns). The value is a JSON array of HXL tag patterns used to match actual hashtags in the document, e.g. "[#adm1", "#adm2"]. When this property is missing, or no columns match the tag patterns, the aggregate function will use the entire document without grouping the results.

value-columns — (required) the columns to visualise. The value is a JSON array of HXL tag patterns used to match actual hashtags in the document, e.g. "[#affected", "#inneed"].

(Are these also available? They don't appear in bites.json)

filteredValues (optional) — ?? a JSON array of ... ??

dataTitle (optional) — ?? a HXL tag pattern for the column to use to label the chart ??

displayCategory (optional) — ??

init (optional) — ??

hash (optional) — ??

unit (optional) — ?? display description of the unit of measure (e.g. "households in need") ??

title (optional) — ?? display title for the visualisation (e.g. "Activities by cluster") ??

value (optional) — ??

Longer example

The following bite will offer to generate counts (for non-numeric values) and sums (for numeric values) of the number of people affected, in need, targeted, and reached, as well as for total population figures, depending on what is present in the original HXL-tagged dataset. If a column matching #date and/or #country is present, the user will also have the option of grouping the aggregated values based on those. As a result, this bite could generate up to 10 different chart options (any of the five value columns grouped by either of the two aggregate columns, or not grouped):

^{
^{"name": "Charts: Sum items for a tag grouped by administrative units",}
^{"description": "",}
^{"type": "timeseries",}
^{"ingredients": {}
^{"aggregateFunctions": ["sum", "count"],}
^{"aggregateColumns": [}
^"#date",
^"#country"
^],
^{"valueColumns":[}
^"#affected",
^"#inneed",
^"#reached",
^"#targeted",
^{"#population"}
^]
^}
^}

Quick Charts JSON formats