TUTORIAL Study objective A (uncertainty)

AESA Phase A: estimating the environmental burden.

Compute IO-LCA outputs from processed MRIO tables and run IO-LCA Monte Carlo uncertainty from deterministic IO-LCA outputs.

Before starting…

Set workspace

Run set_workspace(...) before any later function call. It sets the active workspace root for the current Python session, creates or reuses the workspace, imports package prerequisites under data_raw/, and records setup guidance in data_raw/summary.log.

[ ]:

from pyaesa import set_workspace

# Windows example; update this path before running.
set_workspace(r"C:\Users\username\Documents\aesa_workspace")

# macOS example; update this path before running.
# set_workspace("/Users/username/Documents/aesa_workspace")

Run prerequisites

This tutorial assumes that the workspace has already been set, with all prerequisites available (downloads and processing).

If this is not your case, it is recommended to first go through the core prerequisite notebooks: tutorials/core_prerequisites/0_set_workspace.ipynb, tutorials/core_prerequisites/1_download_data.ipynb, and tutorials/core_prerequisites/2_process_data.ipynb.

Functional units and selectors

The example in this tutorial uses the functional unit L2.c.b with the following selectors: one producing sector s_p="Paper" and one consuming region r_c="FR".

Use tutorials/study_objectives/1_functional_units_and_allocation_methods.md to choose the FU and required selectors. This IO-LCA notebook uses only the FU and selector parts of that guide. Use methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf for detailed FU definitions and mathematical expressions.

[ ]:

project_name_ = "SO_A_demo_paper_fr"

source_ = "exiobase_3102_ixi"
fu_code_ = "L2.c.b"
study_period_ = range(2010, 2021)
s_p_ = ["Paper"]
r_c_ = ["FR"]
lcia_method_ = "pb_lcia"

Basic features of the uncertainty function

In a nutshell

The function takes necessary inputs, for two main purposes:

inputs for the deterministic function with the base_io_lca_args block, including project_name, source, years, lcia_method, fu_code, and the relevant selectors (here s_p and r_c) for the selected functional unit.
inputs for the configuration of uncertainty analysis (Monte Carlo) through the uncertainty_config block. The IO-LCA uncertainty source list contains lcia_uncertainty, plus mc_parameters for the Monte Carlo run policy. lcia_uncertainty is inactive by default because sector resolved rows may require a user provided sector_cov_mapping; activate it explicitly for IO-LCA Monte Carlo uncertainty.

The list of uncertainty sources and their mathematical expressions are documented in methodological_notes/methodological_note__acc_uncertainty_sources.pdf.

The uncertainty output folder contains:

Monte Carlo run values and summary statistics.
results/README.txt explains the public row identity tables, run value fragments, run interval indexes, summary tables, source method logs, and compact CSV or Parquet reading contract.
Figures are rendered by default (figures=True). Use figures=False to skip them; figure_format controls the file format and resolution.
log files, including uncertainty source parameter logs.

Basic features also involve:

MRIO aggregation and disaggregation of sectors and/or regions: use the agg_sec, agg_reg, and agg_version parameters. The MRIO aggregation folder includes packaged agg_reg_eu27.csv and agg_reg_world.csv examples; inspect them in data_raw/mrio/<source>/aggregation/ and follow README_aggregation.txt before writing a custom MRIO aggregation and disaggregation mapping CSV.
overwriting of existing values: use the refresh parameter.

Public argument checklist

The table lists all arguments; the same definitions are available in the function docstring.

Green items = default if omitted.

Orange items = optional feature skipped if omitted.

Do not write green or orange items when that behavior is intended.

uncertainty_io_lca(…) arguments

