GIS Renderers for the GHO

Table of contents

Introduction

This documents explains the use, configuration, and construction of GIS renderers for measures or indicators within the GHO data system.

Usage

Entries in a measure dimension, such as the GHO dimension in the Global Health Observatory, contain an attribute named RENDERER_ID when a suitable GIS renderer definition is available. For example, "Life expectancy at birth (WHOSIS_1)"
WHOSIS_000001: Life expectancy at birth (years)
  Category: Mortality and global health estimates
                      RENDERER_ID: RENDER_2
  Additional details: http://apps.who.int/gho/indicatorregistry/App_Main/view_indicator.aspx?iid=65
contains the RENDERER_ID "RENDER_2".

In order to retrieve the renderer for this measure, use the following URL structure: 

  http://<HOST>:<PORT>/<PREFIX>/athena/<ATHENA_INSTANCE>/RENDERER.json?profile=renderer&x-id=<RENDERER_ID>
where HOST and PORT are the location of the XMart web service host, PREFIX is the path prefix to the Athena web service, ATHENA_INSTANCE is the instance name of the XMart database you wish to use and RENDERER_ID is a semicolon (;) delimited list of renderer ids. If this x-id parameter is omitted, the web service will return the list of all available renderers. Looking up the renderer for WHOSIS_000001 from the Global Health Observatory's staging system gives us the URL: 
  http://hqsudevlin.who.int:8086/athena/data/RENDERER.json?profile=renderer&x-id=RENDER_2
which returns the following response: 
{
  "renderer": [
                 {
                   "label": "RENDER_2",
                   "display": "Renderer 2",
                   "breaks": [
                                {
                                  "min": "0",
                                  "max": "20",
                                  "colour": "rgb(57,59,121)",
                                  "display": "0 - 20"
                                },
                                {
                                  "min": "21",
                                  "max": "40",
                                  "colour": "rgb(82,84,163)",
                                  "display": "21 - 40"
                                },
                                {
                                  "min": "41",
                                  "max": "60",
                                  "colour": "rgb(107,110,207)",
                                  "display": "41 - 60"
                                },
                                {
                                  "min": "61",
                                  "max": "80",
                                  "colour": "rgb(156,158,222)",
                                  "display": "61 - 80"
                                },
                                {
                                  "min": "81",
                                  "max": "100",
                                  "colour": "rgb(200,205,234)",
                                  "display": "81 - 100"
                                }
                             ]
                 }
               ]
}

Storage of renderers

The GIS renderers are implemented using a standard XMart dimension, called RENDERER. The raw XML form can be queried like any other XMart dimension (See Data query API examples) To see the current XML representation of the renderers on the GHO production system, use the following example URL: 

  http://apps.who.int/gho/athena/data/RENDERER.xml
The model uses several attributes specific to the RENDERER dimension. The first is the LABELS attribute that specifies the component names for the components that describe each break class in the particular renderer. The others are BREAK_1, BREAK_2, ... BREAK_10 that each define a class break's component values.

Adding a new renderer

 Each renderer is a dimension member of the RENDERER dimension. As such it can be added and manipulated using either the ITT data loader or the GHO XMart tools (for the purposes of this document we will use the GHO Xmart tools for further examples). A renderer is created like a normal dimension member, but must set at least the LABELS attribute and at least the first class break, BREAK_1, attribute. The LABELS attribute is a semicolon delimited list of labels that will identify the components of each class break. following our example for WHOSIS_000001, the LABELS attribtue value for its renderer is "min;max;colour;display". Each corresponding class break attribute must specify a semicolon delimited list of values for each label.

The load file for the WHOSIS_000001 renderer, RENDER_2, is therefore:


"DimensionCode","DimensionMemberCode","DisplayString","DisplaySequence","URL","LABELS","BREAK_1","BREAK_2","BREAK_3","BREAK_4","BREAK_5","BREAK_6","BREAK_7","BREAK_8","BREAK_9","BREAK_10"
RENDERER,RENDER_2,"Renderer 2", 2,"","min;max;colour;display","0;20;rgb(57,59,121);0 - 20","21;40;rgb(82,84,163);21 - 40","41;60;rgb(107,110,207);41 - 60","61;80;rgb(156,158,222);61 - 80","81;100;rgb(200,205,234);81 - 100",,,,,

Adding GIS Renderer support to an XMart instance

The metadata structure required for supporting the GIS renderers in an XMart instance can be generated using the following load files, designed for the GHO XMart tools:
First, you must create the RENDER dimension, using xmart-load-dimensions: 

DimensionCode,DisplayString
RENDERER,"Renderer"
Then, you must create the attributes using xmart-load-attributes: (This will create the RENDERER attribute as well as add the RENDERER_ID attribute to the GHO measure dimension - you must adapt this accordingly for the measure dimension of your specific instance) 
"AttributeCode","EntityType","EntityCode","DisplayString"
"RENDERER_ID","CORE_DIMENSION","GHO","Renderer ID"
"LABELS","CORE_DIMENSION","RENDERER","Labels"
"BREAK_1","CORE_DIMENSION","RENDERER","break 1"
"BREAK_2","CORE_DIMENSION","RENDERER","break 2"
"BREAK_3","CORE_DIMENSION","RENDERER","break 3"
"BREAK_4","CORE_DIMENSION","RENDERER","break 4"
"BREAK_5","CORE_DIMENSION","RENDERER","break 5"
"BREAK_6","CORE_DIMENSION","RENDERER","break 6"
"BREAK_7","CORE_DIMENSION","RENDERER","break 7"
"BREAK_8","CORE_DIMENSION","RENDERER","break 8"
"BREAK_9","CORE_DIMENSION","RENDERER","break 9"
"BREAK_10","CORE_DIMENSION","RENDERER","break 10"