4. Define OrgUnit coordinates (GIS)

Objectives:

• Learn how to Convert .SHP files into .GML and import them in DHIS2.
   

Assignment overview:

In preparation for creating GIS reports, you must first download and convert shape files to GML files, and import them into DHIS2. This assignment walks you through the steps. The procedure is somewhat long, but don't despair! The results are worth it!

---

Assignment Walkthrough - Define OrgUnit Coordinates

---

Where to work:

You will be working in a GIS editor (we suggest QGIS), a text editor, and directly in DHIS2 for this assignment.

---

Reminder: The organizational unit hierarchy has to be created separately, and then use GML to update the coordinates (of the created org units).

Instructions:  --------------

Step 1. Download a shape file

You need to have shape files, containing coordinates for the org units in DHIS2. One reliable way to acquire your coordinates is here: http://www.gadm.org. You can download the data by country or for the whole world. Click on “country”, select the country of your choice. From “File format” choose “shape file” and then click OK. The newly open window shows the picture of selected country.

You will get a .zip file which contains layers that contain polygons (with coordinates) of the country’s administrative division, such as country’s boundary, regions, provinces, districts, municipalities, etc. Digits at the end of each layer name shows the layer number starting with 0 (the country’s boundary layer). Each layer is formed up by a few files with extensions as shown below. Usually layer names starts with the abbreviation of the country (for example: CAN for Canada, BGR for Bulgaria), followed by “adm” – abbreviation from administration and ends with the layer number – 0, 1, 2, 3…

 

 

Step 2. Simplification of layers in the shape file with Mapshaper program (Optional)

In most cases the boundaries of the geodata are way too accurate for the purposes of a web-based GIS such as the DHIS2. This results in long waiting time for loading the layers. Therefore we suggest a way to simplify that process and reduce waiting time.

For polygons, we need to make the boundary lines less detailed by removing some of the line points. Make a backup of your .shp before you start. Open Mapshaper program available at http://www.mapshaper.org. The program allows online adjustment of shape files. It simplifies them, making them smaller files for faster upload to DHIS2.

Click on the link above to open the program. You will see the following window:

Select your zipped shape file which you downloaded from http://www.gadm.org, drag and drop it onto the area above. Alternatively, you can click on “select” button and from your windows explorer will open, then find the directory your file has been saved.

Once you upload the file you will find it as it is shown below:

Click on the blue button “Import”. On the upper side of your screen you will see Layer 0 – the first layer of your shape file which contains the boundary of your country. Clicking on the white arrow you with open all files contained in the uploaded zip file. By clicking on the “name” you can open any layer you want to explore (shown below).

 

Information about the opened layer can be displayed by clicking on the symbol “i” as it shown below. If you open the district layer, it will display a map with all districts that the country comprises. By clicking on any district, a detailed information will appear on the left side of your screen. You can also explore each of the .csv files that accompanies the layer in order to see the org units it comprises.

 

Program menu is allocated on the upper right side. You can choose Simplify, Console or Export. Simplify allows you to determine the per cent of simplification; Console allows inserting of commands (help is available); Export provides export of the selected simplified layer.

 

To simplify a layer. Click on the menu Simplify and on the pop-down menu click Next.

Slide the bullet to a per cent you want to simplify the geometries.

Once you finish, click Export.

Each layer must be exported separately! Export command allows you to choose the file format of exported file – shape file, csv, GeoJSON, TopoJSON or svg. For the purpose of our task, we will choose a "Shape" file type. Exported layers are zipped files containing 4 files types - .dbf, .shp, and .shx. The new .shp file of each layer has lesser detailed GIS data which will make a smaller GML file.

 

Step 3. Exporting shape files and creating GML files

Now It is time to export the shape file into a format that is recognizable by DHIS2. DHIS2 supports the WSG84 standard coordinate system and the proper identifier - EPSG:4326 . With latitude and longitude being expressed as decimal degrees (e.g. lat. 38.8897 and long. -77.0089). There are many open source programs that convert shape files into EPSG:4326. You can use Proj4js; OpenLayers; QGIS.

 

In this example QGIS is applied: Open QGIS Desktop program, Open menu Layer, from the pop down menu click on Add Vector Layer. This will open a window allowing you to browse and choose the .shp file you will re-project (see below).

 

 

Open the directory of the first layer (this is the boundary layer 0) and select the shape file. Its name is …adm0.shp. Click Open.

A new window will show you the available Coordinate Reference System. Make sure it is WSG84 / Authority ID EPSG: 4326 and click OK as shown below (selected in blue):

 

 

Open menu Layer and select Save as. In the opened window, click Browse to choose the directory where your GML file will be stored (shown below).

 

Make same steps with all available shape files which contains the layers with geometries of the administrative units (regions, districts, municipalities) of your chosen country. Do not forget to save your project files upon closing QGIS program. They might be necessary in case you occasionally delete your GML files.

 

Step 4. Adjustment of GML files and importing in DHIS2

