Skip to contents

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

Source: R/l4h_pm2_5.R
l4h_pm2_5.Rd

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

from

Character or Date. Start date ("YYYY-MM-DD").

to

Character or Date. End date ("YYYY-MM-DD").

region

Spatial object defining the region of interest. Accepts an sf, sfc, or SpatVector object.

scale

Numeric. Reducer scale in meters. Default 1000. (Use a value close to the dataset's native grid; typical choices are a few km.)

stat

Character. Summary statistic per image per region. One of "mean", "median", "min", "max".

sf

Logical. If TRUE, returns an sf; if FALSE, returns a tibble. Default TRUE.

quiet

Logical. If TRUE, suppresses progress bars/messages. Default FALSE.

force

Logical. If TRUE, skips the representativity check (polygons smaller than 1 pixel are still extracted, only a warning is issued). Default FALSE.

...

Additional arguments passed to the extraction backend.

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.

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.

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:

References

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

Examples

# \donttest{
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)
}
# }