Package {land4health}

Title:	Remote Sensing Metrics for Spatial Health Analysis
Version:	0.3.0
Description:	Calculate and extract remote sensing metrics for spatial analysis in the field of health. The package offers R users a quick and straightforward way to obtain areal or zonal statistics of key environmental indicators, covariates, and vector-borne disease data ideal for modeling infectious diseases within the framework of spatial epidemiology.
Maintainer:	Yomali Ferreyra <yomali.ferreyra@upch.pe>
URL:	https://github.com/harmonize-tools/land4health/, https://harmonize-tools.github.io/land4health/
License:	MIT + file LICENSE
Encoding:	UTF-8
Imports:	cli (≥ 3.4.0), lifecycle, tidyr, dplyr, rgee, sf, httr2, ows4R, reticulate, rappdirs, tibble, terra
Suggests:	geojsonio, rmarkdown, knitr, testthat (≥ 3.0.0), rstudioapi, geoidep, withr
Depends:	R (≥ 4.1.0)
VignetteBuilder:	knitr
BugReports:	https://github.com/harmonize-tools/land4health/issues
Config/testthat/edition:	3
Config/roxygen2/version:	8.1.0
NeedsCompilation:	no
Packaged:	2026-09-28 19:18:16 UTC; mvcs_dgppvu_ambi
Author:	Antony Barja [aut, cph], Yomali Ferreyra [cre], Diego Villa [ctb]
Repository:	CRAN
Date/Publication:	2026-10-08 17:40:02 UTC

land4health: Remote Sensing Metrics for Spatial Health Analysis

Description

Calculate and extract remote sensing metrics for spatial analysis in the field of health. The package offers R users a quick and straightforward way to obtain areal or zonal statistics of key environmental indicators, covariates, and vector-borne disease data ideal for modeling infectious diseases within the framework of spatial epidemiology.

Author(s)

Maintainer: Yomali Ferreyra yomali.ferreyra@upch.pe (ORCID)

Authors:

• Antony Barja antony.barja@upch.pe (ORCID) [copyright holder]

Other contributors:

• Diego Villa [contributor]

See Also

Useful links:

• https://github.com/harmonize-tools/land4health/

• https://harmonize-tools.github.io/land4health/

• Report bugs at https://github.com/harmonize-tools/land4health/issues

Convert sf to GeoJSON (internal)

Description

Convert sf to GeoJSON (internal)

Usage

as_geojson_min(x)

Internal: Check that Earth Engine is initialized

Description

Internal: Check that Earth Engine is initialized

Usage

check_ee_initialized()

Evaluates whether a given polygon covers a minimum number of valid pixels in a specified Earth Engine image.

Description

Evaluates whether a given polygon covers a minimum number of valid pixels in a specified Earth Engine image.

Usage

check_representativity(region, scale = 30)

Arguments

Value

Invisible TRUE if all polygons cover at least 1 pixel; otherwise invisible FALSE with a cli warning reporting how many polygons fall below 1 pixel. Extraction is never stopped; use force = TRUE in the calling ⁠l4h_*⁠ function to skip this check entirely.

Reading a csv containing geoidep resources

Description

Reading a csv containing geoidep resources

Usage

get_data()

Internal: Get an Earth Engine reducer Returns a reducer object (e.g., ee$Reducer$mean()) based on a string name.

Description

Internal: Get an Earth Engine reducer Returns a reducer object (e.g., ee$Reducer$mean()) based on a string name.

Usage

get_reducer(name)

Arguments

Value

An Earth Engine reducer object.

Global variables for get_early_warning This code declares global variables used in the some function to avoid R CMD check warnings.

Description

Global variables for get_early_warning This code declares global variables used in the some function to avoid R CMD check warnings.

Extract CHIRPS v3 precipitation data from Google Earth Engine

Description

Extracts CHIRPS v3 precipitation estimates for a user-defined region and time range from the Earth Engine dataset UCSB-CHC/CHIRPS/V3/DAILY_SAT (IMERG-based) or UCSB-CHC/CHIRPS/V3/DAILY_RNL (ERA5-based). The function supports daily, monthly, and annual temporal aggregation. Monthly and annual values are computed as sums of daily precipitation (mm), which is the standard in hydrology and vector-borne disease modelling.

CHIRPS v3 (Climate Hazards Center InfraRed Precipitation with Stations version 3) is a quasi-global (60°S–60°N), high-resolution (0.05°) gridded rainfall dataset from 1981 to near-present, combining satellite thermal infrared estimates with in-situ station observations.

Usage

