No token available. Code chunks will not be evaluated.Introduction
The dtmapi package provides functions to interact with
the Displacement Tracking Matrix (DTM) API. This vignette demonstrates
how to use the package’s functions to fetch data from the API. The
functions covered include:
Install Package
The dtmapi package is available on CRAN and can be
installed using the following command:
install.packages("dtmapi")Setting the Subscription Key
After creating a subscription key on https://dtm-apim-portal.iom.int, that key needs to be
given to R. To do this, the DTM_SUBSCRIPTION_KEY
environment variable needs to be defined as the subscription key. There
are three main ways to do this, as described below.
1. Using set_subscription_key(): interactive, safe
option
By calling set_subscription_key(), after which the user
is prompted to input the key into a pop-up field.
Note that if the environment is not interactive, it is likely for the user to receive an error message instead, such as in the case of using Google Colab. In such cases see the other options described further below.
2. Using set_subscription_key(): the non-interactive,
discouraged option
If the interactive option above fails for the user, such that there
is an error instead of a pop-up, the user may rely on passing their key
directly into set_subscription_key() by naming the
key parameter.
# Specifying `key` is required for non-interactive use.
set_subscription_key(key = "mysubscriptionkey")This is basically using set_subscription_key() as a
wrapper for setting up the environment variable
DTM_SUBSCRIPTION_KEY using base R’s
Sys.setenv(), as shown below:
Sys.setenv("DTM_SUBSCRIPTION_KEY" = "mysubscriptionkey")Please note that by doing this in, say, a Google Colab script, .R script, or Jupyter notebook, you are leaving a secret (your subscription key) exposed and available for anyone to read with ease. This is why this option is not recommended, but it will allow you to get things working faster if you are not familiar with managing secrets in a non-interactive context.
3. Setting up the environment variable with good secrets management
If one would like to avoid re-inputting the subscription key for each R session, and they would like to set the subscription in a way that is both non-interactive and safer, then this becomes a matter of knowing the right secrets management practices depending on where R is being used (e.g. whether that is in a local desktop, a cloud-based programming environment, a server, etc.).
In the vast majority of cases, the approach is the fundamentally the
same: anything that directly stores your key should be separate
from the rest of your code, and your code accesses the key
through an environment variable. That is the main
principle to the most common way to manage your secrets. What differs by
where R is being used is how this principle is applied. Below,
the user guide will mostly focus on how this is handled when using a
code editor such as VSCode, RStudio, or Positron, as this is the most
common case. If these do not reflect your circumstance or use-case, then
researching how to manage secrets generally for that circumstance should
suffice, as the only thing specific about doing so for the
dtmapi package is just the name of the environment
variable, DTM_SUBSCRIPTION_KEY.
Using a code editor such as VSCode or RStudio on a desktop:
Use a .Renviron file to set the key. You can create it
from scratch, and its contents should look something like this:
DTM_SUBSCRIPTION_KEY = "mysubscriptionkey"
Some_Other_Env_Var = "something else if desired"For this to work robustly, your .Renviron should be in
the same working directory that you would like to use for your
R sessions (i.e. it should be in the same location or folder that you
would like your R sessions to use as a default). You can see which
folder that currently is by running:
getwd()This is important to know because, if your R session can start in the
same working directory that the .Renviron file is located
in, then the environment variables specified there are automatically
loaded for your R session!
Usually, your choice of working directory is best managed by creating
an R project or equivalent (such as VS Code
workspaces). That is to say, one should have a dedicated folder for
their specific project, the R sessions they run should make that folder
the working directory, and .Renviron should be placed there
as well. For more information, depending on whether you use RStudio,
VSCode, or Positron, see: Using
RStudio Projects, What is a
VS Code Workspace?, or Launching
Positron in a workspace.
If one is unfamiliar and struggling to create the .Renviron file,
then one quick way to proceed with editing the .Renviron
file or placing it in their project directory (if they have one) is by
calling the following line of code (make sure the usethis
package is installed):
usethis::edit_r_environ("project")Or, if one is not using an R project or equivalent, then this is an option as well, though using the general user directory is not recommended as it is likely to get lost:
usethis::edit_r_environ("user")Remember: NEVER SHARE THE .RENVIRON FILE.
Get All Countries
The get_all_countries() function retrieves a list of all
countries from the DTM API.
# Fetch all countries
countries_df <- get_all_countries()
# Display the first few rows of the data frame
head(countries_df)Get All Operations
The get_all_operations() function retrieves a list of
all operations from the DTM API.
# Fetch all operations
operations_df <- get_all_operations()
# Display the first few rows of the data frame
head(operations_df)Get IDP Data at Admin Level 0
The get_idp_admin0_data() function retrieves Internally
Displaced Persons (IDP) data aggregated at the country level.
# Fetch IDP data at Admin Level 0
idp_admin0_df <-
get_idp_admin0_data(CountryName = "Ethiopia",
FromRoundNumber = 0,
ToRoundNumber = 10)
# Display the first few rows of the data frame
head(idp_admin0_df)Get IDP Data at Admin Level 1
The get_idp_admin1_data() function retrieves IDP data aggregated at Admin Level 1.
# Fetch IDP data at Admin Level 1
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)Get IDP Data at Admin Level 2
The get_idp_admin2_data() function retrieves IDP data aggregated at Admin Level 2
# Fetch IDP data at Admin Level 2
idp_admin2_df <-
get_idp_admin2_data(Operation = "Displacement due to conflict",
CountryName = "Lebanon")
# Display the first few rows of the data frame
head(idp_admin2_df)Function Arguments
Here are the descriptions for the arguments used in the functions of
the dtmapi package to get IDP data. At least one of the
following parameters must be provided: Operation, CountryName, or
Admin0Pcode.
Arguments
Operation: Optional; Name of the DTM operation for which the data was collected.
CountryName: Optional; Name of the country where the data was collected.
Admin0Pcode: Optional; Country code (ISO 3166-1 alpha-3).
Admin1Name: Optional; Name of level 1 administrative boundaries.
Admin1Pcode: Optional; Place code of level 1 administrative boundaries.
Admin2Name: Optional; Name of level 2 administrative boundaries.
Admin2Pcode: Optional; Place code of level 2 administrative boundaries.
FromReportingDate: Optional; Start date for the reporting period (format: ‘YYYY-MM-DD’).
ToReportingDate: Optional; End date for the reporting period (format: ‘YYYY-MM-DD’).
FromRoundNumber: Optional; Starting round number for the data collection range.
ToRoundNumber: Optional; Ending round number for the data collection range.