Skip to contents

Import MERRA-2 Pollution Data for Brazilian Municipalities

Source: R/sus_grid_pollution_merra2.R
sus_grid_pollution_merra2.Rd

sus_grid_pollution_merra2() downloads, spatially aggregates, and caches NASA MERRA-2 aerosol and air quality data for Brazilian municipalities.

MERRA-2 (Modern-Era Retrospective Analysis for Research and Applications v2) from NASA GMAO provides global atmospheric reanalysis from 1980 to present at 0.625\(\times\)0.5\(^\circ\) (~55 km). It is the longest available reanalysis record for aerosol and pollution studies, making it ideal for historical trend analysis and cross-validation with higher- resolution products such as CAMS or GHAP.

Supported variables:

  • PM2.5 ("pm25") – derived from aerosol mass components (\(\mu g/m^3\)): DUSMASS25 + SSSMASS25 + BCSMASS + 1.4*OCSMASS + SO4SMASS, each multiplied by 1\(\times\)10^9 to convert kg/m\(^3\) to \(\mu g/m^3\).

  • AOD ("aod") – Total aerosol optical depth at 550 nm (TOTEXTTAU), dimensionless, proxy for total aerosol column.

  • SO2 ("so2", experimental) – sulfate surface mass concentration from M2I3NVAER (\(\mu g/m^3\)).

Usage

sus_grid_pollution_merra2(
  pollutants = c("pm25", "aod"),
  resolution = "monthly",
  years = NULL,
  months = 1:12,
  municipalities = NULL,
  raster_area = FALSE,
  agg_fun = "mean",
  earthdata_user = Sys.getenv("EARTHDATA_USER"),
  earthdata_pass = Sys.getenv("EARTHDATA_PASSWORD"),
  netrc_path = NULL,
  crop_brazil = TRUE,
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/merra2",
  lang = "pt",
  verbose = TRUE
)

Arguments

pollutants

Character vector. Variables to download. Allowed: "pm25", "aod", "so2". Default: c("pm25", "aod").

resolution

Character. Temporal resolution of source files. One of:

  • "monthly" (default) – uses M2TMNXAER, one file per month, already monthly-averaged. Recommended for most analyses.

  • "daily" – uses M2T1NXAER (hourly), one file per day; 24 hourly layers are aggregated to a single daily value using agg_fun. Note: so2 only available in monthly resolution.

years

Integer vector. Years to download (1980 to current year). NULL defaults to the last two complete years.

months

Integer vector (1-12). Months to include. Default 1:12.

municipalities

An sf POLYGON object (e.g., from geobr::read_municipality()). If provided, raster data are aggregated and a climasus_df is returned. If NULL, returns cached NetCDF paths (or a SpatRaster per raster_area).

raster_area

Only used when municipalities = NULL. One of:

  • FALSE (default) – return the character vector of cached file paths.

  • TRUE – return an in-memory terra::SpatRaster, full extent.

  • an sf POLYGON object – return the SpatRaster cropped and masked to that area.

  • a 2-letter Brazilian state code (e.g. "MT") – auto-download the state boundary via geobr (cached) and crop/mask to it.

Important: composite pollutants (currently only "pm25") are computed from several raw NetCDF component variables (e.g. dust, sea salt, black carbon, organic carbon, sulfate) via a derivation formula that is applied AFTER spatial extraction, not at the raster-cell level. To avoid silently producing an incorrect composite raster, raster_area != FALSE returns the RAW component layers as-is (one layer per NetCDF variable per file, e.g. "DUSMASS25_2020_01", "BCSMASS_2020_01", ...), NOT the final derived pollutant value. A user who needs the derived value (e.g. actual PM2.5) should either apply the same formula to the raw layers themselves, or use the normal municipalities-based tabular workflow, which already computes the derived value correctly.

agg_fun

Character. Spatial aggregation function for exactextractr::exact_extract(). Default "mean" (area-weighted).

earthdata_user

Character. Earthdata username. Defaults to Sys.getenv("EARTHDATA_USER").

earthdata_pass

Character. Earthdata password. Defaults to Sys.getenv("EARTHDATA_PASSWORD").

netrc_path

Character. Path to a .netrc file with Earthdata credentials. If provided, takes precedence over earthdata_user / earthdata_pass.

crop_brazil

Logical. Crop rasters to Brazil's bounding box before extraction to save memory. Default TRUE.

use_cache

Logical. Reuse previously downloaded NetCDF files and previously computed Parquet caches. Default TRUE.

cache_dir

Character. Root cache directory. Default "~/.climasus4r_cache/merra2".

lang

Character. Message language: "pt" (default), "en", "es".

verbose

Logical. Print progress messages. Default TRUE.

Value

  • If municipalities is provided: a climasus_df with columns code_muni, date, and one column per pollutant (e.g., pm25_merra2, aod_merra2). Metadata: stage = "climate", type = "pollution_merra2".

  • If municipalities = NULL and raster_area = FALSE (default): a named character vector of paths to cached NetCDF files.

  • If municipalities = NULL and raster_area != FALSE: a multi-layer terra::SpatRaster with the raw NetCDF component variables as layers (see raster_area for the composite-pollutant caveat), optionally cropped and masked to an area of interest.

Authentication

A free NASA Earthdata Login account is required (https://urs.earthdata.nasa.gov). Set credentials in one of two ways:

  • Environment variables (recommended):

    Sys.setenv(EARTHDATA_USER = "my_user",
               EARTHDATA_PASSWORD = "my_pass")

  • .netrc file (for pipelines), then pass its path via netrc_path:

    machine urs.earthdata.nasa.gov login my_user password my_pass

After registering, activate GES DISC access at https://disc.gsfc.nasa.gov/earthdata-login.

Data source

Gelaro, R. et al. (2017). The Modern-Era Retrospective Analysis for Research and Applications, Version 2 (MERRA-2). Journal of Climate, 30(14), 5419-5454. doi:10.1175/JCLI-D-16-0758.1
NASA/GSFC/EPS GMAO. MERRA-2 tavg1_2d_aer_Nx (M2T1NXAER v5.12.4). NASA Goddard Earth Sciences DISC. doi:10.5067/KLICLTZ8EM9D

See also

sus_grid_pollution_cams(), sus_grid_pollution_ghap(), sus_climate_anomaly(), sus_mod_dlnm()

Examples

if (FALSE) { # \dontrun{
# Set credentials
Sys.setenv(EARTHDATA_USER = "user", EARTHDATA_PASSWORD = "pass")

library(geobr)
mt_mun <- read_municipality(code_muni = "MT", year = 2020)

# Monthly PM2.5 + AOD, Q1 2020
merra2 <- sus_grid_pollution_merra2(
  pollutants    = c("pm25", "aod"),
  resolution    = "monthly",
  years         = 2020,
  months        = 1:3,
  municipalities = mt_mun,
  lang          = "pt"
)

sus_meta(merra2, "stage")  # "climate"
sus_meta(merra2, "type")   # "pollution_merra2"

# Historical PM2.5 trend 2000-2010, annual summary
merra2_hist <- sus_grid_pollution_merra2(
  pollutants = "pm25", resolution = "monthly",
  years = 2000:2010, municipalities = mt_mun, lang = "en"
)
} # }