R/zchunk_L114.bcoc_en_R_S_T_Y.R

In JGCRI/gcamdata: Build the GCAM Input Datasets

# Copyright 2019 Battelle Memorial Institute; see the LICENSE file.

#' module_emissions_L114.bcoc_en_R_S_T_Y
#'
#' Compute emissions coefficients for black carbon (BC) and organic carbon (OC) for a single representative base year
#'
#' @param command API command to execute
#' @param ... other optional parameters, depending on command
#' @return Depends on \code{command}: either a vector of required inputs,
#' a vector of output names, or (if \code{command} is "MAKE") all
#' the generated outputs: \code{L114.bcoc_tgej_R_en_S_F_2000}. The corresponding file in the
#' original data system was \code{L114.bcoc_en_R_S_T_Y.R} (emissions level1).
#' @details Computes black carbon (BC) and organic carbon (OC) emissions by RCP emissions dataset sector/source, and
#' divides by the corresponding drivers for the ~2000 base year in order to compute emissions coefficients. The coefs
#' are in units of Tg per EJ (or kg per GJ) of fuel input. Data are generated by GCAM region, sector (energy system only),
#' and fuel, for the year 2000.
#' @importFrom assertthat assert_that
#' @importFrom dplyr bind_rows filter group_by inner_join mutate select summarise
#' @importFrom tidyr gather spread
#' @author GPK May 2017
module_emissions_L114.bcoc_en_R_S_T_Y <- function(command, ...) {
  if(command == driver.DECLARE_INPUTS) {
    return(c(FILE = "common/iso_GCAM_regID",
             FILE = "emissions/mappings/EPA_ghg_tech",
             FILE = "emissions/mappings/GCAM_sector_tech",
             FILE = "emissions/mappings/GCAM_sector_tech_Revised",
             "L101.in_EJ_R_en_Si_F_Yh",
             "L104.bcoc_tgej_USA_en_T_1990",
             FILE = "emissions/RCP_BC_2000",
             FILE = "emissions/RCP_OC_2000"))
  } else if(command == driver.DECLARE_OUTPUTS) {
    return(c("L114.bcoc_tgej_R_en_S_F_2000"))
  } else if(command == driver.MAKE) {

    BCOC_agg_fuel <- BCOC_agg_sector <- Country <- Non.CO2 <- GCAM_region_ID <-
      RCP_agg_sector <- emissions.factor <- energy <- fuel <- input.emissions <-
      iso  <- scaled_emissions <- scaler <- sector <- stub.technology <- subsector <-
      supplysector <- technology <- unscaled_emissions <- year <- NULL # silence package check notes

    all_data <- list(...)[[1]]

    # Load required inputs
    iso_GCAM_regID <- get_data(all_data, "common/iso_GCAM_regID")
    EPA_ghg_tech <- get_data(all_data, "emissions/mappings/EPA_ghg_tech")
    GCAM_sector_tech <- get_data(all_data, "emissions/mappings/GCAM_sector_tech")

    if (energy.TRAN_UCD_MODE == "rev.mode"){
      GCAM_sector_tech <- get_data(all_data, "emissions/mappings/GCAM_sector_tech_Revised")

    }


    L101.in_EJ_R_en_Si_F_Yh <- get_data(all_data, "L101.in_EJ_R_en_Si_F_Yh")
    L104.bcoc_tgej_USA_en_T_1990 <- get_data(all_data, "L104.bcoc_tgej_USA_en_T_1990")
    RCP_BC_2000 <- get_data(all_data, "emissions/RCP_BC_2000")
    RCP_OC_2000 <- get_data(all_data, "emissions/RCP_OC_2000")

    # Compile the driver data (energy consumption by sector and fuel, around the year 2000)
    BCOC_drivers <- L101.in_EJ_R_en_Si_F_Yh %>%
      gather_years(value_col = "energy") %>%
      filter(year == 2000) %>%
      # Repeat by the names of the gases whose default coefficients will be joined in
      repeat_add_columns(tibble(Non.CO2 = c("BC", "OC"))) %>%
      # Join in the sectors and fuels that correspond to the default BC and OC emissions coefs
      # Note: many of the sector/tech combinations in the GCAM_sector_tech mapping file are duplicates, so
      # the appropriate function to use whenever this table is joined in is the 'first' match. Dealing with this
      # would require a third "by" column (fuel), which would require modifications to the GCAM_sector_tech
      # mapping table.
      left_join_keep_first_only(select(GCAM_sector_tech, sector, technology,BCOC_agg_sector, BCOC_agg_fuel),
                                by = c("sector", "technology"))

    # Prepare the BC/OC default emissions factors (computed in L104) for joining into the BCOC driver table
    BCOC_default_coefs <- L104.bcoc_tgej_USA_en_T_1990 %>%
      gather(Non.CO2, emissions.factor, -sector, -technology) %>%
      # The Non.CO2 column has "bc_em_factor" where we want "BC", and so on for OC
      mutate(Non.CO2 = toupper(substr(Non.CO2, 1, 2))) %>%
      # The "sector" and "technology" columns should be renamed to "BCOC_agg_sector" and "BCOC_agg_fuel"
      rename(BCOC_agg_sector = sector, BCOC_agg_fuel = technology)

    # Join in the coefficients and multiply to get the unscaled BC and OC emissions by
    # region, sector, and technology for the year 2000
    BCOC_unscaled_emissions <- BCOC_drivers %>%
      # inner join because there are NA's and they are intended to be dropped
      inner_join(BCOC_default_coefs, by = c("BCOC_agg_sector", "BCOC_agg_fuel", "Non.CO2")) %>%
      mutate(unscaled_emissions = energy * emissions.factor) %>%
      # Match in the RCP sectors used for scaling these emissions prior to aggregation
      left_join_keep_first_only(select(GCAM_sector_tech, sector, technology, RCP_agg_sector),
                                by = c("sector", "technology"))

    # Aggregate by the broader "RCP" categories for computing scalers
    BCOC_unscaled_emissions_RCP <- BCOC_unscaled_emissions %>%
      group_by(GCAM_region_ID, Non.CO2, RCP_agg_sector) %>%
      summarise(unscaled_emissions = sum(unscaled_emissions)) %>%
      ungroup()

    # Prepare the RCP inventory estimates for joining into the table of unscaled emissions by RCP inventory categories
    RCP_BC_2000$Non.CO2 <- "BC"
    RCP_OC_2000$Non.CO2 <- "OC"
    BCOC_emissions_RCP <- bind_rows(RCP_BC_2000, RCP_OC_2000) %>%
      gather(RCP_agg_sector, scaled_emissions, -Country, -iso, -Non.CO2) %>%
      mutate(scaled_emissions = scaled_emissions * CONV_KG_TO_TG) %>%
      left_join_error_no_match(iso_GCAM_regID, by = "iso") %>%
      group_by(GCAM_region_ID, Non.CO2, RCP_agg_sector) %>%
      summarise(scaled_emissions = sum(scaled_emissions)) %>%
      ungroup()

    # Join the scaled emissions totals from the RCP inventory back into the table of unscaled emissions to compute scalers
    BCOC_emissions_scaler <- BCOC_unscaled_emissions_RCP %>%
      left_join_error_no_match(BCOC_emissions_RCP, by = c("GCAM_region_ID", "Non.CO2", "RCP_agg_sector")) %>%
      mutate(scaler = scaled_emissions / unscaled_emissions) %>%
      select(GCAM_region_ID, Non.CO2, RCP_agg_sector, scaler)

    # Multiply these scalers by the unscaled emissions by GCAM region, sector, and technology to compute scaled emissions
    BCOC_scaled_emissions <- BCOC_unscaled_emissions %>%
      left_join_error_no_match(BCOC_emissions_scaler, by = c("GCAM_region_ID", "Non.CO2", "RCP_agg_sector")) %>%
      mutate(input.emissions = unscaled_emissions * scaler) %>%
      # Join in the supplysector/subsector/technology from the mapping table
      left_join_keep_first_only(select(GCAM_sector_tech, sector, fuel, technology, supplysector, subsector, stub.technology),
                                by = c("sector", "fuel", "technology")) %>%
      # Group by categories for GCAM and aggregate the emissions
      group_by(GCAM_region_ID, Non.CO2, supplysector, subsector, stub.technology) %>%
      summarise(input.emissions = sum(input.emissions)) %>%
      ungroup()

    # Compile energy consumption by the corresponding technologies in order to compute emissions coefficients
    BCOC_drivers_GCAMtech <- BCOC_drivers %>%
      filter(Non.CO2 == "BC") %>% # we only need one of the two
      left_join_keep_first_only(select(GCAM_sector_tech, sector, fuel, technology, supplysector, subsector, stub.technology),
                                by = c("sector", "fuel", "technology")) %>%
      group_by(GCAM_region_ID, supplysector, subsector, stub.technology) %>%
      summarise(energy = sum(energy)) %>%
      ungroup()

    # Compute the emissions coefficients for the year 2000
    L114.bcoc_tgej_R_en_S_F_2000 <- BCOC_scaled_emissions %>%
      left_join_error_no_match(BCOC_drivers_GCAMtech,
                               by = c("GCAM_region_ID", "supplysector", "subsector", "stub.technology")) %>%
      mutate(emissions.factor = input.emissions / energy) %>%
      na.omit() %>%
      mutate(year = 2000) %>%
      select(GCAM_region_ID, Non.CO2, supplysector, subsector, stub.technology, year, emissions.factor) %>%
      spread(year, emissions.factor)
    # Document for output
    L114.bcoc_tgej_R_en_S_F_2000 %>%
      add_title("BC / OC emissions factors for energy technologies by GCAM region / sector / technology / 2000") %>%
      add_units("Tg / EJ (kg/GJ)") %>%
      add_comments("Black carbon (BC) and organic carbon (OC) emissions coefficients (Tg/EJ)") %>%
      add_comments("by GCAM region, sector (energy sectors only), and fuel, for the year 2000") %>%
      add_legacy_name("L114.bcoc_tgej_R_en_S_F_2000") %>%
      add_precursors("common/iso_GCAM_regID",
                     "emissions/mappings/EPA_ghg_tech",
                     "emissions/mappings/GCAM_sector_tech",
                     "emissions/mappings/GCAM_sector_tech_Revised",
                     "L101.in_EJ_R_en_Si_F_Yh",
                     "L104.bcoc_tgej_USA_en_T_1990",
                     "emissions/RCP_BC_2000",
                     "emissions/RCP_OC_2000") ->
      L114.bcoc_tgej_R_en_S_F_2000

    return_data(L114.bcoc_tgej_R_en_S_F_2000)
  } else {
    stop("Unknown command")
  }
}