22.4 Configure program indicators

22.4.1 About program indicators

Program indicators are expressions based on data elements and attributes of tracked entities which can be used to calculate values based on a formula. Program indicators consist of an aggregation type, an analytics type, an expression and a filter.

Program indicators are evaluated based on the assigned aggregation type, expression and filter. The order of evaluation is:

  1. The filter will filter the events which become part of the evaluation/aggregation routine.

  2. The expression will be evaluated per event.

  3. All evaluated expression values will be aggregated according to the aggregation type of the program indicator.

Program indicator components

Program rule component

Description

Aggregation type

The aggregation type determines how the program indicator will be aggregated. The following aggregation types are available:

  • Average

  • Average (number)

  • Average (number, disaggregation)

  • Average (sum in organisation unit hierarchy)

  • Average (sum of numbers)

  • Average (sum of numbers, disaggregation)

  • Average (Yes/No)

  • Count

  • Custom

    The “custom” aggregation type allows you to specify the aggregation type in-line in the expression. All other aggregation types are applied to the entire expression.

    Using the “custom” aggregation type might lead to an exception of the order of evaluation described above where individual parts of the expression can be evaluated and aggregated, as opposed to the entire expression being evaluated prior to aggregation.

  • Default

  • Max

  • Min

  • None

  • Standard deviation

  • Sum

  • Variance

Analytics type

The available analytics types are event and enrollment .

The analytics type defines whether the program indicator is calculated based on events or program enrollments. This has an impact on what type of calculations can be made.

  • Events implies a data source where each event exists as an independent row. This is suitable for performing aggregations such as counts and sums.

  • Enrollments implies a data source where all events for a single enrollment is combined on the same row. This allows for calculations which can compare event data from various program stages within a program enrollment.

Analytics period boundaries

Defines the boundaries for the program indicator calculation. The boundaries determine which events or enrollments gets included in aggregations, always relative to the aggregate reporting period start and end. When creating the program indicator, the default boundaries will get preselected based on analytics type.

  • For analytics type event , the default boundaries will be configured to encapsulate any events with an event date after the reporting period starts and before the reporting period ends.

  • For analytics type enrollment , the default boundaries will encapsulate all enrollments with an enrollment date after the reporting date starts and before the reporting period ends. In addition, the default enrollment program indicator evaluates the newest event for all program stages regardless of date.

It is possible to change the upper and lower boundaries to include a longer or shorter period relative to the reporting period, or delete one of the boundaries - in effect returing all data before or after a certiain period. It is also possible to add more constraints, for example to make an enrollment program indicator only include event data up to a given point in time.

  • Boundary target: Can be incident date , event date or enrollment date . Designates what is being constrained by the boundary.

  • Analytics period boundary type: Defines wether the boundary is a end boundary - starting with “before…”, or a start boundary - “after…”. Also defines whether the boundary relates to the end of the aggregate reporting period or the start of the aggregate reporting period.

  • Offset period by amount: In some cases, for example cohort analytics, the boundary should be offset relative to the aggregate reporting period when running pivots and reports. The offset period by amount is used to move the current boundary either back(negative) or forward(positive) in time. The amount and period type together will determine how big the offset will be. An example can be when making a simple enrollment cohort porgram indicator for a 1 year cohort, it might be enough to offset each boundary of the program indicator with “-1” and “Years”

  • Period type: See above. Can be any period, e.g. Weekly or Quarterly .

Expression

The expression defines how the indicator is being calculated. The expression can contain references to various entities which will be substituted with a related values when the indicator is calculated:

  • Data elements: Will be substituted with the value of the data element for the time period and organisation unit for which the calculation is done. Refers to both program stage and data element.

  • Attributes: Will be substituted with the value of the attribute for the person / tracked entity for which the calculation is done.

  • Variables: Will be substituted with special values linked to the program, including incident date and date of enrollment for the person, current date and count of values in the expression for the time period and organisation unit for which the calculation is done.

  • Constants: Will be substituted with the value of the constant.

The expression is a mathematical expression and can also contain operators.

For single event programs and tracker programs with analytics type event , the expression will be evaluated per event , then aggregated according to its aggregation type.

For tracker programs with analytics type enrollment , the expression will be evaluated per enrollment , then aggregated according to its aggregation type.

Filter

The filter is applied to events and filters the data source used for the calculation of the indicator. I.e. the filter is applied to the set of events before the indicator expression is being evaluated. The filter must evaluate to either true or false. It filter is applied to each individual event. If the filter evaluates to true then the event is included later in the expression evaluation, if not it is ignored. The filter can, in a similar way as expressions, contain references to data elements, attributes and constants.

