PI expressions based on event count

It is often necessary to create indicators that are based on the number of events that meet a certain condition. Creating program indicators to achieve this goal might seem obvious but it is not that simple by using current built in DHIS2 functions.

As an example, let us assume that we want to create an indicator that counts the number of times that a test has been passed 3 times.

PI filter and expression

The first step is to create a PI (PI_1) where the condition is specified in the filter. By doing so, only events that meet the condition will be taken into account for the calculation of the PI. The filter could look similar to this:

  • #{BPO6UrfbnRN.DeFGVeME9fb} == 'passed'

The tricky part comes with the PI expression. Since the calculation is based on the number of events filtered, using the following functions might seem appropriate:

  • d2:condition('V{event_count} == 3',1,0)
  • if(V{event_count} == 3,1,0)

However, DHIS2 needs to perform the event count operation first to be able to evaluate the result in another function. As a consequence, the functions above will not return an appropriate result.

Indicator creation

To sort this problem out, we can create an indicator (IND_1) that feeds from the PI result to make the relevant calculations. Then, the expression of the PI must only return the event count (V{event_count}), the denominator of the indicator must be equal to 1 and the numerator must have the following expression (assuming I{xMs9Y1kccTi} is referring to the PI_1 created above):

  • if(I{xMs9Y1kccTi} == 3,1,0)

With this way around, the output of the indicator will count the number of times that the output of the PI (V{event_count}) equals 3.

Aggregation to lower orgunit levels

When aggregation is needed for lower levels in the orgunit hierarchy, we face a different problem. Let us consider the case where data entry happens at the district level and want to aggregate at the province level. It can be the case that one district has 2 events that meet the filter condition and there is another district that only has 1 event that meet the condition. Since the PI is counting events at the district level but the indicator is evaluating if the number of events equals to 3 in the province level, we have an undesired result. In this case, the indicator result at the province level will be equal to 1 since in total there are 3 events in the province that meet the condition but instead it should be equal to 0 because the events that meet the condition come from 2 different districts.

A solution for the issue described is to create an aggregate dataset that sits at the district level. A data element (DE_1) from this dataset can be used to store the result of the indicator (IND_1) at the district level. Then, this data element can be used in DHIS2 analytic apps to perform aggregation at the province level (we use DE_1 instead of using IND_1)

Pulling data from tracker and pushing to aggregate

To be able to store the result of IND_1 into DE_1 it is necessary to do the mapping of the relevant indicator attributes. DHIS2 has two built in attributes where the target category option combo (COC) and attribute option combo (AOC) ids should be filled in:

  • Category option combination for aggregate data export
  • Attribute option combination for aggregate data export

In our example, since we do not have any disaggregations we can use the default COC id.

We also need to create an indicator attribute to store the mapping of the aggregate data element where the result of IND_1 will be stored (i.e. the id of DE_1 ):

  • Event aggregate mapping

Finally, we can use the DHIS2 API to pull data from tracker into a format that can be imported into an aggregate data set. Next there is an example on how to use the /analytics/dataValueSet API endpoint to retrieve the data values for all indicators belonging to a particular indicator group and all orgunits belonging to a specific orgunit group:

https://my_server_url/api/analytics/dataValueSet.json?dimension=dx:IN_GROUP-savQ7R0wZQE&outputIdScheme=ATTRIBUTE:PZEIEOIhEMU&dimension=ou:OU_GROUP-B2JcQdfG1wi&dimension=pe:2005Oct;2006Oct

In the example link above:

  • my_server_url represents the URL of the server we want to pull data from.
  • savQ7R0wZQ corresponds to the id of the indicator group containing all indicators we want to pull data from.
  • PZEIEOIhEMU corresponds to the id indicator attribute (Event aggregate mapping) that stores the mapping for DE_1.
  • B2JcQdfG1wi corresponds to the id of the orgunit group to use to retrieve data.
  • 2005Oct;2006Oct are the periods we are pulling data from.

The result of the above API query will be a JSON object that can be saved as a file and imported using the DHIS2 import-export app (data import).

After the JSON payload is imported into the server, data will be available in the aggregate datasets. We can also run analytics to be able to visualise the aggregate data values in the DHIS2 analytics apps.