Getting Started

Setting Your Credentials:

1. Obtain Credentials: Secure your DHIS2 username and password through appropriate channels within the DHIS2 organization.

2. Store Credentials Securely: khisr offers a convenient way to store your credentials within your R environment. Refer to the comprehensive guide, Set Your Credentials, for detailed instructions on setting and managing credentials effectively.

# Set the credentials using username and password
khis_cred(username = 'your-dhis2-username', password = 'your-dhis2-password', server = 'https://<your dhis2 instance>')

# Set the credentials using a Personal Access Token (DHIS2's recommended
# method for scripts and integrations) instead of username/password
khis_cred(token = 'your-dhis2-token', server = 'https://<your dhis2 instance>')

# Set credentials using configuration path
khis_cred(config_path = 'path/to/secret.json')

Note: Replace placeholders like ‘your-dhis2-username’ and ‘path/to/your/secret.json’ with your actual credentials and file path.

Metadata helpers in khisr

khisr provides a set of high-level functions — one per DHIS2 metadata type (get_organisation_units(), get_data_elements(), get_programs(), and around 25 others) — that all share the same interface and can be filtered the same way. See ?metadata-helpers for the full list, and your R IDE’s auto-complete for faster typing.

Metadata object filter

khisr filters retrieved metadata using DHIS2’s property:operator:value pattern, exposed through metadata_filter() and a matching set of infix operators (%.eq%, %.like%, %.in%, and about 20 more — see ?metadata_filter for the complete list with descriptions).

Working with metadata filters

Basic usage of the metadata filter

# Retrieve organisation units by province (level 2)
province <- get_organisation_units(level %.eq% '2')
province

# Retrieve province by name (Vientiane Capital)
province <- get_organisation_units(level %.eq% '2',
                                   name %.like% 'vientiane capital')
province

data_element_id <- c('lYsfXxCw6Qi', 'GxlrIgMyEf4')

# Retrieve data elements by ID using operator in
data_elements <- get_data_elements(id %.in% data_element_id)
data_elements

# Retrieve data elements by filtering using dataElementGroups
data_elements <- get_data_elements(dataElementGroups.name %.like% 'malaria')
data_elements

Key Functions

• get_analytics(): Retrieves aggregated data based on specified dimensions and filters.
• get_data_value_sets(): Retrieves the individually entered raw data values behind the aggregates — useful for data-quality auditing.
• analytics_dimension(): Constructs dimensions for queries, ensuring accurate data retrieval.
• %.d% (infix operator): Convenient shorthand for creating dimension filters.
• %.f% (infix operator): Convenient shorthand for creating filter dimensions.
• get_event_analytics_aggregate()/get_enrollment_analytics_aggregate(): pivot-table style totals over Tracker data — see Tracker Data.

Dimension (dx)

The dimension query parameter defines which dimensions should be included in the analytics query. Any number of dimensions can be specified. The dimension parameter should be repeated for each dimension to include in the query response. The query response can potentially contain aggregated values for all combinations of the specified dimension items. The fixed dimensions are the data element (dx) period (time) (pe) and organisation unit (ou) dimension. You can dynamically add dimensions through categories, data element group sets and organisation unit group sets.

Filter (filter)

The filter parameter defines which dimensions should be used as filters for the data retrieved in the analytics query. Any number of filters can be specified. The filter parameter should be repeated for each filter to use in the query. A filter differs from a dimension in that the filter dimensions will not be part of the query response content, and that the aggregated values in the response will be collapsed on the filter dimensions. In other words, the data in the response will be aggregated on the filter dimensions, but the filters will not be included as dimensions in the actual response.

Constructing Queries

• Specify Dimensions: Use the dimensions parameter to define the dimensions you want to include in the query response. Leverage the infix operators %.d% for concise and readable code.

# To include a list dimensions for data elements id, dataset ids
dx %.d% c('dimension-id-1', 'dimension-id-2')

pe %.d% 'LAST_YEAR'

ou %.d% 'USER_ORGUNIT'

# showing in the analytics
get_analytics(
    dx %.d% c('lYsfXxCw6Qi', 'vTRrNdOOT9g', 'GxlrIgMyEf4'),
    pe %.d% 'LAST_YEAR',
    ou %.d% c('W6sNfkJcXGC')
)

# Using the startDate and endDate with organisation unit keyword 'USER_ORGUNIT'
get_analytics(
    dx %.d% c('lYsfXxCw6Qi', 'vTRrNdOOT9g', 'GxlrIgMyEf4'),
    ou %.d% 'USER_ORGUNIT',
    pe %.d% 'all',
    startDate = '2023-07-01',
    endDate = '2023-12-31'
)

• Apply Filters: Use the filters parameter to specify dimensions for filtering data without including them in the response.

# Filter by period
pe %.f% 'LAST_YEAR'

# Filter by organisation unit
ou %.f% 'USER_ORGUNIT'

# showing in the analytics. filter by organisation unit with id 'W6sNfkJcXGC'
# and period 'LAST_YEAR'
get_analytics(
    dx %.d% c('lYsfXxCw6Qi', 'vTRrNdOOT9g', 'GxlrIgMyEf4'),
    pe %.f% 'LAST_YEAR',
    ou %.f% 'W6sNfkJcXGC'
)

Data quality

Alongside the aggregated values themselves, DHIS2 exposes a few endpoints for checking the quality of reported data:

# Completeness registrations for a data set at a province and everything
# below it, for a single period
get_complete_data_set_registrations(
    data_sets = 'VEM58nY22sO',
    org_units = 'W6sNfkJcXGC',
    children = TRUE,
    periods = '202301'
)

get_analytics_outliers() and get_validation_results() require the authenticated user to have the corresponding DHIS2 authority (outlier detection or validation analysis); without it, DHIS2 returns an authorisation error rather than empty results.