---
title: "User Guide"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{User Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
```{r setup, include = FALSE}
subscription_key_available <- !identical(Sys.getenv("DTM_SUBSCRIPTION_KEY"), "")
key_available <- subscription_key_available

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  error = TRUE,
  eval = key_available
)
```

```{r eval = !key_available, echo = FALSE, comment = NA}
message("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:

-   `get_all_countries()`

-   `get_all_operations()`

-   `get_idp_admin0_data()`

-   `get_idp_admin1_data()`

-   `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}
install.packages("dtmapi")
```

## Load Package

After installation, load the package using library():
```{r import}
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}
# 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.

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

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

```{r get_idp_admin1}
# 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
```{r get_idp_admin2}
# 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.