dtmapi is an R package developed by Displacement Tracking Matrix
(DTM). This package allows the humanitarian
community, academia, media, government, and non-governmental
organizations to utilize the data collected by DTM. It provides
non-sensitive Internally Displaced Person (IDP) figures, aggregated at
the country, Admin 1 (states, provinces, or equivalent), and Admin 2
(smaller subnational administrative areas) levels. Country Names and
Operations can be found in this data
coverage
matrix.
Please find more information about DTM API here.
The dtmapi package is available on
CRAN and can be installed
as follows:
install.packages("dtmapi")Using dtmapi requires a subscription key. To obtain one, register with
the DTM API Portal and follow
the instructions there.
The subscription key is secret and should not be exposed. Once it is
obtained, the subscription key should be set for your current R session,
assuming that the dtmapi package is installed. To do this, the
environment variable DTM_SUBSCRIPTION_KEY needs to be defined. This
can be done either interactively or non-interactively.
The interactive option is to call set_subscription_key(), like so:
dtmapi::set_subscription_key()At this point, the user will be prompted to input the key (hidden) into a pop-up field.
Some environments are non-interactive, and so running the above will
likely result in an error. In such a case, the subscription key may be
set non-interactively, by specifying the key parameter, like so:
# Specifying `key` is required for non-interactive use.
dtmapi::set_subscription_key(key = "mysubscriptionkey")However, this option is discouraged and should be avoided as much as
possible, because it blatantly exposes the subscription key. The best
option would be to engage in good secrets management practices, such as
by using a .Renviron file (if applicable). Basic secrets management, and
the issue of setting the subscription key in general, is elaborated on
in more detail in vignette("user_guide").
When the subscription key is set, data on internal displacement may be retrieved through any of the following functions:
get_idp_admin_0_data()get_idp_admin_1_data()get_idp_admin_2_data()
These all retrieve data from the DTM API and return said data in the form of data frames.
Certain parameters have to be specified to any of these, the most
important of which are either the CountryName or the OperationName.
For information on the other parameters and indeed all functions in
dtmapi, see the documentation
here.
As a representative example of the earlier mentioned functions, see the
following use of get_idp_admin_1_data():
# Load the package
library(dtmapi)
idp_admin1_df <- get_idp_admin1_data(CountryName = "Sudan",
Admin1Name = "Blue Nile",
FromReportingDate = "2020-01-01",
ToReportingDate = "2024-08-15")
# Display the first few rows of the data frame
head(idp_admin1_df)
#> id operation admin0Name admin0Pcode admin1Name admin1Pcode
#> 1 4743857 Darfur conflict Sudan SDN Blue Nile SD08
#> 2 4743858 Darfur conflict Sudan SDN Blue Nile SD08
#> 3 4743859 Darfur conflict Sudan SDN Blue Nile SD08
#> 4 4743860 Darfur conflict Sudan SDN Blue Nile SD08
#> 5 4722729 Armed Clashes in Sudan Sudan SDN Blue Nile SD08
#> 6 4722730 Armed Clashes in Sudan Sudan SDN Blue Nile SD08
#> numPresentIdpInd reportingDate yearReportingDate monthReportingDate
#> 1 81693 2021-03-30T00:00:00 2021 3
#> 2 130958 2021-12-31T00:00:00 2021 12
#> 3 151156 2022-01-31T00:00:00 2022 1
#> 4 152656 2022-03-30T00:00:00 2022 3
#> 5 260 2023-04-28T00:00:00 2023 4
#> 6 715 2023-05-07T00:00:00 2023 5
#> roundNumber displacementReason numberMales numberFemales
#> 1 2 Conflict NA NA
#> 2 3 Conflict; Natural disaster NA NA
#> 3 4 Conflict NA NA
#> 4 5 Conflict NA NA
#> 5 2 Conflict NA NA
#> 6 3 Conflict NA NA
#> idpOriginAdmin1Name idpOriginAdmin1Pcode assessmentType
#> 1 Blue Nile SD08 BA
#> 2 Blue Nile SD08 BA
#> 3 Not available Not available BA
#> 4 Blue Nile SD08 BA
#> 5 West Darfur SD04 BA
#> 6 Khartoum SD01 BASince the available country names or operation names are often necessary
to know of, they can be obtained by using the get_all_countries() and
get_all_operations() functions, which do not take any arguments.
# Load the package
library(dtmapi)
countries_df <- get_all_countries()
# Display the first few rows of the data frame
head(countries_df)
#> admin0Name admin0Pcode
#> 1 Afghanistan AFG
#> 2 Antigua and Barbuda ATG
#> 3 Bahamas (the) BHS
#> 4 Benin BEN
#> 5 Bolivia (Plurinational State of) BOL
#> 6 Burkina Faso BFA# Load the package
library(dtmapi)
operations_df <- get_all_operations()
# Display the first few rows of the data frame
head(operations_df)
#> operation operationStatus admin0Name
#> 1 Aceh earthquake Inactive Indonesia
#> 2 Armed Clashes in Sudan Active Sudan
#> 3 Armed Clashes in Sudan (Monthly) Active Sudan
#> 4 Armed Clashes in Sudan (Overview) Active Sudan
#> 5 Arrivals in Armenia Inactive Republic of Armenia
#> 6 Bahamas (the) - Hurricane Dorian Response Inactive Bahamas (the)
#> admin0Pcode
#> 1 IDN
#> 2 SDN
#> 3 SDN
#> 4 SDN
#> 5 ARM
#> 6 BHSThe information given here is further elaborated on in the user guide to
getting started with dtmapi, which is accessible through
vignette("user_guide").
The source code for dtmapi is available on
GitHub.
Feel free to explore the repository, contribute, or raise any issues you may encounter.
For any questions or feedback, please reach out to us at [email protected].