Optional workflow: custom aSoCC inter-method weights

The template function writes equal_weights.csv, README_inter_method_weights.txt, and the rendered probability tree for one allocated shares of carrying capacities (aSoCC) method scope. The preview function validates an edited custom inter-method tree and renders its preview figure.

Workspace setup

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")

Methodological notes from the repository methodological notes folder are imported with package prerequisites:

data_raw/methodological_notes/ contains notes for definition of functional units and allocation methods, prospective allocation, and uncertainty sources.
data_raw/carrying_capacities/ contains the note for definition of steady state and dynamic carrying capacities.

Functional units and selectors

Use tutorials/study_objectives/1_functional_units_and_allocation_methods.md to choose the FU and required selectors before building the inter-method tree. Use methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf for detailed FU definitions and mathematical expressions.

aSoCC method scope

The custom weight functions use the same aSoCC method scope as deterministic and uncertainty aSoCC. Use tutorials/study_objectives/1_functional_units_and_allocation_methods.md for available allocation methods per FU and for method_plan, l1_methods, one_step_methods, two_step_methods, and l1_l2_pairs syntax. Use methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf for detailed method definitions and mathematical expressions.

method_plan="default" includes all pyaesa allocation methods available for the selected FU. Use the selector arguments only when the inter-method tree should cover a smaller method scope. lcia_method is required when LCIA based allocation methods are included. Custom LCIA methods are prepared through data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/README_add_custom_lcia_characterization_matrices.txt and then processed with process_mrio(...).

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.

write_asocc_weight_template(…) arguments

Argument

Description

base_asocc_args

Deterministic aSoCC selector envelope used to resolve the final method leaves represented by the tree. Write nested arguments as base_asocc_args={“project_name”: “…”, “source”: “…”, “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”, 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” aggregates regions before L1 computation. “post” (default) computes on original regions, then aggregates. • lcia_method: LCIA method(s) to characterize for EXIO processing (for example “pb_lcia” or [“pb_lcia”, “gwp100_lcia”]). None means LCIA characterization is skipped. Defaults to None. LCIA characterization is available only for EXIOBASE sources. To add a custom LCIA method, follow README_add_custom_lcia_characterization_matrices.txt in data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/ and pass the 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” 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.

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.

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.

preview_asocc_weight_tree(…) arguments

Argument	Description
base_asocc_args	Deterministic aSoCC selector envelope used to rebuild the expected final method tree. Write nested arguments as base_asocc_args={“project_name”: “…”, “source”: “…”, “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”, 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” aggregates regions before L1 computation. “post” (default) computes on original regions, then aggregates. • lcia_method: LCIA method(s) to characterize for EXIO processing (for example “pb_lcia” or [“pb_lcia”, “gwp100_lcia”]). None means LCIA characterization is skipped. Defaults to None. LCIA characterization is available only for EXIOBASE sources. To add a custom LCIA method, follow README_add_custom_lcia_characterization_matrices.txt in data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/ and pass the 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” 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.
version_name	Required custom version token. The function reads preview_inter_method_weights/weights__<version_name>.csv. The token must be non empty, contain only letters, digits, and underscores. The reserved token “equal_weight_default” is excluded.
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.
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.

Write the editable equal weight template, using defaults where omitted

[ ]:

from pyaesa import write_asocc_weight_template

write_asocc_weight_template(
    base_asocc_args={
        "project_name": "paper_fr_demo",
        "source": "exiobase_3102_ixi",
        "years": 2024,
        "fu_code": "L2.c.b",
        "s_p": ["Paper"],
        "r_c": ["FR"],
        "lcia_method": "gwp100_lcia",
    },
)

Preview an edited custom weight version, using defaults where omitted

[ ]:

from pyaesa import preview_asocc_weight_tree

preview_asocc_weight_tree(
    base_asocc_args={
        "project_name": "paper_fr_demo",
        "source": "exiobase_3102_ixi",
        "years": 2024,
        "fu_code": "L2.c.b",
        "s_p": ["Paper"],
        "r_c": ["FR"],
        "lcia_method": "gwp100_lcia",
    },
    version_name="study_weights_v1",
)