6 THE GIS MODULE
6.3 KEY CONCEPTS
In the following section I make a brief explanation of the key concepts, objects and terms of the GIS module of DHIS 2.
6.3.1 Overview
The GIS server is Java based and integrated into the DHIS 2 core which gives it a three layer architecture:
Communication with the database through Hibernate takes place in the store layer. Objects, service functionality (logic) and an application programming interface (API) are implemented in the service layer.
Action classes are implemented in the service layer. These classes receive requests from the client, calls the appropriate methods in the service layer which provide the desired data back via the store layer. The actions classes then return the data to the client formated as JSON through Velocity templates.
The client is made up of pure JavaScript and the graphical user interface is implemented with Ext JS. The center component, the map area of the view port, are powered by OpenLayers and uses MapFish functionality to calculate and display geo-statistical information on top of it. GeoExt widgets are used for special geo-related tasks such as the advanced container based map layer tree.
67
CLIENT
MapFish lib OpenLayers lib Ext JS lib GeoExt libSERVER
Presentation layer dhis-web-mapping 44 action classes 24 templates dhis-service-mapping 67 service methods 4 deletion handler classesService layer Application
~ 5000 lines of JS code HTML / CSS
dhis-service-mapping
40 store methods Store layer
Relational database
68 6.3.2 Objects
This section presents the current GIS objects.
Map
The map object represents a map registered by the user. Every map has a superior and a secondary organisation unit level. The superior level defines the scope. This is usually set to national level because in most cases you would want to display the entire country. However, it could be set to e.g. province level if you have a particularly detailed map for one specific province and want to leave out the others. The secondary level defines what level you want to display data for. Thus, a map that is supposed to display data for e.g. all chiefdoms in Sierra Leone, the superior level should be set to national and the secondary to chiefdom.
In order to transfer, calculate and display data indicators for organisation units at the secondary level, the map object also holds the name the data column that should be matched against the database. In addition to tedious properties like name, longitude, latitude, zoom level and feature type (point/polygon/line), a specific map source type is persisted in the map object. Map source type is explained in the next section.
MapLayer
A MapLayer object stores information about a map layer that is added to the layer tree, either as a base layer (background) or as an overlay on the thematic map. An overlay needs graphical attributes like fill color, fill opacity, stroke color and stroke width. The fact that a map layer is made up by geospatial vector data similarly to a map, forces them to be grouped by the map source type as well.
MapLegendSet
A legend set is created by first defining a color for the lowest and the highest aggregated indicator values. A desired number of class breaks then splits up the legend in order to make the thematic map meaningful. The selected calculation method decides the size and how the different values (organisation units) are distributed within the prescribed number of classes. There are three different calculation methods:
Equal intervals, which is rather self-explanatory. The legend is simply split into intervals of the same size, like (highest value – lowest value) / number of classes.
69 Distributed values. This method tries to populate the classes equally, which may lead to heavily unequal intervals depending on the value dissipation.
Fixed bounds, which lets you define your own class breaks. Handy if you e.g. want to separate the organisation units above and below a single crucial value.
Finally you are supposed to link the legend set to one or many indicators. The point of doing this is that now the legend set settings will automatically be applied to the
thematic map selections for the assigned indicators. Apart from the practical advantage this could be quite helpful due to the fact that for some indicators a high value is
considered a good result and for others it might be a bad result. A typical scenario that might occur if you do not define a legend set for you indicators, could be when you change the indicator in your selection and forget to change the colors and your map presents the result upside down.
MapOrganisationUnitRelation
An organisation unit relation is related to a specific map object and defines a connection between an organisation unit in the database and an organisation unit in the shapefile. These relations are created by the administrator after a new map has been registered. The fact that the relations are stored means that this process needs to be done only once. The point is to let the application know which organisation unit an aggregated indicator value should be transfered to. Now that we have a genuine link between the respective organisation units we are able to speed up the process of transfering values when drawing thematic maps. This is because the organisation units do not have to be searched for and matched on their names every time.
MapView
The MapView object stores a thematic map selection, more exactly indicator group, indicator, period type, period, map, method, classes, low color and high color. This gives you quick and easy access to your favourite selections. You also have the possibility to add your favourites to the DHIS 2 dashboard. Thus, directly from the dashboard, you can start up the GIS application and display one of your favourite views with only one click.
6.3.3 Map source type
I have extended the system to support three different ways of feeding the application with geospatial vector data. The point is to avoid restricting the user to one single way of doing this and the different alternatives have different pros and cons, which I discuss in
70 the analysis chapter. In the administrator panel you may set the map source type to either GeoJSON, Shapefile or Database. The selected map source type neatly decides the application’s behaviour behind the scenes.
GeoJSON
The map registration panel will look for GeoJSON files that are placed in a specific subfolder of the DHIS2_HOME environment variable path. Only maps, map layers and map views with geojson as map source type will be available.
Shapefile
Gives you the opportunity to connect your private geospatial, server such as Geoserver, and load all your installed shapefiles directly into the application. Maps, map layers and map views will be stored with this map source type to separate them from objects of a different type. You might as well connect to a remote server.
Database
The shapefile generator described in the next section will be used.