l4h_chirps(
  from,
  to,
  by = "month",
  product = "sat",
  region,
  scale = 5566,
  stat = "mean",
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

An sf or tibble with columns:

• date (Date — first day of the period),

• variable (character — "precipitation"),

• value (numeric — mm in the corresponding time unit), plus geometry if sf = TRUE, and any attributes from region.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

Funk, C., Peterson, P., Harrison, L. et al. (2026). The Climate Hazards Center Infrared Precipitation with Stations, Version 3. Scientific Data, 13, 718. doi:10.1038/s41597-026-07096-4

Examples

if (interactive()) {
library(land4health)
rgee::ee_Initialize()

# ROI simple (EPSG:4326)
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))), crs = 4326))

# 1. Monthly precipitation (mm/month) 2020, SAT product
out_monthly <- l4h_chirps(
  from    = "2020-01-01",
  to      = "2020-12-31",
  by      = "month",
  product = "sat",
  region  = region,
  stat    = "mean"
)
head(out_monthly)

# 2. Annual precipitation (mm/year) 2015-2020, RNL product
out_annual <- l4h_chirps(
  from    = "2015-01-01",
  to      = "2020-12-31",
  by      = "annual",
  product = "rnl",
  region  = region,
  stat    = "mean"
)
head(out_annual)

# 3. Daily precipitation (mm/day) for one month
out_daily <- l4h_chirps(
  from    = "2020-06-01",
  to      = "2020-06-30",
  by      = "daily",
  product = "sat",
  region  = region,
  stat    = "mean"
)
head(out_daily)
}

Extracts carbon monoxide (CO) concentration from Sentinel-5P TROPOMI

Description

Retrieves the CO column number density (mol/m2) for a user-defined region and date range from the Sentinel-5P TROPOMI OFFLINE L3 CO dataset.

Usage

l4h_co_column(
  from,
  to,
  region,
  stat = "mean",
  scale = 1113,
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Details

The function uses the Earth Engine dataset COPERNICUS/S5P/OFFL/L3_CO and selects only the "CO_column_number_density" band. Images are composited to daily means before extraction to avoid exceeding the 5000-band limit on toBands().

Value

An sf or tibble containing CO column density (mol/m2) by date and geometry.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

COPERNICUS/S5P/OFFL/L3_CO. Sentinel-5P Offline L3 Carbon Monoxide. European Union / ESA / Copernicus. https://developers.google.com/earth-engine/datasets/catalog/COPERNICUS_S5P_OFFL_L3_CO

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define region as a bounding box polygon
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326)
)

# Run CO column calculation
co_data <- l4h_co_column(
  from = "2022-01-01",
  to = "2022-12-31",
  region = region,
  stat = "mean"
)
head(co_data)
}

Extract dengue case data from OpenDengue

Description

Downloads dengue case counts from the OpenDengue Project, a harmonized, open-access repository of dengue surveillance data from national ministries of health. The function supports national, spatial, and temporal extracts filtered by WHO region and country for a specified date range.

Usage

l4h_dengue(
  from,
  to,
  data_type = c("temporal", "spatial", "national"),
  region = NULL,
  country = "Peru",
  cache = TRUE,
  quiet = FALSE
)

Arguments

Value

A tibble with columns: date_start, date_end, cases, state, area, plus other fields from the source data.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

Source

Data from the OpenDengue Project.

References

Morales, I. et al. (2024). OpenDengue: Harmonized dengue surveillance data for Latin America.

See Also

l4h_malaria()

Examples

if (interactive()) {
  # National extract for Peru in 2019
  df_nat <- l4h_dengue(
    from = "2019-01-01",
    to = "2019-12-31",
    data_type = "national",
    region = "paho",
    country = "peru",
    cache = TRUE,
    quiet = TRUE
  )
  head(df_nat)

  # Spatial extract for Brazil
  df_spat <- l4h_dengue(
    from = "2021-01-01",
    to = "2021-12-31",
    data_type = "spatial",
    region = "Pan-American Region",
    country = "brazil",
    cache = TRUE,
    quiet = TRUE
  )
  head(df_spat)

  # Temporal extract for Argentina
  df_temp <- l4h_dengue(
    from = "2020-01-01",
    to = "2020-12-31",
    data_type = "temporal",
    region = "PAHO",
    country = "Argentina",
    cache = TRUE,
    quiet = TRUE
  )
  head(df_temp)
}

Internal Earth Engine data extraction (Optimized)

Description

Transfers geometries to Earth Engine and extracts statistics using direct invocations of the reduceRegions method to avoid earthengine-api incompatibilities.

Usage

