R/zchunk_LA118.hydro.R

In rohmin9122/gcam-korea-release: Build the GCAM-Korea Input Datasets

#' module_energy_LA118.hydro
#'
#' Calculate hydro potential in EJ from 2010 to 2100 by GCAM region ID
#'
#' @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{L118.out_EJ_R_elec_hydro_Yfut}. The corresponding file in the
#' original data system was \code{LA118.hydro.R} (energy level1).
#' @details Different proxies are used to calculate hydro potential.
#' @details In most cases, a growth potential for each country was calculated, multiplied by its share in the region, and added to the base-year ouput
#' @importFrom assertthat assert_that
#' @importFrom dplyr filter mutate select
#' @importFrom tidyr gather spread
#' @author AS May 2017
module_energy_LA118.hydro <- function(command, ...) {
  if(command == driver.DECLARE_INPUTS) {
    return(c(FILE = "common/iso_GCAM_regID",
             FILE = "energy/Hydropower_potential",
             "L100.IEA_en_bal_ctry_hist",
             FILE = "energy/A18.hydro_output"))
  } else if(command == driver.DECLARE_OUTPUTS) {
    return(c("L118.out_EJ_R_elec_hydro_Yfut"))
  } else if(command == driver.MAKE) {

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

    # Load required inputs
    iso_GCAM_regID <- get_data(all_data, "common/iso_GCAM_regID")
    Hydropower_potential <- get_data(all_data, "energy/Hydropower_potential")
    A18.hydro_output <- get_data(all_data, "energy/A18.hydro_output")
    L100.IEA_en_bal_ctry_hist <- get_data(all_data, "L100.IEA_en_bal_ctry_hist")

    # L100.IEA_en_bal_ctry_hist might be null (meaning the data system is running
    # without the proprietary IEA data files). If this is the case, we substitute a
    # pre-built output dataset and exit.
    if(is.null(L100.IEA_en_bal_ctry_hist)) {
      L118.out_EJ_R_elec_hydro_Yfut <- prebuilt_data("L118.out_EJ_R_elec_hydro_Yfut")
    } else {
      L100.IEA_en_bal_ctry_hist %>%
        gather_years ->
        L100.IEA_en_bal_ctry_hist

      # ===================================================

      iso <- region_GCAM3 <- year <- value_base <- value_growth <- value_max_hist <-
        value <- Economic_EJ <- country_name <- GCAM_region_ID <- share <- sector <-
        fuel <- Technical_GWh <- Economic_GWh <-  Installed_GWh <- Installed_MW <-
        FLOW <- PRODUCT <- .  <- Technical_MW <- Economic_MW <- Growth_potential_EJ <-
        value_interpolated <- Growth_potential_EJ_sum <- year.x <- year.y <- year_base <-
        year_future <- value_future <- NULL   # silence package check notes

      # Calculation of economic hydropower potential by country, in EJ/yr
      # Calculate a capacity factor for translating MW to GWh, using weighted average capacity factor of all existing dams
      Hydropower_potential %>%
        select(Installed_GWh, Installed_MW) %>%
        summarise(Installed_GWh = sum(Installed_GWh), Installed_MW = sum(Installed_MW)) %>%
        mutate(value = Installed_GWh / (Installed_MW * CONV_YEAR_HOURS * CONV_MIL_BIL)) %>%
        pull(value) -> # Convert table to single number
        Hydro_capfac

      # Economic potential is what we are interested in from this database; however it is often not reported. Many countries without reported
      # economic potential nevertheless have estimates of the technical potential.
      # Calculate a translation from Technical potential to Economic potential, using weighted average among regions where both are reported
      # First, for countries reporting in MW, convert to GWh (most countries have potentials as GWh but some are in MW)
      Hydropower_potential %>%
        mutate_if(is.integer, as.numeric) %>% # Convert columns that are getting read in as integers to numbers
        mutate(Technical_GWh = replace(Technical_GWh, is.na(Technical_GWh), (Technical_MW * CONV_YEAR_HOURS * CONV_MIL_BIL * Hydro_capfac)[is.na(Technical_GWh)]),
               Economic_GWh = replace(Economic_GWh, is.na(Economic_GWh), (Economic_MW * CONV_YEAR_HOURS * CONV_MIL_BIL * Hydro_capfac)[is.na(Economic_GWh)])) ->
        Hydropower_potential

      # Among countries with both technical and economic potential reported, calculate an average translation from one to the other
      Hydropower_potential %>%
        filter(!is.na(Technical_GWh), !is.na(Economic_GWh)) %>%
        summarise(value = sum(Economic_GWh) / sum(Technical_GWh)) %>%
        pull(value) -> # Convert table to single number
        Hydro_tech_econ

      # For countries with technical potential reported but no economic potential, estimate the economic potential
      Hydropower_potential %>%
        mutate(Economic_GWh = replace(Economic_GWh, is.na(Economic_GWh), (Technical_GWh * Hydro_tech_econ)[is.na(Economic_GWh)])) %>%
        # This still leaves a few countries for which no estimates of hydro potentials are provided.
        # The largest among them is North Korea; most of the others are islands or deserts that probably don't have much beyond present-day production.
        # Not worrying about these (future growth rates will be set to 0)
        mutate(Economic_EJ = Economic_GWh * CONV_GWH_EJ) %>% # Convert GWh to EJ
        select(iso, Economic_EJ) -> # Stripping down unneeded information from table
        Hydropower_potential

      # Calculate the growth potential by country, which is the economic potential minus the actual generation in the most recent historical year (from the IEA balances)
      L100.IEA_en_bal_ctry_hist %>%
        filter(FLOW == "ELOUTPUT", PRODUCT == "Hydro", year == max(HISTORICAL_YEARS)) %>%
        mutate(value_base = value * CONV_GWH_EJ) %>%
        left_join_error_no_match(iso_GCAM_regID, by = "iso") %>%
        select(iso, region_GCAM3, year, value_base) ->
        L118.out_EJ_ctry_elec_hydro_fby

      # Aggregate by region
      L118.out_EJ_ctry_elec_hydro_fby %>%
        group_by(region_GCAM3, year) %>%
        summarise(value = sum(value_base)) %>%
        ungroup() ->
        L118.out_EJ_RG3_elec_hydro_fby

      # Calculate the future growth potential in each country as the economic potential minus the present-day generation
      Hydropower_potential %>%
        left_join(L118.out_EJ_ctry_elec_hydro_fby, by = "iso") %>%
        mutate(Growth_potential_EJ = Economic_EJ - value_base,
               Growth_potential_EJ = if_else(is.na(Growth_potential_EJ) | Growth_potential_EJ < 0, 0, Growth_potential_EJ)) %>%
        select(-region_GCAM3, -Economic_EJ, -value_base) %>%
        # Some countries (e.g., Bostwana) have NAs for RG3 names. This step is updating them (except Kosovo).
        left_join(select(iso_GCAM_regID, -country_name, -GCAM_region_ID), by = "iso") ->
        Hydropower_potential

      # Downscaling of GCAM 3.0 scenario to the country level: Assign future growth according to shares of growth potential by country
      # Interpolate any between years, and use the final year as a proxy for years thereafter
      # Drop 2020 because it is lower than 2010 in many regions

      # First, convert A18.hydro_output to long form
      A18.hydro_output %>%
        gather_years ->
        A18.hydro_output_long

      # Now combine with L118.out_EJ_RG3_elec_hydro_fby
      L118.out_EJ_RG3_elec_hydro_fby %>%
        bind_rows(A18.hydro_output_long) %>%
        filter(year != 2020) -> # Dropping 2020, as described above
        L118.out_EJ_RG3_elec_hydro_Y_with_values

      # Create a table from 2010 to 2100 in all "FUTURE_YEARS" and interpolate for the missing values
      L118.out_EJ_RG3_elec_hydro_fby %>%
        select(region_GCAM3) %>%
        repeat_add_columns(tibble::tibble(year = c(max(HISTORICAL_YEARS), FUTURE_YEARS))) %>% # Years include historical max and future
        left_join(L118.out_EJ_RG3_elec_hydro_Y_with_values, by = c("region_GCAM3", "year")) %>%
        group_by(region_GCAM3) %>%
        mutate(value_interpolated = approx_fun(year, value, rule = 2)) %>% # Interpolation step
        ungroup() %>%
        select(-value) ->
        L118.out_EJ_RG3_elec_hydro_Y_interp

      # Calculate the growth from the base year in each region_GCAM3. This will be partitioned to countries according to potential
      # First, separate historical max year to use added later as its own column
      L118.out_EJ_RG3_elec_hydro_Y_interp %>%
        filter(year == max(HISTORICAL_YEARS)) %>%
        rename(value_max_hist = value_interpolated) %>%
        select(-year) ->
        L118.out_EJ_RG3_elec_hydro_Y_interp_maxhist

      # Now add the historical max year as its own column, and delete in interpolated column
      L118.out_EJ_RG3_elec_hydro_Y_interp %>%
        filter(year != max(HISTORICAL_YEARS)) %>% # Deleting historical max year to be used in another column
        left_join(L118.out_EJ_RG3_elec_hydro_Y_interp_maxhist, by = "region_GCAM3") %>%
        # Calculate growth, which is total value (interpolated) minus the base (historical max)
        mutate(value_growth = value_interpolated - value_max_hist) %>%
        select(-value_interpolated, -value_max_hist) ->
        L118.growth_EJ_RG3_elec_hydro_Y

      # Calculate the share of the growth potential by each country within its GCAM 3.0 region
      Hydropower_potential %>%
        group_by(region_GCAM3) %>%
        summarise(Growth_potential_EJ_sum = sum(Growth_potential_EJ)) %>%
        filter(!is.na(region_GCAM3)) -> # Getting rid of the NA caused by Kosova not having a RG3 name
        Hydropower_potential_RG3 # Represents total pie of each country

      # Here the countries' shares will be calculated
      Hydropower_potential %>%
        left_join(Hydropower_potential_RG3, by = "region_GCAM3") %>%
        mutate(share = Growth_potential_EJ / Growth_potential_EJ_sum) %>% # Calculating share
        # Add future years to table of base-year hydropower generation as base-year output plus region_GCAM3 growth times country-wise share
        select(iso, share) %>% # Need only share of each iso
        group_by(iso) %>%
        summarise(share = sum(share)) -> # Summing up Serbia...was listed twice
        Hydropower_potential

      # Adding future years
      L118.out_EJ_ctry_elec_hydro_fby %>%
        left_join(Hydropower_potential, by = "iso") %>% # Adding share column
        left_join(L118.growth_EJ_RG3_elec_hydro_Y, by = "region_GCAM3") %>% # Adding RG3 growth
        mutate(value_future = value_base + share * value_growth) %>% # Base-year output plus RG3 growth times country-wise share
        select(-share, -value_growth) %>%
        # Renaming year.x (base year) and year.y (future year)
        rename(year_base = year.x, year_future = year.y) %>%
        spread(year_base, value_base) %>%
        spread(year_future, value_future) %>%
        gather_years ->
        L118.out_EJ_ctry_elec_hydro_Y

      # For countries not in the world dams database (all are very small), copy final historical year forward
      # First create list to use as filter
      iso_list <- Hydropower_potential$iso

      L118.out_EJ_ctry_elec_hydro_Y %>%
        filter(!iso %in% iso_list) %>% # Filtering for what's excluded from list
        arrange(iso, year) %>%
        fill(value) -> # Copying final historical year forward
        countries_not_in_WDdatabase

      # Adding these countries not in the world dams database back in
      L118.out_EJ_ctry_elec_hydro_Y %>%
        filter(iso %in% iso_list) %>%
        bind_rows(countries_not_in_WDdatabase) ->
        L118.out_EJ_ctry_elec_hydro_Y

      # Aggregate by region
      L118.out_EJ_ctry_elec_hydro_Y %>%
        left_join_error_no_match( # Adding GCAM region ID back in for final table
          select(iso_GCAM_regID, iso, GCAM_region_ID),
          by = "iso") %>%
        group_by(GCAM_region_ID, year) %>%
        summarise(value = sum(value)) %>%
        ungroup %>%
        mutate(sector = "electricity generation", fuel = "hydro") %>%
        select(GCAM_region_ID, sector, fuel, year, value) %>%
        add_title("L118.out_EJ_R_elec_hydro_Yfut") ->
        L118.out_EJ_R_elec_hydro_Yfut

      # ===================================================

      L118.out_EJ_R_elec_hydro_Yfut %>%
        add_units("EJ") %>%
        add_comments("Hydro potential was determined using various proxies") %>%
        add_comments("In most cases, a growth potential for each country was calculated,
                   multiplied by its share in the region, and added to the base-year ouput") %>%
        add_legacy_name("L118.out_EJ_R_elec_hydro_Yfut") %>%
        add_precursors("common/iso_GCAM_regID", "energy/Hydropower_potential",
                       "L100.IEA_en_bal_ctry_hist", "energy/A18.hydro_output") ->
        L118.out_EJ_R_elec_hydro_Yfut

      # At this point output should be identical to the prebuilt version
      verify_identical_prebuilt(L118.out_EJ_R_elec_hydro_Yfut)
    }

    return_data(L118.out_EJ_R_elec_hydro_Yfut)
  } else {
    stop("Unknown command")
  }
}