Update documentation for grid decarbonization arguments

docs/config_readable.yml

@@ -73,8 +73,8 @@ ecm_prep:
       null
     grid_decarb_level: (string, required if the grid_decarb key
       is present) Enable grid decarbonization - `95by2050` represents
-      95 percent reduced grid emissions from current levels by
-      2050 and `100by2035` represents 100 percent grid decarbonization
+      a 95 percent reduction in grid emissions from 2005 levels
+      by 2050 and `100by2035` represents 100 percent grid decarbonization
       by 2035. 'DECARB' options were produced as part of EERE's
       DECARB initiative; `DECARB-mid` represents 97 percent grid
       decarbonization by 2050, and `DECARB-high` represents 100

docs/tutorials.rst

@@ -1387,7 +1387,7 @@ Restricted adoption scenarios
 
 Detailed results breakouts
 **************************
-``--detail_brkout`` reports regional, building type, and/or fuel type breakouts of results at the highest possible resolution. Valid options include at least one of "regions", "buildings", and "fuel types". If "regions" is included, then ``--alt_regions`` must be set to "EMM". If "fuel types" is included, then ``--split_fuel`` must be false.
+``--detail_brkout`` reports regional, building type, and/or fuel type breakouts of results at the highest possible resolution. Valid options include at least one of "regions", "buildings", "fuel types", and "all". If "regions" is included, then ``--alt_regions`` must be set to "EMM". If "fuel types" is included, then ``--split_fuel`` must be false.
 
 .. note::
    Default regional breakouts depend on the :ref:`region selection <ecm-baseline_climate-zone>` for the current run. An :ref:`AIA <cz-reg>` region selection does not have a more detailed breakout option. An :ref:`EMM <emm-reg>` region selection defaults to reporting breakouts for a higher-level aggregation of those 25 regions into 11 broader regions that are similar to the `2019 EPA AVERT regions`_ but separate the Great Basin from the Northwest region; the detailed breakout option resolves results by all 25 EMM regions. Finally, a :ref:`U.S. state <state-reg>` region selection defaults to reporting breakouts by the 9 `U.S. Census Divisions`_; the detailed breakout option resolves results by all contiguous U.S. states plus the District of Columbia.
@@ -1397,12 +1397,12 @@ Detailed results breakouts
 High electric grid decarbonization
 **********************************
 
-``--grid_decarb_level`` selects versions of annual and hourly electricity emissions and price inputs that are consistent with a more aggressive decarbonization pathway for the electric grid than is assumed in the default `AEO Reference Case`_. When this argument is passed, the user must specify either "0.8" or "full" to define the additional grid decarbonization scenario. The "0.8" option represents a scenario in which remaining grid emissions are reduced 80% by 2050, while "full" represents a scenario in which remaining grid emissions are reduced to zero by 2035.
+``--grid_decarb_level`` selects versions of annual and hourly electricity emissions and price inputs that are consistent with a more aggressive decarbonization pathway for the electric grid than is assumed in the default `AEO Reference Case`_. When this argument is passed, the user must specify either "95by2050", "100by2035", "DECARB-mid", or "DECARB-high" to define the additional grid decarbonization scenario. "95by2050" represents a 95 percent reduction in grid emissions from 2005 levels by 2050 and "100by2035" represents 100 percent grid decarbonization by 2035. 'DECARB' options were produced as part of EERE's DECARB initiative; "DECARB-mid" represents 97 percent grid decarbonization by 2050, and "DECARB-high" represents 100 percent grid decarbonization by 2035. This argument is only applicable if ``--grid_assessment_timing`` is also provided.
 
-``--grid_assessment_timing`` selects whether avoided emissions and costs from non-fuel switching measures should be assessed *before* or *after* accounting for additional grid decarbonization beyond the Reference Case, by specifying either "before" or "after" with this argument. Avoided emissions and costs for fuel switching measures will always be assessed *after* accounting for additional grid decarbonization beyond the Reference Case.
+``--grid_assessment_timing`` selects whether avoided emissions and costs from non-fuel switching measures should be assessed *before* or *after* accounting for additional grid decarbonization beyond the Reference Case, by specifying either "before" or "after" with this argument. Avoided emissions and costs for fuel switching measures will always be assessed *after* accounting for additional grid decarbonization beyond the Reference Case. This argument is only applicable if ``--grid_decarb_level`` is also provided.
 
 .. note::
-   Annual emissions intensities for the more aggressive grid decarbonization scenarios are drawn from runs of The Brattle Group's `GridSIM modeling tool`_ and are found in |html-filepath| ./scout/supporting_data/convert_data |html-fp-end| . Annual electricity price data (also found in |html-filepath| ./scout/supporting_data/convert_data |html-fp-end| ) and hourly electricity emissions and price data for the more aggressive grid decarbonization scenarios (found in |html-filepath| ./scout/supporting_data/tsv_data |html-fp-end| ) are drawn from different sources --- the `EIA Annual Energy Outlook Low Renewable Cost Side Case`_ for the annual electricity price data, and the `NREL Cambium Low Renewable Energy Cost Scenario`_ for the hourly data.
+   Annual emissions intensities for the more aggressive grid decarbonization scenarios are drawn from the `NREL Cambium scenarios`_ and the `Scout DECARB scenarios`_ and are found in |html-filepath| ./scout/supporting_data/convert_data |html-fp-end| . Annual electricity price data (also found in |html-filepath| ./scout/supporting_data/convert_data |html-fp-end| ) and hourly electricity emissions and price data for the more aggressive grid decarbonization scenarios (found in |html-filepath| ./scout/supporting_data/tsv_data |html-fp-end| ) are drawn from different sources --- the `EIA Annual Energy Outlook Low Renewable Cost Side Case`_ for the annual electricity price data, and the `NREL Cambium Low Renewable Energy Cost Scenario`_ for the hourly data.
 
 .. note::
    Currently the ``--grid_decarb`` option is not supported for state regions; if state regions are selected alongside the ``--grid_decarb`` option, the code will automatically switch the run to EMM regions while warning the user.
