No token available. Code chunks will not be evaluated.The khisr R package simplifies interaction with the
District Health Information System 2 (DHIS2) platform. Designed for
researchers and public health professionals, khisr
streamlines data retrieval and analysis, saving you valuable time
compared to manual methods.
khisr prioritizes security by operating in authenticated
mode by default. This ensures you interact with DHIS2 as a recognized
user. To begin exploring DHIS2 data, you’ll need to establish your
credentials.
Obtain Credentials: Secure your DHIS2 username and password through appropriate channels within the DHIS2 organization.
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', base_url = '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.
DHIS2 utilizes metadata to define the structure and meaning of its data. Explore the data dimensions resource for a deeper understanding.
khisr provides a set of high-level functions to retrieve
details about various DHIS2 metadata categories. These functions often
leverage your R IDE’s auto-complete feature for faster typing.
The following table summarizes these khisr metadata
helper functions:
| khisr function | DHIS2 API Endpoint |
|---|---|
get_categories() |
categories |
get_category_combos() |
categoryCombos |
get_category_option_combos() |
categoryOptionCombos |
get_category_option_group_sets() |
categoryOptionGroupSets |
get_category_option_groups() |
categoryOptionGroups |
get_category_options() |
categoryOptions |
get_data_element_group_sets() |
dataElementGroupSets |
get_data_element_groups() |
dataElementGroups |
get_data_elements() |
dataElements |
get_data_sets() |
dataSets |
get_indicator_group_sets() |
indicatorGroupSets |
get_indicator_groups() |
indicatorGroups |
get_indicators() |
indicators |
get_option_group_sets() |
optionGroupSets |
get_option_groups() |
optionGroups |
get_option_sets() |
optionSets |
get_options() |
options |
get_organisation_unit_groupsets() |
organisationUnitGroupSets |
get_organisation_unit_groups() |
organisationUnitGroups |
get_organisation_units() |
organisationUnits |
get_dimensions() |
dimensions |
get_user_groups() |
userGroups |
get_period_types() |
periodTypes |
khisr allows you to filter retrieved metadata using a
straightforward approach. The filter format follows the pattern
property:operator:value. Here’s a breakdown of the
components:
eq for equality, like for
case-sensitive string matching).The following table provides a summary of the supported operators:
| DHIS2 Operator | Infix Operator | Description |
|---|---|---|
eq |
%.eq% |
Equality |
!eq |
%.~eq% |
Inequality |
ieq |
%.ieq% |
Case insensitive string, match exact |
ne |
%.ne% |
Inequality |
like |
%.Like% |
Case sensitive string, match anywhere |
!like |
%.~Like% |
Case sensitive string, not match anywhere |
$like |
%.^Like% |
Case sensitive string, match start |
!$like |
%.~^Like% |
Case sensitive string, not match start |
like$ |
%.Like$% |
Case sensitive string, match end |
!like$ |
%.~Like$% |
Case sensitive string, not match end |
ilike |
%.like% |
Case insensitive string, match anywhere |
!ilike |
%.~like% |
Case insensitive string, not match anywhere |
$ilike |
%.^like% |
Case insensitive string, match start |
!$ilike |
%.~^like% |
Case insensitive string, not match start |
ilike$ |
%.like$% |
Case insensitive string, match end |
!ilike$ |
%.~like$% |
Case insensitive string, not match end |
gt |
%.gt% |
Greater than |
ge |
%.ge% |
Greater than or equal |
lt |
%.lt% |
Less than |
le |
%.le% |
Less than or equal |
token |
%.token% |
Match on multiple tokens in search property |
!token |
%.~token% |
Not match on multiple tokens in search property |
in |
%.in% |
Find objects matching 1 or more values |
!in |
%.~in% |
Find objects not matching 1 or more values |
Basic usage of the metadata filter
# Retrieve organisation units by county (level 2)
county <- get_organisation_units(level %.eq% '2')
county
# Retrieve county by name (Mombasa)
county <- get_organisation_units(level %.eq% '2',
name %.like% 'mombasa')
county
data_element_id <- c('cXe64Yk0QMY', 'XEX93uLsAm2')
# 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% 'moh 705')
data_elementsThe analytics resource in DHIS2 empowers you to access and analyze aggregated data across various dimensions. To effectively leverage this resource, let’s explore the key functions and parameters involved:
get_analytics(): Retrieves aggregated data based on
specified dimensions and filters.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.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.
| Dimension ID | Dimensions |
|---|---|
| dx | Data elements, indicators, data set reporting rate metrics, |
| data element operands, program indicators, program data elements, | |
| program attributes, validation rules | |
| pe | ISO periods and relative periods (see “date and period format”) |
| ou | Organisation unit hierarchy |
| Organisation unit identifiers, keywords USER_ORGUNIT, | |
| USER_ORGUNIT_CHILDREN, USER_ORGUNIT_GRANDCHILDREN,
LEVEL- |
|
| and OU_GROUP- |
|
| co | Category option combo identifiers (use all
to get all items) |
| ao | Category option combo identifiers (use all
to get all items) |
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.
# 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('siOyOiOJpI8', 'Lt0FqtnHraW', 'OoakJhWiyZp'),
pe %.d% 'LAST_YEAR',
ou %.d% c('qKzosKQPl6G')
)
# Using the startDate and endDate with organisation unit keyword 'USER_ORGUNIT'
get_analytics(
dx %.d% c('siOyOiOJpI8', 'Lt0FqtnHraW', 'OoakJhWiyZp'),
ou %.d% 'USER_ORGUNIT',
pe %.d% 'all',
startDate = '2023-07-01',
endDate = '2023-12-31'
)# 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 'qKzosKQPl6G'
# and period 'LAST_YEAR'
get_analytics(
dx %.d% c('siOyOiOJpI8', 'Lt0FqtnHraW', 'OoakJhWiyZp'),
pe %.f% 'LAST_YEAR',
ou %.f% 'qKzosKQPl6G'
)