Attach gridded weather variables from NASA POWER to rows of an event table. The function:
standardizes/validates time input (single timestamp column or multiple time columns),
plans efficient provider calls by clustering locations (default) and splitting sparse time ranges,
caches downloaded weather segments locally and reuses them,
joins weather back to events using exact or rolling joins.
join_weather(
x,
params,
time,
lat_col = "lat",
lon_col = "lon",
time_api = c("guess", "hourly", "daily"),
tz = "UTC",
roll = c("nearest", "last", "none"),
roll_max_hours = NULL,
spatial_mode = c("cluster", "exact", "by_group"),
group_col = NULL,
cluster_radius_m = 250,
site_elevation = c("constant", "auto"),
elev_constant = 100,
elev_fun = NULL,
community = "ag",
cache_scope = c("user", "project"),
cache_dir = NULL,
verbose = FALSE,
...
)A data.table with weather columns appended. Rows with missing/invalid inputs keep their original values and receive NA weather.
A data.frame/data.table with event rows.
Character vector of NASA POWER parameter codes (e.g. "T2M").
A single column name containing time (POSIXct/Date/character/numeric) OR
a character vector of column names used to assemble a timestamp (e.g. c("YEAR","MO","DY","HR")).
Column names for latitude and longitude (decimal degrees).
One of "guess", "hourly", "daily". If "daily" is chosen
while the input contains time-of-day information, timestamps are downsampled to dates (with a fixed hour).
If "hourly" is chosen but the input has no time-of-day information, an error is raised.
Time zone used to interpret/construct input timestamps (default "UTC"). Weather is requested
from NASA POWER in UTC.
Join behaviour when matching timestamps: "nearest" (default, recommended), "last", or "none" (exact).
Rolling is applied when joining hourly weather to event times.
Maximum allowed time distance (hours) for a rolling match. If NULL, a safe default is used: 1 hour for hourly joins and 24 hours for daily joins.
How to reduce many points to representative locations before calling POWER:
"cluster" (default), "exact", or "by_group".
Clustering reduces accidental explosion of provider calls and matches POWER's coarse spatial resolution.
Grouping column used when spatial_mode="by_group".
Clustering radius in meters when spatial_mode="cluster".
Elevation strategy for POWER calls: "constant" or "auto".
Elevation is resolved for representative locations and becomes part of the cache identity.
Constant elevation (meters) used when site_elevation="constant" and as a fallback for "auto".
Optional function function(lon, lat, ...) returning elevation (meters) for representative points.
Passed to nasapower::get_power() (e.g. "ag").
Where to store cache by default: "user" or "project".
Optional explicit cache directory. If NULL, determined by cache_scope.
If TRUE, print progress messages.
Passed through to nasapower::get_power().
wj_cache_list, wj_cache_clear, weatherjoin_options