@@ -1921,7 +1921,8 @@ In each results tab, rows 2-22 include results summed across the entire ECM port
 .. .. [#] If the warning "there is no package called 'foo'," where "foo" is a replaced by an actual package name, appears in the R Console window, try running the script again. If the warning is repeated, the indicated package should be added manually. From the Packages menu, (Windows) select Install package(s)... or (Mac) from the Packages & Data menu, select Package Installer and click the Get List button in the Package Installer window. If prompted, select a repository from which to download packages. On Windows, select the named package (i.e., "foo") from the list of packages that appears. On a Mac, search in the list for the named package (i.e., "foo"), click the "Install Dependencies" checkbox, and click the "Install Selected" button. When installation is complete, close the Package Installer window.
 
 .. _this plot: https://drive.google.com/file/d/1PNp47uEneuhREx3-AIwPXufXDNpkrZCp/view?usp=sharing
-.. _GridSIM modeling tool: https://www.brattle.com/energy-strategy-and-planning/
+.. _NREL Cambium scenarios: https://scenarioviewer.nrel.gov
+.. _Scout DECARB scenarios: https://zenodo.org/records/10653885
 .. _EIA Annual Energy Outlook Low Renewable Cost Side Case: https://www.eia.gov/outlooks/aeo/tables_side.php
 .. _NREL Cambium Low Renewable Energy Cost Scenario: https://cambium.nrel.gov/?project=579698fe-5a38-4d7c-8611-d0c5969b2e54&mode=view&layout=Default%20Layout
 .. _IECC climate regions: https://codes.iccsafe.org/content/IECC2021P1/chapter-3-ce-general-requirements

scout/ecm_prep.py

@@ -153,8 +153,18 @@ def __init__(self, opts):
         self.hp_convert_rates = fp.CONVERT_DATA / "hp_convert_rates.json"
         self.fug_emissions_dat = fp.CONVERT_DATA / "fugitive_emissions_convert.json"
 
-    def set_decarb_grid_vars(self, opts):
+    def set_decarb_grid_vars(self, opts: argparse.NameSpace):  # noqa: F821
+        """Assign instance variables related to grid decarbonization which are dependent on the
+            alt_regions, alt_ref_carb, grid_decarb_level, and grid_assessment_timing arguments.
+
+        Args:
+            opts (argparse.NameSpace): argparse object containing the argument attributes
+        """
+
         def get_suffix(arg):
+            """Return a suffix derived from a user-supplied argument string to append to filepath
+                variables; if argument is None, return an empty string.
+            """
             if arg is None:
                 return ''
             else:
@@ -181,7 +191,7 @@ def get_suffix(arg):
                 # Set emissions/cost reductions for non-fuel switching measures after grid
                 # decarbonization
                 self.ss_data_altreg_nonfs = None
-            # Set filepaths for EMM region emissions prices
+            # Set filepaths for EMM region emissions and prices
             for var, filesuffix in emission_var_map.items():
                 filepath = fp.CONVERT_DATA / f"emm_region_emissions_prices{filesuffix}.json"
                 setattr(self, var, filepath)
@@ -197,12 +207,12 @@ def get_suffix(arg):
 
         # Set site-source conversions files for grid decarbonization case
         if opts.grid_decarb:
+            self.ss_data = (fp.CONVERT_DATA /
+                            f"site_source_co2_conversions{grid_decarb_level_suffix}.json")
             # Update tsv data file suffixes for DECARB levels
             if "DECARB" in grid_decarb_level_suffix:
                 grid_decarb_level_suffix = {"-DECARB-mid": "-95by2050",
                                             "-DECARB-high": "-100by2035"}[grid_decarb_level_suffix]
-            self.ss_data = (fp.CONVERT_DATA /
-                            f"site_source_co2_conversions{grid_decarb_level_suffix}.json")
             self.tsv_cost_data = fp.TSV_DATA / f"tsv_cost{grid_decarb_level_suffix}.json"
             self.tsv_carbon_data = fp.TSV_DATA / f"tsv_carbon{grid_decarb_level_suffix}.json"
 

scout/supporting_data/config_schema.yml

@@ -149,7 +149,7 @@ properties:
           grid_decarb_level:
             type: ["string", "null"]
             enum: [95by2050, 100by2035, DECARB-mid, DECARB-high, null]
-            description: Enable grid decarbonization - `95by2050` represents 95 percent reduced grid emissions from current levels by 2050 and `100by2035` represents 100 percent grid decarbonization by 2035. 'DECARB' options were produced as part of EERE's DECARB initiative; `DECARB-mid` represents 97 percent grid decarbonization by 2050, and `DECARB-high` represents 100 percent grid decarbonization by 2035. Only applicable if `grid_assessment_timing` is also provided.
+            description: Enable grid decarbonization - `95by2050` represents a 95 percent reduction in grid emissions from 2005 levels by 2050 and `100by2035` represents 100 percent grid decarbonization by 2035. 'DECARB' options were produced as part of EERE's DECARB initiative; `DECARB-mid` represents 97 percent grid decarbonization by 2050, and `DECARB-high` represents 100 percent grid decarbonization by 2035. Only applicable if `grid_assessment_timing` is also provided.
           grid_assessment_timing:
             type: ["string", "null"]
             enum: [before, after, null]