From 3e2d078050f851ad3acb38fc9593e29070c745c7 Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Thu, 17 Jul 2025 15:01:04 +0100 Subject: [PATCH 01/16] Replace magrittr pipe `%>%` with the base R pipe `|>` - Note: The base / native pipe operator was introduced in the R 4.1.0 update. - Remove calls to import the magrittr library or calls to import the pipe specifically. - Replace existing magrittr pipe calls with the base R pipe. --- R/get_all_countries.R | 4 +--- R/get_all_operations.R | 4 +--- R/get_idp_admin0_data.R | 6 ++---- R/get_idp_admin1_data.R | 6 ++---- R/get_idp_admin2_data.R | 6 ++---- 5 files changed, 8 insertions(+), 18 deletions(-) diff --git a/R/get_all_countries.R b/R/get_all_countries.R index b5167b9..7f09f1c 100644 --- a/R/get_all_countries.R +++ b/R/get_all_countries.R @@ -1,6 +1,5 @@ library(httr2) library(jsonlite) -library(magrittr) # For the `%>%` operator #' Fetch All Countries #' @@ -13,7 +12,6 @@ library(magrittr) # For the `%>%` operator #' countries_df <- get_all_countries() #' head(countries_df) #' @importFrom httr2 request req_perform resp_status resp_body_string -#' @importFrom magrittr %>% #' @importFrom jsonlite fromJSON get_all_countries <- function() { @@ -22,7 +20,7 @@ get_all_countries <- function() { api_url <- "https://dtmapi.iom.int/api/Common/GetAllCountryList" # Send GET request to the API using httr2 - response <- request(api_url) %>% req_perform() + response <- request(api_url) |> req_perform() # Check if the request was successful if (resp_status(response) != 200) { diff --git a/R/get_all_operations.R b/R/get_all_operations.R index 4b64dde..d8d5e61 100644 --- a/R/get_all_operations.R +++ b/R/get_all_operations.R @@ -1,6 +1,5 @@ library(httr2) library(jsonlite) -library(magrittr) # For the `%>%` operator #' Fetch All Operations #' @@ -13,7 +12,6 @@ library(magrittr) # For the `%>%` operator #' operations_df <- get_all_operations() #' head(operations_df) #' @importFrom httr2 request req_perform resp_status resp_body_string -#' @importFrom magrittr %>% #' @importFrom jsonlite fromJSON get_all_operations <- function() { @@ -22,7 +20,7 @@ get_all_operations <- function() { api_url <- "https://dtmapi.iom.int/api/Common/GetAllOperationList" # Send GET request to the API using httr2 - response <- request(api_url) %>% req_perform() + response <- request(api_url) |> req_perform() # Check if the request was successful if (resp_status(response) != 200) { diff --git a/R/get_idp_admin0_data.R b/R/get_idp_admin0_data.R index 777fa5a..2f19edf 100644 --- a/R/get_idp_admin0_data.R +++ b/R/get_idp_admin0_data.R @@ -1,6 +1,5 @@ library(httr2) library(jsonlite) -library(magrittr) # For the `%>%` operator #' Fetch IDP Admin0 Data #' @@ -21,7 +20,6 @@ library(magrittr) # For the `%>%` operator #' idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) #' head(idp_admin0_df) #' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom magrittr %>% #' @importFrom jsonlite fromJSON get_idp_admin0_data <- function( Operation = NULL, @@ -48,8 +46,8 @@ get_idp_admin0_data <- function( tryCatch({ # Send GET request to the API with parameters using httr2 - response <- request(api_url) %>% - req_url_query(!!!params) %>% + response <- request(api_url) |> + req_url_query(!!!params) |> req_perform() # Check if the request was successful diff --git a/R/get_idp_admin1_data.R b/R/get_idp_admin1_data.R index 35e5f08..f94d190 100644 --- a/R/get_idp_admin1_data.R +++ b/R/get_idp_admin1_data.R @@ -1,6 +1,5 @@ library(httr2) library(jsonlite) -library(magrittr) # For the `%>%` operator #' Fetch IDP Admin1 Data #' @@ -23,7 +22,6 @@ library(magrittr) # For the `%>%` operator #' idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile") #' head(idp_admin1_df) #' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom magrittr %>% #' @importFrom jsonlite fromJSON get_idp_admin1_data <- function( Operation = NULL, @@ -54,8 +52,8 @@ get_idp_admin1_data <- function( tryCatch({ # Send GET request to the API with parameters using httr2 - response <- request(api_url) %>% - req_url_query(!!!params) %>% + response <- request(api_url) |> + req_url_query(!!!params) |> req_perform() # Check if the request was successful diff --git a/R/get_idp_admin2_data.R b/R/get_idp_admin2_data.R index b2749ff..3ae8fb9 100644 --- a/R/get_idp_admin2_data.R +++ b/R/get_idp_admin2_data.R @@ -1,6 +1,5 @@ library(httr2) library(jsonlite) -library(magrittr) # For the `%>%` operator #' Fetch IDP Admin2 Data #' @@ -27,7 +26,6 @@ library(magrittr) # For the `%>%` operator #' head(idp_admin2_df) #' } #' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom magrittr %>% #' @importFrom jsonlite fromJSON get_idp_admin2_data <- function( Operation = NULL, @@ -62,8 +60,8 @@ get_idp_admin2_data <- function( tryCatch({ # Send GET request to the API with parameters using httr2 - response <- request(api_url) %>% - req_url_query(!!!params) %>% + response <- request(api_url) |> + req_url_query(!!!params) |> req_perform() # Check if the request was successful From 32ced10d9698f234171b9bb053322b5612ac8eb2 Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Thu, 17 Jul 2025 16:32:20 +0100 Subject: [PATCH 02/16] Use httr2's built-in JSON parsing functions - This is as opposed to using jsonlite::fromJSON(). Using httr2::resp_body_string() and then fromJSON() is not as clean as just using httr2::resp_body_json(). httr2::resp_body_json() does uses fromJSON() under the hood. - Some comments were edited or added to reflect the changes in code, particularly regarding the use of as.data.frame() and the expectation that resp_body_json(response, simplifyVector=TRUE)$result will likely be a dataframe. --- R/get_all_countries.R | 9 ++++----- R/get_all_operations.R | 9 ++++----- R/get_idp_admin0_data.R | 9 +++------ R/get_idp_admin1_data.R | 10 ++++------ R/get_idp_admin2_data.R | 8 +++----- 5 files changed, 18 insertions(+), 27 deletions(-) diff --git a/R/get_all_countries.R b/R/get_all_countries.R index 7f09f1c..4db9ac4 100644 --- a/R/get_all_countries.R +++ b/R/get_all_countries.R @@ -1,5 +1,4 @@ library(httr2) -library(jsonlite) #' Fetch All Countries #' @@ -11,8 +10,8 @@ library(jsonlite) #' # Fetch all countries #' countries_df <- get_all_countries() #' head(countries_df) -#' @importFrom httr2 request req_perform resp_status resp_body_string -#' @importFrom jsonlite fromJSON +#' @importFrom httr2 request req_perform resp_status resp_body_json + get_all_countries <- function() { tryCatch({ @@ -28,8 +27,8 @@ get_all_countries <- function() { } # Parse the JSON content and extract the result as a data frame - data <- resp_body_string(response) - df <- fromJSON(data, flatten = TRUE)$result + json_data <- resp_body_json(response, simplifyVector = TRUE) + df <- as.data.frame(json_data$result) # as.data.frame() for consistency's sake. # Return the data frame return(df) diff --git a/R/get_all_operations.R b/R/get_all_operations.R index d8d5e61..4c03917 100644 --- a/R/get_all_operations.R +++ b/R/get_all_operations.R @@ -1,5 +1,4 @@ library(httr2) -library(jsonlite) #' Fetch All Operations #' @@ -11,8 +10,8 @@ library(jsonlite) #' # Fetch all operations #' operations_df <- get_all_operations() #' head(operations_df) -#' @importFrom httr2 request req_perform resp_status resp_body_string -#' @importFrom jsonlite fromJSON +#' @importFrom httr2 request req_perform resp_status resp_body_json + get_all_operations <- function() { tryCatch({ @@ -28,8 +27,8 @@ get_all_operations <- function() { } # Parse the JSON content and extract the result as a data frame - data <- resp_body_string(response) - df <- fromJSON(data, flatten = TRUE)$result + json_data <- resp_body_json(response, simplifyVector = TRUE) + df <- as.data.frame(json_data$result) # as.data.frame() for consistency's sake. # Return the data frame return(df) diff --git a/R/get_idp_admin0_data.R b/R/get_idp_admin0_data.R index 2f19edf..b196778 100644 --- a/R/get_idp_admin0_data.R +++ b/R/get_idp_admin0_data.R @@ -1,5 +1,4 @@ library(httr2) -library(jsonlite) #' Fetch IDP Admin0 Data #' @@ -19,8 +18,7 @@ library(jsonlite) #' # Fetch IDP data at Admin Level 0 #' idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) #' head(idp_admin0_df) -#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom jsonlite fromJSON +#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json get_idp_admin0_data <- function( Operation = NULL, CountryName = NULL, @@ -55,9 +53,8 @@ get_idp_admin0_data <- function( stop("Failed to fetch data. Status code: ", resp_status(response)) } - # Parse the JSON content - data <- resp_body_string(response, encoding = "UTF-8") - json_data <- fromJSON(data, flatten = TRUE) + # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. + json_data <- resp_body_json(response, simplifyVector = TRUE) # Check if the request was successful and extract the result if (json_data$isSuccess) { diff --git a/R/get_idp_admin1_data.R b/R/get_idp_admin1_data.R index f94d190..32215c5 100644 --- a/R/get_idp_admin1_data.R +++ b/R/get_idp_admin1_data.R @@ -1,5 +1,4 @@ library(httr2) -library(jsonlite) #' Fetch IDP Admin1 Data #' @@ -21,8 +20,8 @@ library(jsonlite) #' # Fetch IDP data at Admin Level 1 #' idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile") #' head(idp_admin1_df) -#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom jsonlite fromJSON +#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json + get_idp_admin1_data <- function( Operation = NULL, CountryName = NULL, @@ -61,9 +60,8 @@ get_idp_admin1_data <- function( stop("Failed to fetch data. Status code: ", resp_status(response)) } - # Parse the JSON content - data <- resp_body_string(response, encoding = "UTF-8") - json_data <- fromJSON(data, flatten = TRUE) + # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. + json_data <- resp_body_json(response, simplifyVector = TRUE) # Check if the request was successful and extract the result if (json_data$isSuccess) { diff --git a/R/get_idp_admin2_data.R b/R/get_idp_admin2_data.R index 3ae8fb9..4585bea 100644 --- a/R/get_idp_admin2_data.R +++ b/R/get_idp_admin2_data.R @@ -1,5 +1,4 @@ library(httr2) -library(jsonlite) #' Fetch IDP Admin2 Data #' @@ -26,7 +25,7 @@ library(jsonlite) #' head(idp_admin2_df) #' } #' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string -#' @importFrom jsonlite fromJSON + get_idp_admin2_data <- function( Operation = NULL, CountryName = NULL, @@ -69,9 +68,8 @@ get_idp_admin2_data <- function( stop("Failed to fetch data. Status code: ", resp_status(response)) } - # Parse the JSON content - data <- resp_body_string(response, encoding = "UTF-8") - json_data <- fromJSON(data, flatten = TRUE) + # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. + json_data <- resp_body_json(response, simplifyVector = TRUE) # Check if the request was successful and extract the result if (json_data$isSuccess) { From 0a20d455a7fb88588558871c7b9126e776d74ccd Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Tue, 29 Jul 2025 19:01:49 +0100 Subject: [PATCH 03/16] Refactor codebase and remove unneeded comments - The refactoring is such that the codebase becomes more in line with the tidyverse style guide. Refactor codebase and remove unneeded comments Refactor edit --- R/get_all_countries.R | 5 ----- R/get_idp_admin0_data.R | 18 ++++++++---------- R/get_idp_admin1_data.R | 12 +++--------- R/get_idp_admin2_data.R | 11 +++-------- tests/testthat/test-get_idp_admin0_data.R | 8 ++++++-- tests/testthat/test-get_idp_admin1_data.R | 7 ++++++- 6 files changed, 26 insertions(+), 35 deletions(-) diff --git a/R/get_all_countries.R b/R/get_all_countries.R index 4db9ac4..ea9ec6b 100644 --- a/R/get_all_countries.R +++ b/R/get_all_countries.R @@ -7,7 +7,6 @@ library(httr2) #' @return A data frame containing the list of all countries. #' @export #' @examples -#' # Fetch all countries #' countries_df <- get_all_countries() #' head(countries_df) #' @importFrom httr2 request req_perform resp_status resp_body_json @@ -15,10 +14,8 @@ library(httr2) get_all_countries <- function() { tryCatch({ - # Retrieve the API URL api_url <- "https://dtmapi.iom.int/api/Common/GetAllCountryList" - # Send GET request to the API using httr2 response <- request(api_url) |> req_perform() # Check if the request was successful @@ -26,11 +23,9 @@ get_all_countries <- function() { stop("Failed to fetch data. Status code: ", resp_status(response)) } - # Parse the JSON content and extract the result as a data frame json_data <- resp_body_json(response, simplifyVector = TRUE) df <- as.data.frame(json_data$result) # as.data.frame() for consistency's sake. - # Return the data frame return(df) }, error = function(e) { diff --git a/R/get_idp_admin0_data.R b/R/get_idp_admin0_data.R index b196778..8435789 100644 --- a/R/get_idp_admin0_data.R +++ b/R/get_idp_admin0_data.R @@ -16,9 +16,12 @@ library(httr2) #' @export #' @examples #' # Fetch IDP data at Admin Level 0 -#' idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) +#' idp_admin0_df <- get_idp_admin0_data(CountryName = "Ethiopia", +#' FromRoundNumber = 1, +#' ToRoundNumber = 10) #' head(idp_admin0_df) #' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json + get_idp_admin0_data <- function( Operation = NULL, CountryName = NULL, @@ -28,11 +31,9 @@ get_idp_admin0_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - # Retrieve the API URL api_url <- "https://dtmapi.iom.int/api/idpAdmin0Data/GetAdmin0Datav2" - # Set up query parameters - params <- list( + query_params <- list( Operation = Operation, CountryName = CountryName, Admin0Pcode = Admin0Pcode, @@ -43,12 +44,11 @@ get_idp_admin0_data <- function( ) tryCatch({ - # Send GET request to the API with parameters using httr2 - response <- request(api_url) |> - req_url_query(!!!params) |> + response <- + request(api_url) |> + req_url_query(!!!query_params) |> req_perform() - # Check if the request was successful if (resp_status(response) != 200) { stop("Failed to fetch data. Status code: ", resp_status(response)) } @@ -56,9 +56,7 @@ get_idp_admin0_data <- function( # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. json_data <- resp_body_json(response, simplifyVector = TRUE) - # Check if the request was successful and extract the result if (json_data$isSuccess) { - # Return the result as a data frame return(as.data.frame(json_data$result)) } else { # Handle API-specific errors diff --git a/R/get_idp_admin1_data.R b/R/get_idp_admin1_data.R index 32215c5..b0177a8 100644 --- a/R/get_idp_admin1_data.R +++ b/R/get_idp_admin1_data.R @@ -18,7 +18,7 @@ library(httr2) #' @export #' @examples #' # Fetch IDP data at Admin Level 1 -#' idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile") +#' idp_admin1_df <- get_idp_admin1_data(CountryName = "Sudan", Admin1Name = "Blue Nile") #' head(idp_admin1_df) #' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json @@ -33,11 +33,9 @@ get_idp_admin1_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - # Retrieve the API URL api_url <- "https://dtmapi.iom.int/api/idpAdmin1Data/GetAdmin1Datav2" - # Set up query parameters - params <- list( + query_params <- list( Operation = Operation, CountryName = CountryName, Admin0Pcode = Admin0Pcode, @@ -50,12 +48,10 @@ get_idp_admin1_data <- function( ) tryCatch({ - # Send GET request to the API with parameters using httr2 response <- request(api_url) |> - req_url_query(!!!params) |> + req_url_query(!!!query_params) |> req_perform() - # Check if the request was successful if (resp_status(response) != 200) { stop("Failed to fetch data. Status code: ", resp_status(response)) } @@ -63,9 +59,7 @@ get_idp_admin1_data <- function( # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. json_data <- resp_body_json(response, simplifyVector = TRUE) - # Check if the request was successful and extract the result if (json_data$isSuccess) { - # Return the result as a data frame return(as.data.frame(json_data$result)) } else { # Handle API-specific errors diff --git a/R/get_idp_admin2_data.R b/R/get_idp_admin2_data.R index 4585bea..bdf57cd 100644 --- a/R/get_idp_admin2_data.R +++ b/R/get_idp_admin2_data.R @@ -21,7 +21,7 @@ library(httr2) #' @examples #' \dontrun{ #' # Fetch IDP data at Admin Level 2 -#' idp_admin2_df <- get_idp_admin2_data(Operation='Yemen conflict', CountryName="Yemen") +#' idp_admin2_df <- get_idp_admin2_data(Operation = "Yemen conflict", CountryName = "Yemen") #' head(idp_admin2_df) #' } #' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string @@ -39,11 +39,9 @@ get_idp_admin2_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - # Retrieve the API URL api_url <- "https://dtmapi.iom.int/api/idpAdmin2Data/GetAdmin2Datav2" - # Set up query parameters - params <- list( + query_params <- list( Operation = Operation, CountryName = CountryName, Admin0Pcode = Admin0Pcode, @@ -58,9 +56,8 @@ get_idp_admin2_data <- function( ) tryCatch({ - # Send GET request to the API with parameters using httr2 response <- request(api_url) |> - req_url_query(!!!params) |> + req_url_query(!!!query_params) |> req_perform() # Check if the request was successful @@ -71,9 +68,7 @@ get_idp_admin2_data <- function( # Retrieve content as parsed JSON: simplifyVector helps to later return a dataframe. json_data <- resp_body_json(response, simplifyVector = TRUE) - # Check if the request was successful and extract the result if (json_data$isSuccess) { - # Return the result as a data frame return(as.data.frame(json_data$result)) } else { # Handle API-specific errors diff --git a/tests/testthat/test-get_idp_admin0_data.R b/tests/testthat/test-get_idp_admin0_data.R index 0b46c83..f7544ea 100644 --- a/tests/testthat/test-get_idp_admin0_data.R +++ b/tests/testthat/test-get_idp_admin0_data.R @@ -2,9 +2,13 @@ library(testthat) library(dtmapi) test_that("get_idp_admin0_data works", { - skip_on_cran() # Skip test on CRAN + skip_on_cran() + + idp_admin0_df <- + get_idp_admin0_data(CountryName = "Ethiopia", + FromRoundNumber = 1, + ToRoundNumber = 10) - idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) expect_s3_class(idp_admin0_df, "data.frame") expect_true(nrow(idp_admin0_df) > 0) }) diff --git a/tests/testthat/test-get_idp_admin1_data.R b/tests/testthat/test-get_idp_admin1_data.R index db4f615..4753bd0 100644 --- a/tests/testthat/test-get_idp_admin1_data.R +++ b/tests/testthat/test-get_idp_admin1_data.R @@ -4,7 +4,12 @@ library(dtmapi) test_that("get_idp_admin1_data works", { skip_on_cran() # Skip test on CRAN - idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile", FromReportingDate='2020-01-01', ToReportingDate='2024-08-15') + idp_admin1_df <- + get_idp_admin1_data(CountryName = "Sudan", + Admin1Name = "Blue Nile", + FromReportingDate = "2020-01-01", + ToReportingDate = "2024-08-15") + expect_s3_class(idp_admin1_df, "data.frame") expect_true(nrow(idp_admin1_df) > 0) }) From 08746bda42bda7a9dece590110a8d80cfe311037 Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Tue, 29 Jul 2025 19:14:31 +0100 Subject: [PATCH 04/16] Refactor by removing unnecessary library calls --- R/get_all_countries.R | 2 -- R/get_all_operations.R | 2 -- R/get_idp_admin2_data.R | 2 -- tests/testthat/test-get_all_countries.R | 3 --- tests/testthat/test-get_all_operations.R | 3 --- tests/testthat/test-get_idp_admin0_data.R | 3 --- tests/testthat/test-get_idp_admin1_data.R | 3 --- tests/testthat/test-get_idp_admin2_data.R | 3 --- 8 files changed, 21 deletions(-) diff --git a/R/get_all_countries.R b/R/get_all_countries.R index ea9ec6b..8cdc194 100644 --- a/R/get_all_countries.R +++ b/R/get_all_countries.R @@ -1,5 +1,3 @@ -library(httr2) - #' Fetch All Countries #' #' Retrieve all countries for which DTM data is publicly available through the API. diff --git a/R/get_all_operations.R b/R/get_all_operations.R index 4c03917..fa879dc 100644 --- a/R/get_all_operations.R +++ b/R/get_all_operations.R @@ -1,5 +1,3 @@ -library(httr2) - #' Fetch All Operations #' #' Retrieve all operations for which DTM data is publicly available through the API. diff --git a/R/get_idp_admin2_data.R b/R/get_idp_admin2_data.R index bdf57cd..41789dd 100644 --- a/R/get_idp_admin2_data.R +++ b/R/get_idp_admin2_data.R @@ -1,5 +1,3 @@ -library(httr2) - #' Fetch IDP Admin2 Data #' #' Retrieve IDP data at Admin 2 level based on specified parameters. diff --git a/tests/testthat/test-get_all_countries.R b/tests/testthat/test-get_all_countries.R index 2c47321..0bfd464 100644 --- a/tests/testthat/test-get_all_countries.R +++ b/tests/testthat/test-get_all_countries.R @@ -1,6 +1,3 @@ -library(testthat) -library(dtmapi) - test_that("get_all_countries works", { skip_on_cran() # Skip test on CRAN diff --git a/tests/testthat/test-get_all_operations.R b/tests/testthat/test-get_all_operations.R index 222cbf2..660a6e2 100644 --- a/tests/testthat/test-get_all_operations.R +++ b/tests/testthat/test-get_all_operations.R @@ -1,6 +1,3 @@ -library(testthat) -library(dtmapi) - test_that("get_all_operations works", { skip_on_cran() # Skip test on CRAN diff --git a/tests/testthat/test-get_idp_admin0_data.R b/tests/testthat/test-get_idp_admin0_data.R index f7544ea..ad214fc 100644 --- a/tests/testthat/test-get_idp_admin0_data.R +++ b/tests/testthat/test-get_idp_admin0_data.R @@ -1,6 +1,3 @@ -library(testthat) -library(dtmapi) - test_that("get_idp_admin0_data works", { skip_on_cran() diff --git a/tests/testthat/test-get_idp_admin1_data.R b/tests/testthat/test-get_idp_admin1_data.R index 4753bd0..0ccdb03 100644 --- a/tests/testthat/test-get_idp_admin1_data.R +++ b/tests/testthat/test-get_idp_admin1_data.R @@ -1,6 +1,3 @@ -library(testthat) -library(dtmapi) - test_that("get_idp_admin1_data works", { skip_on_cran() # Skip test on CRAN diff --git a/tests/testthat/test-get_idp_admin2_data.R b/tests/testthat/test-get_idp_admin2_data.R index 26d3f01..ba33c99 100644 --- a/tests/testthat/test-get_idp_admin2_data.R +++ b/tests/testthat/test-get_idp_admin2_data.R @@ -1,6 +1,3 @@ -library(testthat) -library(dtmapi) - test_that("get_idp_admin2_data works", { skip_on_cran() # Skip test on CRAN From 3bff599af08008c7b4ba73dffc620905889e2c57 Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Tue, 29 Jul 2025 18:13:53 +0100 Subject: [PATCH 05/16] Add .Renviron to .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index c48f0ba..c22afd6 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ inst/doc /doc/ /Meta/ +.Renviron \ No newline at end of file From 0f0b1db14e09c2bceea7743c6e73cb940ef3cadd Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Tue, 29 Jul 2025 20:57:01 +0100 Subject: [PATCH 06/16] Add .Rhistory to .gitignore and delete .Rhistory --- .Rhistory | 498 ----------------------------------------------------- .gitignore | 3 +- 2 files changed, 2 insertions(+), 499 deletions(-) delete mode 100644 .Rhistory diff --git a/.Rhistory b/.Rhistory deleted file mode 100644 index 6e55fed..0000000 --- a/.Rhistory +++ /dev/null @@ -1,498 +0,0 @@ -hello <- function() { -print("Hello, world!") -} -hello() -View(hello) -get_all_countries() -get_all_countries() -df = get_all_countries() -df = get_all_countries() -View(df) -operations = get_all_operations() -library(dtmapi) -operations = get_all_operations() -operations = get_all_operations() -devtools::build() -devtools::check() -operations = get_all_operations() -View(operations) -devtools::load_all(".") -devtools::load_all(".") -devtools::load_all(".") -check() -library(devtools) -check() -devtools::load_all(".") ---- -title: "dtmapi document" -knitr::opts_chunk$set( -collapse = TRUE, -comment = "#>" -) -knitr::opts_chunk$set( -collapse = TRUE, -comment = "#>" -) -plot(1:10) -plot(10:1) -knitr::kable(head(mtcars, 10)) -knitr::opts_chunk$set( -collapse = TRUE, -comment = "#>" -) -plot(1:10) -plot(10:1) -knitr::kable(head(mtcars, 10)) -devtools::check() -devtools::build() -data = get_idp_admin0_data(CountryName = "Ethiopia") -View(data) -data = get_idp_admin0_data() -devtools::check() -devtools::build() -lt = get_idp_admin1_data() -lt = get_idp_admin1_data(Admin0Pcode = "ETH") -View(lt) -View(lt) -devtools::check() -devtools::build() -df = get_idp_admin2_data(Admin0Pcode = "ETH") -View(df) -df = get_idp_admin2_data(Admin0Pcode = "ETH", FromRoundNumber = "2", ToRoundNumber = "2") -nn = get_all_countries() -View(nn) -kj = get_all_operations() -View(kj) -library(roxygen2) -roxygen2::roxygenise() -devtools::document() -?get_all_countries -?get_all_operations -?get_all_countries -?get_idp_admin0_data -?get_idp_admin1_data -?get_idp_admin2_data -devtools::check() -devtools::build() -get_all_countries() -install.packages("config") -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -library(dtmapi) -get_all_countries() -devtools::load_all(".") -get_all_countries() -library(dtmapi) -get_all_countries() -get_all_countries() -get_all_countries() -exit -clear -get_all_countries() -devtools::load_all(".") -get_all_countries() -devtools::load_all(".") -get_all_countries() -devtools::load_all(".") -get_all_countries() -devtools::check() -get_all_countries() -getdy = get_idp_admin0_data() -getdy = get_idp_admin0_data(CountryName = "Sudan") -View(getdy) -devtools::check() -devtools::check() -getdy = get_idp_admin0_data(CountryName = "Sudan") -View(getdy) -getdy = get_idp_admin0_data(CountryName = "Sudan") -devtools::check() -getdy = get_idp_admin0_data(CountryName = "Sudan") -View(getdy) -t = get_all_countries() -View(t) -?get_all_countries -?get_idp_admin0_data -?get_idp_admin0_data -?get_idp_admin0_data -devtools::document() -?get_idp_admin0_data -devtools::document() -?get_idp_admin0_data -?get_idp_admin0_data -?get_idp_admin0_data -devtools::document() -?get_idp_admin0_data -devtools::document() -?get_idp_admin1_data -devtools::load_all(".") -devtools::check() -devtools::build() -R CMD check --as-cran . -check --as-cran . -CMD check --as-cran . -R -devtools::check() -devtools::build() -devtools::check() -devtools::build() -g = get_idp_admin2_data() -g = get_idp_admin2_data(CountryName = "Ethiopia") -g -devtools::check() -devtools::check() -devtools::use_vignette("introduction") -install.packages("usethis") -library(usethis) -devtools::use_vignette("introduction") -library(usethis) -library(usethis) -usethis::use_vignette("introduction") -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::check() -get_all_countries() -get_all_operations() -get_idp_admin0_data(Admin0Pcode = "AFG") -get_idp_admin1_data(Admin0Pcode = "ETH") -get_idp_admin2_data(Admin0Pcode = "ETH") -install.packages("testthat") -library(testthat) -test_dir("tests/testthat") -devtools::test() -devtools::document() -devtools::document() -devtools::document() -? get_all_operations -?get_idp_admin0_data -?get_idp_admin0_data -devtools::document() -?get_idp_admin2_data -devtools::build_vignettes() -devtools::build_vignettes() -?get_idp_admin0_data -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::document() -?get_all_countries -abc = get_all_countries() -View(abc) -devtools::build() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -library(dtmapi) -install.packages("devtools") -devtools::install_github("Displacement-Tracking-Matrix/dtmapi-R") -devtools::install_github("Displacement-Tracking-Matrix/dtmapi-R") -devtools::install_github("Displacement-Tracking-Matrix/dtmapi-R") -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -install.packages("tinytex") -tinytex::install_tinytex() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::build() -devtools::check() -# Install released version from CRAN -install.packages("pkgdown") -install.packages("pkgdown") -getwd() -install.packages("pkgdown") -install.packages("devtools") -library(dtmapi) -get_all_countries() -install.packages("devtools") -install.packages("pkgdown") -git push --force -devtools::build_vignettes() -devtools::check() -pkgdown::build_site() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -devtools::build() -pkgdown::build_site() -devtools::check() -devtools::build() -devtools::check() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::check() -devtools::check() -devtools::build_vignettes() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -pkgdown::build_site() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -devtools::check() -pkgdown::build_site() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -devtools::check() -devtools::check() -devtools::build_vignettes() -pkgdown::build_site() -pkgdown::build_site() -pkgdown::build_site() -library(dtmapi) -install.packages("dtmapi") -pkgdown::build_site() -pkgdown::build_site() -pkgdown::build_site() -pkgdown::build_site() -pkgdown::build_site() -devtools::build_vignettes() -devtools::check() -library(dtmapi) -abc <- get_idp_admin0_data(Operation = "abc") -#' @param ToRoundNumber Optional; Ending round number for the data collection range. -#' @return A data frame containing the IDP Admin0 data matching the specified criteria. -#' @export -#' @examples -#' # Fetch IDP data at Admin Level 0 -#' idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) -#' head(idp_admin0_df) -#' @importFrom httr GET status_code content -#' @importFrom jsonlite fromJSON -#' @importFrom config get -get_idp_admin0_data <- function( -Operation = NULL, -CountryName = NULL, -Admin0Pcode = NULL, -FromReportingDate = NULL, -ToReportingDate = NULL, -FromRoundNumber = 0, -ToRoundNumber = 0 -) { -# Retrieve the API URL from the configuration file -# Load configuration -api_url <- "https://dtmapi.iom.int/api/idpAdmin0Data/GetAdmin0Datav2" -# Set up query parameters -params <- list( -Operation = Operation, -CountryName = CountryName, -Admin0Pcode = Admin0Pcode, -FromReportingDate = FromReportingDate, -ToReportingDate = ToReportingDate, -FromRoundNumber = FromRoundNumber, -ToRoundNumber = ToRoundNumber -) -tryCatch({ -# Send GET request to the API with parameters -response <- GET(api_url, query = params) -# Check if the request was successful -if (status_code(response) != 200) { -stop("Failed to fetch data. Status code: ", status_code(response)) -} -# Parse the JSON content -data <- content(response, "text", encoding = "UTF-8") -json_data <- fromJSON(data, flatten = TRUE) -# Check if the request was successful and extract the result -if (json_data$isSuccess) { -# Return the result as a data frame -return(as.data.frame(json_data$result)) -} else { -# Handle API-specific errors -stop("API error: ", json_data$errorMessages[1]) -} -}, error = function(e) { -# Handle and report errors -stop("API request failed: ", e$message) -}) -} -@importFrom config get -#' -#' @return A data frame containing the list of all countries. -#' @export -#' @examples -#' # Fetch all countries -#' countries_df <- get_all_countries() -#' head(countries_df) -#' @importFrom httr GET status_code content -#' @importFrom jsonlite fromJSON -#' @importFrom config get -get_all_countries <- function() { -tryCatch({ -# Retrieve the API URL from the configuration file -api_url <- "https://dtmapi.iom.int/api/Common/GetAllCountryList" -# Send GET request to the API -response <- GET(api_url) -# Check if the request was successful -if (status_code(response) != 200) { -stop("Failed to fetch data. Status code: ", status_code(response)) -} -# Parse the JSON content and extract the result as a data frame -data <- content(response, "text") -df <- fromJSON(data, flatten = TRUE)$result -# Return the data frame -return(df) -}, error = function(e) { -# Handle and report errors -stop("API request failed: ", e$message) -}) -} -abc <- get_idp_admin0_data(Operation = "abc") -abc <- get_idp_admin0_data(CountryName = ) -abc <- get_idp_admin0_data(CountryName = "Ethiopia", FromRoundNumber = 7, ToRoundNumber = 5) -remove.packages("dtmapi") -library(dtmapi) -get_all_countries() -library(dtmapi) -get_all_countries() -remove.packages("dtmapi") -devtools::check() -devtools::check() -devtools::check() -install.packages("httr2") -devtools::check() -devtools::build_vignettes() -devtools::build() -install.packages("magrittr") -install.packages("dplyr") -devtools::build() -install.packages("magrittr") -install.packages("dplyr") -devtools::build() -devtools::build() -install.packages("magrittr") -install.packages("dplyr") -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -install.packages("httr2") -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build() -devtools::install("/Users/bangtranl/Work/dtmapi-r/dtmapi_0.0.1.tar.gz") -library(dtmapi) -install.packages("/Users/bangtranl/Work/dtmapi-r/dtmapi_0.0.1.tar.gz", repos = NULL, type = "source") -library(dtmapi) -abc = get_all_countries() -install.packages("/Users/bangtranl/Work/dtmapi-r/dtmapi_0.0.1.tar.gz") -library(dtmapi) -abc = get_all_countries() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::check() -devtools::build() -install.packages("/Users/bangtranl/Work/dtmapi-r/dtmapi_0.0.1.tar.gz") -library(dtmapi) -abc = get_all_countries() -abc -a = get_idp_admin0_data(CountryName = "Ehiopia") -a = get_idp_admin0_data(CountryName = "Ethiopia") -a -a = get_idp_admin1_data(CountryName = "Ethiopia") -View(a) -a = get_idp_admin2_data(CountryName = "Ethiopia", FromRoundNumber = 1, ToRoundNumber = 2) -pkgdown::build_site() -pkgdown::build_site() -devtools::build_vignettes() -pkgdown::build_site() -devtools::check() -devtools::check() -devtools::build() -pkgdown::build_site() -devtools::build_vignettes() -pkgdown::build_site() -git status -devtools::build() -devtools::build() -devtools::check() -devtools::check() -devtools::build() -devtools::check() -devtools::build() -devtools::check() -devtools::document() -devtools::build() -devtools::check() -devtools::document() -devtools::document() -devtools::build_vignettes() -devtools::build() -devtools::check() -devtools::document() -devtools::build_vignettes() -devtools::build_vignettes() -devtools::build() -devtools::check() -unlink("doc", recursive = TRUE) # Delete old doc/ folder -unlink("vignettes/*.html") # Remove old vignette HTML files -unlink("vignettes/*.R") # Remove old vignette R scripts -devtools::build_vignettes() -vignette(package = "dtmapi") -devtools::document() -devtools::build_vignettes() -devtools::check() -devtools::document() -devtools::build_vignettes() -devtools::build() -devtools::check() -devtools::check() -pkgdown::build_site() -devtools::build() -devtools::release() -devtools::release() -check_rhub() -devtools::check_rhub() -devtools::check_rhub() -devtools::check_rhubv2() -devtools::check() -devtools::release() -use_cran_comments() -usethis::use_cran_comments() -usethis::use_cran_comments() -devtools::submit_cran() -git status diff --git a/.gitignore b/.gitignore index c22afd6..f234b92 100644 --- a/.gitignore +++ b/.gitignore @@ -2,4 +2,5 @@ inst/doc /doc/ /Meta/ -.Renviron \ No newline at end of file +.Renviron +.Rhistory \ No newline at end of file From 01cb8e7f77a19dc98e08936a7dbb6dd90e406cf5 Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Tue, 29 Jul 2025 20:14:36 +0100 Subject: [PATCH 07/16] =?UTF-8?q?API=20V3=20update=E2=80=94subscription=20?= =?UTF-8?q?keys=20and=20new=20endpoints?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change version from 0.0.3 to 0.1.0 --- DESCRIPTION | 15 ++++---- NAMESPACE | 7 ++-- R/get_all_countries.R | 11 ++++-- R/get_all_operations.R | 13 ++++--- R/get_idp_admin0_data.R | 11 +++--- R/get_idp_admin1_data.R | 12 +++++-- R/get_idp_admin2_data.R | 10 ++++-- R/get_subscription_key.R | 42 ++++++++++++++++++++++ R/set_subscription_key.R | 25 +++++++++++++ man/get_all_countries.Rd | 2 -- man/get_all_operations.Rd | 2 -- man/get_idp_admin0_data.Rd | 4 +-- man/get_idp_admin1_data.Rd | 2 -- man/get_idp_admin2_data.Rd | 2 +- tests/testthat/test-set_subscription_key.R | 15 ++++++++ 15 files changed, 136 insertions(+), 37 deletions(-) create mode 100644 R/get_subscription_key.R create mode 100644 R/set_subscription_key.R create mode 100644 tests/testthat/test-set_subscription_key.R diff --git a/DESCRIPTION b/DESCRIPTION index eb1d067..a4c416a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,8 +1,10 @@ Package: dtmapi Title: Fetching Data from the 'Displacement Tracking Matrix' -Version: 0.0.3 -Authors@R: - person("Luong Bang", "Tran", email = "lutran@iom.int", role = c("aut", "cre")) +Version: 0.1.0 +Authors@R: c( + person("Luong Bang", "Tran", email = "lutran@iom.int", role = c("aut", "cre")), + person("Assad", "Asil Companioni", email = "aasil@iom.int", role = c("aut")) + ) Description: Allows humanitarian community, academia, media, government, and non-governmental organizations to utilize the data collected by the 'Displacement Tracking Matrix' (), a unit in the International Organization for Migration. This also provides non-sensitive Internally Displaced Person figures, aggregated at the country, Admin 1 (states, provinces, or equivalent), and Admin 2 (smaller administrative areas) levels. URL: https://github.com/Displacement-Tracking-Matrix/dtmapi-R, https://displacement-tracking-matrix.github.io/dtmapi-R/ License: MIT + file LICENSE @@ -11,10 +13,9 @@ Roxygen: list(markdown = TRUE) RoxygenNote: 7.3.2 Imports: httr2, - jsonlite, - magrittr + testthat (>= 3.1.0), + askpass Suggests: knitr, - rmarkdown, - testthat (>= 3.1.0) + rmarkdown VignetteBuilder: knitr diff --git a/NAMESPACE b/NAMESPACE index f70c760..d1cbe5a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -5,10 +5,13 @@ export(get_all_operations) export(get_idp_admin0_data) export(get_idp_admin1_data) export(get_idp_admin2_data) +export(get_subscription_key) +export(set_subscription_key) +importFrom(askpass,askpass) importFrom(httr2,req_perform) importFrom(httr2,req_url_query) importFrom(httr2,request) +importFrom(httr2,resp_body_json) importFrom(httr2,resp_body_string) importFrom(httr2,resp_status) -importFrom(jsonlite,fromJSON) -importFrom(magrittr,"%>%") +importFrom(httr2,secret_decrypt) diff --git a/R/get_all_countries.R b/R/get_all_countries.R index 8cdc194..c190a5d 100644 --- a/R/get_all_countries.R +++ b/R/get_all_countries.R @@ -7,14 +7,19 @@ #' @examples #' countries_df <- get_all_countries() #' head(countries_df) -#' @importFrom httr2 request req_perform resp_status resp_body_json +#' @importFrom httr2 request req_perform resp_status resp_body_json req_headers_redacted get_all_countries <- function() { tryCatch({ - api_url <- "https://dtmapi.iom.int/api/Common/GetAllCountryList" + api_url <- "https://dtm-apim.iom.int/v3/CountryList" - response <- request(api_url) |> req_perform() + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> + req_perform() # Check if the request was successful if (resp_status(response) != 200) { diff --git a/R/get_all_operations.R b/R/get_all_operations.R index fa879dc..0c06ddd 100644 --- a/R/get_all_operations.R +++ b/R/get_all_operations.R @@ -8,16 +8,19 @@ #' # Fetch all operations #' operations_df <- get_all_operations() #' head(operations_df) -#' @importFrom httr2 request req_perform resp_status resp_body_json +#' @importFrom httr2 request req_perform resp_status resp_body_json req_headers_redacted get_all_operations <- function() { tryCatch({ - # Load configuration - api_url <- "https://dtmapi.iom.int/api/Common/GetAllOperationList" + api_url <- "https://dtm-apim.iom.int/v3/OperationList" - # Send GET request to the API using httr2 - response <- request(api_url) |> req_perform() + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> + req_perform() # Check if the request was successful if (resp_status(response) != 200) { diff --git a/R/get_idp_admin0_data.R b/R/get_idp_admin0_data.R index 8435789..2f9cb5f 100644 --- a/R/get_idp_admin0_data.R +++ b/R/get_idp_admin0_data.R @@ -1,5 +1,3 @@ -library(httr2) - #' Fetch IDP Admin0 Data #' #' Retrieve IDP data at Admin 0 level based on specified parameters. @@ -15,12 +13,14 @@ library(httr2) #' @return A data frame containing the IDP Admin0 data matching the specified criteria. #' @export #' @examples +#' \dontrun{ #' # Fetch IDP data at Admin Level 0 #' idp_admin0_df <- get_idp_admin0_data(CountryName = "Ethiopia", #' FromRoundNumber = 1, #' ToRoundNumber = 10) #' head(idp_admin0_df) -#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json +#' } +#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json req_headers_redacted get_idp_admin0_data <- function( Operation = NULL, @@ -31,7 +31,7 @@ get_idp_admin0_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - api_url <- "https://dtmapi.iom.int/api/idpAdmin0Data/GetAdmin0Datav2" + api_url <- "https://dtm-apim.iom.int/v3/IdpAdmin0Data" query_params <- list( Operation = Operation, @@ -46,6 +46,9 @@ get_idp_admin0_data <- function( tryCatch({ response <- request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> req_url_query(!!!query_params) |> req_perform() diff --git a/R/get_idp_admin1_data.R b/R/get_idp_admin1_data.R index b0177a8..f249b69 100644 --- a/R/get_idp_admin1_data.R +++ b/R/get_idp_admin1_data.R @@ -17,10 +17,12 @@ library(httr2) #' @return A data frame containing the IDP Admin1 data matching the specified criteria. #' @export #' @examples +#' \dontrun{ #' # Fetch IDP data at Admin Level 1 #' idp_admin1_df <- get_idp_admin1_data(CountryName = "Sudan", Admin1Name = "Blue Nile") #' head(idp_admin1_df) -#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json +#' } +#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_json req_headers_redacted get_idp_admin1_data <- function( Operation = NULL, @@ -33,7 +35,7 @@ get_idp_admin1_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - api_url <- "https://dtmapi.iom.int/api/idpAdmin1Data/GetAdmin1Datav2" + api_url <- "https://dtm-apim.iom.int/v3/IdpAdmin1Data" query_params <- list( Operation = Operation, @@ -48,7 +50,11 @@ get_idp_admin1_data <- function( ) tryCatch({ - response <- request(api_url) |> + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> req_url_query(!!!query_params) |> req_perform() diff --git a/R/get_idp_admin2_data.R b/R/get_idp_admin2_data.R index 41789dd..9c653fa 100644 --- a/R/get_idp_admin2_data.R +++ b/R/get_idp_admin2_data.R @@ -22,7 +22,7 @@ #' idp_admin2_df <- get_idp_admin2_data(Operation = "Yemen conflict", CountryName = "Yemen") #' head(idp_admin2_df) #' } -#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string +#' @importFrom httr2 request req_perform req_url_query resp_status resp_body_string req_headers_redacted get_idp_admin2_data <- function( Operation = NULL, @@ -37,7 +37,7 @@ get_idp_admin2_data <- function( FromRoundNumber = 0, ToRoundNumber = 0 ) { - api_url <- "https://dtmapi.iom.int/api/idpAdmin2Data/GetAdmin2Datav2" + api_url <- "https://dtm-apim.iom.int/v3/IdpAdmin2Data" query_params <- list( Operation = Operation, @@ -54,7 +54,11 @@ get_idp_admin2_data <- function( ) tryCatch({ - response <- request(api_url) |> + response <- + request(api_url) |> + req_headers_redacted("Cache-Control" = "no-cache", + "Ocp-Apim-Subscription-Key" = get_subscription_key() + ) |> req_url_query(!!!query_params) |> req_perform() diff --git a/R/get_subscription_key.R b/R/get_subscription_key.R new file mode 100644 index 0000000..36d2272 --- /dev/null +++ b/R/get_subscription_key.R @@ -0,0 +1,42 @@ +#' Retrieval of an API subscription key from the environment. +#' +#' The DTM API subscription key is returned, provided that it is available in +#' the R session as an environment variable. Users will usually need to set +#' the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file or +#' by calling `set_subscription_key()`. +#' +#' On the other hand, if the TESTTHAT environment variable is true, indicating +#' that unit tests are being run by the package maintainers, then the +#' subscription key is returned through different means. +#' @return A string representing a given subscription key for the DTM API. +#' @export +#' @examples +#' # Generally, calling set_subscription_key() without the key as an argument is best, +#' # as the user can then be prompted to input the key without typing it directly +#' # into the console, making it more secure and less likely to exposed. +#' set_subscription_key() +#' @importFrom httr2 secret_decrypt +#' @importFrom testthat is_testing +get_subscription_key <- function() { + key <- Sys.getenv("DTM_SUBSCRIPTION_KEY") + if (!identical(key, "")) { + return(key) + } + + if (is_testing()) { + return(testing_key()) + } else { + stop( + paste("No API key found, please supply with set_subscription_key() or", + "otherwise specifying the DTM_SUBSCRIPTION_KEY environment variable.") + ) + } +} + +testing_key_encrypted <- "gs-XVH-qdoewh5zjCEMPXrrrKDHqs5L-3X43yAPEY0rqBcwEGa2p_mTo89Ki5HqZ" + +testing_key <- function() { + secret_decrypt(encrypted = testing_key_encrypted, + key = "DTMAPIR_KEY" # Environment variable name as a string + ) +} \ No newline at end of file diff --git a/R/set_subscription_key.R b/R/set_subscription_key.R new file mode 100644 index 0000000..a1fbde5 --- /dev/null +++ b/R/set_subscription_key.R @@ -0,0 +1,25 @@ +#' Set the user's API subscription key in order to make the API calls. +#' +#' The API will be stored as an environmental variable named "DTM_API_KEY". +#' @param key +#' Either NULL or a string representing the key. NULL is preferable: using it +#' will prompt the user to type the subscription key in a graphical user +#' interface that masks it. +#' @return Nothing. Creates / overwrites an environmental variable as a side effect. +#' @export +#' @examples +#' \dontrun{ +#' # Generally, calling set_subscription_key() without the key as an argument is best, +#' # as the user can then be prompted to input the key without typing it directly +#' # into the console, making it more secure and less likely to exposed. +#' set_subscription_key() +#' } +#' @importFrom askpass askpass + +set_subscription_key <- function(key = NULL) { + if (is.null(key)) { + Sys.setenv("DTM_SUBSCRIPTION_KEY" = askpass("Please enter your subscription key.")) + } else { + Sys.setenv("DTM_SUBSCRIPTION_KEY" = key) + } +} \ No newline at end of file diff --git a/man/get_all_countries.Rd b/man/get_all_countries.Rd index e27924a..8b67d11 100644 --- a/man/get_all_countries.Rd +++ b/man/get_all_countries.Rd @@ -13,9 +13,7 @@ A data frame containing the list of all countries. Retrieve all countries for which DTM data is publicly available through the API. } \examples{ -\dontrun{ # Fetch all countries countries_df <- get_all_countries() head(countries_df) } -} diff --git a/man/get_all_operations.Rd b/man/get_all_operations.Rd index 8fd3d21..53ff244 100644 --- a/man/get_all_operations.Rd +++ b/man/get_all_operations.Rd @@ -13,9 +13,7 @@ A data frame containing the list of all operations. Retrieve all operations for which DTM data is publicly available through the API. } \examples{ -\dontrun{ # Fetch all operations operations_df <- get_all_operations() head(operations_df) } -} diff --git a/man/get_idp_admin0_data.Rd b/man/get_idp_admin0_data.Rd index 3175e43..6801168 100644 --- a/man/get_idp_admin0_data.Rd +++ b/man/get_idp_admin0_data.Rd @@ -37,9 +37,7 @@ Retrieve IDP data at Admin 0 level based on specified parameters. At least one of the following parameters must be provided: Operation, CountryName, or Admin0Pcode. } \examples{ -\dontrun{ # Fetch IDP data at Admin Level 0 -idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) +idp_admin0_df <- get_idp_admin0_data(CountryName = "Ethiopia", FromRoundNumber = 1, ToRoundNumber = 10) head(idp_admin0_df) } -} diff --git a/man/get_idp_admin1_data.Rd b/man/get_idp_admin1_data.Rd index 2b962d5..1dcfee5 100644 --- a/man/get_idp_admin1_data.Rd +++ b/man/get_idp_admin1_data.Rd @@ -43,9 +43,7 @@ Retrieve IDP data at Admin 1 level based on specified parameters. At least one of the following parameters must be provided: Operation, CountryName, or Admin0Pcode. } \examples{ -\dontrun{ # Fetch IDP data at Admin Level 1 idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile") head(idp_admin1_df) } -} diff --git a/man/get_idp_admin2_data.Rd b/man/get_idp_admin2_data.Rd index b1abedb..b2bc372 100644 --- a/man/get_idp_admin2_data.Rd +++ b/man/get_idp_admin2_data.Rd @@ -51,7 +51,7 @@ At least one of the following parameters must be provided: Operation, CountryNam \examples{ \dontrun{ # Fetch IDP data at Admin Level 2 -idp_admin2_df <- get_idp_admin2_data(Operation='Yemen conflict', CountryName="Yemen") +idp_admin2_df <- get_idp_admin2_data(Operation = "Yemen conflict", CountryName = "Yemen") head(idp_admin2_df) } } diff --git a/tests/testthat/test-set_subscription_key.R b/tests/testthat/test-set_subscription_key.R new file mode 100644 index 0000000..f489883 --- /dev/null +++ b/tests/testthat/test-set_subscription_key.R @@ -0,0 +1,15 @@ +test_that("DTM API subscription key set as environmental variable.", { + skip_on_cran() + + env_var_before_call <- Sys.getenv()["DTM_SUBSCRIPTION_KEY"] |> as.vector() + + subscription_key_input <- "dummyValue" + set_subscription_key(key = subscription_key_input) + + # as.vector() is used to remove all attributes including names. + env_var_after_call <- Sys.getenv()["DTM_SUBSCRIPTION_KEY"] |> as.vector() + # Restore old env variable value to what it was before the function was tested. + Sys.setenv("DTM_SUBSCRIPTION_KEY" = env_var_before_call) + + expect_true(env_var_after_call == subscription_key_input) +}) From a5c116dcb852d817f99af74d45b6f72e026cded2 Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Tue, 29 Jul 2025 21:49:18 +0100 Subject: [PATCH 08/16] Use \dontrun in light of subscription key requirement add dontrun --- R/get_all_countries.R | 2 ++ R/get_all_operations.R | 2 ++ R/get_idp_admin1_data.R | 2 -- R/get_subscription_key.R | 2 ++ 4 files changed, 6 insertions(+), 2 deletions(-) diff --git a/R/get_all_countries.R b/R/get_all_countries.R index c190a5d..a1338d6 100644 --- a/R/get_all_countries.R +++ b/R/get_all_countries.R @@ -5,8 +5,10 @@ #' @return A data frame containing the list of all countries. #' @export #' @examples +#' \dontrun{ #' countries_df <- get_all_countries() #' head(countries_df) +#' } #' @importFrom httr2 request req_perform resp_status resp_body_json req_headers_redacted get_all_countries <- function() { diff --git a/R/get_all_operations.R b/R/get_all_operations.R index 0c06ddd..9db8310 100644 --- a/R/get_all_operations.R +++ b/R/get_all_operations.R @@ -5,9 +5,11 @@ #' @return A data frame containing the list of all operations. #' @export #' @examples +#' \dontrun{ #' # Fetch all operations #' operations_df <- get_all_operations() #' head(operations_df) +#' } #' @importFrom httr2 request req_perform resp_status resp_body_json req_headers_redacted get_all_operations <- function() { diff --git a/R/get_idp_admin1_data.R b/R/get_idp_admin1_data.R index f249b69..fd959ab 100644 --- a/R/get_idp_admin1_data.R +++ b/R/get_idp_admin1_data.R @@ -1,5 +1,3 @@ -library(httr2) - #' Fetch IDP Admin1 Data #' #' Retrieve IDP data at Admin 1 level based on specified parameters. diff --git a/R/get_subscription_key.R b/R/get_subscription_key.R index 36d2272..833c178 100644 --- a/R/get_subscription_key.R +++ b/R/get_subscription_key.R @@ -11,10 +11,12 @@ #' @return A string representing a given subscription key for the DTM API. #' @export #' @examples +#' \dontrun{ #' # Generally, calling set_subscription_key() without the key as an argument is best, #' # as the user can then be prompted to input the key without typing it directly #' # into the console, making it more secure and less likely to exposed. #' set_subscription_key() +#' } #' @importFrom httr2 secret_decrypt #' @importFrom testthat is_testing get_subscription_key <- function() { From 683a9f34b999c9f963bfedb330fe9ec4bafe7445 Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Wed, 30 Jul 2025 09:26:56 +0100 Subject: [PATCH 09/16] Use withr for set_subscription_key test withr is an R library that allows changes to state to be reverted and managed cleanly. Add withr package to DESCRIPTION file --- DESCRIPTION | 3 ++- tests/testthat/test-set_subscription_key.R | 13 +++---------- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index a4c416a..af4b884 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -17,5 +17,6 @@ Imports: askpass Suggests: knitr, - rmarkdown + rmarkdown, + withr VignetteBuilder: knitr diff --git a/tests/testthat/test-set_subscription_key.R b/tests/testthat/test-set_subscription_key.R index f489883..d8c4868 100644 --- a/tests/testthat/test-set_subscription_key.R +++ b/tests/testthat/test-set_subscription_key.R @@ -1,15 +1,8 @@ -test_that("DTM API subscription key set as environmental variable.", { +test_that("DTM API subscription key environment variable is changed.", { skip_on_cran() - env_var_before_call <- Sys.getenv()["DTM_SUBSCRIPTION_KEY"] |> as.vector() - + withr::local_envvar(DTM_SUBSCRIPTION_KEY = Sys.getenv("DTM_SUBSCRIPTION_KEY")) subscription_key_input <- "dummyValue" set_subscription_key(key = subscription_key_input) - - # as.vector() is used to remove all attributes including names. - env_var_after_call <- Sys.getenv()["DTM_SUBSCRIPTION_KEY"] |> as.vector() - # Restore old env variable value to what it was before the function was tested. - Sys.setenv("DTM_SUBSCRIPTION_KEY" = env_var_before_call) - - expect_true(env_var_after_call == subscription_key_input) + expect_equal(Sys.getenv("DTM_SUBSCRIPTION_KEY"), subscription_key_input) }) From 5f031fb65916c5763a713ed624cd750d85efee3d Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Wed, 30 Jul 2025 00:43:16 +0100 Subject: [PATCH 10/16] Edit vignette and disable code evaluation due to reliance on API key --- vignettes/.gitignore | 2 ++ vignettes/introduction.Rmd | 47 ++++++++++++++++++++++++++++++-------- 2 files changed, 39 insertions(+), 10 deletions(-) diff --git a/vignettes/.gitignore b/vignettes/.gitignore index 097b241..9e2bd63 100644 --- a/vignettes/.gitignore +++ b/vignettes/.gitignore @@ -1,2 +1,4 @@ *.html *.R + +/.quarto/ diff --git a/vignettes/introduction.Rmd b/vignettes/introduction.Rmd index 9ce40b5..1fd4efc 100644 --- a/vignettes/introduction.Rmd +++ b/vignettes/introduction.Rmd @@ -12,7 +12,6 @@ knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) -library(httr2) ``` ## Introduction @@ -29,26 +28,54 @@ The `dtmapi` package provides functions to interact with the Displacement Trac - `get_idp_admin2_data()` - ## Install Package -The `dtmapi` package is available on CRAN and can be installed using the following command: : -```{r install , eval = FALSE} +The `dtmapi` package is available on CRAN and can be installed using the following command: +```{r install, eval = FALSE} install.packages("dtmapi") ``` ## Load Package After installation, load the package using library(): -```{r setup} +```{r setup, eval = FALSE} library(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. There are two main ways to do this. + +1. By calling `set_subscription_key()` and then typing in the key. + +The user will be prompted to input the key into a pop-up field. +```{r set_subscription_key_demo, eval = FALSE} +set_subscription_key() +``` + +2. By setting up the environment variable directly. + +If one would like to avoid re-inputting the subscription key for each R session, +an alternative approach is to create the environment variable +`DTM_SUBSCRIPTION_KEY`, with the subscription key as its value. Ideally, this +should be (a) done in a *.Renviron* file, and (b) through the use of *R projects* +or other means of organising files (e.g. if one is using VS Code: *workspaces*). + +One quick way to get started is by calling the following line of code, if one is +using an R project or equivalent: +```{r r_environ_demo_project, eval = FALSE} +usethis::edit_r_environ("project") +``` +Or, if one is not using an R project or equivalent: +```{r r_environ_demo_user, eval = FALSE} +usethis::edit_r_environ("user") +``` + ## Get All Countries The `get_all_countries()` function retrieves a list of all countries from the DTM API. -```{r get_country} +```{r get_country, eval = FALSE} # Fetch all countries countries_df <- get_all_countries() @@ -60,7 +87,7 @@ head(countries_df) The `get_all_operations()` function retrieves a list of all operations from the DTM API. -```{r get_operations} +```{r get_operations, eval = FALSE} # Fetch all operations operations_df <- get_all_operations() @@ -72,7 +99,7 @@ head(operations_df) The `get_idp_admin0_data()` function retrieves Internally Displaced Persons (IDP) data aggregated at the country level. -```{r get_idp_admin0} +```{r get_idp_admin0, eval = FALSE} # Fetch IDP data at Admin Level 0 idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) @@ -84,7 +111,7 @@ head(idp_admin0_df) The get_idp_admin1_data() function retrieves IDP data aggregated at Admin Level 1. -```{r get_idp_admin1} +```{r get_idp_admin1, eval = FALSE} # 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') @@ -95,7 +122,7 @@ 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 -```{r get_idp_admin2} +```{r get_idp_admin2, eval = FALSE} # Fetch IDP data at Admin Level 2 idp_admin2_df <- get_idp_admin2_data(Operation="Displacement due to conflict", CountryName='Lebanon') From 014fdec92d230e55393fe0236873825b66879f4d Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Wed, 30 Jul 2025 10:06:14 +0100 Subject: [PATCH 11/16] Edit README to refer to intro vignette The large deletion and emphasis on referring to the introduction just means that there's much less repetition and that the changes to the introduction vignette are reflected in what users are likely to read. --- README.md | 33 ++------------------------------- 1 file changed, 2 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 0532063..a9204e3 100644 --- a/README.md +++ b/README.md @@ -18,37 +18,8 @@ The `dtmapi` package is available on [CRAN](https://CRAN.R-project.org/package=d install.packages("dtmapi") ``` -## Load Package -After installation, load the package using library(): -```sh -library(dtmapi) -``` - -## Usage -Here's a quick example to get you started: -```R -# Get all countries for which DTM data is publicly available through the API. -countries_df <- get_all_countries() -head(countries_df) - -# Get all operations for which DTM data is publicly available through the API. -operations_df <- get_all_operations() -head(operations_df) - -# Get IDP Admin 0 Data for Ethiopia from Round 1 to Round 10 -idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) -head(idp_admin0_df) - -# Get IDP Admin 1 Data for Sudan from reporting date 2020-01-01 to 2024-08-15 -idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile", FromReportingDate='2020-01-01', ToReportingDate='2024-08-15') -head(idp_admin1_df) - -# Get IDP Admin 2 Data for Lebanon -idp_admin2_df <- get_idp_admin2_data(Operation="Displacement due to conflict", CountryName='Lebanon') -head(idp_admin2_df) -``` -## Documentation -Comprehensive documentation is available at [github.io](https://displacement-tracking-matrix.github.io/dtmapi-R/). +## User Guide +A user guide to getting started with `dtmapi` is available [here](https://displacement-tracking-matrix.github.io/dtmapi-R/). ## Source Code The source code for `dtmapi` is available on [GitHub](https://github.com/Displacement-tracking-Matrix/dtmapi-R). From a454e7bbb2dda85bb06bd33fa12d5f18b9d2822f Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Tue, 29 Jul 2025 21:37:52 +0100 Subject: [PATCH 12/16] Updating continuous integration (CI) systems Updating CI 2 CI edit CI update CI work edit --- .github/workflows/R-CMD-check.yaml | 52 ++++++++++++++++++++++++++++++ README.md | 5 ++- 2 files changed, 56 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/R-CMD-check.yaml diff --git a/.github/workflows/R-CMD-check.yaml b/.github/workflows/R-CMD-check.yaml new file mode 100644 index 0000000..fdb499f --- /dev/null +++ b/.github/workflows/R-CMD-check.yaml @@ -0,0 +1,52 @@ +# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples +# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help +on: + push: + branches: [main, master] + pull_request: + +name: R-CMD-check.yaml + +permissions: read-all + +jobs: + R-CMD-check: + runs-on: ${{ matrix.config.os }} + + name: ${{ matrix.config.os }} (${{ matrix.config.r }}) + + strategy: + fail-fast: false + matrix: + config: + - {os: macos-latest, r: 'release'} + - {os: windows-latest, r: 'release'} + - {os: ubuntu-latest, r: 'devel', http-user-agent: 'release'} + - {os: ubuntu-latest, r: 'release'} + - {os: ubuntu-latest, r: 'oldrel-1'} + + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + R_KEEP_PKG_SOURCE: yes + DTMAPIR_KEY: ${{ secrets.DTMAPIR_KEY}} + + steps: + - uses: actions/checkout@v4 + + - uses: r-lib/actions/setup-pandoc@v2 + + - uses: r-lib/actions/setup-r@v2 + with: + r-version: ${{ matrix.config.r }} + http-user-agent: ${{ matrix.config.http-user-agent }} + use-public-rspm: true + + - uses: r-lib/actions/setup-r-dependencies@v2 + with: + extra-packages: any::rcmdcheck + needs: check + + - uses: r-lib/actions/check-r-package@v2 + with: + upload-snapshots: true + build_args: 'c("--no-manual","--compact-vignettes=gs+qpdf")' diff --git a/README.md b/README.md index a9204e3..bfbbd6e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,12 @@ + +[![R-CMD-check](https://github.com/a-asil-companioni/dtmapi-R/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/a-asil-companioni/dtmapi-R/actions/workflows/R-CMD-check.yaml) + +