The next steps are of a prime importance because they will prepare your GML files for the import into DHIS2. GML files are of XML file format and can be edited with any text processing program, such as Notepad.

Each GML file contains coordinates and names of organization units existing in a certain layer (countries, regions, districts, municipalities, etc.). Coordinates of org units contained in the GML file will be imported and recognized by DHIS2 only if they are already created in DHIS 2. For example, a GML file of a country X contains 50 districts, but in DHIS2 the user has created 4 districts. Therefore, upon the import of the GML, DHIS2 will recognize and import the coordinates of those 4 districts only.

In addition, if you have created a certain number of org units in DHIS2 as districts, but in GML file same names are determined as regions, the import of their coordinates might not be successful. Therefore, you must pay attention to the exact level of the org units listed in the GML file and their levels in DHIS 2.

The names in the GML file should match the names created in DHIS2 Orgunit hierarchy.

Very important: The importer of DHIS2 looks in the GLM file for the tag “ogr:NAME” in order to access the name of an organization unit. However, the GML file you have created from QGIS program contains many tags that determine an org unit and they all contain additional symbols that practically prevents DHIS 2 importer to access the orgunit. Therefore, you have to find where the organization unit name is stored in the GML file and rename it to “ogr:NAME”. As it was mentioned above, the name should be exactly the name as in DHIS2 database, so pay attention to the spelling as well.

The following examples will describe the way such revisions can be made with all layers, starting with Layer 0 (boundary of a country), then Layer 1 (Country Provinces) and Layer 2, etc. One GML file must be uploaded corresponding to each OrgUnit Level in DHIS2

Let’s open the GML file, Layer 0 - the country’s boundary which in this example is Canada (see below). You will find a description of the polygon outlining the country’s boundary. There are a few tags that determine the name of Canada as an Org unit. However, you see that all the tags have additional abbreviations (_ISO, _FAO, _LOCAL, etc.). These abbreviations will prevent the importer of DHIS 2 to recognize the name of the Org unit. Therefore, choose one of the tags, for example <ogr:NAME_ENGLI>Canada</ogr:NAME_ENGLI> and revise it to <ogr:NAME>Canada</ogr:NAME>. You must edit only one of all the tags. Otherwise there will be duplication of the name.

 

Once you edit the above raw, save and close the file. This layer 0 is ready for import into DHIS 2.

Next: level 1 (a part of the GML file is shown below) defines all provinces in Canada. Do not forget that each country has unique administrative hierarchy. In this example layer 1 comprises Provinces. They are 13 in total.

Steps:

In the example below you will see NAME tags of Org units which belongs to Layer 0 and to Layer 1:

PARTS OF LAYER 1 GML FILE

 

 

Proceed with all tags of Org units that belong to Layer 1. In this example they are 27. This means that you have to make 27 changes as it is shown above.

All remaining tags, such as ogr:HASC_1; ogr:CCN_1; or what so ever, have to remain unchanged.

When you finish, save and close the file. Your Layer 1 GML file is ready for import into DHIS 2.

 

Additional Layers/OrgUnit Levels:

In case your chosen country has got additional SHAPE FILE layers, you have to follow same logical steps:

 

FOR LAYER 2 CHANGE THE NAME TAGS OF THE ORG UNITS THAT BELONG TO LAYER 2 ONLY. IT WILL LOOK LIKE:

<ogr:NAME_3>XYZ</ogr:NAME_3>

CHANGE IT TO

<ogr:NAME>XYZ</ogr:NAME>

 

 

Step 5. Generalizing your geodata (Optional)

 

This step is highly significant when working with many layers and the GIS app starts to slow down because of heavy data.

 

The number of significant decimal digits (e.g. 23.02937874993774) should be shortened to fewer digits (e.g. 23.03), that can be applied to both single point coordinates and polygons. Although this will result in some inaccuracies on the map, given the usual scale at which maps in DHIS2 are produced (> 1:50,000), the loss of precision should not be noticeable. Ideally, when generalizing latitude and longitude of a given point, no more than four significant digits after the decimal point should be necessary (23.0294). The same should be applied to polygons as well as reducing the point that form those polygons.

 

In order to do that, open the .gml file and manually delete all digits after the first four. Unfortunately, there is no suggested way to automate this process.

 

Step 6. Import of GML files into DHIS2

Open Import – Export Application

Choose GML Import

 

Click on “Choose file”. Select the first GML (layer 0) containing your country’s boundary. Select “Yes” as a Dry run. Click Import. Wait until you get the following message:

Click on Display import summary. If the import is successful, you will get the following message:

 

 

Repeat this step for the import of all other layers. Depending on the existing Org units in your DHIS 2 same number of imported units should be recognized by DHIS 2.

In case you get an error message of the type:

Look at the Report description to see the reason of rejection. Then check again if the names of org units in your DHIS2 match the names in your GML; check the tags that define the types of your org units; check for special name characters in the GML file.

In case the error message appears again, try to re-project your shape files by repeating the steps described in "Exporting shape files and creating GML files”.

Consult with DHIS2 expert.