# User Guide

## 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:

    install.packages("dtmapi")

## Load Package

After installation, load the package using library():

    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.

    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:

    usethis::edit_r_environ("project")

Or, if one is not using an R project or equivalent:

    usethis::edit_r_environ("user")

## 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)
    #>                         admin0Name admin0Pcode
    #> 1                      Afghanistan         AFG
    #> 2              Antigua and Barbuda         ATG
    #> 3                    Bahamas (the)         BHS
    #> 4                            Benin         BEN
    #> 5 Bolivia (Plurinational State of)         BOL
    #> 6                     Burkina Faso         BFA

## 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)
    #>                                   operation operationStatus          admin0Name
    #> 1                           Aceh earthquake        Inactive           Indonesia
    #> 2                    Armed Clashes in Sudan          Active               Sudan
    #> 3          Armed Clashes in Sudan (Monthly)          Active               Sudan
    #> 4         Armed Clashes in Sudan (Overview)          Active               Sudan
    #> 5                       Arrivals in Armenia        Inactive Republic of Armenia
    #> 6 Bahamas (the) - Hurricane Dorian Response        Inactive       Bahamas (the)
    #>   admin0Pcode
    #> 1         IDN
    #> 2         SDN
    #> 3         SDN
    #> 4         SDN
    #> 5         ARM
    #> 6         BHS

## 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)
    #>                operation admin0Name admin0Pcode numPresentIdpInd
    #> 1 Countrywide monitoring   Ethiopia         ETH             7823
    #> 2 Countrywide monitoring   Ethiopia         ETH            21668
    #> 3 Countrywide monitoring   Ethiopia         ETH            15420
    #> 4 Countrywide monitoring   Ethiopia         ETH           772924
    #> 5 Countrywide monitoring   Ethiopia         ETH           308300
    #> 6 Countrywide monitoring   Ethiopia         ETH             6984
    #>         reportingDate yearReportingDate monthReportingDate roundNumber
    #> 1 2017-12-31T00:00:00              2017                 12           8
    #> 2 2017-12-31T00:00:00              2017                 12           8
    #> 3 2017-12-31T00:00:00              2017                 12           8
    #> 4 2017-12-31T00:00:00              2017                 12           8
    #> 5 2017-12-31T00:00:00              2017                 12           8
    #> 6 2017-12-31T00:00:00              2017                 12           8
    #>   displacementReason numberMales numberFemales idpOriginAdmin1Name
    #> 1           Conflict        4088          3735                Afar
    #> 2           Conflict       11490         10178              Amhara
    #> 3           Conflict        7046          8374             Gambela
    #> 4           Conflict      375655        397269              Oromia
    #> 5           Conflict      152469        155831              Somali
    #> 6           Conflict        3170          3814              Tigray
    #>   idpOriginAdmin1Pcode assessmentType
    #> 1                 ET02             SA
    #> 2                 ET03             SA
    #> 3                 ET12             SA
    #> 4                 ET04             SA
    #> 5                 ET05             SA
    #> 6                 ET01             SA

## 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)
    #>        id              operation admin0Name admin0Pcode admin1Name admin1Pcode
    #> 1 4277072        Darfur conflict      Sudan         SDN  Blue Nile        SD08
    #> 2 4277073        Darfur conflict      Sudan         SDN  Blue Nile        SD08
    #> 3 4277074        Darfur conflict      Sudan         SDN  Blue Nile        SD08
    #> 4 4277075        Darfur conflict      Sudan         SDN  Blue Nile        SD08
    #> 5 4255941 Armed Clashes in Sudan      Sudan         SDN  Blue Nile        SD08
    #> 6 4255942 Armed Clashes in Sudan      Sudan         SDN  Blue Nile        SD08
    #>   numPresentIdpInd       reportingDate yearReportingDate monthReportingDate
    #> 1            81693 2021-03-30T00:00:00              2021                  3
    #> 2           130958 2021-12-31T00:00:00              2021                 12
    #> 3           151156 2022-01-31T00:00:00              2022                  1
    #> 4           152656 2022-03-30T00:00:00              2022                  3
    #> 5              260 2023-04-28T00:00:00              2023                  4
    #> 6              715 2023-05-07T00:00:00              2023                  5
    #>   roundNumber         displacementReason numberMales numberFemales
    #> 1           2                   Conflict          NA            NA
    #> 2           3 Conflict; Natural disaster          NA            NA
    #> 3           4                   Conflict          NA            NA
    #> 4           5                   Conflict          NA            NA
    #> 5           2                   Conflict          NA            NA
    #> 6           3                   Conflict          NA            NA
    #>   idpOriginAdmin1Name idpOriginAdmin1Pcode assessmentType
    #> 1           Blue Nile                 SD08             BA
    #> 2           Blue Nile                 SD08             BA
    #> 3       Not available        Not available             BA
    #> 4           Blue Nile                 SD08             BA
    #> 5         West Darfur                 SD04             BA
    #> 6            Khartoum                 SD01             BA

## 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)
    #>         id                    operation admin0Name admin0Pcode    admin1Name
    #> 1 17490733 Displacement due to conflict    Lebanon         LBN Mount Lebanon
    #> 2 17491237 Displacement due to conflict    Lebanon         LBN Mount Lebanon
    #> 3 17496916 Displacement due to conflict    Lebanon         LBN        Beirut
    #> 4 17498945 Displacement due to conflict    Lebanon         LBN Mount Lebanon
    #> 5 17502015 Displacement due to conflict    Lebanon         LBN Mount Lebanon
    #> 6 17502022 Displacement due to conflict    Lebanon         LBN   El Nabatieh
    #>   admin1Pcode admin2Name admin2Pcode numPresentIdpInd       reportingDate
    #> 1         LB3     Baabda        LB32               10 2023-10-15T00:00:00
    #> 2         LB3       Aley        LB31              364 2023-10-15T00:00:00
    #> 3         LB1     Beirut        LB11               25 2023-10-15T00:00:00
    #> 4         LB3      Chouf        LB33               41 2023-10-15T00:00:00
    #> 5         LB3     Baabda        LB32              591 2023-10-15T00:00:00
    #> 6         LB4    Hasbaya        LB42              150 2023-10-15T00:00:00
    #>   yearReportingDate monthReportingDate roundNumber displacementReason
    #> 1              2023                 10           2           Conflict
    #> 2              2023                 10           2           Conflict
    #> 3              2023                 10           1           Conflict
    #> 4              2023                 10           2           Conflict
    #> 5              2023                 10           1           Conflict
    #> 6              2023                 10           1           Conflict
    #>   numberMales numberFemales idpOriginAdmin1Name idpOriginAdmin1Pcode
    #> 1          NA            NA       Mount Lebanon                  LB3
    #> 2          NA            NA         El Nabatieh                  LB4
    #> 3          NA            NA       Mount Lebanon                  LB3
    #> 4          NA            NA       Mount Lebanon                  LB3
    #> 5          NA            NA         El Nabatieh                  LB4
    #> 6          NA            NA         El Nabatieh                  LB4
    #>   assessmentType
    #> 1             BA
    #> 2             BA
    #> 3             BA
    #> 4             BA
    #> 5             BA
    #> 6             BA

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