...
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.
You can experiment with making your own bites interactively in the HDX Quick Charts Sandbox.
Bites
A simple JSON bite looks like this:
| Code Block | ||
|---|---|---|
| ||
{
"titlename": "Organisationsorgs",
"typetitle": "key figureOrganisations",
"ingredientdescription": {"Number of organisations deployed."
"aggregateColumntype":"key null,
figure",
"ingredient": {
"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”.
Here is a slightly more-complex example, creating a chart (bar or pie, chosen automatically) that shows the number of unique organisations for each admin1 subdivision (“#adm1”):
| Code Block | ||
|---|---|---|
| ||
{
"title": "Organisations",
"type":"chart",
"ingredient": {
"aggregateColumn": "#adm1"
"valueColumn": "#org",
"aggregateFunction": "distinct-count"
},
"unit": "orgs",
"numberFormat": "us"
} |
bite properties
name | The internal reference name for the bite (not displayed). |
title | Chart title to display. |
description | Chart description to display. |
type | Type of chart to display. key figure: a single numeric indicator (e.g. total population, number of organisations) |
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"
]
}
}
See also
...
: us: English format (“,” as thousands separator, “.” as decimal) If not provided, the format will be standard computer number format, with no thousands separator and “.” as the decimal separator. |
“ingredient” object properties
aggregateColumn | A HXL tag pattern identifying the reference column for aggregation (chart and timeseries only). | |||||
dateColumn | A HXL tag pattern identifying the column to use for dates (timeseries only). | |||||
valueColumn | A HXL tag pattern identifying the column containing values. | |||||
aggregateFunction | The aggregation function to apply to valueColumn. If the type is “chart” or “timeseries”, the aggregations will apply to each unique value of aggregateColumn. sum: add all of the values together (numbers only) | |||||
filtersWith | A filter for rows to include in the chart: it should be a list of JSON objects, where the keys are HXL tag patterns and the values are either literal values that must appear in rows to include, or the pseudo values “$MAX” (for the largest value) or “$MIN” (for the smallest value). For example, this filter would include only rows for the latest year (assuming it appears in a column with the HXL hashtag spec “#date+year”).
| |||||
filtersWithout | Like filtersWith, except that it’s a filter for rows to exclude from the chart. |
Recipes
Recipes generate a list of bites that the user can choose from, based on the data available in the source dataset. It is similar to a Bite, except that inside ingredients most of the fields become plural: aggregateColumns, dateColumns, valueColumns, and aggregateFunctions. Each of this contains a list HXL tag patterns, for generating bites that the user may choose (depending on which columns appear in the source data). This example will provide options for the number of orgs, activities, sectors, or subsectors grouped by region, country, or 5 admin levels — up to 28 different bites, depending on what’s present in the source data:
| Code Block |
|---|
{
"name": "Charts: Distinct count of values in value column by the aggregate column",
"description": "",
"type": "chart",
"ingredients": {
"aggregateFunctions": [
"distinct-count"
],
"aggregateColumns": [
"#region",
"#country",
"#adm1",
"#adm2",
"#adm3",
"#adm4",
"#adm5"
],
"valueColumns": [
"#org",
"#activity",
"#sector",
"#subsector"
]
}
} |
Cookbooks
Cookbooks contain one or more recipes and a list of HXL tag patterns; if there are columns in the source data matching all of the tag patterns, then these recipes will be available to the user.
name | The internal reference name for the cookbook (not displayed). |
title | Cookbook title to display. |
type | Always “cookbook”. |
columns | A list of HXL tag patterns that should appear in the source data for these recipes to apply. |
recipes | A list of recipes to make available. |
numberFormat | The format to use for numbers: us: English format (“,” as thousands separator, “.” as decimal) If not provided, the format will be standard computer number format, with no thousands separator and “.” as the decimal separator. |
Cookbook example
| Code Block |
|---|
{
"name": "3w",
"title": "Who is doing What Where",
"type": "cookbook",
"columns": [
"#org",
"#sector",
"#adm1"
],
"recipes": [
{
"name": "Charts: Count items for a value column grouped by aggregate columns",
"description": "",
"type": "chart",
"ingredients": {
"aggregateFunctions": [
"count"
],
"aggregateColumns": [
"#region",
"#country",
"#adm1",
"#adm2",
"#adm3",
"#adm4",
"#adm5",
"#org",
"#activity",
"#sector",
"#subsector"
]
}
},
{
"name": "Charts: Distinct count of values in value column by the aggregate column",
"description": "",
"type": "chart",
"ingredients": {
"aggregateFunctions": [
"distinct-count"
],
"aggregateColumns": [
"#region",
"#country",
"#adm1",
"#adm2",
"#adm3",
"#adm4",
"#adm5"
],
"valueColumns": [
"#org",
"#activity",
"#sector",
"#subsector"
]
}
},
{
"name": "Charts: Distinct count of values in value column by the aggregate column",
"description": "",
"type": "chart",
"ingredients": {
"aggregateFunctions": [
"distinct-count"
],
"aggregateColumns": [
"#org"
],
"valueColumns": [
"#activity",
"#sector",
"#subsector"
]
}
},
{
"name": "Charts: Distinct count of values in value column by the aggregate column",
"description": "",
"type": "chart",
"ingredients": {
"aggregateFunctions": [
"distinct-count"
],
"aggregateColumns": [
"#activity",
"#sector",
"#subsector"
],
"valueColumns": [
"#org"
]
}
}
]
}
|
See also
HDX Quick Charts Sandbox — a simple, browser-side web tool for experimenting with bites interactively (can also be run locally from your computer).
...