epwshiftr

June 24, 2026 · View on GitHub

R build status CRAN status Codecov test coverage CRAN Download Badge

Shift weather files with climate projection data and generate future EPW files.

epwshiftr helps you request climate projection data, collect file records in a local store, extract site-level climate variables, morph a baseline EnergyPlus Weather (EPW) file, and write shifted future EPW files. The recommended user-facing path is the shift_* workflow.

Installation

You can install the latest stable release of epwshiftr from CRAN.

install.packages("epwshiftr")

Alternatively, you can install the development version from R-universe.

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

The current development line and the next CRAN release use the new store-native implementation. If you need the old data.table-oriented workflow, use the legacy branch on GitHub or install epwshiftr v0.1.4.

Quick start

The shift_* workflow keeps the complete process readable: create a site, request climate data, collect file records, extract the needed site data, morph, and write EPW outputs. Each stage returns an inspectable object and carries the internal store IDs forward automatically.

library(epwshiftr)

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

site <- shift_site(
    id = "SIN",
    label = "singapore",
    epw = epw
)

req <- shift_request(
    provider = "esgf",
    project = "CMIP6",
    source = "EC-Earth3",
    experiment = "ssp585",
    variant = "r1i1p1f1",
    variables = epw_morph_variables("recommended"),
    frequency = "mon",
    time = c("2060-01-01T00:00:00Z", "2060-12-31T23:59:59Z"),
    filters = list(activity_id = "ScenarioMIP", table_id = "Amon")
)

epws <-
    req |>
    shift_collect(store = "cache/singapore-store") |>
    shift_extract(site = site, periods = epw_morph_periods(`2060s` = 2060L)) |>
    shift_morph(baseline = site, strict = TRUE) |>
    shift_epw()

shift_status(epws)
shift_outputs(epws)

This example uses monthly CMIP6 Amon records and the recommended EPW morphing variable set. The code is not evaluated when building the README because it performs live ESGF queries and remote data reads.

Inspect a workflow

Use these helpers when you want to inspect a stage before continuing or diagnose why a stage is blocked.

shift_status(epws)
shift_diagnostics(epws)
shift_outputs(epws)

extracted <- req |>
    shift_collect(store = "cache/singapore-store") |>
    shift_extract(site = site, periods = epw_morph_periods(`2060s` = 2060L))

shift_coverage(extracted)
shift_data(extracted)
shift_ids(extracted)

morphed <- shift_morph(extracted, baseline = site, strict = TRUE)
shift_data(morphed)

epws <- shift_epw(morphed)
shift_outputs(epws)
shift_data(epws)

shift_ids() exposes underlying manifest IDs for advanced debugging, but normal workflows should not require users to pass query_id, plan_id, summary_id, or morph_id by hand.

To keep a complete local copy of the source NetCDF files, insert shift_download() after shift_collect(). This is optional for the normal single-site workflow because shift_extract() reads through OPeNDAP first and only falls back to HTTP downloads when fallback = "auto" and remote access is unavailable.

Advanced workflows

The shift_* functions are a thin user-facing facade over lower-level engines:

  • EsgQuery builds and collects ESGF queries.
  • EsgStore manages file records, downloads, extraction plans, and artifacts.
  • EpwMorpher summarises climate data, builds morphing plans, runs morphing, and writes EPW files.

Use those lower-level objects when you need to inspect or tune manifests, download candidate selection, extraction coverage, morphing factors, or output registration. See Create Future EPW Files for the expanded query/download/extract/morph/write path.

Legacy workflow

The older workflow based on init_cmip6_index(), summary_database(), extract_data(), morphing_epw(), and future_epw() belongs to the legacy implementation. It is no longer the recommended README path.

Use the legacy branch on GitHub or epwshiftr v0.1.4 if you need that workflow unchanged while migrating to the store-native API.

How to cite

To cite epwshiftr in publications use:

Jia, Hongyuan, Chong, Adrian, Ning, Baisong, 2023.
Epwshiftr: incorporating open data of climate change prediction into building performance simulation for future adaptation and mitigation,
in: Proceedings of Building Simulation 2023: 18th Conference of IBPSA, Building Simulation.
Presented at the Building Simulation 2023, IBPSA, Shanghai, China, pp. 3201-3207.
https://doi.org/10.26868/25222708.2023.1612

A BibTeX entry for LaTeX users is:

@inproceedings{jia2023epwshiftr,
  title = {Epwshiftr: Incorporating Open Data of Climate Change Prediction into Building Performance Simulation for Future Adaptation and Mitigation},
  shorttitle = {Epwshiftr},
  booktitle = {Proceedings of {{Building Simulation}} 2023: 18th {{Conference}} of {{IBPSA}}},
  author = {Jia, Hongyuan and Chong, Adrian and Ning, Baisong},
  year = {2023},
  series = {Building {{Simulation}}},
  volume = {18},
  pages = {3201--3207},
  publisher = {{IBPSA}},
  address = {{Shanghai, China}},
  doi = {10.26868/25222708.2023.1612}
}

Author

Hongyuan Jia and Adrian Chong

License

  • epwshiftr

    epwshiftr is released under the terms of MIT License.

    Copyright (c) 2019-2024 Hongyuan Jia and Adrian Chong

  • CMIP6 data

    To enable modeling groups and others who support CMIP6 to demonstrate its impact (and secure ongoing funding), you are required to cite and acknowledge those who have made CMIP6 possible. You also must abide by any licensing restrictions, which are recorded in each file as a global attribute (named “license”).

    Please carefully read and adhere to the CMIP6 Terms of Use.

Disclaimer

CMIP6 model data is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. Consult Terms of Use for terms of use governing CMIP6 output, including citation requirements and proper acknowledgment. Further information about each GCM output data, including some limitations, can be found via the further_info_url recorded as a global attribute in the NetCDF file. The data producers and data providers make no warranty, either express or implied, including, but not limited to, warranties of merchantability and fitness for a particular purpose. All liabilities arising from the supply of the information, including any liability arising in negligence, are excluded to the fullest extent permitted by law.

Contribute

If you encounter a clear bug or have questions about the usage, please file an issue with a minimal reproducible example on GitHub.

If you have a solution for an existing bug or an implementation for a missing feature, please send a pull request and let us review.

Please note that the ‘epwshiftr’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.