Adding Country Capacity
HXLDash is a dashboard and online mapping tool designed for humanitarians and humanitarian contexts. HXLDash's aim is to make creating dashboards possible in less than 2 minutes by leveraging the power of the Humanitarian Exchange Language and linking to the common operational datasets.
Not all countries and their respective administration levels are currently available in HXLDash. You can find a list of current available countries on the HXLDash website, here: https://hxldash.com/info/mapping.
If you do not find your country listed and have some basic programming and data skills, adding country capacity is easy.
Adding country capacity in HXLDash involves inserting new spatial data files with corresponding p-codes into the Github repository and directing HXLDash to the file structure of the new country.
What you’ll need:
- A .TopoJSON file of a country with corresponding p-codes. Each administration level requires its own .TopoJSON file. This is reviewed in Step 1.
- The HXL Dash repository which can be found here: https://github.com/SimonbJohnson/quickX3
It is recommended you have some basic knowledge of GitHub, as this requires initiating a pull request to integrate your changes into the repository.
HXLDash spatial datasets should have corresponding p-codes. This is because humanitarian datasets use p-codes (or place codes).
P-codes are unique geographic (geo) identification codes, represented by combinations of letters and/or numbers to identify a specific location or feature on a map or within a database. For specific place, point, or positional locations, the geo-codes have come into common usages as P-codes (abbreviated for Place-code). These terms can be essentially interchange as long as one recognizes the focus on “position or place” for P-codes.
They are also used to provide unique reference codes to refer to settlements or administrative boundaries in other datasets.
Many countries already have P-codes. Before creating P-codes for administrative levels yourself, it is important to make sure they haven’t already been created.
COD datasets with P-codes can be found on the Humanitarian Data Exchange: https://data.humdata.org/
You can find more information and guidance on using them here: https://www.humanitarianresponse.info/sites/www.humanitarianresponse.info/files/documents/files/FieldGuideForTheUseOfGeo-Codes.pdf
HXLDash spatial data is in .TopoJSON format, an extension of .GeoJSON. The main reason for this is because .TopoJSON format is up to 80% smaller and has more accessibility for users in low latency environments. TopoJSON is ideal for tidy features that "snap" to each other, like administrative regions
Depending on your situation, the spatial data you have may not be in .TopoJSON format. There are many services to help you convert your data to .TopoJSON format, such as MapShaper: https://mapshaper.org/
Your spatial data file should be as small as possible and only contain relevant data.
An an example below, we see the attribute table for the Brazil admin level 1 TopoJSON file in QGIS:
When looking at the same dataset as a .JSON file in an application such as Atom, we see that is it a collection of features (each administrative area) with corresponding spatial points:
The dataset only has three columns: ID, admin1Name, admin1Pcode. Other columns would only make the file larger and are not needed.
Very important: your admin name and admin p-code must be properly named.
The column with administration area names must be named “admin[admin level]Name.” For example:
- admin1Name
- admin2Name
- admin3Name
The same must be followed for the Pcode column. For example:
- admin1Pcode
- admin2Pcode
- admin3Pcode
The next step is adding your spatial data to the GitHub repository. Make sure your file is exported as a .TopoJSON file. Rename the file geom.json (make sure .json is the file extension).
Next, find out where your .json file should be stored. The file path will go as follows:
[Github Repository Location]\quickX3\hxldash\static\geoms\topojson[Country ISO3 code][Admin level]
For instance, for the Brazil admin 1 level, the file path is follows:
[Github Repository Location]\quickX3\hxldash\static\geoms\topojson\BRA\1
You will most likely need to create the country ISO3 folder and admin level folder yourself unless you are adding to a country or fixing an admin level. For instance if you were adding country capacity for Canada’s 3 admin levels, you’d insert the follow folders in the \static\geoms\ folder:
- \CAN\1\
- \CAN\2\
- \CAN\3\
Then insert the corresponding admin level geom.json file in each admin level folder.
This is a small but important step.
Open your geom.json file using Atom or another programme that allows editing of .json files. In the file, normally the first line, should read something like this:
{"type":"Topology","objects":{"geometry":{"type":"GeometryCollection","geometries":[{"id":"0","type":"Polygon","properties":{"admin1Name":"Acre","admin1Pcode":"BR12"}
After “objects” change “geometry” to “geom” where it reads as follows:
{"type":"Topology","objects":{"geom":{"type":"GeometryCollection","geometries":[{"id":"0","type":"Polygon","properties":{"admin1Name":"Acre","admin1Pcode":"BR12"}
The reason why will become clear in the next steps, as we direct HXLDash to your data.
Once you have inserted your geom.json file, the next step is to direct HXLDash to your spatial data so it can be visualised.
All of the following sub-steps take place in the hxlBitesMap.js file which can be found here:
\GitHub\quickX3\hxldash\static\libs\hxlbites
First check, you want to check your country can be visualised at the world level. If you look for:
hxlBites._mapValues = {'world':[
{'name':'world_iso3','level':0,'url':'/static/geoms/world.json','codes':[
You will find a list of ISO3 and ISO2 codes. Make sure both your ISO3 and ISO2 codes for your country are in this list, otherwise the admin0 level of your country cannot be visualised.
Below the list of ISO3 and ISO2 codes for the world.json file, you will find a list of individual countries.
Add a new line for your country in the same format. As an example of Canada again:
{'iso3':'CAN', 'iso2':'CN', 'use':'CN', 'url':'/static/geoms/topojson/{{country}}/{{level}}/geom.json','adjustment':0,'code_att':'admin{{level}}Pcode','name_att':'admin{{level}}Name','levels':[1,2,3]},
Make sure to change:
- The ISO3 code
- The ISO2 code
- The ‘use’ code
- The number of admin levels at the end. If you only have admin 1 and admin 2 make sure it reads [1,2] for instance, instead of [1,2,3].
And that’s it! Next, it’s time to test whether it worked or not.
Now that you’ve directed HXLDash to find your spatial data
You can find instructions on how to do this in the readme file. This requires some basic knowledge of Python and using your terminal, however, the needed commands can be found in the Readme file.
Create dummy data that you know will visualise. I normally use Google Drive since you are able to share a Google Spreadsheet to HXLDash for easy testing.
Here is an example of a dataset meant to test both admin 1 and admin 2 of Brazil:
This dummy data consists of admin 1 and admin 2 levels with a random number of “hospitals” in each region. The 2nd row contains the **required ** HXL Tags for HXLDash. Make sure you have #adm1+code and #adm2+code, etc.. for the columns with p-codes.
When you have your data click share and copy the link. Make sure the link is public!
After uploading your data, HXLDash should immediately tell you if it worked:
If you do not see “# map(s) generation” then either it is not recognizing your spatial data, or it is not connecting your test data to the spatial data in HXLDash.
If you are getting errors, double check:
- The test dataset contains the correct HXLTags
- The hxlBitesMap.js file is directed to your spatial data.
- The objects in your geom.json files are called “geom” and not “geometries.”
If it does work correct, you should be able to create a dashboard with your new country!
Make sure to document proof of your new country capacity working as a dashboard by taking screenshots.
Afterwards, you can initiate a pull request where the change can be reviewed. If everything works then it will be updated on the server for everyone to use.