TUTORIAL: Study objective C (deterministic)

AESA Phase C: absolute sustainability ratio (ASR).

Compute deterministic absolute sustainability ratio (ASR) outputs. ASR = LCA / aCC; the numerator can be IO-LCA or staged external LCA, and the denominator can include staged external 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_C_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 four 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.

• inputs for the LCA numerator route in the lca_args block, such as external_lca and io_lca. The numerator route must match the selected FU boundary.

• 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:

• absolute sustainability ratio tables computed as ASR = LCA / aCC. Required aCC and IO-LCA prerequisites are created or reused when needed; staged external LCA is used when selected.

• 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_asr(…) 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	Shared downstream LCIA method name or list of names. When static carrying capacity (CC) is active, the denominator requires a matching carrying capacity CSV. The package includes static CC files for “pb_lcia”, “gwp100_lcia”, and “ef_3.1”; among these, “ef_3.1” is the default carrying capacity method that currently has no MRIO LCIA characterization matrix. It is dynamic AR6 compatible through its “GWP_100” impact category. Dynamic AR6 CC is available for any selected method whose static carrying capacity CSV contains an impact row equal to “GWP_100”. Custom static CC methods also require a matching file in data_raw/carrying_capacities/; follow README_add_custom_carrying_capacities.txt. When upstream allocated shares of carrying capacities (aSoCC) LCIA based methods or IO-LCA generation is in scope, custom EXIOBASE MRIO LCIA methods must be prepared with data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/README_add_custom_lcia_characterization_matrices.txt and processed with process_mrio(…). base_asocc_args[“include_lcia_based_allocation_methods”] controls whether LCIA based allocation methods are included. When it is False, upstream aSoCC keeps only non LCIA dependent methods, so the requested lcia_method may be non MRIO when the matching carrying capacity and selected LCA numerator prerequisites exist.
base_asocc_args	Optional aSoCC only envelope reused to resolve the deterministic upstream aSoCC prerequisite. 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.
lca_args	Required LCA numerator route envelope. Exactly one route block must have active=True. The default signature selects external_lca. Set external_lca.active=False and io_lca.active=True to use IO-LCA generation. Nested keys: • external_lca: External LCA route block. Nested keys: • active: Whether staged external LCA files under A_lca/external_lca/ are used. • version_name: External LCA version selected from staged files. Use prepare_external_inputs(…) to import the external LCA real input folders, runnable CSV examples, and README_external_lca_templates.txt, then follow that README for version syntax and data input format. • io_lca: IO-LCA generation route block. Nested key: • active: Whether IO-LCA generation is used.
output_format	Persisted output file format: “csv” (default), “pickle”, or “parquet”.
figures	Whether to render figures. Default is True.
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. Deterministic ASR renders deterministic polar figures for eligible single year, multi impact, static carrying capacity per method scopes. It does not expose polar or polar_years in figure_options; select the polar figure year through the main years argument.
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.
subfigures	Whether prerequisite LCA and dynamic AR6 CC figures are rendered when figures=True. Default is True.
refresh	If True, clear and recompute the resolved deterministic ASR output scope for this project, source and aggregation version, numerator route, carrying capacity source, and carrying capacity type, plus the matching deterministic aCC prerequisite scope and, when the numerator route is IO-LCA, the IO-LCA prerequisite scope used by that request. Through the deterministic aCC prerequisite, this can include the matching deterministic aSoCC output scope and, when dynamic AR6 CC is used, the matching processed AR6 output scope selected by process_ar6(…) and the matching deterministic_ar6_cc(…) output scope. External LCA staged inputs, processed MRIO inputs, processed population and GDP, and raw downloads are not refreshed. Defaults to False.

Deterministic ASR with IO-LCA and static pb_lcia aCC

from pyaesa import deterministic_asr

deterministic_asr(
    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",
    lca_args={
        "io_lca": {},
    },
    refresh=True,
)

Deterministic ASR with EF 3.1 static aCC and external LCA numerator

Run this after staging the external LCA files with prepare_external_inputs(...). The packaged external LCA example is ready to run with version_name="template" (numeric values are dummy demonstration values). For file layout and version naming, use tutorials/optional_workflows/external_asocc_lca_input_staging.ipynb; it writes README_external_lca_templates.txt under A_lca/external_lca/templates/.

This example uses the EF 3.1 route: ef_3.1 has no EXIOBASE LCIA characterization matrix in pyaesa, so original pyaesa LCIA based allocation methods are disabled with base_asocc_args["include_lcia_based_allocation_methods"] = False.

from pyaesa import prepare_external_inputs

prepare_external_inputs(project_name=project_name_)

deterministic_asr(
    project_name=project_name_,
    source=source_,
    years=range(2019, 2031),
    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,
        "ssp_scenario": ["SSP2"],
    },
    lca_args={
        "external_lca": {
            "version_name": "template",
        },
    },
    refresh=True,
)

Deterministic ASR with dynamic AR6 aCC denominator

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. The figures parameter is hence set to False given the large number of model-scenarios. With a subset of model-scenarios selected, figure rendering is useful in deterministic mode.

deterministic_asr(
    project_name=f"{project_name_}_prosp",
    source=source_,
    years=study_period_,
    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"],
        },
    },
    lca_args={
        "io_lca": {},
    },
    figures=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:

• Custom external LCA numerator

• Custom external aSoCC

Custom external aSoCC

Use external_method when the aCC denominator should include staged external aSoCC methods. Prepare those files with tutorials/optional_workflows/external_asocc_lca_input_staging.ipynb. That optional workflow writes README_external_asocc_templates.txt under B1_asocc/external_asocc/templates/ with method names, filename syntax, and deterministic or Monte Carlo row preparation rules.

The packaged dummy examples include the one step CO(S) route and the two step AR(E)::UT(S) route. In this EF 3.1 example, CO(S) is non LCIA specific, while AR(E)::UT(S) is supplied directly as an external EF 3.1 LCIA specific method. pyaesa original LCIA based allocation methods remain disabled for the same reason as above.

prepare_external_inputs(project_name=project_name_)

deterministic_asr(
    project_name=project_name_,
    source=source_,
    years=range(2019, 2031),
    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 native LCIA based allocation methods because they require
        # an EXIOBASE LCIA characterization matrix. The external AR(E)::UT(S)
        # rows below are supplied directly by external input files.
        "include_lcia_based_allocation_methods": False,
        "ssp_scenario": ["SSP2"],
    },
    external_method={
        "one_step_methods": ["CO(S)"],
        "l1_l2_pairs": ["AR(E)::UT(S)"],
    },
    lca_args={
        "external_lca": {
            "version_name": "template",
        },
    },
    refresh=True,
)