TUTORIAL: Study objective B2 (deterministic)

AESA Phase B: allocated shares of carrying capacities.

Compute deterministic allocated carrying capacities (aCC). aCC = aSoCC * CC; allocated shares 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_B2_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. lcia_method selects the carrying capacity reference used by aCC. Package prerequisites include pb_lcia, gwp100_lcia, and ef_3.1.
denominator aSoCC choices through the base_asocc_args block. These choices include allocation method and enacting metric settings.
carrying capacity choices through the base_cc_args block. The static block selects static carrying capacities. The dynamic_ar6 block selects dynamic carrying capacity parameters. Dynamic AR6 carrying capacity is available for any selected method whose static carrying capacity CSV contains an impact row equal to GWP_100.

The deterministic output folder contains:

allocated carrying capacity tables computed as aCC = aSoCC * CC. Required aSoCC and dynamic AR6 CC prerequisites are created or reused when needed.
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, the aSoCC denominator uses all allocation methods available for the selected FU. If a study uses a smaller denominator method set, justify that normative choice and pass method_plan, l1_methods, one_step_methods, two_step_methods, and l1_l2_pairs inside base_asocc_args. 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_acc(…) 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.
lcia_method	Carrying capacity reference method(s) selected for aCC (for example “pb_lcia”, “gwp100_lcia”, or “ef_3.1”). Static CC requires a matching reference file in data_raw/carrying_capacities/; to add a custom carrying capacity reference, follow README_add_custom_carrying_capacities.txt in that folder and pass the custom method file stem here. Some references support only steady state CC. Dynamic AR6 CC is available for any selected method whose static carrying capacity CSV contains an impact row equal to “GWP_100”. base_asocc_args[“include_lcia_based_allocation_methods”] controls whether LCIA based allocation methods are included; it defaults to True. When included, the selected lcia_method must also be available as a processed MRIO LCIA method. 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 there.
base_asocc_args	Optional aSoCC only envelope used to resolve the upstream deterministic deterministic_asocc(…) scope. Write nested arguments as base_asocc_args={“method_plan”: “default”}. Omit the envelope or any accepted key to use its default. Nested keys: • 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” aggregates regions before L1 computation. “post” (default) computes on original regions, then aggregates. • 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” projects UT inputs for future years. “historical_reuse” reuses 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. • include_lcia_based_allocation_methods: Whether to include LCIA based allocation methods (e.g.: acquired rights - AR, or historical responsibility - PR-HR). Defaults to True. False keeps only non LCIA dependent allocation methods.
external_method	Optional external aSoCC method selector. Use {“l1_methods”: […]} for L1 functional units. For L2 functional units use {“one_step_methods”: […]} and/or {“l1_l2_pairs”: [“<l1_method>::<l2_method>”, …]}. Omit this argument or pass None when using only native pyaesa deterministic aSoCC methods. Use prepare_external_inputs(…) to import the external aSoCC runnable CSV examples and README_external_asocc_templates.txt, then follow that README for external method names, selector syntax, and deterministic or Monte Carlo external aSoCC CSV preparation.
base_cc_args	Carrying capacity family envelope. The package default is static active and dynamic AR6 inactive. Provide a dynamic_ar6 block to add dynamic AR6 carrying capacities. Set static.active=False for dynamic only runs. Nested keys: • static: Static carrying capacity route. It is active by default unless active=False is provided. Nested keys: • active: Whether the static route is active. Defaults to True. • exclude_max_cc: Whether to use only min_cc. Defaults to False. False keeps the paired min_cc plus max_cc interpretation when max_cc is present. True uses only min_cc. • dynamic_ar6: Dynamic AR6 carrying capacity route. It is inactive when omitted. When the block is provided, it is active unless active=False is provided. It uses top level years and requires at least two consecutive years. Nested keys: • active: Whether the dynamic AR6 route is active. • harmonization: Whether to harmonize retained AR6 pathways to the historical baseline. Defaults to True. • harmonization_method: Harmonization method applied only when harmonization=True. Defaults to “offset”. The only supported value is currently “offset”. Ignored when harmonization=False. • category: AR6 category classification selector for global warming trajectories. Accepts a string such as “C3” or a list such as [“C1”, “C2”]. Valid values are “C1” through “C8”. Defaults to C1 to C4, the categories aligned with the 2015 Paris Agreement. • ssp_scenario: Canonical SSP selector as a string, list, or None, such as “SSP2” or [“SSP1”, “SSP2”]. Defaults to SSP1 to SSP5. • emission_type: Dynamic AR6 emission type. Accepted values are “kyoto_gases” (default) and “co2”. emission_type=”kyoto_gases” uses the GWP100 Kyoto Gases aggregate; emission_type=”co2” uses direct CO2 pathways. • include_afolu: Whether AFOLU emissions are included inside the selected emission_type. Defaults to False. • emissions_mode: Dynamic AR6 emissions mode. Accepted values are “net”, “gross”, and “gross_alt”. Defaults to “gross_alt”. “net” uses net AR6 emissions pathways directly. “gross” removes all sequestration sources from net emissions. “gross_alt” removes all sequestration sources except CCS. CCS is retained because IPCC AR6 treats CCS as capture at fossil or industrial point sources rather than direct removal of CO2 from the atmosphere, so it is kept separate from net negative sequestration. Gross modes write positive emissions rows and signed negative sequestration companion rows; downstream aCC and ASR consume only the positive emissions rows. See data_raw/methodological_notes/methodological_note__steady_state__dynamic_cc.pdf for the methodological explanation. • subset_version: Optional selector for a subset of AR6 model-scenario pairs. Follow data_processed/ar6/<processed_scope>/README_model_scenario_subset.txt to create the subset CSV.
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.
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.
subfigures	Whether prerequisite deterministic aSoCC and dynamic AR6 CC figures are rendered when figures=True. Default: True.

