reVeal.load.downscale_total#

downscale_total(grid_df, grid_priority_col, grid_baseline_load_col, baseline_year, grid_capacity_col, load_df, load_value_col, load_year_col, max_site_addition_per_year=None, site_saturation_limit=1, priority_power=1, n_bootstraps=10000, random_seed=0, max_workers=None, hide_pbar=False, reduce_output=False)[source]#

Downscale aggregate load projections to grid based on grid priority column. Note that this method uses a random bootstrapping approach to achieve greater dispersion of load across multiple grid cells, and the degree of dispersion can be tuned manually using input parameters such as site_saturation_limit, priority_power, and n_bootstraps.

Parameters:

  • grid_df (pandas.DataFrame) – Pandas dataframe where each record represents a site to which load projections may be downscaled

  • grid_priority_col (str) – Name of column in grid_df to use for prioritizing sites for downscaling load.

  • grid_baseline_load_col (str) – Name of column in grid_df with numeric values indicating the baseline, or initial, load in each site, corresponding to the baseline_year.

  • baseline_year (int) – Year corresponding to the baseline load values in grid_baseline_load_col.

  • grid_capacity_col (str) – Name of column in grid_df indicating the developable capacity of load within each site.

  • load_df (pandas.DataFrame) – Dataframe containing aggregate load projections for the area encompassing the input grid_df sites.

  • load_value_col (str) – Name of column in load_df containing projections of load.

  • load_year_col (str) – Name of column in load_df containing year values corresponding to load projections.

  • max_site_addition_per_year (float, optional) – Value indicating the maximum allowable increment of load that can be added in a given year to an individual site. The default value is None, which will not apply a cap. This value can be used to ensure that the rate of expansion of large load capacity in localized areas is not unrealistically rapid. Using this parameter can also have the effect of achieving greater geographic dispersion of load: since there is a limit to the pace at which individual sites can build out load, more sites are typically required for the same amount of project load.

  • site_saturation_limit (float, optional) – Adjustment factor limit the developable capacity of load within each site. This value is used to scale the values in the grid_capacity_col. For example, to limit the maximum deployed load in each site to half of the actual developable load, use site_saturation_limit=0.5. The lower this value is set, the greater the degree of dispersion of load across sites will be. The dfault is 1, which leaves the values in the grid_capacity_col unmodified.

  • priority_power (int, optional) – This factor can be used to exaggerate the influence of the values in grid_priority_col, such that higher values have an increased likelihood of load deployment and lower values have a decreased likelihood. This effect is implemented by raising the values in grid_priority_col to the specified priority_power. As a result, if the input values in grid_priority_col are < 1, setting priority_power to high values can result in completely eliminating lower priority sites from consideration. The default value is 1, which leaves the values in grid_priority_col unmodified. To achieve less dispersion and greater clustering of downscaled load in higher priority sites, increase this value.

  • n_bootstraps (int, optional) – Number of bootstraps to simulate in each projection year. Default is 10,000. In general, larger values will produce more stable results, with less chance for lower priority sites to receive large amounts of deployed load. However, larger values will also cause longer run times.

  • random_seed (int, optional) – Random seed to use for reproducible bootstrapping. Default is 0. In general, this value does not need to be modified. The exception is if you are interested in testing sensitivities and/or producing multiple realizations or scenarios of deployment for a given set of values in load_priority_col.

  • max_workers (int, optional) – Number of workers to use for bootstrapping. By default None, which uses all available workers. In general, this value should only be changed if you are running into out-of-memory errors.

  • hide_pbar (bool, optional) – If specified as True, hide the progress bar when running bootstraps. Default is True, which will show the progress bar.

  • reduce_output (bool, optional) – If specified as True, reduce the output DataFrame to only include essential columns. Default is False.

Returns:

pandas.DataFrame – Returns DataFrame consisting of load projections downscaled to the grid. This dataframe will contain all of the columns from the input grid_df, as well as three new columns, including year (indicating the year of the projection) and a “new_” and “total_” load column, named with a suffix corresponding to the load_value_col.

Raises:

ValueError – A ValueError will be raised if internal consistency checks for downscaled results do not pass.

On this page