Optional workflow: disaggregate aSoCC MRIO sectors

Disaggregate non LCIA deterministic allocated shares of carrying capacities (aSoCC). The function starts from a target source available at an aggregated sector resolution and publishes a new disaggregated source. It uses a reference ixi MRIO available at both the same aggregated sector resolution and the requested detailed sector resolution to distribute the target aggregated sector across detailed sectors.

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.

The function writes a published disaggregated aSoCC source from a target source available at an aggregated sector resolution. It uses a reference ixi MRIO available at both the same aggregated sector resolution and the requested detailed sector resolution to distribute each target aggregated sector across the detailed sectors. Figures are rendered by default (figures=True). Use figures=False to skip them.

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.

disaggregate_asocc(…) arguments

Argument	Description
disaggregation_config	Required disaggregation envelope. Required keys are target_agg_run, ref_agg_run, ref_disagg_run, disaggregation_specs, and new_disagg_version_name. Disaggregation configuration fields: • target_agg_run: aggregated deterministic aSoCC source to disaggregate. Its published rows supply target_aggregated in the formula above. Example: OECD ICIO sector D. • ref_agg_run: reference ixi source aggregated to the same sector labels as target_agg_run. Its published rows supply ref_aggregated. Example: EXIOBASE ixi aggregated to OECD ICIO sector D. • ref_disagg_run: the same reference source as ref_agg_run, but at the detailed disaggregated sector labels that should be written in the new source. Its published rows supply ref_disaggregated. Example: EXIOBASE ixi electricity sectors. • disaggregation_specs: mapping from each aggregated sector label to the detailed disaggregated sector label(s) that replace it in the new source. • new_disagg_version_name: output source label used for the published disaggregated aSoCC source created by this function. Each *_run selector requires: • source: supported MRIO source key for this transformation. Accepted values are “oecd_v2025”, “exiobase_3102_ixi”, and “exiobase_396_ixi”. Only ixi MRIO layouts are supported. • s_p: non empty list of sector labels. • 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. disaggregation_specs is a non empty list of {“agg_sector_label”: …, “disagg_sector_label”: …} mappings. target_agg_run.s_p and ref_agg_run.s_p must exactly match the aggregated labels, ref_disagg_run.s_p must exactly match the disaggregated labels, ref_agg_run.source must equal ref_disagg_run.source, and one disaggregated sector can map to exactly one aggregated sector. The studied region labels requested through r_p, r_c, or r_f must be present with the same names in all three selected prerequisite scopes. If source native region names differ, use agg_reg=True and an aggregation version to rename or aggregate regions before disaggregation.
base_asocc_args	Deterministic aSoCC scope used to match prerequisite published outputs and define the written disaggregated output scope. Write nested arguments as base_asocc_args={“project_name”: “…”, “fu_code”: “L2.c.b”}. Source, MRIO aggregation and disaggregation, and sector identity are owned by disaggregation_config. LCIA selectors are not accepted, and the scope must resolve non LCIA deterministic aSoCC outputs. Nested keys: • project_name: Required project name used to build <repo>/<project_name>. • 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. Disaggregation is defined only on L2 published outputs. • 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. • 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. • 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.
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_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 only the published disaggregated aSoCC source created by this call. The cleared scope is the deterministic folder under <project>/B1_asocc/<new_disagg_version_name>. The deterministic prerequisite scopes named in target_agg_run, ref_agg_run, and ref_disagg_run are not refreshed. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream aCC or ASR outputs are not refreshed. Defaults to False.

Only non LCIA aSoCC methods are supported. Do not pass lcia_method in base_asocc_args. Supported sources are oecd_v2025, exiobase_3102_ixi, and exiobase_396_ixi. Region labels are matched strictly between MRIO sources. Use region aggregation to update region names syntax when they do not already match.

Prerequisite process and deterministic aSoCC scopes

The disaggregation call reads existing published aSoCC outputs. Run the three processed MRIO scopes first: target aggregated, reference aggregated, and reference disaggregated. The target and reference aggregated scopes must use the same sector resolution. The reference disaggregated scope must use the detailed sector resolution that will be written in the new published source. Raw MRIO archives must already exist from download_mrio(...).

