-
Notifications
You must be signed in to change notification settings - Fork 0
/
khisr.Rmd
257 lines (205 loc) · 12.2 KB
/
khisr.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
---
title: "Getting Started"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Getting Started}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
can_decrypt <- httr2::secret_has_key('KHIS_KEY')
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
error = TRUE,
purl = can_decrypt,
eval = can_decrypt
)
options(tibble.print_min = 5L, tibble.print_max = 5L)
```
```{r, eval = !can_decrypt, echo = FALSE, comment = NA}
message("No token available. Code chunks will not be evaluated.")
```
```{r, eval = can_decrypt, include=FALSE}
khisr:::khis_cred_docs()
```
```{r, include=FALSE}
library(khisr)
```
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.
## Authentication
`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.
### 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](https://khisr.damurka.com/articles/set-your-credentials.html), for detailed instructions on setting and managing credentials effectively.
```{r, eval = FALSE}
# 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.
## Metadata
DHIS2 utilizes metadata to define the structure and meaning of its data. Explore the [data dimensions](https://khisr.damurka.com/articles/data-dimensions.html) resource for a deeper understanding.
### Metadata helpers in khisr
`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 |
### Metadata object filter
`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:
- **property**: The property of the metadata you want to filter on.
- **operator**: The comparison operator you want to perform (examples: `eq` for equality, `like` for case-sensitive string matching).
- **value**: The value to use for comparison (not required for all operators).
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 |
### Working with metadata filters
Basic usage of the metadata filter
```{r, eval = can_decrypt}
# 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_elements
```
## Data analytics
The 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:
### Key Functions
- `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.
### 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.
| 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-<level>,|
| | and OU_GROUP-<group-id> |
| | |
| co | Category option combo identifiers (use `all` to get all items) |
| | |
| ao |Category option combo identifiers (use `all` to get all items) |
### 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.
```{r, eval = can_decrypt}
# 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'
)
```
- **Apply Filters:** Use the filters parameter to specify dimensions for filtering
data without including them in the response.
```{r, eval = can_decrypt}
# 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'
)
```