Update vignette and test

R/pkg_utils.R

@@ -115,7 +115,7 @@ find_mapping_grid <- function(data = NULL, spatial = NULL) {
 
     if ('subRegion' %in% names(spatial)){
 
-      shape <- rmap::map_find(spatial)[[2]]
+      shape <- rmap::map_find(spatial)
 
       mapping <- helios::mapping_grid(grid = grid,
                                       shape = shape)
@@ -177,7 +177,7 @@ mapping_grid <- function(grid = NULL, shape = NULL){
   pnts_sf <- sf::st_as_sf(grid,
                           coords = c('lon', 'lat'),
                           crs = sf::st_crs(shape))
-
+  sf::sf_use_s2(FALSE)
   pnts_sf <- sf::st_join(pnts_sf, shape,
                          join = sf::st_nearest_feature,
                          suffix = c('', '.nearest'))

paper/paper.md

@@ -21,21 +21,21 @@ affiliations:
    index: 1
  - name: Joint Global Change Research Institute, Pacific Northwest National Laboratory, College Park, MD, USA
    index: 2
-date: 20 April 2023
+date: July 2023
 bibliography: paper.bib
 ---
 
 # Summary
 
-`helios` is an open-source R package that estimates population-weighted heating and cooling degree-hours (HDH and CDH) and degree-days (HDD and CDD) at various temporal (e.g., energy dispatch segments, monthly, yearly) and spatial scales (e.g., U.S. states, global political regions). The degree hour and degree day outputs from `helios` are used to inform electricity demand load in the Global Change Analysis Model (GCAM) [@calvin2019gcam] as well as in GCAM-USA (which is the version of GCAM with U.S. state-level details) [@binsted2022gcam-usa]. `helios` uses a workflow with four steps: processing raw data; calculating heating and cooling degrees; visualizing performance diagnostics; and outputing results in various formats. There are two sources of widely-used climate data compatible with `helios`: (1) hourly climate data with 12-km resolution that are dynamically downscaled with the Weather Research and Forecasting (WRF) model and projected using a thermal global warming (TGW) approach [@jones2022im3]; and (2) daily climate data with 0.5-degree resolution from the Coupled Model Intercomparison Project (CMIP) that is bias-adjusted and statistical downscaled by the Inter-Sectoral Impact Model Intercomparison Project (ISIMIP). In summary, `helios` is a model that standardizes methodology of heating and cooling degrees-hours and degree-days using publicly available data and advance the understanding of the impact of spatial and temporal temperature variability on building energy services.
+`helios` is an open-source R package that estimates population-weighted heating and cooling degree-hours (HDH and CDH) and degree-days (HDD and CDD) at various temporal (e.g., energy dispatch segments, monthly, yearly) and spatial scales (e.g., U.S. states, global political regions, countries). The degree hour and degree day outputs from `helios` are used to inform electricity demand load in the Global Change Analysis Model (GCAM) [@calvin2019gcam] as well as in GCAM-USA (which is the version of GCAM with U.S. state-level details) [@binsted2022gcam-usa]. `helios` uses a workflow with four steps: processing raw data; calculating heating and cooling degrees; visualizing performance diagnostics; and outputing results in various formats. There are two sources of widely-used climate data compatible with `helios`: (1) hourly climate data with 12-km resolution that are dynamically downscaled with the Weather Research and Forecasting (WRF) model and projected using a thermal global warming (TGW) approach [@jones2022im3]; and (2) daily climate data with 0.5-degree resolution from the Coupled Model Intercomparison Project (CMIP) that is bias-adjusted and statistical downscaled by the Inter-Sectoral Impact Model Intercomparison Project (ISIMIP). In summary, `helios` is a model that standardizes methodology of heating and cooling degrees-hours and degree-days using publicly available data and advance the understanding of the impact of spatial and temporal temperature variability on building energy services.
 
 # Statement of Need
 
 `helios` was developed to meet the increasing research interests to explore the spatial and temporal heterogeneity of climate impacts on sub-annual electricity demand from buildings. @ciscar2014integrated pointed out most integrated modeling systems designed to link human-Earth systems are unable to take advantage of the publicly available high resolution data to account for the impact of seasonal temperature change on energy system. To better fill in this gap, researchers have developed GCAM versions (e.g., GCAM-USA) to include power sector details at sub-annual and sub-national level [@wise2019representing]. For example, @khan2021impacts used GCAM-USA to show that the temperature-induced heating and cooling demands can significantly affect sub-annual electricity demand profiles and peak electricity loads. Understanding the seasonal dynamics of electricity demand and capacity within IAMs is of importance to support future infrastructure planning [@binsted2022electrified]. We develop `helios` to bridge the gap between high resolution data and global scale models by facilitating the workflow in estimating population-weighted heating and cooling degrees. `helios` serves as a pre-processing tool of GCAM for researchers to capture the impact of sub-annual variation of different climate and socioeconomic scenarios on building energy demand.
 
 # Design and Functionality
 
-`helios` is designed to provide heating and cooling degrees to GCAM (or GCAM-USA) at two spatiotemporal scales: (1) HDH and CDH for the U.S. States for dispatch segments by building thermal service (for GCAM-USA); (2) annual HDD and CDD for GCAM's 32 geopolitical regions at 5-year time step by building thermal service (for GCAM-Regions). Beyond providing information for GCAM, `helios` also provides heating and cooling degrees at a monthly time step. The use of `helios` requires users to provide information about the input files, such as the climate model source for climate data and the variable name for temperature. For example, the ISIMIP-CMIP data uses "tas" for the variable name for temperature while the WRF data uses "T2". Figure 1 shows the workflow for both GCAM-USA and GCAM-Regions. More details can be accessed in the `helios` [documentation](https://jgcri.github.io/helios/index.html) page on Github.
+`helios` is designed to provide heating and cooling degrees to GCAM (or GCAM-USA) at two spatiotemporal scales: (1) HDH and CDH for the U.S. States for dispatch segments by building thermal service (for GCAM-USA); (2) annual HDD and CDD for GCAM's 32 geopolitical regions at 5-year time step by building thermal service (for GCAM-Regions). Beyond providing information for GCAM, `helios` can serve as a general tool to calculate heating and cooling degrees at a monthly time step and various spatial scales (e.g., country, basin). The use of `helios` requires users to provide information about the input files, such as the climate model source for climate data and the variable name for temperature. For example, the ISIMIP-CMIP data uses "tas" for the variable name for temperature while the WRF data uses "T2". Figure 1 shows the workflow for both GCAM-USA and GCAM-Regions. More details can be accessed in the `helios` [documentation](https://jgcri.github.io/helios/index.html) page on Github.
 
 ![The workflow for helios.\label{fig:1}](Fig1_helios_workflow.jpg)
 

tests/testthat/helper.R

@@ -1,3 +1,4 @@
+library(rmap)
 #.......................
 # Prepare data for tests
 #.......................

tests/testthat/test-hdcd.R

@@ -38,6 +38,12 @@ test_that("monthly and annual HD values are negative, CD values are positive", {
 run_diagnostics()
 run_hdcd_usa(xml = TRUE)
 
+# ------------------------------------
+# Testing Different scales
+# ------------------------------------
+
+run_hdcd_china(spatial = 'gcam_countries')
+run_hdcd_china(spatial = data.frame(subRegion = 'China'))
 
 # ------------------------------------
 # Testing Conditions

vignettes/vignette_gcam-regions.Rmd

@@ -158,14 +158,15 @@ knitr::kable(population[1:10, ],
 
 <br />
 
-## Calculate heating and cooling degree-days
+## Calculate HDD and CDD
+
 
 The following example specifies the arguments for processing CMIP6 dataset. More information for the arguments can be found in (`helios::hdcd` Reference)[https://jgcri.github.io/helios/reference/hdcd.html].
 
 * `ncdf_var = 'tas'` specifies climate variable to extract from the netCDF, which is temperature in this case.
 * `model = 'cmip'` specifies the model used to produce the climate forcing data, which is CMIP6 model in this case.
 * `model_timestep = 'daily'` indicates the temporal resolution of the climate forcing data, which is daily in this case.
-* `spatial = 'gcam_regions32'` specifies we are  calculating the cooling and heating degree-days for 32 GCAM regions. This will produce outputs that can be used for general GCAM. For tutorial of using `helios` to calculate heating and cooling degree-hours for CONUS in GCAM-USA, please check out [GCAM-USA](vignette_gcam-usa.html) tutorial page.
+* `spatial = 'gcam_regions32'` specifies we are calculating the cooling and heating degree-days for 32 GCAM regions. This will produce outputs that can be used for general GCAM. For tutorial of using `helios` to calculate heating and cooling degree-hours for CONUS in GCAM-USA, please check out [GCAM-USA](vignette_gcam-usa.html) tutorial page.
 * `time_periods = 2020` specifies the time period (e.g., 2020) to extract from the dataset covering 2015 - 2020. Users can also specify multiple time period (e.g. `time_periods = c(2017, 2018, 2019, 2020)`) if those time periods are within the time span of the climate and population dataset.
 * `dispatch_segment = FALSE` indicates the model will output annual heating and cooling degree-days for selected spatial scale. Annual HDD/CDD is the common input time step for GCAM core.
 
@@ -255,6 +256,143 @@ knitr::kable(hdcd_annual,
 
 <br />
 
+## Various Spatial Scales
+
+Beyond using `helios` for GCAM regions (e.g., `spatial = 'gcam_region32'`), we can use `helios` as a general tool to calculate heating and cooling degrees at various spatial scales by using `spatial` argument. More details about available spatial scales are described in `helios::spatial_options`.
+
+* `spatial = 'gcam_region32'` for global countries
+* `spatial = 'gcam_countries'` for global countries
+* `spatial = 'gcam_basins'` for global 235 basins
+* `spatial = data.frame(subRegion = c('Shanghai', 'Beijing'))` will automatically find the corresponding spatial map that is at the same scale with the `subRegion` names provided. In this case, `helios` will identify states/province level spatial scale. The final output will  depend on input climate data's coverage. Users need to provide this in the format of data frame or tibble.
+
+
+<br />
+
+**1. Country Scale**
+
+
+```{r eval=TRUE}
+library(helios)
+
+# example data: CMIP6 daily climate at 0.5 degree resolution
+path_to_climate_ncdf <- helios::pkg_example('gfdl-esm4_r1i1p1f1_w5e5_ssp126_tas_global_daily_2015_2020_sub.nc')
+
+# example data: population of 2020 at 0.125 degree resolution
+path_to_population <- helios::pkg_example('ssp1_2020_sub.nc')
+
+# Calculate heating and coolong degrees for GCAM regions (e.g., part of China in the example)
+hdcd <- helios::hdcd(ncdf = path_to_climate_ncdf,
+                     ncdf_var = 'tas',
+                     model = 'cmip',
+                     model_timestep = 'daily',
+                     population = path_to_population,
+                     spatial = 'gcam_countries',
+                     time_periods = 2020,
+                     dispatch_segment = FALSE,
+                     reference_temp_F = 65,
+                     folder = file.path(getwd(), 'output'),
+                     diagnostics = F,
+                     xml = F,
+                     name_append = '',
+                     save = F)
+```
+```{r eval=FALSE, echo=FALSE}
+# Heating and cooling degree-days at annual scale
+hdcd$hdcd_comb_annual
+```
+
+```{r eval=TRUE, echo=FALSE}
+knitr::kable(hdcd$hdcd_comb_annual, 
+             caption = 'Table. Annual heating and cooling degree-days for global countries.') %>% 
+  kable_styling(bootstrap_options = 'striped', full_width = T, position = 'center')
+```
+
+<br />
+
+**2. Basin Scale**
+
+```{r eval=TRUE}
+library(helios)
+
+# example data: CMIP6 daily climate at 0.5 degree resolution
+path_to_climate_ncdf <- helios::pkg_example('gfdl-esm4_r1i1p1f1_w5e5_ssp126_tas_global_daily_2015_2020_sub.nc')
+
+# example data: population of 2020 at 0.125 degree resolution
+path_to_population <- helios::pkg_example('ssp1_2020_sub.nc')
+
+# Calculate heating and coolong degrees for GCAM regions (e.g., part of China in the example)
+hdcd <- helios::hdcd(ncdf = path_to_climate_ncdf,
+                     ncdf_var = 'tas',
+                     model = 'cmip',
+                     model_timestep = 'daily',
+                     population = path_to_population,
+                     spatial = 'gcam_basins',
+                     time_periods = 2020,
+                     dispatch_segment = FALSE,
+                     reference_temp_F = 65,
+                     folder = file.path(getwd(), 'output'),
+                     diagnostics = F,
+                     xml = F,
+                     name_append = '',
+                     save = F)
+```
+```{r eval=FALSE, echo=FALSE}
+# Heating and cooling degree-days at annual scale
+hdcd$hdcd_comb_annual
+```
+
+```{r eval=TRUE, echo=FALSE}
+knitr::kable(hdcd$hdcd_comb_annual, 
+             caption = 'Table. Annual heating and cooling degree-days for global basins.') %>% 
+  kable_styling(bootstrap_options = 'striped', full_width = T, position = 'center')
+```
+<br />
+
+**3. User Specified `subRegion` Scale**
+
+
+```{r eval=TRUE}
+library(helios)
+library(rmap)
+
+# example data: CMIP6 daily climate at 0.5 degree resolution
+path_to_climate_ncdf <- helios::pkg_example('gfdl-esm4_r1i1p1f1_w5e5_ssp126_tas_global_daily_2015_2020_sub.nc')
+
+# example data: population of 2020 at 0.125 degree resolution
+path_to_population <- helios::pkg_example('ssp1_2020_sub.nc')
+
+# specify few province names to indicate calculate HDDCDD at province scale
+scale_province <- data.frame(subRegion = c('Shanghai', 'Beijing'))
+
+# Calculate heating and coolong degrees for GCAM regions (e.g., part of China in the example)
+hdcd <- helios::hdcd(ncdf = path_to_climate_ncdf,
+                     ncdf_var = 'tas',
+                     model = 'cmip',
+                     model_timestep = 'daily',
+                     population = path_to_population,
+                     spatial = scale_province,
+                     time_periods = 2020,
+                     dispatch_segment = FALSE,
+                     reference_temp_F = 65,
+                     folder = file.path(getwd(), 'output'),
+                     diagnostics = F,
+                     xml = F,
+                     name_append = '',
+                     save = F)
+```
+```{r eval=FALSE, echo=FALSE}
+# Heating and cooling degree-days at annual scale
+hdcd$hdcd_comb_annual
+```
+
+
+```{r eval=TRUE, echo=FALSE}
+knitr::kable(hdcd$hdcd_comb_annual, 
+             caption = 'Table. Annual heating and cooling degree-days for User Specified Scale.') %>% 
+  kable_styling(bootstrap_options = 'striped', full_width = T, position = 'center')
+```
+<br />
+
 ## Diagnostics
 
 After getting the data table for heating and cooling degrees, users can perform diagnostics. The following example is only for demonstration of how to use `helios::diagnostics`.