Getting started with dhis2r

library(dhis2r)

Connect to the DHIS2 instance using Dhis2r$new()

In this vignette I used a Personal Access Token (PAT) as a more secure alternative to HTTP Basic Authentication, and should be your preferred choice when creating a new app/script etc.

dhis2_play_connection <- Dhis2r$new(base_url = "https://play.im.dhis2.org/stable-2-40-5",
                                    username = "admin",
                                    password = "district")
dhis2_play_connection <- Dhis2r$new(base_url = "https://play.im.dhis2.org/stable-2-40-5",
                                    api_token = "d2pat_2EkxmqdxtwAGDGe1hXzpWEixYdvHGRw71587176066")

Get user information

# [Ways of keeping your user credentials safe](https://solutions.posit.co/connections/db/best-practices/managing-credentials/)
dhis2_play_connection$get_user_info()
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/me"
#>              name             email 
#>     "John Traore" "dummy@dhis2.org"

Get information about the account

dhis2_play_connection$account_info
#>                   created 
#> "2013-04-18T17:15:08.407"

Get access rights information about the account

dhis2_play_connection$access_rights
#>      manage externalize       write        read      update      delete 
#>        TRUE       FALSE        TRUE        TRUE        TRUE        TRUE

Get metadata

Get all resources on which you can get metadata on.

 dhis2_play_connection$get_metadata()
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/resources"
#> # A tibble: 89 × 4
#>    displayName                singular               plural                href 
#>    <chr>                      <chr>                  <chr>                 <chr>
#>  1 Relationships              relationship           relationships         http…
#>  2 Tracked Entity Attributes  trackedEntityAttribute trackedEntityAttribu… http…
#>  3 Data Element Operands      dataElementOperand     dataElementOperands   http…
#>  4 Program Indicators         programIndicator       programIndicators     http…
#>  5 Job Configurations         jobConfiguration       jobConfigurations     http…
#>  6 Icons                      icon                   icons                 http…
#>  7 Program Rules              programRule            programRules          http…
#>  8 Category Option Group Sets categoryOptionGroupSet categoryOptionGroupS… http…
#>  9 Event Hooks                eventHook              eventHooks            http…
#> 10 User Groups                userGroup              userGroups            http…
#> # ℹ 79 more rows

Get metadata on Data Elements using the plural name dataElements.

dhis2_play_connection$get_metadata(endpoint = "dataElements")
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/dataElements?fields=name%2Cid"
#> # A tibble: 5 × 1
#>   `response_data[[1]]`
#>   <named list>        
#> 1 <int [1]>           
#> 2 <int [1]>           
#> 3 <int [1]>           
#> 4 <chr [1]>           
#> 5 <int [1]>

The code above only returns it’s name and code/ID used on DHIS2, we shall use the code to get analytics.

Get all possible fields of a metadata of a resource

You can get more fields beyond ID and name

NOTE All resources have different fields

 dhis2_play_connection$get_metadata_fields(endpoint = "dataElements")
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/dataElements?fields=%3Aall&paging=true&pageSize=1"
#>  [1] "access"            "aggregationLevels" "aggregationType"  
#>  [4] "attributeValues"   "categoryCombo"     "code"             
#>  [7] "created"           "createdBy"         "dataElementGroups"
#> [10] "dataSetElements"   "dimensionItem"     "dimensionItemType"
#> [13] "displayFormName"   "displayName"       "displayShortName" 
#> [16] "domainType"        "externalAccess"    "favorite"         
#> [19] "favorites"         "href"              "id"               
#> [22] "lastUpdated"       "legendSets"        "name"             
#> [25] "optionSetValue"    "publicAccess"      "sharing"          
#> [28] "shortName"         "translations"      "url"              
#> [31] "user"              "userAccesses"      "userGroupAccesses"
#> [34] "valueType"         "zeroIsSignificant"
 dhis2_play_connection$get_metadata_fields(endpoint = "organisationUnits")
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/organisationUnits?fields=%3Aall&paging=true&pageSize=1"
#>  [1] "access"                 "ancestors"              "attributeValues"       
#>  [4] "children"               "code"                   "created"               
#>  [7] "dataSets"               "dimensionItem"          "dimensionItemType"     
#> [10] "displayFormName"        "displayName"            "displayShortName"      
#> [13] "externalAccess"         "favorite"               "favorites"             
#> [16] "href"                   "id"                     "lastUpdated"           
#> [19] "leaf"                   "legendSets"             "level"                 
#> [22] "name"                   "openingDate"            "organisationUnitGroups"
#> [25] "parent"                 "path"                   "programs"              
#> [28] "sharing"                "shortName"              "translations"          
#> [31] "userAccesses"           "userGroupAccesses"      "users"
 dhis2_play_connection$get_metadata_fields(endpoint = "indicators")
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/indicators?fields=%3Aall&paging=true&pageSize=1"
#>  [1] "access"                        "annualized"                   
#>  [3] "attributeValues"               "code"                         
#>  [5] "created"                       "createdBy"                    
#>  [7] "dataSets"                      "denominator"                  
#>  [9] "denominatorDescription"        "description"                  
#> [11] "dimensionItem"                 "dimensionItemType"            
#> [13] "displayDenominatorDescription" "displayDescription"           
#> [15] "displayFormName"               "displayName"                  
#> [17] "displayNumeratorDescription"   "displayShortName"             
#> [19] "externalAccess"                "favorite"                     
#> [21] "favorites"                     "href"                         
#> [23] "id"                            "indicatorGroups"              
#> [25] "indicatorType"                 "lastUpdated"                  
#> [27] "legendSets"                    "name"                         
#> [29] "numerator"                     "numeratorDescription"         
#> [31] "publicAccess"                  "sharing"                      
#> [33] "shortName"                     "translations"                 
#> [35] "url"                           "user"                         
#> [37] "userAccesses"                  "userGroupAccesses"

