In jkeast/ResourceRefocus:

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

Guide to Using Functions

Set Up

Run the following code to install the package

# 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

extrafont::loadfonts(device = "pdf")

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:

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.

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:

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:

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.

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.

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.

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.

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.

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.

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.

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