DTM Logo

- ----------------- ## About From 3e966ae464b31312e04f9206ee0164bf1c24abca Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Wed, 30 Jul 2025 12:25:49 +0100 Subject: [PATCH 13/16] Refactor user_guide.Rmd --- vignettes/introduction.Rmd | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/vignettes/introduction.Rmd b/vignettes/introduction.Rmd index 1fd4efc..be897d6 100644 --- a/vignettes/introduction.Rmd +++ b/vignettes/introduction.Rmd @@ -101,7 +101,10 @@ The `get_idp_admin0_data()` function retrieves Internally Displaced Persons (IDP ```{r get_idp_admin0, eval = FALSE} # Fetch IDP data at Admin Level 0 -idp_admin0_df <- get_idp_admin0_data(CountryName='Ethiopia', FromRoundNumber=1, ToRoundNumber=10) +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) @@ -113,7 +116,11 @@ The get_idp_admin1_data() function retrieves IDP data aggregated at Admin Level ```{r get_idp_admin1, eval = FALSE} # 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') +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) @@ -124,7 +131,9 @@ head(idp_admin1_df) The get_idp_admin2_data() function retrieves IDP data aggregated at Admin Level 2 ```{r get_idp_admin2, eval = FALSE} # Fetch IDP data at Admin Level 2 -idp_admin2_df <- get_idp_admin2_data(Operation="Displacement due to conflict", CountryName='Lebanon') +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) From c491375c63fe9c08e4a493d3a3e6df5d99d7007d Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Tue, 29 Jul 2025 22:52:54 +0100 Subject: [PATCH 14/16] Update auto-documented files Update Roxygen2-generated files --- NAMESPACE | 2 ++ man/get_all_countries.Rd | 3 ++- man/get_all_operations.Rd | 2 ++ man/get_idp_admin0_data.Rd | 6 +++++- man/get_idp_admin1_data.Rd | 4 +++- man/get_subscription_key.Rd | 30 ++++++++++++++++++++++++++++++ man/set_subscription_key.Rd | 27 +++++++++++++++++++++++++++ 7 files changed, 71 insertions(+), 3 deletions(-) create mode 100644 man/get_subscription_key.Rd create mode 100644 man/set_subscription_key.Rd diff --git a/NAMESPACE b/NAMESPACE index d1cbe5a..2975198 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -8,6 +8,7 @@ export(get_idp_admin2_data) export(get_subscription_key) export(set_subscription_key) importFrom(askpass,askpass) +importFrom(httr2,req_headers_redacted) importFrom(httr2,req_perform) importFrom(httr2,req_url_query) importFrom(httr2,request) @@ -15,3 +16,4 @@ importFrom(httr2,resp_body_json) importFrom(httr2,resp_body_string) importFrom(httr2,resp_status) importFrom(httr2,secret_decrypt) +importFrom(testthat,is_testing) diff --git a/man/get_all_countries.Rd b/man/get_all_countries.Rd index 8b67d11..09ca06a 100644 --- a/man/get_all_countries.Rd +++ b/man/get_all_countries.Rd @@ -13,7 +13,8 @@ A data frame containing the list of all countries. Retrieve all countries for which DTM data is publicly available through the API. } \examples{ -# Fetch all countries +\dontrun{ countries_df <- get_all_countries() head(countries_df) } +} diff --git a/man/get_all_operations.Rd b/man/get_all_operations.Rd index 53ff244..8fd3d21 100644 --- a/man/get_all_operations.Rd +++ b/man/get_all_operations.Rd @@ -13,7 +13,9 @@ A data frame containing the list of all operations. Retrieve all operations for which DTM data is publicly available through the API. } \examples{ +\dontrun{ # Fetch all operations operations_df <- get_all_operations() head(operations_df) } +} diff --git a/man/get_idp_admin0_data.Rd b/man/get_idp_admin0_data.Rd index 6801168..8097b90 100644 --- a/man/get_idp_admin0_data.Rd +++ b/man/get_idp_admin0_data.Rd @@ -37,7 +37,11 @@ Retrieve IDP data at Admin 0 level based on specified parameters. At least one of the following parameters must be provided: Operation, CountryName, or Admin0Pcode. } \examples{ +\dontrun{ # Fetch IDP data at Admin Level 0 -idp_admin0_df <- get_idp_admin0_data(CountryName = "Ethiopia", FromRoundNumber = 1, ToRoundNumber = 10) +idp_admin0_df <- get_idp_admin0_data(CountryName = "Ethiopia", + FromRoundNumber = 1, + ToRoundNumber = 10) head(idp_admin0_df) } +} diff --git a/man/get_idp_admin1_data.Rd b/man/get_idp_admin1_data.Rd index 1dcfee5..6541cb1 100644 --- a/man/get_idp_admin1_data.Rd +++ b/man/get_idp_admin1_data.Rd @@ -43,7 +43,9 @@ Retrieve IDP data at Admin 1 level based on specified parameters. At least one of the following parameters must be provided: Operation, CountryName, or Admin0Pcode. } \examples{ +\dontrun{ # Fetch IDP data at Admin Level 1 -idp_admin1_df <- get_idp_admin1_data(CountryName='Sudan', Admin1Name="Blue Nile") +idp_admin1_df <- get_idp_admin1_data(CountryName = "Sudan", Admin1Name = "Blue Nile") head(idp_admin1_df) } +} diff --git a/man/get_subscription_key.Rd b/man/get_subscription_key.Rd new file mode 100644 index 0000000..a68c2b3 --- /dev/null +++ b/man/get_subscription_key.Rd @@ -0,0 +1,30 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/get_subscription_key.R +\name{get_subscription_key} +\alias{get_subscription_key} +\title{Retrieval of an API subscription key from the environment.} +\usage{ +get_subscription_key() +} +\value{ +A string representing a given subscription key for the DTM API. +} +\description{ +The DTM API subscription key is returned, provided that it is available in +the R session as an environment variable. Users will usually need to set +the DTM_SUBSCRIPTION_KEY environment variable through a .Renviron file or +by calling \code{set_subscription_key()}. +} +\details{ +On the other hand, if the TESTTHAT environment variable is true, indicating +that unit tests are being run by the package maintainers, then the +subscription key is returned through different means. +} +\examples{ +\dontrun{ +# Generally, calling set_subscription_key() without the key as an argument is best, +# as the user can then be prompted to input the key without typing it directly +# into the console, making it more secure and less likely to exposed. +set_subscription_key() +} +} diff --git a/man/set_subscription_key.Rd b/man/set_subscription_key.Rd new file mode 100644 index 0000000..9bf1b8c --- /dev/null +++ b/man/set_subscription_key.Rd @@ -0,0 +1,27 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/set_subscription_key.R +\name{set_subscription_key} +\alias{set_subscription_key} +\title{Set the user's API subscription key in order to make the API calls.} +\usage{ +set_subscription_key(key = NULL) +} +\arguments{ +\item{key}{Either NULL or a string representing the key. NULL is preferable: using it +will prompt the user to type the subscription key in a graphical user +interface that masks it.} +} +\value{ +Nothing. Creates / overwrites an environmental variable as a side effect. +} +\description{ +The API will be stored as an environmental variable named "DTM_API_KEY". +} +\examples{ +\dontrun{ +# Generally, calling set_subscription_key() without the key as an argument is best, +# as the user can then be prompted to input the key without typing it directly +# into the console, making it more secure and less likely to exposed. +set_subscription_key() +} +} From 72c95de95ef3ac04c661cac26c8c1b3cc47fe14e Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Wed, 30 Jul 2025 10:39:24 +0100 Subject: [PATCH 15/16] Rename title, vignettes, and file of introduction.Rmd -> user_guide.Rmd Edit _pkgdown.yml to reflect change in introduction.Rmd --- _pkgdown.yml | 4 ++-- vignettes/{introduction.Rmd => user_guide.Rmd} | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) rename vignettes/{introduction.Rmd => user_guide.Rmd} (98%) diff --git a/_pkgdown.yml b/_pkgdown.yml index 1547801..691cdb8 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -11,8 +11,8 @@ navbar: - Reference components: home: - text: Quick Start - href: articles/introduction.html + text: User Guide + href: articles/user_guide.html Reference: text: Reference href: reference/index.html diff --git a/vignettes/introduction.Rmd b/vignettes/user_guide.Rmd similarity index 98% rename from vignettes/introduction.Rmd rename to vignettes/user_guide.Rmd index be897d6..8d07a9f 100644 --- a/vignettes/introduction.Rmd +++ b/vignettes/user_guide.Rmd @@ -1,8 +1,8 @@ --- -title: "dtmapi" +title: "User Guide" output: rmarkdown::html_vignette vignette: > - %\VignetteIndexEntry{introduction} + %\VignetteIndexEntry{User Guide} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- From b027a7b6e42d889ab3da827bf6c45558509dd9b6 Mon Sep 17 00:00:00 2001 From: a-asil-companioni Date: Wed, 30 Jul 2025 11:29:58 +0100 Subject: [PATCH 16/16] Build vignettes and site --- docs/404.html | 59 +- docs/LICENSE-text.html | 50 +- docs/articles/index.html | 50 +- .../{introduction.html => user_guide.html} | 203 +- docs/authors.html | 74 +- docs/deps/bootstrap-5.3.1/bootstrap.min.css | 2 +- .../bootstrap-toc-1.0.1/bootstrap-toc.min.js | 5 - .../deps/clipboard.js-2.0.11/clipboard.min.js | 7 - docs/deps/data-deps.txt | 9 - docs/deps/font-awesome-6.4.2/css/all.css | 7968 ----------------- docs/deps/font-awesome-6.4.2/css/all.min.css | 9 - docs/deps/font-awesome-6.4.2/css/v4-shims.css | 2194 ----- .../font-awesome-6.4.2/css/v4-shims.min.css | 6 - .../webfonts/fa-brands-400.ttf | Bin 189684 -> 0 bytes .../webfonts/fa-brands-400.woff2 | Bin 109808 -> 0 bytes .../webfonts/fa-regular-400.ttf | Bin 63348 -> 0 bytes .../webfonts/fa-regular-400.woff2 | Bin 24488 -> 0 bytes .../webfonts/fa-solid-900.ttf | Bin 394668 -> 0 bytes .../webfonts/fa-solid-900.woff2 | Bin 150020 -> 0 bytes .../webfonts/fa-v4compatibility.ttf | Bin 10172 -> 0 bytes .../webfonts/fa-v4compatibility.woff2 | Bin 4568 -> 0 bytes docs/deps/headroom-0.11.0/headroom.min.js | 7 - .../headroom-0.11.0/jQuery.headroom.min.js | 7 - .../search-1.0.0/autocomplete.jquery.min.js | 7 - docs/deps/search-1.0.0/fuse.min.js | 9 - docs/deps/search-1.0.0/mark.min.js | 7 - docs/index.html | 104 +- docs/katex-auto.js | 14 - docs/lightswitch.js | 85 - docs/pkgdown.js | 2 + docs/pkgdown.yml | 9 +- docs/reference/Rplot001.png | Bin 1011 -> 0 bytes docs/reference/get_all_countries.html | 64 +- docs/reference/get_all_operations.html | 72 +- docs/reference/get_idp_admin0_data.html | 103 +- docs/reference/get_idp_admin1_data.html | 105 +- docs/reference/get_idp_admin2_data.html | 109 +- docs/reference/get_subscription_key.html | 108 + docs/reference/index.html | 97 +- docs/reference/set_subscription_key.html | 101 + docs/search.json | 2 +- docs/sitemap.xml | 58 +- 42 files changed, 812 insertions(+), 10894 deletions(-) rename docs/articles/{introduction.html => user_guide.html} (50%) delete mode 100644 docs/deps/bootstrap-toc-1.0.1/bootstrap-toc.min.js delete mode 100644 docs/deps/clipboard.js-2.0.11/clipboard.min.js delete mode 100644 docs/deps/font-awesome-6.4.2/css/all.css delete mode 100644 docs/deps/font-awesome-6.4.2/css/all.min.css delete mode 100644 docs/deps/font-awesome-6.4.2/css/v4-shims.css delete mode 100644 docs/deps/font-awesome-6.4.2/css/v4-shims.min.css delete mode 100644 docs/deps/font-awesome-6.4.2/webfonts/fa-brands-400.ttf delete mode 100644 docs/deps/font-awesome-6.4.2/webfonts/fa-brands-400.woff2 delete mode 100644 docs/deps/font-awesome-6.4.2/webfonts/fa-regular-400.ttf delete mode 100644 docs/deps/font-awesome-6.4.2/webfonts/fa-regular-400.woff2 delete mode 100644 docs/deps/font-awesome-6.4.2/webfonts/fa-solid-900.ttf delete mode 100644 docs/deps/font-awesome-6.4.2/webfonts/fa-solid-900.woff2 delete mode 100644 docs/deps/font-awesome-6.4.2/webfonts/fa-v4compatibility.ttf delete mode 100644 docs/deps/font-awesome-6.4.2/webfonts/fa-v4compatibility.woff2 delete mode 100644 docs/deps/headroom-0.11.0/headroom.min.js delete mode 100644 docs/deps/headroom-0.11.0/jQuery.headroom.min.js delete mode 100644 docs/deps/search-1.0.0/autocomplete.jquery.min.js delete mode 100644 docs/deps/search-1.0.0/fuse.min.js delete mode 100644 docs/deps/search-1.0.0/mark.min.js delete mode 100644 docs/katex-auto.js delete mode 100644 docs/lightswitch.js delete mode 100644 docs/reference/Rplot001.png create mode 100644 docs/reference/get_subscription_key.html create mode 100644 docs/reference/set_subscription_key.html diff --git a/docs/404.html b/docs/404.html index 5806ed7..f90922a 100644 --- a/docs/404.html +++ b/docs/404.html @@ -8,46 +8,59 @@ Page not found (404) • dtmapi - - - + + + + Skip to contents + - -