Create independent annual weather files without a baseline EPW or GCM. This first implementation supports hourly ERA5 single-level data and whole-hour standard timezone offsets, without daylight saving time.
A shift_era5() specification for product = "single_levels".
Leave variables and frequency unset. Its years select local calendar years.
One shift_site() or a list of sites. Each site's metadata
must provide timezone (standard UTC offset in hours) and elevation
(metres). Optional state and country appear in the EPW header.
Directory for source caches, immutable conversion attempts and receipts.
Optional local NetCDF path(s), an explicit data bundle, or a named
list of those inputs keyed by site ID. Local input never contacts CDS.
A bundle contains data (a data.frame), units (a named character vector),
grid (latitude/longitude), interval_seconds = 3600, and optional
provenance. Its columns are utc_time (ordered POSIXct validity times),
tas, tdps, ps, uas, vas, rsds, fdir, rlds,
clt, and pr. NetCDF input must already use the hourly ERA5
single-level validity-time convention; forecast-step/ensemble dimensions
must be resolved before calling. No implicit accumulation reset is inferred.
With NULL, the existing CDS transport retrieves small monthly requests;
this is not a bulk-download accelerator.
Keep February 29 (8784 hours in leap years), or drop it for a 8760-hour calendar. The omitted source hours remain in an artifact.
"calendar" uses the actual January 1 weekday. Alternatively
supply an English weekday, e.g. "Monday", for a fixed simulation schedule.
Default "missing" leaves EPW liquid precipitation
missing because ERA5 total precipitation does not resolve its phase.
"total_water_equivalent" explicitly writes that total into the liquid
precipitation field, with a provenance warning.
Reuse successful results only when inputs, implementation, options and all output hashes match.
A data.table with one row per site/year, status, reuse flag, EPW and
receipt paths, and any error. Partial failures are retained and warned.
complete means conversion and EPW readback passed, not building validation.
Instantaneous variables are assigned at hour end. Radiation and precipitation cover the preceding hour: accumulated radiation in J/m2 is divided by 3600; hourly mean W/m2 and hourly Wh/m2 have the same numeric EPW value. FDIR is direct horizontal radiation. Diffuse radiation is SSRD minus FDIR; DNI uses the shared hourly solar projection at the target site's coordinates. Negative energy, inconsistent fields, missing hours and impossible DNI fail that annual job without clipping or substituting weather.
Relative humidity uses the ECMWF liquid-water saturation relation, including below freezing. Original dew point is retained. EnergyPlus interprets RH using a different saturation relation below freezing; the accompanying hourly diagnostics quantify the resulting humidity-ratio difference. Thus a complete conversion does not establish moisture equivalence for building simulation. Grid values are not elevation-adjusted to the target site.
Unsupported weather fields use documented EPW missing sentinels. Ground temperatures, design conditions, holidays and typical/extreme periods are not fabricated. These and precipitation/snow assumptions must be configured as appropriate in the simulation model. This creates reanalysis annual weather, not observations or a typical meteorological year. Leap-day removal changes calendar continuity; original timestamps and omitted hours remain available. Solar conversion uses each source record's original calendar date.
site <- shift_site("example", lon = 113.3, lat = 23.2,
metadata = list(timezone = 8, elevation = 10))
if (FALSE) { # \dontrun{
shift_epw_reanalysis(shift_era5(1995), site, "reference-weather",
data = c("instantaneous.nc", "accumulated.nc"))
} # }