On this page you will find instructions on how to set up a Topo Chart.
Uploading topological Data
To be able to display topological data in a topo Chart we first need to upload a topological map. This can be done in the admin section under “/maps/upload“.
go to your-domain/[workspace-code]/maps/upload
here you will be presented with a form in which you can input all the data the following fields are available:
Map code: The code to identify the map in the database (needed when configuring a topo Chart) e.g. “provinces-of-india“. No spaces are allowed.
Map name: The name for the map e.g. “Provinces of India“
Feature Identifier Path: This property is used by the topo chart to map the data from the aggregation to the topological data. For example if we have a property named “HASC_1” in the topological data that corresponds to a field in the data that serves as an identifier then this is the identifier (see image below).
Feature Name Path: This property serves as the display name for the feature in a tooltip.
Description: Add a description to the map
select topoJSON: Upload a .json file in the topoJSON format. If the data is in correct topoJSON format and can be read it will display a table with available properties
Topological Map overview
To see all the uploaded topological maps go to your-domain/[workspace-code]/maps/overview or if you are on the upload page just click the “Maps“ tab on top of the page. This will lead you to the view shown in below image.
On the view a table is displayed with each map in a row. If a row is clicked a panel will open on the right side that displays the map and shows a table with the porperties (just like in the upload view) below the map. If you scroll down further you will find a small form where you can edit the properties map name, feature name path, feature identifer path and description.
Topo Chart configuration
A Topo Chart compares values based on predefined areas (e.g. countries or states). It should be used when you want to show the spatial distribution of a category.
Filter data on dashboard by selecting map area
You can configure a filter for your topo chart that will let you filter data on the dashboard by clicking on a area on the map. The selected area will be highlighted on the map and the corresponding filter (e.g. Provinces) will be applied to the entire dashboard.
Here is an example of the JSON code snippet that you need to add to the topo chart configuration:
filter: {
filterCode: 'province2',
filterField: 'HASC_1'
},
filterCode = the name of the filter you want to apply
filterField = the field in the TopoMap data where the values will be taken from
Create custom color coding scheme
The topo chart will mark areas that have different values with shades of a single color based on the default theme as you can see in the example on top of this page. If you prefer to use a different color, you can easily change it with the following configuration:
{
customFillColor: '#ff0000'
}
You can also use several custom colors and assign thresholds to them.
Here is an example of the JSON code snippet that you need to add to the topo chart configuration:
fillColors: [
{
start: 1,
color: '#ff0000'
},
{
start: 4,
color: '#00ff00'
}
],
Map legend
The topo chart has a map legend that explains the color coding based on either the default/custom color or the custom data thresholds that you have set. To display the legend, add the following line to the topo chart configuration:
legend: true
Legend Title
To have a title for a Legend you have to define the property “legendTitle“ and give it a localized value of your choosing.
legendTitle: {
en: 'My Title'
}
Legend labelling
You can choose to label your thresholds as text instead of numeric values. For example, say that you want to label your legend with low, medium, high this would look as follows:
fillColors: [
{
start: 1,
color: '#ff0000',
title: {
en: 'Low'
}
},
{
start: 4,
color: '#00ff00',
title: {
en: 'Medium'
}
},
{
start: 8,
color: '#00ff99',
title: {
en: 'High'
}
}
],
The property “title“ defines a localized value for title. The property “en“ in this object stands for English. This labeling is only possible for manually a manually defined color palette not for “customFillColor“ or automatic color scheming (no color property).
Drilldown
Drilldown option requires several configurations. First we need to define a hierarchy in the system that reflects the maps topological hierarchy. Then we need to add several configs to the aggregation config and lastly we need to add the layers object to the chart config.
Hierarchy
To learn how to define a data hierarchy go to Creating a data hierarchy
In this example we need the following hierarchy:
Generel overview and country level:
province level:
district level:
Chart config
layers: [
{
mapKey: 'afghanistan-provinces',
layer: 1,
filterField: 'ADM0_NAME'
},
{
mapKey: 'afghanistan-districts',
filterField: 'NAME_1',
layer: 2,
parentMapFilterField: 'ADM0_NAME'
}
],
Here, we add an Array of layers to the config. Each layer has a “mapKey” which is the code of the topoMap uploaded and a layer number called “layer“ that defines the position in the layer hierarchy. The lower layer (the one drilled down to) has an additional property “parentLayerIdentifier“.
The property “parentLayerIdentifier“ is for filtering the correct features from the map. Its the property of the current layer that identifies that a feature is part of the area that has been clicked.
Example:
If we have a map of all provinces of Afghanistan and we click on the province Hirat to load a map of all districts of Hirat. Now this identifier tells us to only fetch the districts that have the value “Hirat“ in the field given to “parentLayerIdentifier“. If you are unsure what field to put into “parentLayerIdentifier“ then look what is defined as “filterField“ under “filter” in your chart config. The values in those two fields should match. So if you have selected a field for the filter that matches a name then you should configure an equivalent field as “parentLayerIdentifier“. Often the fields are named exactly the same in both maps but if you have the maps from different sources their names might differ.
Aggregation config
Example aggregation config for data collection named “consultants“. We want all consultants in a Province or district on a topo map:
{
modificationTime: '2022-03-29T06:14:39.352+00:00',
parameters: [
{
code: 'hierarchy',
type: 'REPLACE',
required: false,
multiValue: false,
name: {
en: 'Hierarchy'
},
dataType: 'STRING',
expressionValue: false
},
{
code: 'hierarchySelector',
type: 'REPLACE',
required: false,
multiValue: false,
name: {
en: 'Hierarchy Selector'
},
dataType: 'STRING',
expressionValue: false
}
],
parameterValues: {
hierarchy: 'province'
},
filterCriteria: [],
permissionProfiles: [],
lookUpPaths: [],
aggregations: [
{
'$group': {
_id: '###hierarchy###',
count: {
'$sum': 1
},
consultant: {
'$first': '$$ROOT'
}
}
},
{
'$project': {
_id: 0,
value: '$consultant.###hierarchyProjectionPath.iso###',
result: '$count',
total: '$count'
}
}
]
}
Explanations
Parameters:
“code: hierarchy”:
“code: hierarchySelector“:
ParameterValues:
hierarchy: The code of the entry layer for the chart and config. E.g. if you have the layers with codes “country”, “province” and “district” and you want a map that first shows the results by provinces when first loading the dashboard, then you would type “province“ as your entry layer. The codes are the same as defined in your chart config above for the object “layers“.
aggregations:
###hierarchy###:
$$ROOT:
###hierarchyProjectionPath.iso###:
Additionally we need to select our data hierarchy defined previously in the field “Use Data Hierarchy“ on the left panel and define the entry path into the hierarchy from our collection in the field “Data Hierarchy entry path“ also on the left panel.
Add Comment