from pyaesa import process_mrio

# Target aggregated source: OECD ICIO sector D.
# Region aggregation example fr renames the OECD ISO3 label "FRA"
# to the EXIOBASE ISO2 label "FR" so region labels match across sources.
target_aggregated_mrio_report = process_mrio(
    source="oecd_v2025",
    years=2022,
    agg_reg=True,
    agg_version="fr",
)
print(target_aggregated_mrio_report)
print()

# Reference aggregated source: EXIOBASE ixi aggregated to OECD ICIO sector D.
ref_aggregated_mrio_report = process_mrio(
    source="exiobase_3102_ixi",
    years=2022,
    agg_sec=True,
    agg_version="oecd_d",
)
print(ref_aggregated_mrio_report)
print()

# Reference disaggregated source: EXIOBASE ixi at the detailed electricity resolution.
ref_disaggregated_mrio_report = process_mrio(
    source="exiobase_3102_ixi",
    years=2022,
    agg_sec=True,
    agg_version="elec",
)
print(ref_disaggregated_mrio_report)

Then publish the three matching deterministic aSoCC scopes. These calls must use the same year, functional unit, region selector, and sector labels that will be referenced by disaggregation_config.

Use tutorials/study_objectives/1_functional_units_and_allocation_methods.md to choose the compatible FU and selector arguments for the deterministic aSoCC scopes used by this workflow.

from pyaesa import deterministic_asocc

# target_agg_run
# Region aggregation example fr renames the OECD ISO3 label "FRA"
# to the EXIOBASE ISO2 label "FR" so region labels match across sources.
target_aggregated_asocc_report = deterministic_asocc(
    project_name="elec_fr_demo",
    source="oecd_v2025",
    agg_reg=True,
    agg_version="fr",
    years=range(1995, 2031),
    fu_code="L2.c.b",
    s_p=["D"],
    r_c=["FR"],
    figures=False,
)
print(target_aggregated_asocc_report)
print()

# ref_agg_run
ref_aggregated_asocc_report = deterministic_asocc(
    project_name="elec_fr_demo",
    source="exiobase_3102_ixi",
    agg_sec=True,
    agg_version="oecd_d",
    years=range(1995, 2031),
    fu_code="L2.c.b",
    s_p=["D"],
    r_c=["FR"],
    figures=False,
)
print(ref_aggregated_asocc_report)
print()

# ref_disagg_run
ref_disaggregated_asocc_report = deterministic_asocc(
    project_name="elec_fr_demo",
    source="exiobase_3102_ixi",
    agg_sec=True,
    agg_version="elec",
    years=range(1995, 2031),
    fu_code="L2.c.b",
    s_p=["Electricity"],
    r_c=["FR"],
    figures=False,
)
print(ref_disaggregated_asocc_report)

Disaggregate OECD ICIO sector D into EXIOBASE electricity sector

from pyaesa import disaggregate_asocc

disaggregate_asocc(
    disaggregation_config={
        "target_agg_run": {
            "source": "oecd_v2025",
            # Region aggregation example fr renames the OECD ISO3 label "FRA"
            # to the EXIOBASE ISO2 label "FR" so region labels match across sources.
            "agg_reg": True,
            "agg_version": "fr",
            "s_p": ["D"],
        },
        "ref_agg_run": {
            "source": "exiobase_3102_ixi",
            "agg_sec": True,
            "agg_version": "oecd_d",
            "s_p": ["D"],
        },
        "ref_disagg_run": {
            "source": "exiobase_3102_ixi",
            "agg_sec": True,
            "agg_version": "elec",
            "s_p": ["Electricity"],
        },
        "disaggregation_specs": [
            {
                "agg_sector_label": "D",
                "disagg_sector_label": "Electricity",
            }
        ],
        "new_disagg_version_name": "oecd_electricity",
    },
    base_asocc_args={
        "project_name": "elec_fr_demo",
        "years": range(1995, 2031),
        "fu_code": "L2.c.b",
        "r_c": ["FR"],
    },
)