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()
#> 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()
#> https://play.im.dhis2.org/stable-2-40-5/api/resources
#> # A tibble: 89 × 4
#>    displayName                     singular                    plural      href 
#>    <chr>                           <chr>                       <chr>       <chr>
#>  1 Program Rule Actions            programRuleAction           programRul… http…
#>  2 Job Configurations              jobConfiguration            jobConfigu… http…
#>  3 Program Rules                   programRule                 programRul… http…
#>  4 Constants                       constant                    constants   http…
#>  5 Data Approval Workflows         dataApprovalWorkflow        dataApprov… http…
#>  6 Category Combos                 categoryCombo               categoryCo… http…
#>  7 Data Set Notification Templates dataSetNotificationTemplate dataSetNot… http…
#>  8 Program Stage Sections          programStageSection         programSta… http…
#>  9 Analytics Table Hooks           analyticsTableHook          analyticsT… http…
#> 10 Event Hooks                     eventHook                   eventHooks  http…
#> # ℹ 79 more rows

Get metadata on Data Elements using the plural name dataElements.

dhis2_play_connection$get_metadata(endpoint = "dataElements")
#> https://play.im.dhis2.org/stable-2-40-5/api/dataElements?fields=name%2Cid
#> # A tibble: 50 × 2
#>    name                                      id         
#>    <chr>                                     <chr>      
#>  1 Accute Flaccid Paralysis (Deaths < 5 yrs) FTRrcoaog83
#>  2 Acute Flaccid Paralysis (AFP) follow-up   P3jJH5Tu5VC
#>  3 Acute Flaccid Paralysis (AFP) new         FQ2o8UBlcrS
#>  4 Acute Flaccid Paralysis (AFP) referrals   M62VHgYT2n0
#>  5 Additional medication                     WO8yRIZb7nb
#>  6 Additional notes related to facility      uF1DLnZNlWe
#>  7 Admission Date                            eMyVanycQSC
#>  8 adresse exact                             eTuKNBLi58g
#>  9 Age in years                              qrur9Dvnyt5
#> 10 Age of LLINs                              JuTpJ2Ywq5b
#> # ℹ 40 more rows

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")
#> 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")
#> 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")
#> 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"))
#> https://play.im.dhis2.org/stable-2-40-5/api/dataElements?fields=name%2Cid%2CaggregationType
#> # A tibble: 50 × 3
#>    name                                      aggregationType id         
#>    <chr>                                     <chr>           <chr>      
#>  1 Accute Flaccid Paralysis (Deaths < 5 yrs) SUM             FTRrcoaog83
#>  2 Acute Flaccid Paralysis (AFP) follow-up   SUM             P3jJH5Tu5VC
#>  3 Acute Flaccid Paralysis (AFP) new         SUM             FQ2o8UBlcrS
#>  4 Acute Flaccid Paralysis (AFP) referrals   SUM             M62VHgYT2n0
#>  5 Additional medication                     NONE            WO8yRIZb7nb
#>  6 Additional notes related to facility      SUM             uF1DLnZNlWe
#>  7 Admission Date                            AVERAGE         eMyVanycQSC
#>  8 adresse exact                             NONE            eTuKNBLi58g
#>  9 Age in years                              AVERAGE         qrur9Dvnyt5
#> 10 Age of LLINs                              SUM             JuTpJ2Ywq5b
#> # ℹ 40 more rows

organisationUnits

dhis2_play_connection$get_metadata(endpoint = "organisationUnits",
                                                        fields =  c("name","id", "level"))
#> https://play.im.dhis2.org/stable-2-40-5/api/organisationUnits?fields=name%2Cid%2Clevel
#> # A tibble: 50 × 3
#>    name                      id          level
#>    <chr>                     <chr>       <int>
#>  1 Adonkia CHP               Rp268JB6Ne4     4
#>  2 Afro Arab Clinic          cDw53Ej8rju     4
#>  3 Agape CHP                 GvFqTavdpGE     4
#>  4 Ahamadyya Mission Cl      plnHVbJR6p4     4
#>  5 Ahmadiyya Muslim Hospital BV4IomHvri4     4
#>  6 Air Port Centre, Lungi    qjboFI0irVu     4
#>  7 Alkalia CHP               dWOAzMcK2Wt     4
#>  8 Allen Town Health Post    kbGqmM6ZWWV     4
#>  9 Antananarivo              w8OOoqYFAWI     2
#> 10 Approved School CHP       eoYV2p74eVz     4
#> # ℹ 40 more rows

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")
#> 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")
#> https://play.im.dhis2.org/stable-2-40-5/api/indicators?fields=name%2Cid
#> # A tibble: 50 × 2
#>    name                                 id         
#>    <chr>                                <chr>      
#>  1 ANC 1-3 Dropout Rate                 ReUHfIn0pTQ
#>  2 ANC 1 Coverage                       Uvn6LCg7dVU
#>  3 ANC 2 Coverage                       OdiHJayrsKo
#>  4 ANC 3 Coverage                       sB79w2hiLp8
#>  5 ANC => 4 Coverage                    AUqdhY4mpvp
#>  6 ANC IPT 1 Coverage                   dwEq7wi6nXV
#>  7 ANC IPT 2 Coverage                   c8fABiNpT0B
#>  8 ANC LLITN coverage                   Tt5TAvdfdVK
#>  9 ANC TT2 coverage                     puykO1tbcdi
#> 10 ANC visits per clinical professional Lzg9LtG1xg3
#> # ℹ 40 more rows

Get analtyics

dhis2_play_connection$get_analytics(analytic = "s46m5MS0hxu",
                                    org_unit = c("O6uvpzGd5pu", "fdc6uOvgoji"),
                                    period = "202101",
                                    output_scheme = "NAME")
#> https://play.im.dhis2.org/stable-2-40-5/api/analytics?dimension=dx%3As46m5MS0hxu&dimension=ou%3AO6uvpzGd5pu%3Bfdc6uOvgoji&dimension=pe%3A202101&outputIdScheme=NAME
#> # A tibble: 2 × 4
#>   analytic        org_unit period       value
#>   <fct>           <fct>    <chr>        <dbl>
#> 1 BCG doses given Bombali  January 2021   537
#> 2 BCG doses given Bo       January 2021  1196
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")
#> https://play.im.dhis2.org/stable-2-40-5/api/analytics?dimension=dx%3AFTRrcoaog83&dimension=ou%3AImspTQPwCqd&dimension=pe%3ALAST_12_MONTHS&outputIdScheme=NAME
#> # A tibble: 6 × 4
#>   analytic                                  org_unit     period         value
#>   <fct>                                     <fct>        <chr>          <dbl>
#> 1 Accute Flaccid Paralysis (Deaths < 5 yrs) Sierra Leone October 2024       3
#> 2 Accute Flaccid Paralysis (Deaths < 5 yrs) Sierra Leone September 2024   101
#> 3 Accute Flaccid Paralysis (Deaths < 5 yrs) Sierra Leone August 2024      254
#> 4 Accute Flaccid Paralysis (Deaths < 5 yrs) Sierra Leone March 2024         1
#> 5 Accute Flaccid Paralysis (Deaths < 5 yrs) Sierra Leone February 2024     61
#> 6 Accute Flaccid Paralysis (Deaths < 5 yrs) Sierra Leone January 2024      23