epwshiftr

epwshiftr is an R package for generating future EnergyPlus Weather (EPW) files from CMIP6 climate projections and baseline weather, for use in building simulation.

Features

  • Discover climate data from ESGF for the variables, models and periods your method needs.
  • Extract site data through OPeNDAP where available, without downloading whole climate files.
  • Choose weather-generation methods at monthly, daily and hourly scales.
  • Run batches across locations, models, scenarios and methods.
  • Reuse and inspect work with local caches, resumable workflows and source tracking, through R or the CLI.

Installation

Install the development version used below:

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

For CRAN v0.1.4, see the migration guide.

Example

Generate weather for Singapore and San Francisco using two monthly methods. Place your baseline EPWs in the working directory; this example uses Singapore IWEC and San Francisco TMY3. Missing baseline precipitation is retained with precipitation = "off".

library(epwshiftr)

batch <- shift_epw_future(
    sites = list(
        shift_site("Singapore", epw = "Singapore.epw"),
        shift_site("SanFrancisco", epw = "SanFrancisco.epw")
    ),
    climate = shift_cmip6(model = "IPSL-CM6A-LR", scenarios = "ssp245"),
    periods = list(`2060s` = 2055:2065),
    transform = list(
        monthly_transform("original_morphing", precipitation = "off"),
        monthly_transform("bws_btws")
    ),
    reference = historical_reference(1995:2014),
    dir = "future-epw-batch",
    store = "store",
    control = shift_control(
        download = "never",
        resume = FALSE,
        overwrite = TRUE
    )
)

Actual terminal recording of two-city future EPW generation.

Actual terminal recording of shift_epw_future(), regenerated from cached climate inputs. Playback is accelerated 4×, with long waits shortened.

shift_status(batch)
#> [1] "completed"
outputs <- shift_outputs(batch)
outputs[, .(
    site_id, method, model, period,
    epw_exists = file.exists(export_path)
)]
#>         site_id            method        model period epw_exists
#>          <char>            <char>       <char> <char>     <lgcl>
#> 1: SanFrancisco original_morphing IPSL-CM6A-LR  2060s       TRUE
#> 2: SanFrancisco          bws_btws IPSL-CM6A-LR  2060s       TRUE
#> 3:    Singapore original_morphing IPSL-CM6A-LR  2060s       TRUE
#> 4:    Singapore          bws_btws IPSL-CM6A-LR  2060s       TRUE
summary <- shift_summary(batch, weather = TRUE)
summary[, .(site_id, method, weather_hours, mean_temperature_c)]
#>         site_id            method weather_hours mean_temperature_c
#>          <char>            <char>         <int>              <num>
#> 1: SanFrancisco original_morphing          8760           15.42045
#> 2: SanFrancisco          bws_btws          8760           15.42045
#> 3:    Singapore original_morphing          8760           28.28410
#> 4:    Singapore          bws_btws          8760           28.28410
shift_diagnostics(batch)[, .N, by = severity]
#>    severity     N
#>      <char> <int>
#> 1:  warning     1
#> 2:     info     2

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.

Report an issue.