PFUWorkflow

library(PFUWorkflow)

Introduction

PFUWorkflow is an R package that provides functions to build a database of primary-to-final-to-useful (PFU) energy conversion chain (ECC) societal exergy analyses (SEA). PFUWorkflow makes use of the drake package. PFUWorkflow creates drake workflows that ensure that “What gets done stays done,” leading to analyses that are more reproducible and less prone to errors.

Quick start

To get started, follow these steps:

1. Create a new R project in a new folder or repository.
2. Make an R directory inside the new folder.
3. Inside the R directory, make a file called plan.R that calls PFUWorkflow::get_plan() like this:

plan <- PFUWorkflow::get_plan(countries = c("GHA", "ZAF"), 
                              max_year = 2017,
                              iea_data_path = "<<IEA extended energy balance path>>", 
                              country_concordance_path = "<<Country concordance path>>",
                              phi_constants_path = "<<phi constants path>>", 
                              ceda_data_folder = "<<CEDA temperature data path>>",
                              machine_data_path = "<<Machine data path>>",
                              exemplar_table_path = "<<exemplar table path>>",
                              fu_analysis_folder = "<<FU analysis folder>>", 
                              reports_source_folders = "<<Reports source folders>>",
                              reports_dest_folder = "<<Reports output folder>>",
                              pipeline_caches_folder = "<<Pipeline caches folder>>",
                              pipeline_releases_folder = "<<Pipeline releases folder>>",
                              release = FALSE)

where

• countries is the list of countries to be analyzed,
• max_year is the latest year to be analyzed,
• <<IEA extended energy balance path>> is the path to a .csv file that contains IEA extended energy balance data,
• <<phi constants path>> is the path to an Excel file of constant values of phi (the exergy-to-energy ratio),
• <<CEDA temperature data path>> is the path to CEDA cru_cy temperature data downloaded through CEDATools,
• <<Machine data path>> is the path to the Machine data excel files containing Eta.fu, Phi.u, and other data.
• <<exemplar table path>> is the path to an exemplar table (see below),
• <<FU analysis folder>> is the path to a folder containing final-to-useful analyses,
• <<Reports source folders>> is a vector of paths to folders containing report sources (usually .Rmd and .Rnw files),
• <<Reports output folder>> is the path to a folder for completed reports,
• <<Pipeline caches folder>> is the path to a folder in which the pipeline cache is stored as a .zip file, and
• <<Pipeline releases folder>> is the path to a folder in which releases of pipeline objects are stored.

The plan object is a data frame that provides a list of “targets” and code that will generate the target, in the order the targets will be completed.

plan
#> # A tibble: 51 × 3
#>    target                   command                                dynamic   
#>    <chr>                    <expr_lst>                             <expr_lst>
#>  1 countries                c(c("GHA", "ZAF"))                     NA        
#>  2 alloc_and_eff_couns      unique(c(countries, NULL))             NA        
#>  3 max_year                 2017                                   NA        
#>  4 iea_data_path            "<<IEA extended energy balance path>>" NA        
#>  5 country_concordance_path "<<Country concordance path>>"         NA        
#>  6 phi_constants_path       "<<phi constants path>>"               NA        
#>  7 ceda_data_folder         "<<CEDA temperature data path>>"       NA        
#>  8 machine_data_path        "<<Machine data path>>"                NA        
#>  9 exemplar_table_path      "<<exemplar table path>>"              NA        
#> 10 fu_analysis_folder       "<<FU analysis folder>>"               NA        
#> # … with 41 more rows

4. To visualize all dependencies in the plan,

drake::vis_drake_graph(plan)

5. To execute the plan, call `drake::make(plan) or drake::r_make(plan). When drake is installed, the Addins menu contains the item Run a drake workflow, which sources the plan.R file and calls drake::r_make(plan).

Targets

A list of targets can be found with PFUWorkflow::target_names. The meanings of the targets can be obtained with ?PFUWorkflow::target_names.

Results

To query the results of executing the plan, say drake::readd(<<target>>), where <<target>> is unquoted. Alternatively, drake::readd("<<target>>", character_only = TRUE) for a string <<target>>.

Targets are computed by country. Say PFUWorkflow::readd_by_country("<<target>>", "<<country>>") to obtain the value of a target for a country or vector of countries. Both <<target>> and <<country>> need to be strings (enclosed in "") for PFUWorkflow::readd_by_country().