Argument	Description
base_io_lca_args	Deterministic IO-LCA selector envelope. Write nested arguments as base_io_lca_args={“project_name”: “…”, “source”: “…”, “lcia_method”: “…”, “fu_code”: “…”}. Required keys are project_name, source, lcia_method, and fu_code. Nested keys: • project_name: Required project name used to build <repo>/<project_name>. • source: MRIO source key (“exiobase_396_ixi”, “exiobase_396_pxp”, “exiobase_3102_ixi”, “exiobase_3102_pxp”). pyaesa currently only supports EXIOBASE for LCIA characterization. • agg_reg: If True, reclassify MRIO regions with the agg_reg_<agg_version>.csv MRIO aggregation and disaggregation mapping. The mapping can keep native labels, aggregate several native regions into one target label, or disaggregate one native region across several target labels when a weight column is provided. Default False keeps native source regions. • agg_sec: If True, reclassify MRIO sectors with the agg_sec_<agg_version>.csv MRIO aggregation and disaggregation mapping. The mapping can keep native labels, aggregate several native sectors into one target label, or disaggregate one native sector across several target labels when a weight column is provided. Default False keeps native source sectors. • agg_version: Name token used to resolve the matching agg_reg_<agg_version>.csv and/or agg_sec_<agg_version>.csv MRIO aggregation and disaggregation mapping files in data_raw/mrio/<source>/aggregation. Required when agg_reg or agg_sec is True. Defaults to an empty string for native source classification. Use the same token in downstream calls that should reuse the processed classification. If a mapping file has a weight column, weights must sum to 1 for each original label. • years: Studied years. Accepts a single year, list, or range. If omitted, all available MRIO years for the selected source and agg_version are used. • lcia_method: Required LCIA method(s) selected for IO-LCA results (for example “pb_lcia” or [“pb_lcia”, “gwp100_lcia”]). The method(s) must have been processed for the same MRIO source with process_mrio(…). pyaesa currently supports IO-LCA only for EXIOBASE sources. To add a custom LCIA method with which run process_mrio(…), follow README_add_custom_lcia_characterization_matrices.txt in data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/ and pass the custom method file stem here. • fu_code: Required functional unit code (for example “L1.a”, “L2.c.b”). See data_raw/methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf for all available functional unit codes and the system boundaries each represents. • s_p: Producing sector filter(s), single string or list. If this is a required axis for fu_code and the argument is omitted, the run expands to all valid producing sectors. To identify valid sector names, see the first column of the relevant data_raw/mrio/…/aggregation/…/agg_sec_template.csv file. For EXIOBASE sector definitions, see data_raw/mrio/exiobase_3/sector_classification.xlsx; EXIOBASE ixi and pxp use different sector lists. • r_p: Producing region filter(s), single string or list. If this is a required axis for fu_code and the argument is omitted, the run expands to all valid producing regions. To identify valid region names, see the first column of the relevant data_raw/mrio/…/aggregation/agg_reg_template.csv file. • r_c: Consuming region filter(s), single string or list. If this is a required axis for fu_code and the argument is omitted, the run expands to all valid consuming regions. To identify valid region names, see the first column of the relevant data_raw/mrio/…/aggregation/agg_reg_template.csv file. • r_f: Final demand region filter(s), single string or list. If this is a required axis for fu_code and the argument is omitted, the run expands to all valid final demand regions. To identify valid region names, see the first column of the relevant data_raw/mrio/…/aggregation/agg_reg_template.csv file. • group_indices: Whether multiple selected region or sector filter values are kept as separate result rows or summed into one result row after the function calculation has been performed. • False (default): keep selected values as independent rows. • True: sum selected values into one result row. The function refuses to run when group_indices=True is used with L2.a.b, L2.b.b, or L2.c.b because summing output rows for CBA total demand boundaries can double count. For these functional units, change the upstream MRIO aggregation and disaggregation scope with agg_reg, agg_sec, and agg_version before running the study.
uncertainty_config	Monte Carlo configuration dictionary. It must activate lcia_uncertainty, which is the IO-LCA public uncertainty source. LCIA uncertainty is inactive by default because L2 LCIA rows require sector_cov_mapping: keys are output s_p labels and values are sector CoV codes from sec_cbca_covs.csv. Source blocks use an active boolean. See data_raw/methodological_notes/methodological_note__acc_uncertainty_sources.pdf for uncertainty source definitions and mathematical expressions. Accepted keys: • mc_parameters: optional dictionary with convergence and fixed mode blocks. Exactly one mode must be active. Nested mode blocks: • convergence: convergence mode block. This is the default active mode. Nested keys: • active: Whether convergence mode is active. • max_runs: Maximum number of Monte Carlo runs allowed before stopping. • rtol: Relative tolerance used to decide whether monitored summary statistics have converged. • stable_runs: Number of consecutive accepted runs that must remain within tolerance before the run stops. • convergence_statistics: Statistic monitored for convergence. Monte Carlo convergence is mean only and defaults to [“mean”]. • fixed: fixed run count mode block. Nested keys: • active: Whether fixed mode is active. • n_runs: Exact number of Monte Carlo runs. • lcia_uncertainty: optional LCIA source block. It defaults to {“active”: False, “sector_cov_mapping”: {}}. Country level LCIA CoVs are resolved automatically. L2 sector resolved LCIA rows require sector_cov_mapping to map output s_p labels to sector CoV codes from sec_cbca_covs.csv, for example {“active”: True, “sector_cov_mapping”: {“Paper”: “Paper”}}. Carbon consumption based accounts coefficients of variation (CoV) files are available under data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/. Users can inspect sec_cbca_covs.csv for sector CoV codes before choosing sector_cov_mapping values. Nested keys: • active: Whether LCIA uncertainty is active. • sector_cov_mapping: Mapping from output s_p labels to sector CoV codes from sec_cbca_covs.csv.
output_format	Public uncertainty table format, either “csv_compact” or “parquet”. Defaults to “csv_compact”.
figures	Whether to render figures. Default is True.
figure_format	Figure render settings mapping. Defaults to {“format”: “png”, “dpi”: 500}. Nested keys: • format: Figure file format. Accepted values are “png”, “pdf”, and “svg”. • dpi: Positive integer figure resolution used for raster outputs.
refresh	If True, refresh both the resolved deterministic IO-LCA prerequisite and the resolved IO-LCA Monte Carlo outputs for this uncertainty request. The deterministic refresh clears the selected deterministic_io_lca(…) source and version output scope under <project>/A_lca/io_lca. The Monte Carlo refresh removes matching run folders for the current request under the adjacent monte_carlo root. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream ASR outputs are not refreshed. Defaults to False.