l4h_ee_extract(
  image,
  sf_region,
  scale = NULL,
  fun = "mean",
  sf = TRUE,
  tile_scale = 1,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

An sf or tbl_df (data.frame) object with the extracted data.

Extract ERA5-Land climate variables from Google Earth Engine

Description

Extracts ERA5-Land climate variables for a user-defined region and time range from the Earth Engine datasets ECMWF/ERA5_LAND/DAILY_AGGR (by = "daily") or ECMWF/ERA5_LAND/MONTHLY_AGGR (by = "month"). Each image is summarized over the region using a chosen statistic (e.g., mean/median), values are converted to conventional units (degrees Celsius, mm, volume fraction), and the function returns an sf or tibble.

ERA5-Land is the land-component replay of the ECMWF ERA5 climate reanalysis (Copernicus Climate Data Store), with global coverage from 1950 to near-present at ~9 km (0.1 degrees) resolution. It complements l4h_chirps() (finer precipitation) and l4h_terra_climate() (finer monthly climatology) by providing daily exposure windows and soil-moisture variables that are key for vector-borne disease modelling (temperature/precipitation lags).

Usage

l4h_era5land(
  from,
  to,
  by = "month",
  band = "t2m",
  region,
  scale = 11132,
  stat = "mean",
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

An sf or tibble with columns:

• date (Date — first day of the period),

• variable (character — band code, e.g. "t2m"),

• value (numeric — degrees C, mm, or volume fraction), plus geometry if sf = TRUE, and any attributes from region.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

Muñoz Sabater, J. (2019): ERA5-Land monthly averaged data from 1950 to present. Copernicus Climate Change Service (C3S) Climate Data Store (CDS). doi:10.24381/cds.68d2bb30

Examples

if (interactive()) {
library(land4health)
rgee::ee_Initialize()

# ROI simple (EPSG:4326)
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))), crs = 4326))

# 1. Monthly 2m temperature (degrees C) 2020
out_monthly <- l4h_era5land(
  from   = "2020-01-01",
  to     = "2020-12-31",
  by     = "month",
  band   = "t2m",
  region = region,
  stat   = "mean"
)
head(out_monthly)

# 2. Daily precipitation (mm) + soil moisture, one month
out_daily <- l4h_era5land(
  from   = "2020-06-01",
  to     = "2020-06-30",
  by     = "daily",
  band   = c("pr", "soil"),
  region = region,
  stat   = "mean"
)
head(out_daily)
}

Extracts forest cover loss within a defined polygon

Description

Calculates forest loss within a user-defined region for a specified year range. Forest loss is defined as a stand-replacement disturbance, or a change from forest to non-forest state.

Usage

l4h_forest_loss(from, to, region, sf = TRUE, quiet = FALSE, force = FALSE, ...)

Arguments

Details

Forest loss is derived from the Hansen Global Forest Change dataset. The lossyear band encodes the year of forest cover loss as follows:

• Values range from 1 to n, where 1 corresponds to the year 2001 and n to the year 2000 + n.

• A value of 0 indicates no forest loss detected.

Value

A sf or tibble object with forest loss per year in square kilometers.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

Hansen, M. C., Potapov, P. V., Moore, R., Hancher, M., Turubanova, S. A., Tyukavina, A., ... & Townshend, J. R. G. (2013). High-Resolution Global Maps of 21st-Century Forest Cover Change. Science, 342(6160), 850–853. DOI: doi:10.1126/science.1244693

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define region as a bounding box polygon
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326
))

# Run forest loss calculation
result <- l4h_forest_loss(
  from = '2005-01-01',
  to = '2007-01-01',
  region = region)

head(result)
}

Extracts built‑up surface area from GHSL Built‑Up Surface dataset

Description

Retrieves total built‑up surface area (in m2 per 100m grid cell) from the GHSL Built-Up Surface dataset (GHS‑BUILT‑S R2023A), over a user-defined region and date range. The dataset is provided in 5‑year epochs (1975–2030) at ~100m resolution.

Usage

l4h_human_built(
  from,
  to,
  region,
  scale = 100,
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

A sf or tibble with columns date, variable, and built_surface_m2.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

• Pesaresi, M. & Politis, P. (2023). GHS‑BUILT‑S R2023A: Red de superficie construida de GHS, derivada de la composición de Sentinel-2 y Landsat, multitemporal (1975–2030). European Commission, Joint Research Centre (JRC). doi:10.2905/9F06F36F-4B11-47EC-ABB0-4F8B7B1D72EA.

• Pesaresi, M., Schiavina, M., Politis, P., Freire, S., Krasnodebska, K., Uhl, J.H., Carioli, A., et al. (2024). Avances en la capa de asentamientos humanos globales a través de la evaluación conjunta de datos de observación de la Tierra y encuestas demográficas. International Journal of Digital Earth, 17(1). doi:10.1080/17538947.2024.2390454

• Dataset on Google Earth Engine: https://developers.google.com/earth-engine/datasets/catalog/JRC_GHSL_P2023A_GHS_BUILT_S

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define a bounding box region in Ucayali, Peru
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326
))