The program indicator filter can in addition use logical operators. These operators can be used to form logical expressions which ultimately evaluate to either true or false. For example you can assert that multiple data elements must be a specific value, or that specific attributes must have numerical values less or greater than a constant.

In the Maintenance app, you manage the following program indicator objects:

Object type

Available functions

Program indicator

Create, edit, clone, share, delete, show details and translate

Program indicator group

Create, edit, clone, share, delete, show details and translate

22.4.2 Create or edit a program indicator

Note

A program indicator belongs to exactly one program.

  1. Open the Maintenance app and click Indicator > Program indicator .

  2. Click the add button.

  3. Select a Program and enter:

    • Name

    • Short name

    • Code

    • Description

  4. Select number of Decimals in data output .

  5. Select an Aggregation type .

  6. Select a if you want to Display in form .

  7. Assign one or multiple Legend s.

  8. (Optional) Enter a Category option combination for aggregate data export .

  9. (Optional) Enter an Attribute option combination for aggregate data export .

  10. Create the expression.

    1. Click Edit expression .

    2. Create the expression based on mathematical operators and the attributes, variables and constants listed to the right.

  11. Create the filter.

    1. Click Edit filter .

    2. Create the expression based on mathematical operators and the attributes, variables and constants listed to the right.

  12. Click Save .

22.4.3 Create or edit a program indicator group

  1. Open the Maintenance app and click Indicator > Program indicator group .

  2. Click the add button.

  3. Enter Name and Code .

  4. In the list of available program indicators, double-click the program indicators you want to assign to your group.

  5. Click Save .

22.4.4 Reference information: Expression and filter examples per value type

The table below shows examples of how to write expressions and filters for different data element and attribute value types:

Expression and filter examples per value type
Value types Example syntax

Integer

Negative integer

Positive or zero integer

Positive integer

Number

Percentage

Numeric fields, can be used for aggregation as an expression, or in filters:

#{mCXR7u4kNBW.K0A4BauXJDl} >= 3

Yes/No

Yes only

Boolean fields. Yes is translated to numeric 1, No to numeric 0. Can be used for aggregation as an expression, or in filters:

#{mCXR7u4kNBW.Popa3BauXJss} == 1

Text

Long text

Phone number

Email

Text fields. Can be checked for equality in filters:

#{mCXR7u4kNBW.L8K4BauIKsl} == 'LiteralValue'

Date

Age

Date fields. Most useful when combined with a d2:daysBetween function, which produces a number that can be aggregated as an expression or used in filters:

