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%"
)

baseline_csv <- system.file("extdata", "sample_baseline_design.csv", package = "ResourceRefocus")

proposed_csv <- system.file("extdata", "sample_proposed_design_w-pumpsMeter.csv", package = "ResourceRefocus")

dualfuel_csv <- system.file("extdata", "sample_baseline_dual-fuel_design.csv", package = "ResourceRefocus")

CO2_conversions <- system.file("extdata", "GHG_index_E3_2030.csv", package = "ResourceRefocus")
```

# Resource Refocus R Data Visualization Package for 8760 Building End-Use Level Data <img src="Resource-Refocus-Secondary-Logo-RGB-Borderless.png" align="right" height=130/>

## Guide to Using Functions

### Set Up

Run the following code to install the package 

```{r, warning=FALSE}
# install.packages("devtools")
# devtools::install_github("jkeast/ResourceRefocus")

library(ResourceRefocus)
```


To ensure the fonts are consistent with the Resource Refocus style guide, make sure the "Muli" and "Roboto" fonts are installed to your computer and install and library the `extrafont` package. Then, for each font family run
`ttf_import("[Path to font]")` and finally 

```{r, message=FALSE}
extrafont::loadfonts(device = "pdf")
```



<!-- badges: start -->
<!-- badges: end -->

### Getting Data Ready for Plotting

I wrote a couple of functions to transform model outputs into a workable format for plotting: 

- `simple_cap()` capitalizes the first letter of each word (for labeling purposes)
- `clean_enduse()` modifies the names of enduse columns to be visually appealing (for labeling purposes)
- `to_remove()` determines if there is an enduse equalling sum of others and removes it
- `convert()` converts energy from original units to kWh
- `clean_data()` utilizes the above functions and some existing R functions to make the data completely ready for plotting

`clean_data()` is automatically called by all plotting functions, but can also be used on its own if ever helpful. To utilize it, call `clean_data()` with the path to a csv of your data. E.g:

```{r}
library(ResourceRefocus)