# Extract built-up surface area from 2000 to 2020
built_area <- l4h_human_built(
  from = "2000-01-01",
  to = "2020-12-31",
  region = region,
  scale = 100,
  stat = "sum"
)
head(built_area)

# Example using as tibble
built_tbl <- l4h_human_built(
  from = "1990-01-01",
  to = "2015-12-31",
  region = region,
  sf = FALSE,
  stat = "mean"
)
dplyr::glimpse(built_tbl)
}

Install Python dependencies for land4health package

Description

Installs required Python packages (earthengine-api and numpy). By default uses uv when available (much faster downloads with a live progress bar in the console) and falls back to pip via reticulate::py_install() otherwise.

Usage

l4h_install(
  pip = TRUE,
  system = FALSE,
  force = FALSE,
  restart = TRUE,
  backend = c("auto", "uv", "pip"),
  ...
)

Arguments

Value

Invisibly returns NULL

Examples

# Installation is intentionally not run in examples because it modifies
# the Python environment and may be slow.

# See the installation vignette for instructions:
vignette("land4health-setup", package = "land4health")

List available metrics in land4health

Description

Returns a tibble with the metadata of every metric shipped with land4health. You can optionally filter by thematic category, metric short name, or provider. If open_in_browser = TRUE, all matching URLs are opened in your default browser; for safety you must supply at least one filter, and—if more than five tabs would open—you are asked to confirm in interactive sessions.

Usage

l4h_list_metrics(
  category = NULL,
  metric = NULL,
  provider = NULL,
  open_in_browser = FALSE
)

Arguments

Value

A tibble (returned invisibly). When open_in_browser = FALSE a compact preview (max 10 rows) is printed before the tibble is returned.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

Examples

## All examples keep `open_in_browser = FALSE` to avoid side-effects
## during automated checks.

## 1  Show the full inventory (truncated to 10 rows).
l4h_list_metrics()

## 2  Filter by category (“Human intervention”).
l4h_list_metrics(category = "Human intervention")

## 3  Filter by provider (“WorldPop”) and store the result.
worldpop_tbl <- l4h_list_metrics(provider = "WorldPop")
head(worldpop_tbl)

Extract malaria metrics from the Malaria Atlas Project GeoServer

Description

Downloads modeled malaria raster surfaces from the Malaria Atlas Project (MAP) GeoServer via WCS 2.0.1, extracts zonal statistics for a user-defined region and time range, and returns an sf or tibble.

Available species: Plasmodium falciparum ("pf") and Plasmodium vivax ("pv"). Available measures: "incidence_rate", "incidence_count", "parasite_rate", "mortality_rate", "mortality_count". The function automatically selects the latest release available on the server for the requested species + measure combination.

Usage

l4h_malaria(
  from,
  to,
  species = "pf",
  measure = "incidence_rate",
  region,
  stat = "mean",
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Details

The MAP GeoServer provides modeled global raster surfaces at ~5 km resolution. Rates are expressed per person (0-1 scale for parasite rate, per 1,000 for incidence), and counts are absolute numbers. The function connects to the GeoServer via ows4R::WCSClient, downloads the coverage clipped to the region bounding box, and uses terra::extract() for zonal statistics.

Value

An sf or tibble with columns:

• date (Date, first day of year),

• species (character, "pf" or "pv"),

• measure (character, the requested measure),

• value (numeric, in native units), plus geometry if sf = TRUE, and any attributes from region.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

Malaria Atlas Project. https://malariaatlas.org/

Examples

if (interactive()) {
library(land4health)

# ROI simple (EPSG:4326)
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))), crs = 4326))

# Pf incidence rate 2015-2020
out <- l4h_malaria(
  from    = 2015,
  to      = 2020,
  species = "pf",
  measure = "incidence_rate",
  region  = region
)
head(out)

# Pv parasite rate
out_pv <- l4h_malaria(
  from    = 2020,
  to      = 2022,
  species = "pv",
  measure = "parasite_rate",
  region  = region,
  sf      = FALSE
)
head(out_pv)
}

Extracts global night‑time lights using harmonized DMSP‑OLS and VIIRS data

Description

Retrieves annual night‑time light radiance (average radiance, nanoWatt/sr/cm²) from the Harmonized Global Night Time Lights dataset for a user-defined region and time range. The dataset harmonizes DMSP-OLS (1992‑2013) with VIIRS‑like data (2014‑2021), ensuring consistent long-term time series at ~1km resolution.

Usage

l4h_night_lights(
  from,
  to,
  region,
  stat = "mean",
  scale = 1000,
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

A sf or tibble with annual night‑time light statistics per region and date.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define a bounding box region in Ucayali, Peru
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326
))

# Extract only DMSP-OLS data (1998–2010)
ntl_dmsp <- l4h_night_lights(
  from = "1998-01-01",
  to = "2010-12-31",
  region = region,
  stat = "mean"
)
head(ntl_dmsp)

