NOTE: This documentation is not yet correct. There seem to be different properties in use for a single bite sent to a visualisation, or a pattern to generate bites (recipe?) inside HDX.
HDX Quick Charts use JSON configuration files to define the different kinds of charts to offer to users for HXL-tagged data. There are two slightly-different 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 bit looks like this:
...
bite looks like this:
| Code Block | ||
|---|---|---|
| ||
{
"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.
...
(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:
...
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"
...
...
]
...
}
...
}
See also
bites.json — the current list of bites in production use on HDX.
...