NETL-RIC · m-jamieson · Jun 2, 2026 · Dec 12, 2025 · Dec 12, 2025 · Dec 12, 2025
diff --git a/DataYears.md b/DataYears.md
@@ -30,14 +30,16 @@ The following is a summary of input data and years available for use in building
 | Coal mining and transport LCI | | x | | | | | | |
 | Geothermal LCI<sup>1</sup> | | x | | | | | | |
 | Hydro LCI<sup>1</sup> | | x | | | | | | |
-| Natural gas LCI | | x | | | | | | |
+| Natural gas LCI<sup>2</sup> | | x | | | | x | | |
 | Nuclear LCI<sup>1</sup> | | x | | | | | | |
-| Solar PV LCI<sup>2</sup> | | x | | | | x | | |
-| Solar thermal LCI<sup>2</sup> | | x | | | | x | | |
-| Wind farm LCI<sup>2</sup> | | x | | | | x | | |
+| Solar PV LCI<sup>3</sup> | | x | | | | x | | |
+| Solar thermal LCI<sup>3</sup> | | x | | | | x | | |
+| Wind farm LCI<sup>3</sup> | | x | | | | x | | |
 
 Notes:
 
 <sup>1</sup> The inventories for these technologies are based on data from 2016; however, so long as the same plants exist in other years in the EIA 923 data, that inventory can be re-used and applied to different years.
 
-<sup>2</sup> The inventories for these technologies are based on data from 2016 and 2020 (as defined in the RENEWABLE_VINTAGE parameter in globals.py).
+<sup>2</sup> This cradle-to-gate inventory is based on data from 2016 or 2020 (as defined in the `ng_model_year` parameter in the model configuration YAML files).
+
+<sup>3</sup> The cradle-to-gate inventories for these technologies are based on data from 2016 or 2020 (as defined in the `renewable_vintage` parameter in the model configuration YAML files).
diff --git a/README.md b/README.md
diff --git a/electricitylci/__init__.py b/electricitylci/__init__.py
@@ -24,9 +24,12 @@
 end user.
 
 Last updated:
-    2025-06-09
+    2026-03-27
 """
 __version__ = elci_version
+__all__ = [
+    "basic_setup",
+]
 
 
 ##############################################################################
@@ -101,6 +104,14 @@ def aggregate_gen(gen_df, subregion="BA"):
     return aggregate_df
 
 
+def basic_setup(lvl='INFO', elci='ELCI_2023'):
+    """Quickly create a stream logger and define model specs."""
+    from electricitylci.utils import get_logger
+    log = get_logger(True, False, str_lv=lvl)
+    config.model_specs = config.build_model_class(elci)
+    log.info("Setup complete")
+
+
 def combine_upstream_and_gen_df(gen_df, upstream_df):
     """
     Combine the generation and upstream dataframes into a single dataframe.
@@ -588,7 +599,7 @@ def get_facility_level_inventory(to_save=False, sep_by_fac=True):
         upstream_df = None
 
     # NOTE: This method triggers an input request for EPA data API key;
-    #       see https://github.com/USEPA/ElectricityLCI/issues/207
+    #       see https://github.com/NETL-RIC/ElectricityLCI/issues/207
     # NOTE: This method runs aggregation and emission uncertainty
     #       calculations.
     logging.info("get aggregated generation process")
@@ -788,9 +799,17 @@ def run_net_trade(generation_mix_dict):
     return dist_mix_dicts
 
 
-def run_post_processes():
+def run_post_processes(json_path=None):
     """Run post processes on JSON-LD file.
 
+    Parameters
+    ----------
+    json_path : str, optional
+        The file path to a JSON-LD, defaults to none.
+        If none, uses the current model run's JSON-LD file.
+
+    Notes
+    -----
     There is no easy way of editing files archived in a zip and no
     easy way of remove files from a zip without just creating a new zip,
     so that's what's done here.
@@ -799,21 +818,46 @@ def run_post_processes():
         addressed in the new _save_to_json (olca_jsonld_writer.py)
     2.  Remove flows/*.json that are not found in a process exchange.
         See cleanup SQL queries in GitHub issue
-        https://github.com/USEPA/ElectricityLCI/issues/216
+        https://github.com/NETL-RIC/ElectricityLCI/issues/216
     3.  Remove zero flows from quantitative reference exchanges
-        https://github.com/USEPA/ElectricityLCI/issues/217
+        https://github.com/NETL-RIC/ElectricityLCI/issues/217
     4.  DO NOT ADD NETL TRACI 2.1 characterization factors
     5.  Fix labeling of Heat input to elementary flow
-        https://github.com/USEPA/ElectricityLCI/issues/293
-    6.  Create product systems for select processes (user, consumption mixes)
+        https://github.com/NETL-RIC/ElectricityLCI/issues/293
+    6.  Create product systems for select processes (user, consumption mixes);
+        now includes residual mixes (if configured in model specifications)
+
+    If you have JSON-LD without residual mixes that you want to add residual
+    mixes (and product systems) to, follow these steps:
+
+    1.  Edit the config.yml that was used to create the original JSON-LD by
+        enabling the 'add_residual_mix' and, optionally,
+        'add_rem_product_systems', and configure the two settings (i.e.,
+        'rem_weight_method' and 'neg_rem_method').
+    2.  Quick-start ElectricityLCI with your configuration in Python (e.g.,
+        ``basic_setup("ELCI_2023")``).
+    3.  Define your JSON-LD file path
+        (e.g., ``my_json = "~/ELCI_2023_jsonld_20260327_094053-rem.zip"``).
+    4.  Run post-processes on your JSON-LD. The residual processes will be
+        added to the JSON-LD file and will be cleaned;
+        ``run_post_processes(my_json)``.
     """
     from electricitylci.olca_jsonld_writer import build_product_systems
     from electricitylci.olca_jsonld_writer import clean_json