# Extract only VIIRS data (2016–2021)
ntl_viirs <- l4h_night_lights(
  from = "2016-01-01",
  to = "2021-12-31",
  region = region,
  stat = "mean"
)
head(ntl_viirs)

# Extract both DMSP and VIIRS (2008–2020)
ntl_mixed <- l4h_night_lights(
  from = "2008-01-01",
  to = "2020-12-31",
  region = region,
  stat = "mean"
)
head(ntl_mixed)
}

List all land4health packages

Description

List all land4health packages

Usage

l4h_packages(include_self = TRUE)

Arguments

Value

A character vector of package names included in the "land4health" meta-package.

Examples

l4h_packages()

Extract Global PM2.5 (monthly) from Google Earth Engine

Description

Extracts monthly PM2.5 concentrations for a user-defined region and time range from the Earth Engine Community Catalog dataset Global PM2.5 (V6GL02 CNN). Each monthly image is summarized over the region using a selected statistic (e.g., mean/median). The function returns either an sf or a tibble, with dates normalized to the first day of each month.

Usage

l4h_pm2_5(
  from,
  to,
  region,
  scale = 1000,
  stat = "mean",
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Details

This function queries the Global PM2.5 monthly product (V6GL02, CNN‐based fusion) from the GEE Community Catalog and aggregates it over the provided region and dates. The dataset provides monthly surface PM2.5 concentrations (µg/m^3). Values are returned in native units (no extra scale factor is applied here).

Notes

• Dates are validated (YYYY-MM-DD) and constrained to the dataset range used in this package (default: 2000–2019).

• Output dates are normalized to the first day of each month found in the bands.

• The function expects a reasonable scale relative to the dataset resolution to avoid oversampling or excessive smoothing.

Value

An sf or tibble with columns:

• date (Date) — first day of the month,

• variable (character) — fixed as "pm2.5",

• value (numeric) — PM2.5 in µg/m^3, plus geometry if sf = TRUE, and any attributes from region.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

GEE Community Catalog – Global PM2.5 (V6GL02 CNN). https://gee-community-catalog.org/projects/global_pm25/

Examples

if (interactive()) {
library(land4health)
rgee::ee_Initialize()

# ROI simple (EPSG:4326)
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))), crs = 4326))

# Monthly PM2.5 (ug/m^3) for 2010, spatial mean
out_pm <- l4h_pm2_5(
  from   = "2010-01-01",
  to     = "2010-12-31",
  band   = "b1",        # ignored (single band)
  region = region,
  stat   = "mean",
  scale  = 3000
)
head(out_pm)
}

Compute Rural Access Index (RAI)

Description

Calculates the Rural Access Index (RAI) for a given region using datasets from the GEE Community Catalog. The RAI represents the proportion of the rural population living within 2 km of an all-season road, aligning with SDG indicator 9.1.1.

Usage

l4h_rural_access_index(
  region,
  weighted = FALSE,
  fun = NULL,
  sf = FALSE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Details

This function uses the following datasets from the GEE Community Catalog:

• projects/sat-io/open-datasets/RAI/ruralpopaccess/ – raster of rural population with access to all-season roads

• projects/sat-io/open-datasets/RAI/inaccessibilityindex/ – binary raster indicating access areas (1 = access, 0 = no access)

When weighted = TRUE, the RAI is calculated as the sum (or chosen summary via fun) of the accessible rural population divided by the total rural population within the specified region.

When weighted = FALSE, the RAI is calculated as the ratio of pixel areas: the total area (in in km^2) with access divided by the total rural area.

The fun parameter only applies when weighted = TRUE. It will be ignored otherwise.

Value

A spatial object containing the computed RAI value for the region in an sf or tibble object.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

GEE Community Catalog: https://gee-community-catalog.org/projects/rai/

Frontiers in Remote Sensing (2024): doi:10.3389/frsen.2024.1375476

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define a bounding box region in Ucayali, Peru
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326
))

# Population-weighted RAI
rai_w <- l4h_rural_access_index(
    region = region,
    weighted = TRUE,
    fun = "sum",
    sf = TRUE)
head(rai_w)

# Area-based RAI
rai <- l4h_rural_access_index(
    region = region,
    weighted = FALSE,
    sf = TRUE)
head(rai)
}

Download and process evapotranspiration data

Description

This function accesses the geeSEBAL-MODIS collection published by the ET-Brasil project, extracts the etp band (daily evapotranspiration in mm/day), and allows temporal aggregation by 8-day images or monthly or yearly composites period. Optionally, results can be returned as sf/tibble objects in R.

Usage

