Package 'idmc'

Title: Load and Wrangle IDMC Displacement Data
Description: Utilities to work with data from the Internal Displacement Monitoring Centre (IDMC) (<https://www.internal-displacement.org/>), with convenient functions for loading events data from the IDMC API and transforming events data to daily displacement estimates.
Authors: Seth Caldwell [aut, cre, cph]
Maintainer: Seth Caldwell <[email protected]>
License: GPL (>= 3)
Version: 0.3.1
Built: 2025-02-06 04:56:44 UTC
Source: https://github.com/ocha-dap/idmc

Help Index

Get data from the IDMC API

Description

idmc_get_data() calls the IDMC API to retrieve displacement data. The data is converted from JSON to a data frame, date columns converted to Date types, and returned as a dplyr::tibble.

Usage

idmc_get_data(api_url = NULL)

Arguments

api_url

URL to the IDMC API. If NULL, the default, searches for the IDMC_API environment variable.

Value

Tibble of displacement data. Description of the data frame variables are included in the documentation for the IDMC IDU API. # nolint

Examples

idmc_get_data()

Transform displacement event data to daily data

Description

idmc_transform_daily() transforms event data from the IDMC API (accessed through idmc_get_data()). For each event, identified by an event_id, potentially duplicated data is filtered out. If there are ⁠Recommended figure⁠ rows based on the role column, then only those are kept. If there are no recommended figures, then only the latest update to the event_id data is kept, using created_at to find latest updates.

Usage

idmc_transform_daily(
  df,
  min_date = as.Date("2018-01-01"),
  max_date = Sys.Date(),
  filter_min_date = TRUE
)

Arguments

df

Event displacement data frame, generated from idmc_get_data().
min_date

Date to backfill displacement data to. By default, min_date is set the first day of 2018. Only a few observations of the IDMC data are from before 2018, spanning back to 2011. If NULL, no backfilling is done, and the first reported case in the IDMC database is taken as the earliest.
max_date

Date to extrapolate all data to, filling with 0. If the The latest date in the data frame is used if later than max_date. If NULL, no extrapolation is done.
filter_min_date

If TRUE, the default, filters the data to only contain data from min_date onward. Ensures that the few countries with observations from 2011 but nothing until 2018 do not skew results.

Details

The data for each event is spread out between the start and end date, with the total displacement uniformly distributed across all days. For each country and displacement type (conflict, disaster, or other), all displacement on a day is summed up to create a total daily displacement figure.

By default, data is backfilled for all countries and displacement types to the first reported date in the IDMC dataset. Data is always infilled with 0 between start and end dates.

Value

Data frame of daily displacement with the following columns:

iso3

Country ISO3 code.

country

Country or area name.

displacement_type

Type of displacement.

date

Date.

displacement_daily

Daily level of displacement.

Examples

idmc_get_data() %>%
  idmc_transform_daily()