refresh	If True, clear and recompute the resolved deterministic aCC output scope for this project, source and aggregation version, carrying capacity source, and carrying capacity type, plus the matching deterministic aSoCC prerequisite used by that request. When dynamic AR6 CC is used, this also refreshes the matching processed AR6 output scope selected by process_ar6(…) and the matching deterministic_ar6_cc(…) output scope. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream ASR outputs are not refreshed. Defaults to False.

Deterministic aCC with static pb_lcia carrying capacities

[ ]:

from pyaesa import deterministic_acc

deterministic_acc(
    project_name=project_name_,
    source=source_,
    years=study_period_,
    fu_code=fu_code_,
    s_p=s_p_,
    r_c=r_c_,
    lcia_method="pb_lcia",
    refresh=True,
)

Deterministic aCC with EF 3.1 static carrying capacities

[ ]:

deterministic_acc(
    project_name=project_name_,
    source=source_,
    years=study_period_,
    fu_code=fu_code_,
    s_p=s_p_,
    r_c=r_c_,
    lcia_method="ef_3.1",
    base_asocc_args={
        # ef_3.1 has no EXIOBASE LCIA characterization matrix in pyaesa.
        # Hence "include_lcia_based_allocation_methods" is False.
        # This excludes LCIA based allocation methods, such as acquired rights (AR),
        # because they require an EXIOBASE LCIA characterization matrix.
        "include_lcia_based_allocation_methods": False,
    },
    refresh=True,
)

Deterministic aCC with dynamic AR6 CC only

By default, all figures are rendered by the function. In this case, this can lead to a significant number of figures (several hundreds), as one figure will be generated for each model-scenario, SSP, and category in the deterministic mode. The figure_options parameter is used to disable the rendering of figures “per_method”, therefore significantly reducing the total amount of figures to render, if they are not needed by the user.

[ ]:

deterministic_acc(
    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="gwp100_lcia",
    base_asocc_args={
        "ssp_scenario": ["SSP2"],
    },
    base_cc_args={
        "static": {"active": False},
        "dynamic_ar6": {
            "category": ["C1", "C2"],
            "ssp_scenario": ["SSP2"],
        },
    },
    figure_options={"per_method": False},
    refresh=True,
)

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:

AR with EF3.1

AR with EF3.1

When a study needs acquired rights (AR) allocation with EF 3.1, combine the native non LCIA allocation methods with a staged external aSoCC method.

Use external_method for the EF 3.1 AR rows because EF 3.1 global normalization factors (NF) are available only for 2010. For the reference year, build the staged external allocated shares as:

\[\mathrm{aSoCC_{AR}} = \frac{\mathrm{LCA_{results}}}{\mathrm{EF\ 3.1\ global\ NF}}\]

Inputs and staging guidance:

Global NF table: data_raw/carrying_capacities/ef_3.1_cc_steady_state.csv
External aSoCC workflow: tutorials/optional_workflows/external_asocc_lca_input_staging.ipynb
External aSoCC template README: B1_asocc/external_asocc/templates/README_external_asocc_templates.txt