l4h_sebal_modis(
  from,
  to,
  by = "8 days",
  region,
  fun = "mean",
  sf = TRUE,
  force = FALSE,
  quiet = FALSE,
  ...
)

Arguments

Value

A sf or tibble object with etp values.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

• Comini,B., Ruhoff,A., Laipelt,L., Fleischmann,A., Huntington,J., Morton,C., Melton,F., Erickson,T., Roberti,D., Souza,V., Biudes,M., Machado,N., Santos,C. & Cosio,E. (2023). geeSEBAL‑MODIS: Continental‑scale evapotranspiration based on the surface energy balance for South America. Preprint. DOI: 10.13140/RG.2.2.17579.11041

• geeSEBAL‑MODIS v0‑02 dataset. Licensed under the Creative Commons Attribution 4.0 International (CC‑BY‑4.0) license.

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define a bounding box region in Ucayali, Peru
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326
))

# 1. Eight-day composites (8 days)
# 2020-01-01 → 2020-12-31, reducer = "mean"
sebal_8d <- l4h_sebal_modis(
  from   = "2020-01-01",
  to     = "2020-12-31",
  region = region
)

# 2. Monthly means
# Same period, but aggregated to calendar months
sebal_month <- l4h_sebal_modis(
  from   = "2020-01-01",
  to     = "2020-12-31",
  by     = "month",
  region = region
)

# 3. Annual evapotranspiration
# 2015 → 2022, one value per year
sebal_annual <- l4h_sebal_modis(
  from   = "2015-01-01",
  to     = "2022-12-31",
  by     = "annual",
  fun    = "sum",
  region = region,
  sf     = FALSE
)

}

Extracts Land Surface Temperature (LST) from MODIS MOD11A1

Description

Extracts daytime or nighttime Land Surface Temperature (LST) for a user-defined region and time range using the MODIS MOD11A1.061 product. The function supports summarizing the temperature data over each date (or each month) using a selected statistic (e.g., mean or median).

Usage

l4h_surface_temp(
  from,
  to,
  region,
  band = "day",
  level = "strict",
  by = "day",
  scale = 1000,
  stat = "mean",
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Details

The MODIS MOD11A1.061 product provides daily Land Surface Temperature and quality information. This function filters out low-quality or cloud-contaminated pixels based on the QC_Day or QC_Night band.

When by = "month", for each calendar month in ⁠[from, to]⁠ the function:

1. Filters the daily collection to that month.

2. Applies the same quality mask used for daily extraction to every image.

3. Reduces the masked images to a single monthly image using the reducer implied by stat.

Because masking happens before reducing, a cloudy day never drags the monthly value down or up — it simply does not contribute a pixel to that month's calculation.

LST values are originally stored as Kelvin multiplied by 0.02. This function automatically converts them to degrees Celsius using the formula: ⁠LST = (value x 0.02) - 273.15⁠.

Value

A sf or tibble object with LST values (in degrees Celsius) extracted from MODIS MOD11A1, at daily or monthly resolution depending on by.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

References

Wan, Z., Hook, S., & Hulley, G. (2015). MOD11A1 MODIS/Terra Land Surface Temperature and Emissivity Daily L3 Global 1km SIN Grid V006 (Version 6.1). NASA EOSDIS Land Processes DAAC. doi:10.5067/MODIS/MOD11A1.061

MODIS MOD11A1.061 - Google Earth Engine Dataset Catalog. https://developers.google.com/earth-engine/datasets/catalog/MODIS_061_MOD11A1

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326
))

# Daily (unchanged default behaviour)
lst_day <- l4h_surface_temp(
  from = "2020-01-01", to = "2020-12-31",
  region = region, band = "day", stat = "mean")

# Monthly
lst_month <- l4h_surface_temp(
  from = "2020-01-01", to = "2020-12-31",
  region = region, band = "day", stat = "mean", by = "month")

head(lst_month)
}

Extract TerraClimate variables (monthly) from Google Earth Engine

Description

Extracts one or more TerraClimate variables for a user-defined region and time range from the Earth Engine dataset IDAHO_EPSCOR/TERRACLIMATE. The function summarizes each monthly image over the region using a chosen statistic (e.g., mean/median), applies the appropriate scale factors to return values in native units, and returns an sf or tibble.

Usage

l4h_terra_climate(
  from,
  to,
  band,
  region,
  scale = 1000,
  stat = "mean",
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

An sf or tibble with columns:

• date (Date, first day of the month),

• variable (character, TerraClimate code),

• value (numeric, in native units with scale factors applied), plus geometry if sf = TRUE, and any attributes from region.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

Abatzoglou, J. T., Dobrowski, S. Z., Parks, S. A., & Hegewisch, K. C. (2018). TerraClimate, a high-resolution global dataset of monthly climate and climatic water balance from 1958–2015. Scientific Data, 5, 170191. doi:10.1038/sdata.2017.191

Examples

if (interactive()) {
library(land4health)
rgee::ee_Initialize()

# ROI simple (EPSG:4326)
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))), crs = 4326))