+    from electricitylci.residual_grid_mix import add_residual_mixes
+
+    if json_path is None:
+        json_path = config.model_specs.namestr
+    else:
+        logging.info("Running post-processes on %s" % json_path)
 
-    clean_json(config.model_specs.namestr)
+    # HOTFIX: clean JSON after residual mix processes [260107; TWD]
+    add_residual_mixes(json_path)  # skipped if not configured
+    clean_json(json_path)
     build_product_systems(
-        file_path=config.model_specs.namestr,
-        elci_config=config.model_specs.model_name
+        file_path=json_path,
+        elci_config=config.model_specs.model_name,
+        add_residuals=config.model_specs.add_rem_product_systems
     )
 
 

diff --git a/electricitylci/bulk_eia_data.py b/electricitylci/bulk_eia_data.py
@@ -29,7 +29,7 @@
 consumption mix for a given region.
 
 Last updated:
-    2024-08-21
+    2026-03-25
 """
 __all__ = [
     "ba_exchange_to_df",
@@ -272,7 +272,9 @@ def ba_exchange_to_df(rows, data_type='ba_to_ba'):
                     )
                     continue
         data = [x[1] for x in row['data']]
+        # Trim 'EBA.' from series ID
         from_region = row['series_id'].split('-')[0][4:]
+        # Trim '.ID.D' from series ID
         to_region = row['series_id'].split('-')[1][:-5]
         tuple_data = [
             x for x in zip(

diff --git a/electricitylci/cems_data.py b/electricitylci/cems_data.py
@@ -58,7 +58,7 @@
 CC-BY-4.0
 
 In the current release, the PUDL methods are replaced with EPA's API:
-https://github.com/USEPA/ElectricityLCI/issues/207#issuecomment-1751075194
+https://github.com/NETL-RIC/ElectricityLCI/issues/207#issuecomment-1751075194
 
 Last edited:
     2025-08-13

diff --git a/electricitylci/coal_upstream.py b/electricitylci/coal_upstream.py
@@ -16,7 +16,10 @@
 from ast import literal_eval
 from electricitylci.globals import paths
 from electricitylci.globals import data_dir
+from electricitylci.globals import GH_URL
 from electricitylci.globals import STATE_ABBREV
+from electricitylci.globals import COAL_BASIN_CODES
+from electricitylci.globals import COAL_TYPE_CODES
 from electricitylci.eia860_facilities import eia860_balancing_authority
 from electricitylci.eia923_generation import eia923_download
 from electricitylci.eia923_generation import eia923_generation_and_fuel
@@ -58,13 +61,10 @@
 transportation, but still mainly represents 2016.
 
 Last updated:
-    2025-09-05
+    2026-03-05
 """
 __all__ = [
-    "basin_codes",       # Globals
-    "coal_type_codes",
-    "mine_type_codes",
-    "transport_dict",
+    "transport_dict",    # Globals
     "eia_7a_download",   # Methods
     "fix_coal_mining_lci",
     "generate_upstream_coal",
@@ -82,38 +82,6 @@
 ##############################################################################
 # GLOBALS
 ##############################################################################
-basin_codes = {
-    'Central Appalachia': 'CA',
-    'Central Interior': 'CI',
-    'Gulf Lignite': 'GL',
-    'Illinois Basin': 'IB',
-    'Lignite': 'L',
-    'Northern Appalachia': 'NA',
-    'Powder River Basin': 'PRB',
-    'Rocky Mountain': 'RM',
-    'Southern Appalachia': 'SA',
-    'West/Northwest': 'WNW',
-    'Import': 'IMP',
-}
-'''dict : A map between NETL coal basin names and their abbreviations.'''
-
-coal_type_codes = {
-    'BIT': 'B',
-    'LIG': 'L',
-    'SUB': 'S',
-    'WC': 'W',
-    'RC' : 'RC',
-}
-'''dict : Map between EIA coal fuel source codes and NETL coal codes.'''
-
-mine_type_codes = {
-    'Surface': 'S',
-    'Underground': 'U',
-    'Facility': 'F',
-    'Processing': 'P',
-}
-'''dict : A map between coal mine type and their abbreviation.'''
-
 transport_dict = {
     'Avg Barge Ton*Miles': 'Barge',
     'Avg Lake Vessel Ton*Miles': 'Lake Vessel',
@@ -145,8 +113,8 @@ def _clean_columns(df):
 def _coal_code(row):
     """Generate coal basin + energy source + mine type string-based code."""
     coal_code_str = (
-        f'{basin_codes[row["netl_basin"]]}-'
-        f'{coal_type_codes[row["energy_source"]]}-'
+        f'{COAL_BASIN_CODES[row["netl_basin"]]}-'
+        f'{COAL_TYPE_CODES[row["energy_source"]]}-'
         f'{row["coalmine_type"]}'
     ).upper()
 
@@ -198,7 +166,7 @@ def _make_2023_coal_transport_data(year):
     coal_map_df = coal_map_df.drop(columns=['coal_source_code', 'heat_input'])
 
     # Read the 2023 coal model transportation data
-    # Source: https://github.com/USEPA/ElectricityLCI/discussions/273
+    # Source: https://github.com/NETL-RIC/ElectricityLCI/discussions/273
     coal_dir = os.path.join(data_dir, "coal", "2023")
     coal_file = os.path.join(coal_dir, "coal_transport_dist.csv")
     if not os.path.isfile(coal_file):
@@ -209,7 +177,7 @@ def _make_2023_coal_transport_data(year):
 
     # NOTE: the 2023 coal model uses a slightly different naming scheme
     # for WNW coal basin, so let's fix it.
-    basin_codes_new = {k:v for k, v in basin_codes.items()}
+    basin_codes_new = {k:v for k, v in COAL_BASIN_CODES.items()}
     del basin_codes_new["West/Northwest"]
     basin_codes_new["West/North West"] = "WNW"
 
@@ -433,7 +401,7 @@ def eia_7a_download(year, save_path):
     -----
     Some years are provided in XML format and require re-saving to work with
     the remainder of the code. If you run into troubles with the download,
-    see https://github.com/USEPA/ElectricityLCI/issues/230 for a solution.
+    see https://github.com/NETL-RIC/ElectricityLCI/issues/230 for a solution.
     """
     eia7a_base_url = 'http://www.eia.gov/coal/data/public/xls/'
     name = ('coalpublic{}.xls'.format(year) if year <= 2022 else
@@ -1070,7 +1038,7 @@ def generate_upstream_coal_map(year):
     # Map to NETL coal types --- these should match the coal type found in
     # the coal source code.
     eia_fuel_receipts_good["coal_type"] = eia_fuel_receipts_good[
-        "energy_source"].map(coal_type_codes)
+        "energy_source"].map(COAL_TYPE_CODES)
 
     final_df = eia_fuel_receipts_good.groupby(
         ['plant_id', 'coal_type', 'coal_source_code'],
@@ -1101,7 +1069,7 @@ def generate_upstream_coal_map(year):
         "elec_fuel_consumption_mmbtu"
     ]].copy()
     eia_923_gen_fuel["coal_type"] = eia_923_gen_fuel[
-        "reported_fuel_type_code"].map(coal_type_codes)
+        "reported_fuel_type_code"].map(COAL_TYPE_CODES)
     eia_923_gen_fuel["plant_id"] = eia_923_gen_fuel["plant_id"].astype(int)
     # Effectively filters out NaNs in coal type
     # NOTE: quantity is in short tons
@@ -1675,7 +1643,7 @@ def read_eia7a_public_coal(year):
         file_pattern_match=['coalpublic'],
         return_name=False)
     # If you're here, then see the following for hotfix:
-    # https://github.com/USEPA/ElectricityLCI/issues/230
+    # https://github.com/NETL-RIC/ElectricityLCI/issues/230
     try:
         eia7a_df = pd.read_excel(
             eia7a_path,
@@ -1684,9 +1652,8 @@ def read_eia7a_public_coal(year):
         )
     except ValueError:
         raise ValueError(
-            f'Error reading {eia7a_path}. Please see '
-            'https://github.com/USEPA/ElectricityLCI/issues/230 '
-            'for a solution'
+            f'Error reading {eia7a_path}. '
+            f'Please see {GH_URL}/issues/230 for a solution'
         )
     eia7a_df = _clean_columns(eia7a_df)