get_plan: Create a drake plan for societal exergy analysis

In MatthewHeun/SEAPSUTWorkflow: Functions and Workflows for Primary-Final-Useful Societal Exergy Analysis Within the PSUT Framework

Create a drake plan for societal exergy analysis

Description

Creates a drake workflow for societal exergy analysis. The caller specifies location of IEA data, which countries should be analyzed, and which the maximum year to be analyzed.

Usage

get_plan(
  countries,
  additional_exemplar_countries = NULL,
  max_year,
  how_far = "all_targets",
  iea_data_path,
  country_concordance_path,
  phi_constants_path,
  ceda_data_folder,
  machine_data_path,
  exemplar_table_path,
  fu_analysis_folder,
  reports_source_folders,
  reports_dest_folder,
  pipeline_caches_folder,
  pipeline_releases_folder,
  release = FALSE
)

Arguments

countries	A vector of abbreviations for countries whose energy conversion chain is to be analyzed, such as "c('GHA', 'ZAF')". Countries named in countries can also serve as exemplars for final-to-useful allocations and efficiencies.
additional_exemplar_countries	A vector of country abbreviations for which final-to-useful allocations and efficiencies will be read. An energy conversion chain will not be constructed for these countries. However, their final-to-useful allocations and efficiencies may be used as exemplar information for the countries in countries. Default is NULL, indicating no additional exemplars.
max_year	The last year to be studied, typically the last year for which data are available.
how_far	A string indicating the last target to include in the plan that is returned. Default is "all_targets" to indicate all targets of the plan should be returned.
iea_data_path	The path to IEA extended energy balance data in .csv format.
country_concordance_path	The path to the country concordance Excel file.
phi_constants_path	The path to a phi (exergy-to-energy ratio) Excel file.
ceda_data_folder	The path to the CEDA data in text file, .per, format.
machine_data_path	The path to the machine data in .xlsx format.
exemplar_table_path	The path to an exemplar table.
fu_analysis_folder	The path to a folder containing final-to-useful analyses. Sub-folders named with 3-letter country abbreviations are assumed.
reports_source_folders	A string vector containing paths to folders of report sources, usually .Rnw or .Rmd files.
reports_dest_folder	The path to a folder into which reports are written.
pipeline_caches_folder	The path to a folder where .zip files of the pipeline cache folders are stored.
pipeline_releases_folder	The path to a folder where releases of important targets are stored for later retrieval as pinned items on a pinboard..
release	A boolean that tells whether a new release of the PSUT target should be made. Default is FALSE.

Details

The return value is a drake plan object with the following targets:

• countries: The countries to be analyzed, supplied in the countries argument.

• alloc_and_eff_couns: The full set of countries for which final-to-useful allocations and efficiencies will be read. This is the sum of countries and additional_exemplar_countries, with duplicates removed.

• max_year: The maximum year to be analyzed, supplied in the max_year argument.

• iea_data_path: The path to IEA extended energy balance data, supplied in the iea_data_path argument.

• country_concordance_path: The path to the country concordance file, supplied in the country_concordance_path argument.

• phi_constants_path: The path to a phi (exergy-to-energy ratio) file, supplied in the phi_constants_path argument.

• ceda_data_folder: The path to the CEDA data, supplied in the ceda_data_folder argument.

• machine_data_path: The path to the machine data excel files, supplied in the machine_data_path argument.

• exemplar_table_path: The path to an exemplar table, supplied in the exemplar_table_path argument.

• fu_analysis_folder: The path to the final-to-useful analysis folder, supplied in the fu_analysis_folder argument.

• report_output_folder: The path to a report output folder, supplied in the report_output_folder argument.

• CountryConcordanceTable: A data frame containing concordance information which maps full country names to custom 3 letter codes.

• AllIEAData: A data frame with all IEA extended energy balance data read from iea_data_path.

• IEAData: A version of the AllIEAData data frame containing data for only those countries specified in countries.

• CEDAData: A data frame containing temperature data supplied through CEDATools::read_cru_cy_files.

