subincomeR (version 0.2.2)

matchDOSE: Match coordinates to DOSE dataset

Description

This function matches input coordinates (latitude and longitude) to the DOSE dataset. It accepts either vectors of latitudes and longitudes or a dataframe containing these coordinates. Before matching, it ensures that only unique coordinates are processed to avoid duplicating operations on identical coordinates. It uses GADM-1 geometries to match coordinates to regions and returns a dataframe with unique input coordinates and matched DOSE data.

Usage

matchDOSE(
  lat = NULL,
  long = NULL,
  df = NULL,
  lat_col = "lat",
  long_col = "long",
  years = NULL,
  countries = NULL,
  format_countries = "iso3c",
  path = NULL,
  download = FALSE
)

Value

A dataframe with input coordinates (and any additional input dataframe columns) and matched DOSE data.

Arguments

lat

Optional vector of latitudes of the points to match. Required if no dataframe is provided.

long

Optional vector of longitudes of the points to match. Required if no dataframe is provided.

df

Optional dataframe containing coordinates and possibly additional columns. If provided, 'lat' and 'long' vectors should not be provided. The dataframe must include columns specified by 'lat_col' and 'long_col' parameters.

lat_col

Optional name of the latitude column in 'df'. Only used if 'df' is provided. Defaults to "lat".

long_col

Optional name of the longitude column in 'df'. Only used if 'df' is provided. Defaults to "long".

years

Optional vector of years for which to filter the DOSE dataset. If NULL (the default), a 1:m matching is performed and data for all years are returned.

countries

Optional vector or dataframe column name of country identifiers. If provided, the function skips the country matching step. Can significantly reduce processing time.

format_countries

Specifies the format of the country identifiers in 'countries'. Options are "country.name" (default), "iso3c", and "iso2c". This parameter is ignored if 'countries' is NULL.

path

Optional character string specifying where to store downloaded files. If NULL (default), uses tempdir().

download

Logical indicating whether to download without confirmation. Default is FALSE, which will prompt for confirmation in interactive sessions. Set to TRUE to skip confirmation.

Examples

# \donttest{
# Match coordinates using vectors
matched_data <- matchDOSE(lat = c(19.4326, 51.5074), 
                         long = c(-99.1332, -0.1276))

# Match coordinates using a dataframe
df <- data.frame(ID = 1:2, 
                 latitude = c(19.4326, 51.5074), 
                 longitude = c(-99.1332, -0.1276))
matched_data_df <- matchDOSE(df = df, 
                            lat_col = "latitude", 
                            long_col = "longitude")

# Match coordinates for a specific year
matched_data_2019 <- matchDOSE(lat = c(19.4326), 
                               long = c(-99.1332), 
                               years = 2019)

# Match coordinates with known countries
matched_data_countries <- matchDOSE(lat = c(19.4326, 51.5074),
                                   long = c(-99.1332, -0.1276),
                                   countries = c("MEX", "GBR"),
                                   format_countries = "iso3c")
# }