Getting metadata fields beyond ID and Name

dataElements

 dhis2_play_connection$get_metadata(endpoint = "dataElements", fields = c("name","id","aggregationType"))
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/dataElements?fields=name%2Cid%2CaggregationType"
#> # A tibble: 5 × 1
#>   `response_data[[1]]`
#>   <named list>        
#> 1 <int [1]>           
#> 2 <int [1]>           
#> 3 <int [1]>           
#> 4 <chr [1]>           
#> 5 <int [1]>

organisationUnits

dhis2_play_connection$get_metadata(endpoint = "organisationUnits",
                                                        fields =  c("name","id", "level"))
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/organisationUnits?fields=name%2Cid%2Clevel"
#> # A tibble: 5 × 1
#>   `response_data[[1]]`
#>   <named list>        
#> 1 <int [1]>           
#> 2 <int [1]>           
#> 3 <int [1]>           
#> 4 <chr [1]>           
#> 5 <int [1]>

You can use ":all" in the fields to get all fields of metadata associated with a resources

periodTypes

dhis2_play_connection$get_metadata(endpoint = "periodTypes", fields = ":all")
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/periodTypes?fields=%3Aall"
#> # A tibble: 19 × 4
#>    name            isoDuration isoFormat   frequencyOrder
#>    <chr>           <chr>       <chr>                <int>
#>  1 Daily           P1D         yyyyMMdd                 1
#>  2 Weekly          P7D         yyyyWn                   7
#>  3 WeeklyWednesday P7D         yyyyWedWn                7
#>  4 WeeklyThursday  P7D         yyyyThuWn                7
#>  5 WeeklySaturday  P7D         yyyySatWn                7
#>  6 WeeklySunday    P7D         yyyySunWn                7
#>  7 BiWeekly        P14D        yyyyBiWn                14
#>  8 Monthly         P1M         yyyyMM                  30
#>  9 BiMonthly       P2M         yyyyMMB                 61
#> 10 Quarterly       P3M         yyyyQn                  91
#> 11 QuarterlyNov    P3M         yyyyNovQn               91
#> 12 SixMonthly      P6M         yyyySn                 182
#> 13 SixMonthlyApril P6M         yyyyAprilSn            182
#> 14 SixMonthlyNov   P6M         yyyyNovSn              182
#> 15 Yearly          P1Y         yyyy                   365
#> 16 FinancialApril  P1Y         yyyyApril              365
#> 17 FinancialJuly   P1Y         yyyyJuly               365
#> 18 FinancialOct    P1Y         yyyyOct                365
#> 19 FinancialNov    P1Y         yyyyNov                365

indicators

dhis2_play_connection$get_metadata(endpoint = "indicators")
#> [1] "https://play.im.dhis2.org/stable-2-40-5/api/indicators?fields=name%2Cid"
#> # A tibble: 5 × 1
#>   `response_data[[1]]`
#>   <named list>        
#> 1 <int [1]>           
#> 2 <int [1]>           
#> 3 <int [1]>           
#> 4 <chr [1]>           
#> 5 <int [1]>

Get analtyics

# dhis2_play_connection$get_analytics(analytic = "s46m5MS0hxu",
#                                     org_unit = c("O6uvpzGd5pu", "fdc6uOvgoji"),
#                                     period = "202101",
#                                     output_scheme = "NAME")
# dhis2_play_connection$get_analytics(analytic = "FTRrcoaog83", #Accute Flaccid Paralysis (Deaths < 5 yrs)
#                                     org_unit =   c("ImspTQPwCqd"), #Sierra Leone (National level)
#                                     period = "LAST_12_MONTHS",
#                                     output_scheme = "NAME")