Uncertainty IO-LCA in default convergence mode

[ ]:

from pyaesa import uncertainty_io_lca

uncertainty_io_lca(
    base_io_lca_args={
        "project_name": project_name_,
        "source": source_,
        "years": study_period_,
        "lcia_method": lcia_method_,
        "fu_code": fu_code_,
        "s_p": s_p_,
        "r_c": r_c_,
    },
    uncertainty_config={
        # mc_parameters is omitted, so Monte Carlo uses convergence mode defaults.
        # To change convergence tolerance or maximum run count, add for example:
        # "mc_parameters": {"convergence": {"rtol": 0.02, "max_runs": 100000}},
        "lcia_uncertainty": {
            "sector_cov_mapping": {"Paper": "Paper"},
        },
    },
    refresh=True,
)

External LCA results

If you want to use externally provided LCA results instead of pyaesa IO-LCA results computed with EXIOBASE for the ASR numerator, use tutorials/optional_workflows/external_asocc_lca_input_staging.ipynb.

What to do next

Beginners

If you are a new user in the process of discovering pyaesa, it is recommend that you first discover all study objectives with the basic features available. Have a look at the other notebooks available at tutorials/study_objectives/0_study_objectives.md

Experts

If you are already familiar with pyaesa and if you want to discover advanced features available, check out examples in the next section of this tutorial !

Advanced features

Advanced features currently available include:

LCIA uncertainty CoVs for MRIO agg_* and group_indices handling
changing convergence tolerance

LCIA uncertainty CoVs for MRIO `agg_*` and `group_indices` handling

LCIA uncertainty is activated with lcia_uncertainty. Country level CoVs are resolved from the LCIA CoV files. Sector resolved L2 rows require sector_cov_mapping, where each key is the output sector label and each value is the sector CoV code from sec_cbca_covs.csv.

For LCIA uncertainty with aggregated regions, use the packaged agg_reg_eu27.csv or agg_reg_world.csv examples by setting agg_reg=True and agg_version="eu27" or "world". Matching reg_cbca_covs_agg_eu27.csv and reg_cbca_covs_agg_world.csv files are provided in data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/.

For LCIA uncertainty on group_indices outputs, prepare CoV files whose region and sector labels match the combined labels written by the selected public result scope. The code cell below demonstrates EU27 region aggregation with the matching CoV file shipped in the workspace templates.

[ ]:

uncertainty_io_lca(
    base_io_lca_args={
        "project_name": f"{project_name_}_agg_eu27_lcia_uncertainty",
        "source": source_,
        "agg_reg": True,
        "agg_version": "eu27",
        "years": study_period_,
        "lcia_method": lcia_method_,
        "fu_code": "L2.c.a",
        "s_p": ["Paper"],
        "r_c": ["EU27"],
    },
    uncertainty_config={
        "mc_parameters": {
            "fixed": {"active": True, "n_runs": 1000},
            "convergence": {"active": False},
        },
        "lcia_uncertainty": {
            "sector_cov_mapping": {"Paper": "Paper"},
        },
    },
)

Changing convergence tolerance or maximum runs

The default convergence examples above omit mc_parameters. To change convergence controls, add "mc_parameters": {"convergence": {"rtol": 0.02, "max_runs": 100000}} under uncertainty_config. Omit nested values that should keep their defaults.