README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)

library(epwshiftr)

# copy files in advance
f <- c("tas_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20490101-20491231.nc",
       "tas_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20500101-20501231.nc",
       "tas_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20510101-20511231.nc",
       "hurs_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20490101-20491231.nc",
       "hurs_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20500101-20501231.nc",
       "hurs_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20510101-20511231.nc",
       "tas_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20790101-20791231.nc",
       "tas_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20800101-20801231.nc",
       "tas_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20810101-20811231.nc",
       "hurs_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20790101-20791231.nc",
       "hurs_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20800101-20801231.nc",
       "hurs_day_AWI-CM-1-1-MR_ssp585_r1i1p1f1_gn_20810101-20811231.nc"
)
file.copy(file.path("/mnt/d/ScenarioMIP", f), tempdir())
```

# epwshiftr <img src="man/figures/logo.svg" align="right" />

<!-- badges: start -->
[![R build status](https://github.com/ideas-lab-nus/epwshiftr/workflows/R-CMD-check/badge.svg)](https://github.com/ideas-lab-nus/epwshiftr/actions)
[![CRAN status](https://www.r-pkg.org/badges/version/epwshiftr)](https://CRAN.R-project.org/package=epwshiftr)
[![Codecov test coverage](https://codecov.io/gh/ideas-lab-nus/epwshiftr/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ideas-lab-nus/epwshiftr?branch=master)
[![CRAN Download Badge](https://cranlogs.r-pkg.org/badges/epwshiftr)](https://cran.r-project.org/package=epwshiftr)
<!-- badges: end -->

> Create future EnergyPlus Weather files using CMIP6 data

## 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:

```bibtex
@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}
}
```

<!-- TOC GFM -->

* [Installation](#installation)
* [Get started](#get-started)
    * [Build CMIP6 output file index](#build-cmip6-output-file-index)
    * [Manage CMIP6 output files](#download-cmip6-output-files)
    * [Extract CMIP6 output data](#extract-cmip6-output-data)
    * [Morphing EPW weather variables](#morphing-epw-weather-variables)
    * [Create future EPW files](#create-future-epw-files)
* [Author](#author)
* [License](#license)
* [Contribute](#contribute)

<!-- /TOC -->

## Installation

You can install the latest stable release of epwshiftr from
[CRAN](https://CRAN.R-project.org).

```{r cran-install, eval = FALSE}
install.packages("epwshiftr")
```

Alternatively, you can install the development version from GitHub.

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

## Get started

### Build CMIP6 output file index

* The first step is to build CMIP6 experiment output file index based on queries
  using ESGF search RESTful API

```{r index}
# set directory to store files
options(epwshiftr.dir = tempdir())
options(epwshiftr.verbose = TRUE)

# get CMIP6 data nodes
(nodes <- get_data_node())

# create a CMIP6 output file index
idx <- init_cmip6_index(
    # only consider ScenarioMIP activity
    activity = "ScenarioMIP",

    # specify dry-bulb temperature and relative humidity
    variable = c("tas", "hurs"),

    # specify report frequent
    frequency = "day",

    # specify experiment name
    experiment = c("ssp585"),

    # specify GCM name
    source = "AWI-CM-1-1-MR",

    # specify variant,
    variant = "r1i1p1f1",

    # specify years of interest
    years = c(2050, 2080),

    # save to data dictionary
    save = TRUE
)

# the index has been automatically saved into directory specified using
# `epwshiftr.dir` option and can be reloaded
idx <- load_cmip6_index()

str(head(idx))
```

### Manage CMIP6 output files

* You have to download CMIP6 output file by yourself using your preferable
  methods or tools. The download url can be found in the `file_url` column in
  the index.

* After you have downloaded CMIP6 output files of interest, you can use
  `suumary_database()` to get a summary on files downloaded against the CMIP6
  output file index.

* This step is necessary as it map the loaded files against index so that
  epwshiftr knows which case is complete and can be used for the next step.

```{r database}
# Summary downloaded file by GCM and variable, use the latest downloaded file if
# multiple matches are detected and save matched information into the index file
sm <- summary_database(tempdir(), by = c("source", "variable"), mult = "latest", update = TRUE)

knitr::kable(sm)
```

### Extract CMIP6 output data

* With previous step, now we can match coordinates of an EPW in the CMIP6 output
  file

```{r coord}
epw <- file.path(eplusr::eplus_config(8.8)$dir, "WeatherData/USA_CA_San.Francisco.Intl.AP.724940_TMY3.epw")
# match any coordinates with absolute distance less than 1 degree
coord <- match_coord(epw, threshold = list(lon = 1, lat = 1), max_num = 1)

class(coord)

names(coord)

coord$meta

coord$coord[, .(file_path, coord)]

str(coord$coord$coord[[1]])
```

* Once we get the matched coordinates, we can extract corresponding data related
  to input EPW file using `extract_data()`

```{r data}
data <- extract_data(coord, years = c(2050, 2080))

class(data)
names(data)
knitr::kable(head(data$data))
```

### Morphing EPW weather variables

* With all necessary information extracted above, now we can perform morphing on
  out EPW

```{r morph}
morphed <- morphing_epw(data)

class(morphed)

names(morphed)

knitr::kable(head(morphed$tdb))

knitr::kable(head(morphed$rh))
```

### Create future EPW files

* Once we get the morphed data using `morphing_epw()`, we can now create future
  EPW files using `future_epw()`

```{r epw}
# create future EPWs grouped by GCM, experiment ID, interval (year)
epws <- future_epw(morphed, by = c("source", "experiment", "interval"),
    dir = tempdir(), separate = TRUE, overwrite = TRUE
)

epws

sapply(epws, function (epw) epw$path())
```

## Author

Hongyuan Jia and Adrian Chong

## License

* **epwshiftr**

  epwshiftr is released under the terms of MIT License.

  Copyright © 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](https://pcmdi.llnl.gov/CMIP6/TermsOfUse/).

## Disclaimer

CMIP6 model data is licensed under a [Creative Commons Attribution-ShareAlike
4.0 International License](https://creativecommons.org/licenses/).
Consult [Terms of Use](https://pcmdi.llnl.gov/CMIP6/TermsOfUse/) 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) and at [EC-Earth](https://ec-earth.org/). 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](https://github.com/ideas-lab-nus/epwshiftr/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
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](https://github.com/ideas-lab-nus/epwshiftr/blob/master/.github/CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.