Air Pollution Predictor Commons • appc

About

The goal of the appc package is to provide daily, high resolution, near real-time, model-based ambient air pollution exposure assessments. This is achieved by training a generalized random forest on several geomarkers to predict daily average EPA AQS concentrations from 2017 until the near-present (currently June 2026) at exact locations across the contiguous United States (see the model-performance report for more details).

APPC collects and harmonizes EPA AQS outcomes and handles model development, evaluation, and prediction. The geomarker package supplies the environmental predictors.

Installing

Install the latest stable release of appc from R-universe with:

install.packages("appc", repos = c("https://geomarker-io.r-universe.dev", "https://cloud.r-project.org"))

Install the latest, under-development version of appc from GitHub with:

# install.packages("remotes")
remotes::install_github("geomarker-io/appc")

Example

In R, create model-based predictions of ambient air pollution concentrations at exact locations on specific dates using the predict_pm25() function:

appc::predict_pm25(
  x = s2::as_s2_cell(c("8841b39a7c46e25f", "8841a45555555555")),
  dates = list(as.Date(c("2025-05-18", "2025-06-10")), as.Date(c("2025-06-22", "2025-09-20")))
)

See more examples in the timeline example.

You can also pass a geomarker s2cd object directly. Its stored dates are used:

locations <- geomarker::s2cd(
  s2::as_s2_cell(c("8841b39a7c46e25f", "8841a45555555555")),
  dates = list(as.Date(c("2025-05-18", "2025-06-10")), as.Date("2025-06-22"))
)
appc::predict_pm25(locations, keep_predictors = TRUE)

Environmental predictors

APPC uses the geomarker package for environmental predictor assessment. See its documentation for S2 location/date inputs, available geomarkers, and source-data management.

Data storage

Environmental downloads and assessment are managed by geomarker under its own R user data directory. See geomarker’s data and offline-operation documentation for cache and source-refresh options. APPC retains AQS outcomes, assembled training data, and fitted models under tools::R_user_dir("appc", "data"). Set R_USER_DATA_DIR to choose a different root for both packages.

Developing

The committed workflow has two steps:

just make_training_data
just train_model

The first script downloads and harmonizes AQS outcomes, assembles predictors with geomarker, and saves the training data. The second reads that table and fits the model. These are large, manually invoked jobs. Neither is run by package checks.

Use terra 1.9.46 or newer to avoid the compressed NetCDF extraction slowdown in earlier 1.9 versions. The training-data script normally refreshes current-year AQS outcomes. After a successful AQS refresh, you can reuse that annual cache when restarting predictor assembly:

options(appc.refresh_aqs = FALSE)
source("inst/make_training_data.R")

Install the package dependencies from the repository root:

pak::pak(".")

The model specification in inst/ records the predictors, date coverage, and exact geomarker dependency used for training. Retain the assembled training artifact to reproduce fitting after upstream AQS or weather revisions. Use a dedicated R_USER_DATA_DIR for an official build so existing local monthly MERRA overrides are not picked up unintentionally. No automatic NASA source refresh is performed.

Move existing artifacts aside before rebuilding.

Run just render_model_dash to evaluate the model. Set APPC_BUILD_MODEL_ARTICLES=true when rebuilding model-dependent pkgdown articles. Ordinary package checks skip these large jobs.