TUTORIAL: Study objective B1 (deterministic)

AESA Phase B: allocated shares of carrying capacities.

Compute deterministic allocated shares of carrying capacities (aSoCC). Workflows can include pyaesa computed aSoCC methods and staged external user provided aSoCC methods.

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. Use methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf for detailed FU definitions and mathematical expressions.

[ ]:

project_name_ = "SO_B1_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, mainly for three purposes:

public scope arguments, 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.
allocation method arguments, such as method_plan, l1_methods, one_step_methods, two_step_methods, l1_l2_pairs, and l1_reg_aggreg.
enacting metric settings, such as reference_years, ssp_scenario, projection_mode, reg_window, and l2_reuse_years.

The deterministic output folder contains:

allocated share tables for the resolved L1 or L2 scope. Enacting metrics used to compute the allocated shares are optionally written with intermediate_outputs.
Figures are rendered by default (figures=True). Use figures=False to skip them; figure_format controls the file format and resolution. figure_options can restrict figure families.
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.
allocation methods: by default, pyaesa runs all allocation methods available for the selected FU. If a study uses a smaller method set, justify that normative choice and use method_plan, l1_methods, one_step_methods, two_step_methods, and l1_l2_pairs. Available methods per FU are listed in tutorials/study_objectives/1_functional_units_and_allocation_methods.md; definitions and mathematical expressions are in methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf.
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_asocc(…) 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”, or “oecd_v2025”), or “iso3” for ISO3 only mode (L1 EG/PR(GDPcap) only).
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.
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.
method_plan	method_plan defaults to “default” and accepts “default”, “one_step”, “two_steps”, “pairs”, or “one_step_pairs”. When omitted, all pyaesa allocation methods available for the selected fu_code are applied. See data_raw/methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf for the allocation methods available per functional unit, including definitions and mathematical expressions.
l1_methods	Optional L1 subset. Omit it to keep all L1 methods allowed by method_plan. In “default”, this filters only L1 weights used by two step methods. In “two_steps”, it filters the two step cartesian L1 side.
one_step_methods	Optional one step L2 subset. Omit it to keep all one step methods allowed by method_plan.
two_step_methods	Optional two step L2 subset. Omit it to keep all two step L2 methods allowed by method_plan.
l1_l2_pairs	Explicit pair list formatted as “L1METHOD::L2METHOD”. Omit it unless method_plan is “pairs” or “one_step_pairs”.
l1_reg_aggreg	L1 aggregation mode for methods where timing matters (PR(GDPcap), PR-HR(Ecap) and AR(Ecap)). • “pre”: aggregate regions before L1 computation. • “post” (default): compute on original regions, then aggregate.
lcia_method	LCIA method(s) selected for LCIA based allocation methods (acquired rights (AR) methods at L1 and L2 and historical responsibility (PR-HR) at L1). Options are for example “pb_lcia” or [“pb_lcia”, “gwp100_lcia”]. None skips LCIA characterization and excludes LCIA based allocation methods. Defaults to None. pyaesa currently supports LCIA based allocation methods 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.
reference_years	Acquired rights (AR) methods reference year selector. Accepts a single year, list, or range. If omitted, AR routes use all historical years in the studied range up to the source registry historical cutoff. For EXIOBASE 3.10.2 and OECD ICIO v2025, the cutoff is 2022; other supported MRIO sources use their own registry cutoff.
ssp_scenario	SSP scenario name or list. Defaults to [“SSP1”, “SSP2”, “SSP3”, “SSP4”, “SSP5”] and is applied when scenario dependent inputs are required.
projection_mode	Projection policy for post historical years of L2 utilitarian (UT) methods (MRIO economic enacting metrics). Defaults to “regression”. • “regression”: project UT inputs for future years. • “historical_reuse”: reuse historical UT structures.
reg_window	Historical regression fit window for regression mode. Provide it as range(start_year, end_year + 1) or as an explicit list of consecutive years in fit window order. When omitted, the source registry supplies the default fit window from the modeled year minimum through the source historical cutoff. For EXIOBASE 3.10.2 and OECD ICIO v2025, this resolves to 1995 to 2022; other supported MRIO sources use their own registry window.
l2_reuse_years	Historical L2 reuse year selector used by all UT historical reuse routes. In projection_mode=”historical_reuse” it applies to all UT methods; in projection_mode=”regression” it applies to adjusted UT routes (UT(FDa), UT(GVAa)), which always use historical reuse as regression is not supported (would require regression on full MRIO). If omitted, defaults to reg_window when required.
output_format	Persisted output file format: “csv” (default), “pickle”, or “parquet”.
intermediate_outputs	Whether to write intermediate output families. These outputs are for user audit and method inspection only; they are not used by downstream package functions. • False (default): skip writing enacting metrics and utility_propagation_contrib (L2*b for FUs) outputs. • True: write all output families.
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.
figure_options	Figure product selector mapping. Defaults to {“per_method”: True, “multi_method”: True}. Nested keys: • per_method: Whether to render method specific figures, with one separate figure for each allocation method. • multi_method: Whether to render cross method comparison figures, with multiple allocation methods shown in the same figure.
figure_external_method	Optional external deterministic aSoCC selector block used only for figure rendering. Use prepare_external_inputs(…) to import the external aSoCC runnable CSV examples and README_external_asocc_templates.txt, then follow that README for method syntax and data input format. This argument is valid only when figures=True. Omit it to render only native deterministic aSoCC method rows. Defaults to None.