• AllMachineData: A data frame containing Eta.fu values read through functions in machine_functions.R.

• MachineData: A filtered version of AllMachineData containing information for only alloc_and_eff_couns.

• balanced_before: A boolean that tells where the data were balanced as received, usually a vector of FALSE, one for each country.

• BalancedIEAData: A data frame containing balanced IEA extended energy balance data.

• balanced_after: A boolean telling whether IEA extended energy balance data is balanced after balancing, usually a vector of TRUE, one for each country.

• OKToProceed: NULL means everything is balanced and proceeding is OK.

• Specified: A data frame with specified industries. See IEATools::specify_all().

• PSUT_final: A data frame containing PSUT matrices up to the final stage.

• ExemplarLists: A data frame containing lists of exemplar countries on a per-country, per-year basis.

Value

A drake plan object.

Phi_constants: A table of reasonable constant values for phi, the energy-to-exergy ratio.

• IncompleteAllocationTables: A data frame containing final-to-useful allocation tables.

• TidyIncompleteAllocationTables: A data frame containing final-to-useful allocation tables.

• CompletedAllocationTables : A data frame containing completed final-to-useful allocation tables.

• CompletedEfficiencyTables: A data frame containing completed final-to-useful efficiency tables.

• CompletedPhiTables : A data frame of completed exergy-to-energy ratios.

• Cmats : A data frame containing CompletedAllocationTables in matrix form.

• EtaPhivecs : A data frame containing final-to-useful efficiency and exergy-to-energy ratio vectors.

• PSUT_useful : A data frame containing PSUT matrices up to the useful stage.

• FinalDemandSectors: A list of final demand sectors, supplied through the get_fd_sectors function.

• PrimaryIndustryPrefixes: A string vector of primary industry prefixes, supplied through the get_p_industry_prefixes function.

• AggregatePrimaryData : A data frame containing aggregate primary energy and exergy values by total, product, and flow.

• AggregateFinalUsefulData : A data frame containing aggregate final and useful energy and exergy values by total, product, and sector.

• SocioEconData : A data frame containing socioeconomic data, supplied by the get_L_K_GDP_data function.

• AllocationGraphs : A data frame containing allocation plots.

• NonStationaryAllocationGraphs : A data frame containing allocation plots for non-stationary data only.

• EfficiencyGraphs : A data frame containing final-to-useful efficiency plots.

• ExergyEnergyGraphs : A data frame containing exergy-to-energy ratio plots.

• report_source_paths: A string vector of paths to sources for reports.

• report_dest_paths: A string for the path to a folder into which reports will written.

• reports_complete: A boolean that tells whether reports were written successfully.

Callers can execute the plan by calling drake::make(plan). Results can be recovered with drake::readd(target = iea_data_path) or similar.

Note that some targets can be read using readd_by_country(), including:

• AllIEAData,

• IEAData,

• BalancedIEAData,

• Specified,

• PSUT_final,

• ExemplarLists,

• IncompleteAllocationTables,

• CompletedAllocationTables,

• IncompleteEfficiencyTables, and

• CompletedEfficiencyTables,

See Also

• How to create a plan in a function

• Best practices for unit tests on custom functions for a drake workflow

• drakepkg

• Workflows as R packages

Examples

get_plan(countries = c("GHA", "ZAF"),
         max_year = 1999,
         iea_data_path = "iea_path",
         country_concordance_path = "country_concordance_path",
         phi_constants_path = "phi_constants_path",
         ceda_data_folder = "ceda_path",
         machine_data_path = "machine_path",
         exemplar_table_path = "exemplar_path",
         fu_analysis_folder = "fu_folder",
         reports_source_folders = "reports_source_folders",
         reports_dest_folder = "reports_dest_folder",
         pipeline_caches_folder = "pipeline_caches_folder",
         pipeline_releases_folder = "pipeline_releases_folder")

MatthewHeun/SEAPSUTWorkflow documentation built on April 22, 2022, 2:21 p.m.