data <- clean_data(baseline_csv)
head(data)
```

In addition to the path to a csv, `clean_data()` has a number of other arguments:

- `by_month`: designates whether to summarize data by month (the default) or omit month (NULL)
- `by_enduse`: designates whether to summarize data by enduse (the default) or omit enduse (NULL)
- `by_hour`: designates whether to summarize data by hour (the default) or omit hour (NULL)
- `by_fuel`: designates whether to summarize data by fuel (the default) or omit fuel (NULL)

Each of these arguments shape how granular the summaries are. The default for the function is to include all these variables, so you need to indicate which you want the function to NOT consider. For example, if you want to just focus on energy usage by month -- ignoring end-use, hour of the day, and fuel -- you can set `by_enduse`, `by_hour`, and `by_fuel` to NULL.

```{r, message=FALSE}
data <- clean_data(baseline_csv, by_enduse = NULL, by_hour = NULL, by_fuel = NULL)
head(data)
```

You can also use these arguments in conjunction, say to focus on end-use and hour of the day:

```{r, message=FALSE}
data <- clean_data(baseline_csv, by_fuel = NULL, by_month = NULL)
head(data)
```

`clean_data()` also passes a `conversion_factor` argument to the `convert()` function. This is what you should use if the source data is in some units other than Joules --- just supply `clean_data()` with the correct factor to convert from the original units to kWh. For example, say our original units are kBtu. We would want to divide the energy by 3.412 to convert to kWh:

```{r}
data <- clean_data(baseline_csv, conversion_factor = 3.412)
head(data)
```

As you can see, the function also sends a message reminding you which conversion factor you used.

`clean_data()` also has an `emissions_conversions` argument for the path to csv with hourly tonne CO2-e/MWh and tonne CO2-e/therm conversion factors (see inst/extdataGHG_index_E3_2030.csv for example). If utilized, `clean_data()` will also return emissions summaries.

```{r}
data <- clean_data(baseline_csv, emissions_conversions = CO2_conversions)
head(data)
```


### Using the plotting functions

#### Plot one model

`plot_model()` plots the consumption or emissions generated by one model. It takes the following arguments:

- `model`: character string of path to csv containing model data
- `title`: character string of desired plot title. Default is NULL

and passes `by_month` and `conversion_factor` (and `emissions_conversions` if applicable) to `clean_data()`, which it calls automatically.

```{r, message=FALSE}
plot_model(baseline_csv, title = "Placeholder Title")
plot_model(baseline_csv, title = "Placeholder Title", result = "Emissions", emissions_conversions = CO2_conversions)
plot_model(baseline_csv, by_month = NULL, title = "Placeholder Title")
plot_model(baseline_csv, by_month = NULL, title = "Placeholder Title", result = "Emissions", emissions_conversions = CO2_conversions)
```

`plot_emissions()` is identical to `plot_model()` except that it only plots emissions – no need to specify result.

```{r, message = FALSE}
plot_emissions(baseline_csv, title = "Placeholder Title", emissions_conversions = CO2_conversions)
plot_emissions(baseline_csv, title = "Placeholder Title", emissions_conversions = CO2_conversions, by_month = NULL)
```


#### Compare different models

`plot_comps()` shows the comparison of a baseline model to proposed. It takes the following arguments:

- `baseline`: character string of path to csv containing baseline data
- `proposed`: character string of path to csv containing proposed data
- `title`: character string of desired plot title. Default is NULL
- `bw`: boolean designating whether to plot in color (FALSE, default), or black and white (TRUE)

and passes `by_month` and `conversion_factor` (and `emissions_conversions` if applicable) to `clean_data()`, which it calls automatically.

```{r, message=FALSE}
plot_comps(baseline_csv, proposed_csv, title = "Placeholder Title")
plot_comps(baseline_csv, proposed_csv, title = "Placeholder Title", result = "Emissions", emissions_conversions = CO2_conversions)
plot_comps(baseline_csv, proposed_csv, by_month = NULL, title = "Placeholder Title")
plot_comps(baseline_csv, proposed_csv, by_month = NULL, title = "Placeholder Title", result = "Emissions", emissions_conversions = CO2_conversions)
plot_comps(baseline_csv, proposed_csv, by_month = NULL, title = "Placeholder Title", bw = TRUE)
```

#### Plot End-use Averages

`plot_enduse_avgs()` shows average hourly energy projections stratified by end-use. It takes the following arguments:

- `csv`: character string of path to csv containing model outputs
- `title`: character string of desired plot title. Default is NULL
- `bw`: boolean designating whether to plot in color (FALSE, default), or black and white (TRUE)

and passes `by_month` and `conversion_factor` to `clean_data()`, which it calls automatically.

```{r, message=FALSE}
plot_enduse_avgs(baseline_csv, title = "Placeholder Title")
plot_enduse_avgs(baseline_csv, by_month = NULL, title = "Placeholder Title")
plot_enduse_avgs(baseline_csv, by_month = NULL, title = "Placeholder Title", result = "Emissions", emissions_conversions = CO2_conversions)
plot_enduse_avgs(baseline_csv, title = "Placeholder Title", by_month = NULL, bw = TRUE)
```

#### Plot Dual-Fuel Averages

`plot_dualfuel_avgs()` shows average hourly energy projections from a dual-fuel model stratified by end-use. It takes the following arguments:

- `csv`: character string of path to csv containing model outputs
- `title`: character string of desired plot title. Default is NULL

and passes `by_month` and `conversion_factor` to `clean_data()`, which it calls automatically.

```{r, message=FALSE}
plot_dualfuel_avgs(dualfuel_csv, title = "Placeholder Title", by_month = NULL)
plot_dualfuel_avgs(dualfuel_csv, title = "Placeholder Title", result = "Emissions", by_month = NULL, emissions_conversions = CO2_conversions)
```

#### End Use Averages Barcharts

`plot_stacked_enduses()` creates barcharts to show average energy projections. If provided with two paths to csvs it will compare the two models. It can also stratify the data by month and/or visualize a dual-fuel model. It takes the following arguments:

- `baseline`: character string of path to csv containing data
- `proposed`: character string of path to csv containing data to compare, or NULL (default)
- `title`: character string of desired plot title. Default is NULL
- `by_fuel`: designates whether plotting dual-fuel (default) or not (NULL)

and passes `by_month` and `conversion_factor` to `clean_data()`, which it calls automatically.

```{r, message=FALSE}
plot_stacked_enduses(baseline_csv, proposed_csv, title = "Placeholder Title", by_month = NULL, by_fuel = NULL)
plot_stacked_enduses(baseline_csv, proposed_csv, title = "Placeholder Title", by_month = NULL, by_fuel = NULL, result = "Emissions", emissions_conversions = CO2_conversions)
plot_stacked_enduses(baseline_csv, proposed_csv, title = "Placeholder Title", by_fuel = NULL)
plot_stacked_enduses(dualfuel_csv, title = "Placeholder Title", by_month = NULL)
plot_stacked_enduses(dualfuel_csv, title = "Placeholder Title")
```