d2:daysBetween(#{mCXR7u4kNBW.JKJKBausssl},V{enrollment_date}) > 100

Can also directly be checked for equality in filters:

#{mCXR7u4kNBW.JKJKBausssl} == '2011-10-28'

Date

Age

Date fields. Most useful when combined with a d2:daysBetween function, which produces a number that can be aggregated as an expression or used in filters:

d2:daysBetween(#{mCXR7u4kNBW.JKJKBausssl},V{enrollment_date}) > 100

Can also directly be checked for equality in filters:

#{mCXR7u4kNBW.JKJKBausssl} == '2011-10-28'

22.4.5 Reference information: Functions, variables and operators to use in program indicator expressions and filters

An expression that includes both attributes, data elements and constants looks like this:

(A{GPkGfbmArby} + #{mCXR7u4kNBW.NFkjsNiQ9PH}) * C{bCqvfPR02Im}

An expression which uses the custom aggregation type and hence can use inline aggregation types looks like this:

(sum(#{mCXR7u4kNBW.K0A4BauXJDl} * #{mCXR7u4kNBW.NFkjsNiQ9PH}) / sum(#{mCXR7u4kNBW.NFkjsNiQ9PH})) * 100

Note how the “sum” aggregation operator is used inside the expression itself.

22.4.5.1 Functions to use in a program indicator expression or filter

The program indicator expression and filter support a range of functions. The functions can be applied to data elements and attributes:

Functions to use in a program indicator expression or filter

Function

Arguments

Description

d2:hasValue

(object)

Returns true if the data element/attribute has a value. Can be used in filters to distinguish between the number 0 and no value, and to distinguish between exlicit “No” and no selection for a Yes/No field.

d2:minutesBetween

(datetime, datetime)

Produces the number of minutes between two data elements/attributes of type “date and time”. The static datetime format is ‘yyyy-MM-dd hh:mm’.

d2:daysBetween

(date, date)

Produces the number of days between two data elements/attributes of type date. The static date format is ‘yyyy-MM-dd’.

d2:weeksBetween

(date, date)

Produces the number of full weeks between two data elements/attributes of type date. The static date format is ‘yyyy-MM-dd’.

d2:monthsBetween

(date, date)

Produces the number of full months between two data elements/attributes of type date. The static date format is ‘yyyy-MM-dd’.

d2:yearsBetween

(date, date)

Produces the number of full years between two data elements/attributes of type date. The static date format is ‘yyyy-MM-dd’.

d2:condition

(boolean-expr, true-val, false-val)

Evaluates the conditional expression and if true returns the true value, if false returns the false value. The conditional expression must be quoted.

d2:zing

(number)

Evaluates the data element/attribute of type number to zero if the value is negative, otherwise to the value itself.

d2:oizp

(number)

Evaluates the data element/attribute of type number to one if the value is zero or positive, otherwise to zero.

d2:zpvc

(object, [,object, object,…])

Returns the number of numeric zero and positive values among the given object arguments. Can be provided any number of arguments.

A filter that uses the “hasValue” function looks like this: this:

d2:hasValue(#{mCXR7u4kNBW.NFkjsNiQ9PH})

An expression that uses the “zing” and “oizp” functions looks like this:

d2:zing(A{GPkGfbmArby}) + d2:oizp(#{mCXR7u4kNBW.NFkjsNiQ9PH}))

An expression that uses the “daysBetween” function looks like this:

d2:daysBetween(#{mCXR7u4kNBW.k8ja2Aif1Ae},'2015-06-01')

An expression that uses the “condition” function looks like this:

d2:condition('#{mCXR7u4kNBW.NFkjsNiQ9PH} > 100',150,50)

An expression that uses the “zpvc” function looks like this:

d2:zpvc(A{GPkGfbmArby}),#{mCXR7u4kNBW.NFkjsNiQ9PH}),4,-1)

22.4.5.2 Variables to use in a program indicator expression or filter

The program indicator expression and filter support a range of variables:

Variables to use in a program indicator expression or filter

Variable

Description

event_date

The date of when the event took place.

due_date

The date of when an event is due.

incident_date

The date of the incidence of the event.

enrollment_date

The date of when the tracked entity instance was enrolled in the program.

enrollment_status

Can be used to include or exclude enrollments in certain statuses.

When calculating the hemoglobin improvement/deterioration throughout a pregnancy, it might make sense to only consider completed enrollments. If non-completed enrollments is not filtered out, these will represent half-finished ANC followups, where the final improvement/deterioration is not yet established.

current_date

The current date.

value_count

The number of non-null values in the expression part of the event.

zero_pos_value_count

The number of numeric positive values in the expression part of the event.

event_count

The count of events (useful in combination with filters).

enrollment_count

The count of enrollments (useful in combination with filters).

tei_count

The count of tracked entity instances (useful in combination with filters).

program_stage_name

Can be used in filters for including only certain program stages in a filter for tracker programs. Uses the name of the program stage:

V{program_stage_name} == 'ANC first visit'

program_stage_id

Can be used in filters for including only certain program stages in a filter for tracker programs. Uses the unique identifier of the program stage:

V{program_stage_id} == 'YPSSfbmAtt1'

An expression that uses the “value count” variable looks like this:

(#{A03MvHHogjR.a3kGcGDCuk6} + #{A03MvHHogjR.wQLfBvPrXqq}) / V{value_count}

An expression that uses the “event_date” and “incident_date” variables looks like this:

d2:daysBetween(V{incident_date},V{event_date})

22.4.5.3 Operators to use in a program indicator filter

Operators to use in a program indicator filter

Operator

Description

and

Logical AND

or

Logical OR

==

Equal to

!=

Not equal to

<

Less than

<=

Less than or equal to

>

Greater than

>=

Greater than or equal to

These operators can be used to form logical expressions which ultimately evaluate to either true or false. For example you can assert that multiple data elements must be a specific value, or that specific attributes must have numerical values less or greater than a constant.

A filter that uses both attributes and data elements looks like this:

A{cejWyOfXge6} == 'Female' and #{A03MvHHogjR.a3kGcGDCuk6} <= 2

Tip

DHIS2 is using the JEXL library for evaluating expressions which supports additional syntax beyond what is covered in this documentation. See the reference at the project home page to learn how you can create more sophisticated expressions