# Monthly precipitation (mm) 2020, spatial mean
out_pr <- l4h_terra_climate(
  from = "2020-01-01",
  to   = "2020-12-31",
  band = "pr",
  region = region,
  stat = "mean",
  scale = 5000
)
head(out_pr)

# Multiple variables: Tmax (C) + VPD (kPa)
out_multi <- l4h_terra_climate(
  from = "2019-01-01",
  to   = "2019-12-31",
  band = c("tmmx","vpd"),
  region = region,
  stat = "median",
  scale = 5000
)
}

Internal wrapper around rgee::rdate_to_eedate Mockable with with_mocked_bindings in tests.

Description

Internal wrapper around rgee::rdate_to_eedate Mockable with with_mocked_bindings in tests.

Usage

l4h_to_eedate(x)

Travel Time to Healthcare or Cities (Oxford Dataset)

Description

Retrieves the travel time raster (in minutes) to the nearest healthcare facility or populated city, based on the Oxford Global Map of Accessibility datasets.

Usage

l4h_travel_time(
  region,
  destination = "cities",
  transport_mode = "all",
  fun = "mean",
  sf = FALSE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

A spatial object containing the computed RAI value for the region in an sf or tibble object.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

• Weiss, D.J. et al. (2018). A global map of travel time to cities to assess inequalities in accessibility in 2015. Nature, 553(7688), 333–336. DOI: 10.1038/nature25181

• Weiss, D.J. et al. (2020). Global maps of travel time to healthcare facilities. Nature Medicine, 26, 1835–1838. DOI: 10.1038/s41591-020-1059-1

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define a bounding-box region in Ucayali, Peru
region <- st_as_sf(
  st_sfc(
    st_polygon(list(matrix(
      c(
        -74.1, -4.4,
        -74.1, -3.7,
        -73.2, -3.7,
        -73.2, -4.4,
        -74.1, -4.4
      ), ncol = 2, byrow = TRUE
    )))
  ),
  crs = 4326
)

# Travel time to nearest healthcare facility (all modes)
result_hosp_all <- l4h_travel_time(region = region)
head(result_hosp_all)

# Travel time to nearest healthcare facility (walking only)
result_hosp_walk <- l4h_travel_time(
  region        = region,
  destination   = "healthcare",
  transport_mode = "walking_only")

head(result_hosp_walk)

# Mean travel time to nearest cities (mixed modes)
result_city_mean <- l4h_travel_time(
  region      = region,
  destination = "cities",
  fun         = "mean")

head(result_city_mean)

# Sum of travel time to nearest cities
result_city_sum <- l4h_travel_time(
  region      = region,
  destination = "cities",
  fun         = "sum")

head(result_city_sum)
}

Calculates the Surface Urban Heat Island (SUHI) index using MODIS LST and GHS-SMOD

Description

Computes the SUHI (Surface Urban Heat Island) index as the difference between the mean land surface temperature (LST) in urban and rural areas for each date in a user-defined region and time range.

Usage

l4h_urban_heat_index(
  from,
  to,
  region,
  band = "day",
  level = "strict",
  stat = "max",
  scale = 1000,
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

A tibble or sf object with columns: date, variable = "SUHI", and value (°C).

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define a bounding box region (Ucayali, Peru)
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326
))

# Calculate SUHI using daytime LST (mean temperature difference)
suhi_day <- l4h_urban_heat_index(
  from = "2020-01-01",
  to = "2020-12-31",
  region = region,
  band = "day",
  stat = "mean"
)
head(suhi_day)

# Calculate SUHI using nighttime LST (max difference)
suhi_night <- l4h_urban_heat_index(
  from = "2020-01-01",
  to = "2020-12-31",
  region = region,
  band = "night",
  stat = "max"
)
head(suhi_night)
}

Extracts surface areas by urban and rural categories from GHS-SMOD

Description

Calculates the surface area (in km2) of urban, rural, or all settlement classes every 5 years between 1985 and 2030 using the GHS-SMOD R2023A dataset. This product applies the Degree of Urbanization methodology (Stage I) to the GHS-POP R2023A and GHS-BUILT-S R2023A layers. The function summarizes areas by category and year over the specified region.

Usage

l4h_urban_rural_area(
  region,
  category = "all",
  scale = 1000,
  sf = TRUE,
  quiet = FALSE,
  force = FALSE,
  ...
)

Arguments

Value

A tibble with estimated settlement area (in km2) by year and category.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

References

