README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
subscription_key_available <- !identical(Sys.getenv("DTM_SUBSCRIPTION_KEY"), "")
key_available <- subscription_key_available

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%",
  eval = key_available
)
```

<br>

<p align="center">
  <img alt="DTM Logo" src="man/figures/dtm_global_logo.svg" width="400">
</p>
-----------------
# dtmapi

<!-- badges: start -->
[![R-CMD-check](https://github.com/Displacement-Tracking-Matrix/dtmapi-R/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/Displacement-Tracking-Matrix/dtmapi-R/actions/workflows/R-CMD-check.yaml)
[![CRAN status](https://www.r-pkg.org/badges/version/dtmapi)](https://CRAN.R-project.org/package=dtmapi)
<!-- badges: end -->



## About
`dtmapi` is an R package developed by [Displacement Tracking Matrix (DTM)](https://dtm.iom.int/). 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](https://dtm.iom.int/data-and-analysis/dtm-api/data-coverage) matrix. 

Please find more information 
about [DTM API here.](https://dtm.iom.int/data-and-analysis/dtm-api)

## Installation
The `dtmapi` package is available 
on [CRAN](https://CRAN.R-project.org/package=dtmapi) and can be 
installed as follows:

```{r, eval = FALSE}
install.packages("dtmapi")
```

## Pre-Requisites
Using `dtmapi` requires a subscription key. To obtain one, register with 
the [DTM API Portal](https://dtm-apim-portal.iom.int/signin) 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:

```{r set_subscription_key_demo, eval = FALSE}
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:
```{r, eval = FALSE}
# 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")`.

## Usage
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.](https://displacement-tracking-matrix.github.io/dtmapi-R/reference/index.html)

As a representative example of the earlier mentioned functions, see the following use of `get_idp_admin_1_data()`:

```{r}
# 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)
```

Since 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.

```{r}
# Load the package
library(dtmapi)
countries_df <- get_all_countries()

# Display the first few rows of the data frame
head(countries_df)
```

```{r}
# Load the package
library(dtmapi)

operations_df <- get_all_operations()

# Display the first few rows of the data frame
head(operations_df)
```

## User Guide
The information given here is further elaborated on in the user guide to
getting started with `dtmapi`, which is 
accessible through `vignette("user_guide")`.

## Source Code
The source code for `dtmapi` is available on 
[GitHub](https://github.com/Displacement-tracking-Matrix/dtmapi-R).

Feel free to explore the repository, contribute, or raise any issues you may encounter.

## Contact
For any questions or feedback, please reach out to us at 
[dtmdataconsolidation@iom.int](mailto:dtmdataconsolidation@iom.int).