refresh	If True, remove and rebuild the resolved deterministic aSoCC source and version output scope for this project, source label, and aggregate version. The cleared scope is the source and version deterministic folder under <project>/B1_asocc/<source_or_source__agg_version>. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream aCC or ASR outputs are not refreshed. Defaults to False.

Deterministic aSoCC with defaults where omitted

[ ]:

from pyaesa import deterministic_asocc

deterministic_asocc(
    project_name=project_name_,
    source=source_,
    years=study_period_,
    fu_code=fu_code_,
    s_p=s_p_,
    r_c=r_c_,
    lcia_method=lcia_method_,
)

Deterministic aSoCC with a given allocation method selected instead of all available methods

[ ]:

deterministic_asocc(
    project_name=project_name_,
    source=source_,
    years=study_period_,
    fu_code=fu_code_,
    s_p=s_p_,
    r_c=r_c_,
    lcia_method=lcia_method_,
    method_plan="pairs",
    l1_l2_pairs=["EG(Pop)::UT(FDa)", "PR(GDPcap)::UT(FDa)", "AR(Ecap^{CBA_FD})::UT(FDa)"],
)

Deterministic aSoCC with a subset of SSP scenarios

Using SSP scenarios for aSoCC means that the user is interested in prospective allocation. The study period is therefore extended to 2030 for the sake of this example.

[ ]:

deterministic_asocc(
    project_name=f"{project_name_}_prosp",
    source=source_,
    years=range(study_period_[0], 2031),
    fu_code=fu_code_,
    s_p=s_p_,
    r_c=r_c_,
    lcia_method=lcia_method_,
    ssp_scenario=["SSP1", "SSP2"],
)

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:

Custom external aSoCC
Custom LCIA method
indices aggregation

Custom external aSoCC

The package ships working external aSoCC examples for tests, the same way it ships working external LCA examples. Import those runnable examples into a project with the optional workflow tutorials/optional_workflows/external_asocc_lca_input_staging.ipynb. That workflow writes the external aSoCC and external LCA example CSVs plus a README explaining external method names, selector syntax, and deterministic or Monte Carlo row preparation.

For deterministic aSoCC, external methods are used for figure comparison with figure_external_method. They are not written to deterministic output tables, because deterministic_asocc(...) does not compute external aSoCC result rows. For uncertainty runs, the same staged external method names are selected with the external_method argument.

[ ]:

deterministic_asocc(
    project_name=f"{project_name_}_external_figures",
    source=source_,
    years=study_period_,
    fu_code=fu_code_,
    s_p=s_p_,
    r_c=r_c_,
    lcia_method=lcia_method_,
    figure_external_method={
        "one_step_methods": ["CO(S)"],
        "l1_l2_pairs": ["AR(E)::UT(S)"],
    },
)

Indices aggregation

group_indices=True reports multiple selected region or sector indices as one summed result row after the selected aSoCC 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_asocc(
    project_name=f"{project_name_}_group_indices",
    source=source_,
    years=study_period_,
    fu_code="L2.c.a",
    s_p=["Paper"],
    r_c=["FR", "DE"],
    lcia_method=lcia_method_,
    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.