• European Commission, Joint Research Centre (JRC). GHS Settlement Grid R2023A (1975–2030). Available at: https://data.jrc.ec.europa.eu/dataset/a0df7a6f-49de-46ea-9bde-563437a6e2ba#dataaccess

Examples

if (interactive()) {
library(land4health)
ee_Initialize()

# Define region as a bounding box (Ucayali, Peru)
region <- st_as_sf(st_sfc(
  st_polygon(list(matrix(c(
    -74.1, -4.4,
    -74.1, -3.7,
    -73.2, -3.7,
    -73.2, -4.4,
    -74.1, -4.4
  ), ncol = 2, byrow = TRUE))),
  crs = 4326
))

# Extract surface area of urban category (in km2)
urban_area <- l4h_urban_rural_area(
  category = "urban",
  region = region)

head(urban_area)

# Extract surface area of rural category (in km2)
rural_area <- l4h_urban_rural_area(
  category = "rural",
  region = region)

head(rural_area)

# Extract total surface area (urban + rural) (in km2)
all_area <- l4h_urban_rural_area(
  category = "all",
  region = region)

head(all_area)
}

Configure Python environment for land4health

Description

Sets up the Python environment automatically based on installation.

Usage

l4h_use_python(envname = NULL, method = NULL, quiet = FALSE)

Arguments

Value

Invisibly returns NULL

Examples

if (interactive()) {
l4h_use_python()
l4h_use_python("r-land4health", "virtualenv")
}

Extract vegetation indices from MODIS MOD13A1

Description

Computes monthly or annual areal statistics of vegetation indices (NDVI, EVI, or SAVI) from MODIS MOD13A1 (500 m, 16-day composite) for a given spatial region, applying quality filtering via the DetailedQA bitmask.

Usage

l4h_vegetation(
  region,
  from,
  to,
  band = c("NDVI", "EVI", "SAVI"),
  by = c("month", "year"),
  fun = c("mean", "max", "min", "median", "sum", "sd", "first"),
  scale = 500,
  sf = FALSE,
  quiet = FALSE,
  force = FALSE
)

Arguments

Details

Temporal aggregation

MODIS MOD13A1 produces one composite every 16 days. This function aggregates those composites into a coarser temporal unit:

• by = "month": All 16-day images within each calendar month are reduced to a single image using max() (maximum value composite), yielding one value per region per month.

• by = "year": All 16-day images within each calendar year are reduced to a single image using max(), yielding one value per region per year.

The fun argument controls the spatial (zonal) statistic applied over each region polygon, and is independent of the temporal aggregation.

Quality filtering

Applied through the DetailedQA bitmask of MODIS/061/MOD13A1:

• Bits 0-1: VI quality (value 2 = not produced/cloudy, excluded).

• Bit 14: Adjacent cloud detected (excluded).

• Bit 15: Possible shadow (excluded).

Scale factors

• NDVI and EVI: multiplied by 0.0001.

• SAVI: computed on-the-fly from surface reflectance bands sur_refl_b01 (red) and sur_refl_b02 (NIR), L = 0.5.

Value

A tibble (or sf tibble if sf = TRUE) in long format:

<id_cols>

Original attribute columns from region.

date

Date object. First day of each month (by = "month") or first day of each year (by = "year").

variable

Name of the vegetation index (e.g. "NDVI").

value

Computed zonal statistic for that region and period.

Credits

Pioneering geospatial health analytics and open-science tools. Developed by the Innovalab Team. For more information, send an email to imt.innovlab@oficinas-upch.pe.

Follow us on:

• Innovalab Linkedin

• Innovalab X

• Innovalab facebook

• Innovalab instagram

• Innovalab tiktok

• Innovalab Podcast

Examples

if (interactive()) {
library(land4health)
library(geoidep)

rgee::ee_Initialize(quiet = TRUE)

provinces <- get_provinces(show_progress = FALSE) |>
  subset(nombdep == "LORETO")

# Monthly mean NDVI
result_monthly <- provinces |>
  l4h_vegetation(
    from = "2010-01-01",
    to   = "2012-12-31",
    band = "NDVI",
    by   = "month",
    fun  = "mean",
    sf   = TRUE
  )

 head(result_monthly)

# Annual mean NDVI
result_annual <- provinces |>
  l4h_vegetation(
    from = "2010-01-01",
    to   = "2020-12-31",
    band = "NDVI",
    by   = "year",
    fun  = "mean",
    sf   = TRUE
  )

 str(result_annual)

}

Internal: Safe toBands with band count check

Description

Internal: Safe toBands with band count check

Usage

safe_toBands(collection, max_bands = 5000)

Arguments

Value

An ee$Image with named bands.

Split an sf object into a list of single-row sf objects

Description

Split an sf object into a list of single-row sf objects

Usage

split_sf(sf_region)

Arguments

Value

A list of single-row sf objects.