epwshiftr: Create future EnergyPlus Weather files using CMIP6 data

20 November 2021


Building energy simulation (BES) has become increasingly applied to assess building performance under climate changes and yield a more sustainable and resilient design (Yassaghi and Hoque 2019). Multiple morphing-based weather-file modification tools have been developed to integrate climate change predictions (Troup 2016). Most of the widely adopted weather generators, including CCWorldWeatherGen (Jentsch, Bahaj, and James 2008), Meteonorm (Remund et al. 2020), and WeatherShift (Dickinson and Brannon 2016), use GCM (Global Climate Models) data from the CMIP (Coupled Model Intercomparison Project) that covers worldwide locations.

Currently, the CMIP project is in its sixth phase (CMIP6) (Eyring et al. 2016), which has developed new emission scenarios that have a similar range as its fifth phase (CMIP5) but fill critical gaps for intermediate forcing levels (O’Neill et al. 2016). It will be used in the Sixth IPCC (Intergovernmental Panel on Climate Change) Climate Assessments Reports (IPCC 2021). However, existing tools based on the previous CMIP were unable to utilize the data from the latest climate change research. Currently, there are no tools available that could process user-defined climate simulations in an automated way and allow further statistical analysis.

The epwshiftr package bridges these gaps. It is a free, open-source R package for adapting a whole-building energy simulation EnergyPlus (Crawley et al. 2001) Weather (EPW) files to incorporate climate change predictions using the morphing statistical downscaling method (Belcher, Hacker, and Powell 2005). The primary goal is to automatically process large amounts of climate change prediction outputs from the CMIP6 (CMIP Phase 6) GCMs and create future climate data for BES across worldwide locations in a user-friendly and flexible way.

Epwshiftr R package

Epwshiftr is capable of processing multiple GCM outputs at various spatial and temporal resolutions. Additionally, the package is designed in a modular manner for flexibility and extensibility. There are five modules in total, and the table below lists their corresponding names and functionalities.

The modules designed in the epwshiftr package
Module name Description
Query module Query and store metadata of online CMIP6 GCM outputs via the ESGF (Earth System Grid Federation) Search RESTful API. Meta includes the name of GCM, the institution that developed the GCM, emission scenarios, output interval, nominal resolution, output variable, output unit, etc.
Database module Create and manage a local database of GCM outputs using NetCDF files downloaded in the ESGF portal.
Data Extraction Module Extract climate variable data of desired temporal domain and specified grid distances to the input baseline EPW file
Morphing Module Calculate future weather data under the latest CMIP6 emission scenarios using the morphing method
EPW Generation Module Create future EPW files using various data aggregation strategies using the eplusr package (Jia and Chong 2021)

Each module stores climate data in a consistent Tidy (Wickham 2014) data format, allowing exploring a considerably broad pool of ready-to-use methods available in R for customized statistical analysis. Computational-intensive processes have been designed to run in parallel for speed-up.

The epwshiftr is distributed via CRAN (The Comprehensive R Archive Network). The source code is available on GitHub at https://github.com/ideas-lab-nus/epwshiftr and released under the MIT license.


This research was funded by the Republic of Singapore’s National Research Foundation through a grant to the Berkeley Education Alliance for Research in Singapore (BEARS) for the Singapore-Berkeley Building Efficiency and Sustainability in the Tropics (SinBerBEST) Program. BEARS has been established by the University of California, Berkeley as a center for intellectual excellence in research and education in Singapore.


Belcher, Se, Jn Hacker, and Ds Powell. 2005. “Constructing Design Weather Data for Future Climates.” Building Services Engineering Research and Technology 26 (1): 49–61. https://doi.org/10.1191/0143624405BT112OA.
Crawley, Drury B., Linda K. Lawrie, Frederick C. Winkelmann, W. F. Buhl, Y. Joe Huang, Curtis O. Pedersen, Richard K. Strand, et al. 2001. “EnergyPlus: Creating a New-Generation Building Energy Simulation Program.” Energy and Buildings, Special issue: BUILDING SIMULATION’99, 33 (4): 319–31. https://doi.org/10.1016/s0378-7788(00)00114-6.
Dickinson, Robert, and Benjamin Brannon. 2016. “36 Th International Conference on Passive and Low Energy Architecture.” In, 6. Los Angeles, U.S.
Eyring, Veronika, Sandrine Bony, Gerald A. Meehl, Catherine A. Senior, Bjorn Stevens, Ronald J. Stouffer, and Karl E. Taylor. 2016. “Overview of the Coupled Model Intercomparison Project Phase 6 (CMIP6) Experimental Design and Organization.” Geoscientific Model Development 9 (5): 1937–58. https://doi.org/10.5194/gmd-9-1937-2016.
IPCC. 2021. “Climate Change 2021: The Physical Science Basis. Contribution of Working Group i to the Sixth Assessment Report of the Intergovernmental Panel on Climate Change.” U.K. https://www.ipcc.ch/report/ar6/wg1/.
Jentsch, Mark F., AbuBakr S. Bahaj, and Patrick A. B. James. 2008. “Climate Change Future Proofing of BuildingsGeneration and Assessment of Building Simulation Weather Files.” Energy and Buildings 40 (12): 2148–68. https://doi.org/10.1016/J.ENBUILD.2008.06.005.
Jia, Hongyuan, and Adrian Chong. 2021. “Eplusr: A Framework for Integrating Building Energy Simulation and Data-Driven Analytics.” Energy and Buildings 237 (April): 110757. https://doi.org/10.1016/j.enbuild.2021.110757.
O’Neill, Brian C., Claudia Tebaldi, Detlef P. van Vuuren, Veronika Eyring, Pierre Friedlingstein, George Hurtt, Reto Knutti, et al. 2016. “The Scenario Model Intercomparison Project (ScenarioMIP) for CMIP6.” Geoscientific Model Development 9 (9): 3461–82. https://doi.org/10.5194/gmd-9-3461-2016.
Remund, Jan, Stefan Müller, Michael Schmutz, and Pascal Graf. 2020. “38th European Photovoltaic Solar Energy Conference and Exhibition.” In. Lisbon, Portugal. https://meteonorm.com/assets/publications/5BV.3.8_pvsec_2020_mn8.pdf.
Troup, Luke. 2016. “Building Performance Modeling Conference.” In, 8. Salt Lake City, UT, U.S.
Wickham, Hadley. 2014. “Tidy Data.” Journal of Statistical Software 59 (1): 1–23. https://doi.org/10.18637/jss.v059.i10.
Yassaghi, and Hoque. 2019. “An Overview of Climate Change and Building Energy: Performance, Responses and Uncertainties.” Buildings 9 (7): 166. https://doi.org/10.3390/buildings9070166.