TUTORIAL Study objective A (deterministic)

AESA Phase A: estimating the environmental burden.

Compute deterministic IO-LCA outputs from processed MRIO tables.

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 deterministic function

In a nutshell

The function takes necessary inputs such as project_name, source, years, lcia_method, fu_code and the relevant selectors (here s_p and r_c) for the selected functional unit.

IO-LCA currently requires EXIOBASE processed with an LCIA method. Characterization matrices for EXIOBASE are available for PB-LCIA and GWP100.

The deterministic output folder contains:

IO-LCA result tables.
Figures are rendered by default (figures=True). Use figures=False to skip them; figure_format controls the file format and resolution.
log files

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.

deterministic_io_lca(…) arguments

Argument	Description
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.
upstream_analysis	Whether upstream diagnostic outputs are written. These outputs are for user audit only and are not used by any downstream package function. Default is False. • False: write only main IO-LCA result tables. • True: also write origin tables attributing the footprint to producer sector-region pairs where impacts occur, and when supported by the FU, stage tables showing each upstream supply chain step with direct, embedded, and total impacts.
upstream_stages	Number of upstream supply chain steps written when upstream_analysis=True. Default 3 writes n to n-3.
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.
output_format	Persisted output file format: “csv” (default), “pickle”, or “parquet”.
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, clear and recompute the resolved deterministic IO-LCA source and version output scope under <project>/A_lca/io_lca. It is not limited to one LCIA method inside that output scope. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream ASR outputs are not refreshed. Defaults to False.

Deterministic IO-LCA with defaults where omitted

[ ]:

from pyaesa import deterministic_io_lca

deterministic_io_lca(
    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_,
)

External deterministic 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:

upstream analysis
custom LCIA method
indices aggregation

Upstream analysis

Optional upstream origin and supply chain stage outputs are written only when upstream_analysis=True.

[ ]:

deterministic_io_lca(
    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_,
    upstream_analysis=True,
)

Indices aggregation

group_indices=True reports multiple selected region or sector indices as one summed result row after the selected IO-LCA scope is computed. The default False keeps selected indices as separate rows.

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 those functional units, define aggregated regions or sectors during MRIO processing with agg_reg, agg_sec, and agg_version.

The basic notebook example uses L2.c.b, so this aggregation example switches to L2.c.a.

[ ]:

deterministic_io_lca(
    project_name=f"{project_name_}_group_indices",
    source=source_,
    years=study_period_,
    lcia_method=lcia_method_,
    fu_code="L2.c.a",
    s_p=["Paper"],
    r_c=["FR", "DE"],
    group_indices=True,
)

Custom LCIA method

To add a custom LCIA method, follow data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/README_add_custom_lcia_characterization_matrices.txt and run process_mrio(...) with the custom method file stem.