epwshiftr

Generate future EnergyPlus weather files from CMIP6 climate projections.

epwshiftr is an R package that combines a baseline EnergyPlus Weather (EPW) file with projected climate changes to produce future weather for building simulation. Use the R API or CLI to select methods and models, follow progress, and inspect or resume work saved in a local store.

Recorded with the package’s own terminal UI and scripted states; model selection, timings, and counts are illustrative.

Quick start · Methods and models · CLI · Documentation

Installation

This README describes the development API. Install the development build from R-universe:

install.packages(
    "epwshiftr",
    repos = c(
        ideaslab = "https://ideas-lab-nus.r-universe.dev",
        cran = "https://cran.r-project.org"
    )
)

Released versions are available on CRAN. For the older v0.1.4 API, see the legacy branch and migration guide.

Quick start

Start with original monthly morphing, one compatible climate model, and two scenarios. This example uses a bundled Singapore EPW; an EnergyPlus installation is not required. Climate data access requires an internet connection.

library(epwshiftr)

epw <- system.file(
    "extdata/examples/SGP_Singapore.486980_IWEC.epw",
    package = "epwshiftr",
    mustWork = TRUE
)

run <- shift_future_epw(
    epw = epw,
    climate = shift_cmip6(model = 1L, scenarios = c("ssp126", "ssp585")),
    periods = list(`2060s` = 2055:2065),
    methods = "original_morphing",
    dir = "future-epw"
)

shift_outputs(run)      # Delivered EPW paths and method/model identity
shift_diagnostics(run)  # Warnings and coverage issues

The workflow finds matching future and historical CMIP6 inputs, applies the chosen transform, and writes EPWs to future-epw. Replace epw with your own baseline file for a different site. Repeating the same completed request with the same store reuses its verified outputs.

For longer jobs, add background = TRUE and follow progress with shift_watch(run). See the workflow guide for planning, output inspection, and recovery.

Methods and models

Use weather_transforms() to browse monthly, daily, and hourly configurations, including their input requirements and production / experimental status. For method-specific settings, use monthly_transform(), daily_transform(), or hourly_transform() through the transform argument.

To run several methods across the same compatible models:

batch <- shift_future_epw(
    epw = epw,
    climate = shift_cmip6(model = 2L, scenarios = c("ssp126", "ssp585")),
    periods = list(`2060s` = 2055:2065),
    methods = c("original_morphing", "qdm"),
    calibration = shift_era5(years = 1995:2014),
    dir = "future-epw-batch"
)

Here, QDM uses ERA5 observations and is marked experimental. Configure CDS access before running it. A positive model count selects that many compatible models; a character vector names exact models, and NULL selects all.

Model discovery uses one live panel for all methods. It identifies the current variable combination and future/historical coverage check. Catalog records, cached responses, downloaded files, and generated EPWs have separate counts; method numbers indicate search order, not a completion percentage.

Watch model discovery and coverage checks

This recording uses the production UI with scripted catalog responses.

Each method/model child can be inspected and resumed independently. Output tables preserve method and model identity; cases and EPW files are counted separately because multi-year methods can write several files per case. Use shift_history() to find saved work and shift_summary(batch, weather = TRUE) to compare local EPW summaries with valid-hour counts.

Watch batch progress, reuse, and recovery diagnostics

The same terminal UI shows a four-child batch, followed by a larger matrix with active, failed, and cancelled children. Scripted states illustrate progress, reuse, height limits, and recovery diagnostics.

Command line

Install the optional launcher from R with install_cli() and put its reported directory on PATH. The CLI uses the same methods and workflow engine:

epwshiftr morph transforms
epwshiftr morph describe --scale daily --method qdm
epwshiftr shift config example --output workflow.json

Edit workflow.json for your baseline EPW, scenarios, periods, and output directory, then validate and run it:

epwshiftr shift config validate --config workflow.json
epwshiftr shift run --config workflow.json
epwshiftr shift list --type batch
epwshiftr shift summary --batch <batch_id> --weather

For multiple methods and models, generate a config with --methods original_morphing,qdm --model 2. The CLI guide covers ERA5 setup, background jobs, --run / --batch monitoring and resume, and JSON output for automation.

Documentation

Task	Guide
Plan, run, inspect, or resume a workflow	Future EPW workflow
Choose methods, settings, and required inputs	Weather transformations
Configure terminal output and background jobs	Live feedback
Automate workflows from the shell	CLI guide
Diagnose access, coverage, or download failures	Troubleshooting
Find every function and argument	API reference

Citation and license

Jia, H., Chong, A., and Ning, B. (2023). Epwshiftr: Incorporating Open Data of Climate Change Prediction into Building Performance Simulation for Future Adaptation and Mitigation. Building Simulation 2023, pp. 3201–3207. DOI: 10.26868/25222708.2023.1612. Run citation("epwshiftr") for the full citation and BibTeX entry.

Developed by Hongyuan Jia and Adrian Chong. The package is released under the MIT license. Climate data has separate terms: follow the official CMIP licensing and citation guidance and the terms of any calibration dataset you use.

Get help and contribute

Report an issue with a minimal reproducible example, or submit a pull request following the contributing guide and Code of Conduct.