Update Vignettes

.gitignore

@@ -37,3 +37,4 @@ vignettes/*.pdf
 
 # R Environment Variables
 .Renviron
+inst/doc

DESCRIPTION

@@ -13,7 +13,7 @@ Depends: R (>= 2.10)
 License: BSD_2_clause + file LICENSE
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.1.1
+RoxygenNote: 7.2.1
 Imports: 
 	knitr,
 	ggplot2,
@@ -33,8 +33,4 @@ Suggests:
 	testthat
 Remotes: 
 	github::JGCRI/gcamdata
-VignetteBuilder: 
-    knitr,
-	ggplot2,
-	RColorBrewer
-
+VignetteBuilder: knitr

README.md

@@ -18,7 +18,7 @@
 <br>
 
 <p align="center">
-<a href="https://jgcri.github.io/helios/articles/vignette_userguide.html" target="_blank"><img src="https://github.com/JGCRI/jgcricolors/blob/main/vignettes/button_user_guide.PNG?raw=true" alt="https://jgcri.github.io/helios/articles/vignette_userguide.html" height="60"/></a>
+<a href="https://jgcri.github.io/helios/articles/vignette_helios.html" target="_blank"><img src="https://github.com/JGCRI/jgcricolors/blob/main/vignettes/button_user_guide.PNG?raw=true" alt="https://jgcri.github.io/helios/articles/vignette_helios.html" height="60"/></a>
 <img src="https://github.com/JGCRI/jgcricolors/blob/main/vignettes/button_divider.PNG?raw=true" height="40"/>
 </p>
 

_config.yml

@@ -0,0 +1,3 @@
+theme: jekyll-theme-slate
+gems:
+  - jekyll-mentions

_pkgdown.yml

@@ -1,24 +1,43 @@
 title: helios
 
-template:
-  params:
-    bootswatch: cosmo
+home:
+  sidebar:
+    structure: [links, license, community, authors, dev]
 
 navbar:
+  type: inverse
   left:
     - icon: fa-home
       href: index.html
     - text: "Guide"
       icon: fas fa-book
-      href: articles/vignette_examples.html
-    - icon: fa-file-code-o
+      href: articles/vignette_helios.html
+    - icon: fas fa-code-branch
       text: "Reference"
       href: reference/index.html
     - text: "Contribute"
       href: CONTRIBUTING.html
     - icon: fa-newspaper-o
       text: "News"
       href: news/index.html
-
+
+reference:
+- title: "Functions"
+- contents:
+  - hdcd
+  - diagnostics
+  - save_xml
+- title: "Pre-loaded Data"
+- contents:
+  - L2441.HDDCDD_Fixed_gcamusa_seg
+  - mapping_wrf_us49
+  - mapUS52
+  - noaa_hddcdd
+  - segment_map_utc
+- title: "Package File"
+- contents:
+  - helios
+
+
 toc:
-  depth: 2
+  depth: 3

vignettes/.gitignore

@@ -0,0 +1,2 @@
+*.html
+*.R

vignettes/vignette_helios.Rmd

@@ -0,0 +1,124 @@
+---
+title: "Introduction"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{Introduction}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+
+<!-------------------------->
+<!-------------------------->
+# Input Data
+<!-------------------------->
+<!-------------------------->
+<p align="center"> <img src="vignetteFigs/divider.png"></p>
+
+`helios` is an R package that calculates heating and cooling degrees based on high temporal and spatial resolution of climate data (ourly and 12km resolution) and population data (yearly and 12km resolution). Currently, `helios` only supports climate data over CONUS from WRF or those with the same format. Data are available on NERSC if users have access. [Table 1](#table1) shows more details on the climate and population data supported by `helios`.
+
+<br />
+
+<a name="table1"></a>
+**Table 1:** Description of required input data for CONUS.
+
+| Specification | WRF Climate Data | Population Data |
+|---|---|---|
+| Input Format | NetCDF File | CSV File |
+| Spatial Resolution | WRF Resolution: 12 x 12 km | WRF Resolution: 12 x 12 km |
+| Temporal Resolution | Yearly | Hourly |
+| Required Variable | Temperature (K) | Population (Capita) |
+| Cluster Location | (NERSC) /global/cfs/cdirs/m2702/gsharing/tgw-wrf-conus | (NERSC) /global/cfs/cdirs/m2702/gcamusa/hddcdd/pop_1km |
+| Public Download | N/A | https://zenodo.org/record/3756179#.Y5fLK3bMKUl |
+| More Information | https://www.mmm.ucar.edu/models/wrf | https://www.mdpi.com/2071-1050/12/8/3374 |
+
+Please note that `helios` can process one climate NetCDF file with one population CSV file for each run. Parallelization may be needed for large dataset with longer time coverage.
+
+<br />
+
+<!-------------------------->
+<!-------------------------->
+# Workflow
+<!-------------------------->
+<!-------------------------->
+<p align="center"> <img src="vignetteFigs/divider.png"></p>
+
+`helios` includes 6 major steps in its workflow ([Figure 1](#figure1)),
+
+* Step 1: Process climate NetCDF.
+* Step 2: Calculate weighted population.
+* Step 3: Calculate heating and cooling degree-hours at grid resolution.
+* Step 4: Aggregate heating and cooling degree-hours to CONUS States scale.
+* Step 5: Aggregate heating and cooling degree-hours to dispatch segment scale and monthly scale.
+* Step 6: Post-process for diagnostic and convert to GCAM required format.
+
+***Note:** Dispatch segments are defined as 24 day and night segments in each month of the year, plus a "super-peak" segment that has the top 10% of loads within a year for each grid region. Dispatch segments are specifically used in GCAM-USA.
+
+<br />
+
+<p align="center"> <img src="vignetteFigs/helios_workflow.jpg"></p>
+<a name="figure1"></a>
+<p align="center" style="font-size:14px;"> *Figure 1:* Helios Workflow. </p>
+
+<br />
+
+<!-------------------------->
+<!-------------------------->
+# Examples
+<!-------------------------->
+<!-------------------------->
+<p align="center"> <img src="vignetteFigs/divider.png"></p>
+
+`helios` has many functionalities under development. Currently, the usage of `helios` are limited to spatial and temporal resolution designed for GCAM-USA. Here is an example using one WRF climate input data (hourly data from 2020-01-01 01:00:00 to 2020-01-08 00:00:00) and population data.
+
+```{r eval=FALSE}
+library(helios)
+
+output <- helios::hdcd(ncdf = 'path_to_wrf_data/wrfout_d01_2020-01-01_01%3A00%3A00.nc',
+                       spatial = 'gcamusa',
+                       temporal = 'gcamusa',
+                       population = 'path_to_pop_data/population_conus_total_ssp2_2020-2100_wrf_wgs84.csv',
+                       reference_temp_F = 65,
+                       folder = paste0(getwd(), "/output"),
+                       diagnostics = F,
+                       xml = F,
+                       name_append = "",
+                       save = F)
+```
+
+<br />
+
+The output is a list containing two tables.
+
+```{r eval=FALSE}
+# Heating and cooling degree-hours at dispatch segment scale for CONUS
+hdcd_segment <- output$hdcd_comb
+head(hdcd_segment)
+
+# Heating and cooling degree-hours at dispatch monthly scale for CONUS
+hdcd_monthly <- output$hdcd_comb_monthly
+head(hdcd_monthly)
+```
+
+<br />
+
+After getting the data table for heating and cooling degrees, users can perform diagnostics and compare with NOAA observations. The following example is only for demonstration of how to use `helios::diagnostic`.
+
+
+```{r eval=FALSE}
+# Perform monthly diagnostic
+helios::diagnostics(hdcd_monthly = hdcd_monthly,
+                    folder = paste0(getwd(), "/output"))
+```
+
+
+```{r eval=FALSE}
+# Perform segment diagnostic
+helios::diagnostics(hdcd = hdcd_segment,
+                    folder = paste0(getwd(), "/output"))
+
+```
+
+<br />
+
+***Note:** Please note that if users are following the example provided here, we use one WRF input climate NetCDF data, which only covers 7 days. Thus, the diagnostic will not show the full picture of heating and cooling degrees over a year. To get heating and cooling degrees for a complete year, users need to repeatly run climate NetCDF files in `helios` that cover the length of a year. For example, if each climate NetCDF is for 7-days, then user need to run about 52 climate NetCDF through `helios` to cover a whole year of climate. Then, users can combine all the output tables from `helios` and run `helios::diagnostic` to create the heating and cooling degree behavior throughout a year.