API Reference

This page documents the package level public functions, including signatures, parameters, return values, and examples from their public docstrings.

Package Level Functions

set_workspace

pyaesa.set_workspace(top_path: str | Path, *, refresh: bool = False) → None

Set the active workspace repository and ensure prerequisites exist.

The function resolves <top_path>/pyaesa, creates that workspace repository root when missing, imports prerequisite files according to refresh, and records the resolved path as the active workspace repository root. Later public functions read inputs and write outputs relative to this active workspace. Omit arguments to use their default.

Packaged prerequisites are copied under the workspace data_raw/ tree when missing or when refresh=True. They include MRIO aggregation templates, region matching tables for population and GDP processing, the EXIOBASE sector definition guide, EXIOBASE LCIA characterization matrices, LCIA responsibility period tables, carbon consumption based accounts coefficients of variation (CoV) tables, static carrying capacity CSVs and templates, local README guides for editable prerequisite folders, methodological PDF references, the recommended citation guide, and the functional unit and allocation method guide. Methodological assets are copied into data_raw/methodological_notes from installed package resources.

Parameters:

• top_path – Parent directory where the workspace repository root pyaesa/ is created or reused. Accepts a string path or pathlib.Path.

• refresh – If True, overwrite the prerequisite files copied by set_workspace(...) under the resolved workspace data_raw tree and rewrite the setup summary log. The scope is limited to prerequisite files such as default carrying capacities, methodological notes, citation guidance, aggregation templates, matching tables, LCIA templates, and README guides. Raw downloads, processed outputs, and project outputs are not refreshed. Defaults to False.

Returns:

None.

Raises:

OSError – If workspace directory or prerequisite file creation, copying, or refresh fails.

Example

Initialize a workspace:

from pathlib import Path
from pyaesa import set_workspace

# Windows example.
set_workspace(Path(r"C:/Users/username/Documents/aesa_workspace"))
# macOS example.
# set_workspace(Path("/Users/username/Documents/aesa_workspace"))

download_mrio

pyaesa.download_mrio(source: str, years: int | range | Sequence[int] | None = None, *, refresh: bool = False) → DownloadReportMRIO | None

Download missing MRIO archives for source.

The function inspects archives under the source download folder and downloads selected years that are missing. When refresh=True the selected archive scope is downloaded again to replace existing files. Omit arguments to use their default.

Parameters:

• source – MRIO source key ("exiobase_396_ixi", "exiobase_396_pxp", "exiobase_3102_ixi", "exiobase_3102_pxp", or "oecd_v2025").

• years – Optional year selection. Accepted forms are None, one integer year, a range, or a sequence of integer years. Defaults to None, which selects all supported years for source: EXIOBASE 3.9.6 uses 1995 to 2022, EXIOBASE 3.10.2 uses 1995 to 2024, and OECD ICIO v2025 uses 1995 to 2022.

• refresh – If True, download the selected raw MRIO archive scope again to replace previous downloads. For EXIOBASE, the scope is each requested year archive under the selected source and system raw folder. For OECD ICIO, the scope is the OECD bundle containing each requested year, so refreshing one year can replace every yearly CSV extracted from that bundle. Processed MRIO outputs and project outputs are not refreshed. Defaults to False.

Returns:

DownloadReportMRIO capturing requested, downloaded or refreshed, skipped_already_saved, and error states, or None when nothing was downloaded and no errors occurred.

Raises:

• ValueError – If source or years falls outside the supported MRIO selection contract.

• OSError – If raw download directory creation or metadata writing fails.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function. The source download folder is created lazily when missing.

Example

Download EXIOBASE 3.10.2 ixi archives with default years:

from pyaesa import download_mrio

download_mrio("exiobase_3102_ixi")

download_pop_gdp

pyaesa.download_pop_gdp(*, past_years: bool = True, future_years: bool = True, refresh: bool = False) → None

Download population/GDP datasets used by processing.

Omit arguments to use their default.

Parameters:

• past_years – If True, include World Bank and IMF Taiwan historical population/GDP raw files. Default True.

• future_years – If True, include SSP future population/GDP raw files. Default True.

• refresh – If True, clear and rebuild only the selected raw population and GDP tables. past_years=True refreshes the World Bank and IMF Taiwan raw CSV files. future_years=True refreshes the SSP raw CSV file. Processed population and GDP outputs and project outputs are not refreshed. Defaults to False.

Returns:

None.

Raises:

• OSError – If writing a selected raw CSV or metadata file fails.

• RuntimeError – If retrieving or converting a selected upstream data source into the expected raw table fails.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function. With refresh=False, the function does not check whether more recent World Bank, IMF Taiwan, or SSP releases are available upstream. Run download_pop_gdp(refresh=True) when you intentionally want to pick up upstream revisions or newly covered years.

Example

Download historical and future population/GDP inputs:

from pyaesa import download_pop_gdp

download_pop_gdp()

download_ar6

pyaesa.download_ar6(*, refresh: bool = False, manager_url: str = 'https://api.manager.ece.iiasa.ac.at') → DownloadReportAR6 | None

Download the raw datasets required for dynamic AR6 climate change

carrying capacity processing.

The function retrieves the AR6 public scenario explorer table together with the historical PRIMAP and Global Carbon Budget datasets used to construct the historical GHG and CO2 historical baselines in process_ar6(...). AR6 categories included: C1-C8; SSPs included: SSP1-SSP5. Downstream process_ar6(...) defaults to the recommended Paris aligned C1 through C4 scope although additional categories can be included.

Raw source files are written under data_raw/carrying_capacities/dynamic_climate_change_ar6. A single metadata JSON describing the raw output signature and source provenance is written under data_raw/logs. When all required raw outputs already exist on disk and match the stored metadata, the function performs no work and prints nothing. Omit arguments to use their default.

Parameters:

• refresh – If True, clears only the AR6 raw output scope, then downloads it again. Processed AR6 outputs, dynamic carrying capacity outputs, and project outputs are not refreshed. Defaults to False.

• manager_url – IIASA Scenario Explorer manager endpoint.

Returns:

DownloadReportAR6 when the function downloads or refreshes at least one raw source, or when the run fails after an error is captured on the report. Returns None when all required raw outputs already exist on disk and no work is needed.

Raises:

• RuntimeError – If existing raw files are inconsistent with missing or unreadable metadata.

• ValueError – If remote payloads are structurally invalid.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Download AR6 climate change pathways:

from pyaesa import download_ar6

download_ar6()

process_mrio

pyaesa.process_mrio(source: str, years: int | range | Sequence[int] | None = None, *, refresh: bool = False, lcia_method: str | Sequence[str] | None = None, agg_reg: bool = False, agg_sec: bool = False, agg_version: str = '', keep_intermediate_uncasext: bool = False, pymrio_calc_all: bool = False) → ProcessReportMRIO | None

Process MRIO archives into data_processed folder for selected years.

Raw MRIO archives produced by download_mrio(...) must already exist on disk in the active workspace. This function reads those archives and does not download missing MRIO data. Omit arguments to use their default.

Parameters:

• source – MRIO source key ("exiobase_396_ixi", "exiobase_396_pxp", "exiobase_3102_ixi", "exiobase_3102_pxp", or "oecd_v2025").

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

• refresh – If True, clear and recompute only the requested processed MRIO year folders inside the resolved source and classification output scope. The output scope is data_processed/mrio/<source>/<version_tag>, where version_tag is original_classification for native source classification or custom_classification_<agg_version> for custom MRIO aggregation and disaggregation processing. For each requested year, the corresponding processed year folder and metadata year entry are removed before recomputation. Raw downloads and project outputs are not refreshed. Defaults to False.

• lcia_method – LCIA method(s) used to characterize MRIO environmental stressors into the selected method(s) impact categories (for example "pb_lcia" or ["pb_lcia", "gwp100_lcia"]). None skips LCIA characterization. Defaults to None. pyaesa currently supports LCIA characterization 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 custom method file stem here.

• 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. When a mapping file has a weight column, weights must sum to 1 for each original label.

• keep_intermediate_uncasext – If True, keep intermediate UNCASExt matrices needed only for optional diagnostic upstream supply chain decomposition in deterministic_io_lca(..., upstream_analysis=True). Written files are the post clip core matrices (A, G, L, Z, unit), plus characterized LCIA extensions/ payloads. Default False writes only the required processed outputs and avoids saving optional intermediate outputs.

• pymrio_calc_all – If True, write the optional PyMRIO function calc_all diagnostic outputs. These outputs are not used by any downstream pyaesa public function. The written payload is PyMRIO calc_all on original matrices without clipping negative values, stored under preclip/ and preclip/extensions/. Default False skips this diagnostic payload.

Returns:

A ProcessReportMRIO when something was processed or failed, otherwise None when all requested years were already satisfied.

Raises:

ValueError – If source, aggregation, or LCIA arguments are invalid for the requested public processing scope.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function. Run download_mrio(...) for the same source and years before processing when the raw archives are not already present. The workspace prerequisite folders used by MRIO aggregation and disaggregation and EXIOBASE LCIA extension are documented in local README guides under data_raw. Use README_aggregation.txt inside the active MRIO aggregation folder for custom region or sector MRIO aggregation and disaggregation, and use README_add_custom_lcia_characterization_matrices.txt plus README_add_custom_lcia_responsibility_periods.txt inside the EXIOBASE LCIA prerequisite folders when adding custom method specific files beyond the package shipped methods. If custom regional MRIO aggregation and disaggregation outputs will later be used with LCIA uncertainty, follow README_agg_reg_and_group_indices_lcia_covs.txt in data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/.

Example

Process EXIOBASE 3.10.2 ixi outputs with selected LCIA methods:

from pyaesa import process_mrio

process_mrio(
    source="exiobase_3102_ixi",
    lcia_method=["pb_lcia","gwp100_lcia"],
)

process_pop_gdp

pyaesa.process_pop_gdp(*, past_years: bool = True, future_years: bool = True, refresh: bool = False) → None

Process raw population/GDP data into harmonised analysis tables.

Raw population/GDP files produced by download_pop_gdp(...) must already exist on disk in the active workspace. This function reads those files and does not download missing population or GDP data. Omit arguments to use their default.

Parameters:

• past_years – If True, build the historical (World Bank + IMF) processed output. Default True includes the historical branch.

• future_years – If True, build the SSP processed output. Default True includes the prospective branch.

• refresh – If True, clear and recompute only the selected processed population and GDP tables under data_processed/pop_gdp. past_years=True refreshes wb_processed.csv, its metadata, and the World Bank fill log. future_years=True refreshes ssp_processed.csv and its metadata. Raw downloads and project outputs are not refreshed. Defaults to False.

Returns:

None.

Raises:

• RuntimeError – If a required raw population, GDP, or packaged matching CSV is missing from the active workspace.

• OSError – If writing a selected processed output, log, or metadata file fails.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function. Run download_pop_gdp(...) before processing when the raw population, GDP, and SSP files are not already present. The processed outputs contain GDP and population rows for the requested year ranges.

Example

Process historical and SSP population/GDP inputs:

from pyaesa import process_pop_gdp

process_pop_gdp()

process_ar6

pyaesa.process_ar6(years: list[int] | range, figures: bool = True, harmonization: bool = True, harmonization_method: str = 'offset', category: str | list[str] = ['C1', 'C2', 'C3', 'C4'], refresh: bool = False, figure_format: dict[str, object] = {'dpi': 500, 'format': 'png'}, figure_convergence_tol: float = 0.05, figure_convergence_max_runs: int = 20000000, _status: PhasePrinter | NullPhasePrinter | None = None) → ProcessReportAR6

Process AR6 scenarios for use by downstream workflows with optional harmonization of pathways based on an update of historical baselines.

The function transforms the downloaded AR6 scenario table into processed pathway outputs for a user defined study period. Depending on the harmonization argument, it either harmonizes retained scenarios to the historical PRIMAP plus Global Carbon Budget baseline or keeps only the scenarios that pass the package interpolation and derived variable construction rules without harmonization. The retained AR6 domain is the requested category selector within C1 through C8, SSP families SSP1-SSP5, and pathways whose historical and future AR6 vetting fields both equal "Pass". The default category selector is ["C1", "C2", "C3", "C4"], the categories aligned with the 2015 Paris Agreement. Categories C5 through C8 are available as explicit opt in selectors. Processing first keeps model-scenario pairs whose raw CO2 row has the requested study start year and year 2100, then applies the CO2 decomposition reconstruction check, derives net emissions and carbon sequestration rows from the downloaded AR6 decomposition inputs, removes model-scenario pairs with negative carbon sequestration, and harmonizes the retained net emissions variables. It then appends the matching sequestration companion rows, computes gross and gross alternative emissions from the harmonized net pathways, and writes twelve positive emissions variables plus two sequestration variables. Later dynamic AR6 carrying capacity (CC) functions can subset the saved tables by category, SSP family, and model-scenario pair. Omit arguments to use their default.

Parameters:

• years – Study year selector provided as a consecutive year list or range(start_year, end_year + 1). The resolved years must contain at least two consecutive years with no gaps.

• figures – Whether to render figures. Default is True.

• harmonization – Whether to harmonize retained AR6 pathways to the historical baseline. Defaults to True. If True, write harmonized_ar6_public.xlsx plus the separate harmonization log workbook harmonized_ar6_public_log.xlsx. If False, apply the same required CO2 coverage and derived variable construction filters, write filtered_original_ar6_public.xlsx, and omit the harmonization log workbook. When required component inputs are missing for a derived retained variable, the package omits that derived row and records the omission in the AR6 row issue log. The required CO2 coverage, CO2 reconstruction, sequestration, and gross emissions filters are shared with the harmonized mode. Figure generation is available for harmonized runs.

• 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", "C2", "C3", "C4"], the categories aligned with the 2015 Paris Agreement.

• refresh – If True, clear and recompute only the resolved processed AR6 output scope for the requested study period, harmonization flag, harmonization method, and category selector. Raw downloads and downstream AR6 CC, aCC, or ASR outputs are not refreshed. Defaults to False.

• 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_convergence_tol – Relative convergence tolerance used only by the SRS/LHS figure sampling diagnostics when figures=True. The default is 5e-2, i.e. a 5% maximum relative change between successive checkpoint summaries for each monitored summary statistic. Figure sampling is accepted only after 3 consecutive stable checkpoint comparisons. Because the figure workflow evaluates those comparisons every 10000 runs per bucket, the earliest accepted convergence checkpoint is 40000 completed runs per bucket.

• figure_convergence_max_runs – Maximum per bucket run count allowed for the SRS/LHS figure sampling convergence loop when figures=True before figure generation fails. Default: 20000000.

Returns:

ProcessReportAR6 describing the requested processed AR6 scope. The same summary contract is returned for new processing, figure generation, and compatible reuse of existing outputs.

Raises:

• ValueError – If years has fewer than two consecutive years, has gaps, or lies outside AR6 coverage.

• RuntimeError – If required raw AR6 inputs are missing or saved artefacts are structurally inconsistent.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function. download_ar6(...) must have run before this function can read raw AR6 inputs. Methodological details on AR6 scenario filtering, harmonization, and dynamic carrying capacity construction are provided in data_raw/methodological_notes/methodological_note__steady_state__dynamic_cc.pdf.

Example

Process the AR6 study period used by dynamic carrying capacities:

from pyaesa import process_ar6

process_ar6(range(2019, 2061))

deterministic_acc

pyaesa.deterministic_acc(*, project_name: str, source: str, agg_reg: bool = False, agg_sec: bool = False, agg_version: str = '', years: int | list[int] | range, fu_code: str, s_p: str | list[str] | None = None, r_p: str | list[str] | None = None, r_c: str | list[str] | None = None, r_f: str | list[str] | None = None, group_indices: bool = False, lcia_method: str | list[str], base_asocc_args: dict = {'include_lcia_based_allocation_methods': True, 'l1_l2_pairs': None, 'l1_methods': None, 'l1_reg_aggreg': 'post', 'l2_reuse_years': None, 'method_plan': 'default', 'one_step_methods': None, 'projection_mode': 'regression', 'reference_years': None, 'reg_window': None, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'two_step_methods': None}, external_method: dict | None = None, base_cc_args: dict = {'dynamic_ar6': {'active': False, 'category': ['C1', 'C2', 'C3', 'C4'], 'emission_type': 'kyoto_gases', 'emissions_mode': 'gross_alt', 'harmonization': True, 'harmonization_method': 'offset', 'include_afolu': False, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'subset_version': None}, 'static': {'active': True, 'exclude_max_cc': False}}, output_format: str = 'csv', figures: bool = True, figure_format: dict[str, Any] = {'dpi': 500, 'format': 'png'}, figure_options: dict[str, bool] = {'multi_method': True, 'per_method': True}, subfigures: bool = True, refresh: bool = False, _phase: PhasePrinter | None = None, _shared_asocc_lcia_methods: list[str] | None = None) → ComputeACCReport

Compute deterministic allocated carrying capacities (aCC).

The function creates or reuses deterministic allocated shares of carrying capacities (aSoCC) and dynamic AR6 carrying capacity (CC) prerequisites when required, then computes aCC = aSoCC * CC. It writes deterministic aCC tables and renders figures when requested. Omit arguments to use their default.

Parameters:

• 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. When 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.

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

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

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

• 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 branch. It is active by default unless active=False is provided.

    Nested keys:

    • active: Whether the static branch 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 branch. 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 branch 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, as a string or list, such as "C3" or ["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.

• 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 README guidance and runnable CSV examples, then follow the imported README guidance for external method names, selector syntax, and deterministic or Monte Carlo external aSoCC CSV preparation.

• 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 calls should render their own figures 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. For example, for project_name="demo", source="exiobase_3102_ixi", agg_version="elec", and static cc_source="gwp100_lcia", the refreshed scope is <repo>/demo/B2_acc/exiobase_3102_ixi__elec/deterministic/static__gwp100_lcia. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream ASR outputs are not refreshed. Defaults to False.

Returns:

ComputeACCReport describing deterministic aCC table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the shared scope is invalid, a prerequisite contract is not satisfied, a required envelope key is missing, an envelope key or value falls outside the accepted contract, or a scenario dependent aSoCC branch is paired with a different dynamic AR6 SSP set.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Compute static aCC for L2.c.b producing sector Paper and consuming region FR, using defaults where omitted:

deterministic_acc(
    project_name="demo",
    source="exiobase_3102_ixi",
    years=range(2020, 2031),
    lcia_method="gwp100_lcia",
    fu_code="L2.c.b",
    s_p=["Paper"],
    r_c=["FR"],
)

deterministic_asr

pyaesa.deterministic_asr(*, project_name: str, source: str, agg_reg: bool = False, agg_sec: bool = False, agg_version: str = '', years: int | list[int] | range, fu_code: str, s_p: str | list[str] | None = None, r_p: str | list[str] | None = None, r_c: str | list[str] | None = None, r_f: str | list[str] | None = None, group_indices: bool = False, lcia_method: str | list[str], base_asocc_args: dict = {'include_lcia_based_allocation_methods': True, 'l1_l2_pairs': None, 'l1_methods': None, 'l1_reg_aggreg': 'post', 'l2_reuse_years': None, 'method_plan': 'default', 'one_step_methods': None, 'projection_mode': 'regression', 'reference_years': None, 'reg_window': None, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'two_step_methods': None}, external_method: dict | None = None, base_cc_args: dict = {'dynamic_ar6': {'active': False, 'category': ['C1', 'C2', 'C3', 'C4'], 'emission_type': 'kyoto_gases', 'emissions_mode': 'gross_alt', 'harmonization': True, 'harmonization_method': 'offset', 'include_afolu': False, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'subset_version': None}, 'static': {'active': True, 'exclude_max_cc': False}}, lca_args: dict = {'external_lca': {'active': True, 'version_name': None}, 'io_lca': {'active': False}}, output_format: str = 'csv', figures: bool = True, figure_options: dict = {'multi_method': True, 'per_method': True, 'polar': {'active': True, 'polar_years': None}}, figure_format: dict = {'dpi': 500, 'format': 'png'}, subfigures: bool = True, refresh: bool = False) → ComputeASRReport

Compute deterministic absolute sustainability ratio (ASR) outputs.

The function creates or reuses deterministic allocated carrying capacity (aCC) and IO-LCA prerequisites when required, consumes staged external LCA when selected, and computes ASR = LCA / aCC. It writes deterministic ASR tables and renders figures when requested. Omit arguments to use their default.

Parameters:

• 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. When 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.

• 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 still dynamic AR6 compatible for 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.

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

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

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

• 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 branch. It is active by default unless active=False is provided.

    Nested keys:

    • active: Whether the static branch 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 branch. 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 branch 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, as a string or list, such as "C3" or ["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, README guidance, and runnable CSV examples, then follow the imported README guidance for version syntax and data input format.

  • io_lca: IO-LCA generation route block.

    Nested key:

    • active: Whether IO-LCA generation is used.

• 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 README guidance and runnable CSV examples, then follow the imported README guidance for external method names, selector syntax, and deterministic or Monte Carlo external aSoCC CSV preparation.

• output_format – Persisted output file format: "csv" (default), "pickle", or "parquet".

• figures – Whether to render figures. Default is True.

• figure_options –

  Deterministic ASR figure options. Defaults to {"per_method": True, "multi_method": True, "polar": {"active": True, "polar_years": None}}.

  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.

  • polar: Nested deterministic polar figure selector. The block is optional and defaults to {"active": True, "polar_years": None}. Its active key enables deterministic polar figures and defaults to True. Its polar_years key selects studied output years evaluated by deterministic ASR polar figures; when omitted, polar figures use only the first and last studied years in the requested studied year set. Deterministic ASR does not support polar_style because deterministic polar figures use a fixed deterministic style.

• 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 also 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. The refresh removes the scope manifest plus recorded ASR result tables and figures for that scope before recomputation. For example, for project_name="demo", source="exiobase_3102_ixi", agg_version="elec", external LCA version "test_v1", and static cc_source="gwp100_lcia", the refreshed scope is <repo>/demo/C_asr/exiobase_3102_ixi__elec/external_lca__test_v1/deterministic/static__gwp100_lcia. External LCA staged inputs, processed MRIO inputs, processed population and GDP, and raw downloads are not refreshed. Defaults to False.

Returns:

ComputeASRReport describing deterministic ASR table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the shared scope is invalid or a prerequisite contract is not satisfied. This includes missing required envelope keys, envelope keys or values outside the accepted contract, dynamic AR6 branches with a scenario dependent denominator aSoCC branch that uses a different SSP set from the selected dynamic AR6 scope, and external LCA routes whose SSP set is incompatible with the denominator side aSoCC scope.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function. Required deterministic prerequisites are created or reused through deterministic_acc(...) and deterministic_io_lca(...). External LCA routes consume user staged deterministic LCA files. When denominator aSoCC shares are impact independent, ASR keeps the denominator impact category axis when matching numerator LCA rows.

Example

Compute static ASR for L2.c.b producing sector Paper and consuming region FR with IO-LCA inputs:

deterministic_asr(
    project_name="demo",
    source="exiobase_3102_ixi",
    years=range(2020, 2031),
    lcia_method="gwp100_lcia",
    fu_code="L2.c.b",
    s_p=["Paper"],
    r_c=["FR"],
    lca_args={
        "external_lca": {"active": False, "version_name": None},
        "io_lca": {"active": True},
    },
)

deterministic_asocc

pyaesa.deterministic_asocc(*, project_name: str, source: str, agg_reg: bool = False, agg_sec: bool = False, agg_version: str = '', years: int | list[int] | range | None = None, fu_code: str, s_p: str | list[str] | None = None, r_p: str | list[str] | None = None, r_c: str | list[str] | None = None, r_f: str | list[str] | None = None, group_indices: bool = False, method_plan: str = 'default', l1_methods: list[str] | None = None, one_step_methods: list[str] | None = None, two_step_methods: list[str] | None = None, l1_l2_pairs: list[str] | None = None, l1_reg_aggreg: str = 'post', lcia_method: str | list[str] | None = None, reference_years: int | list[int] | range | None = None, ssp_scenario: str | list[str] = ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], projection_mode: str = 'regression', reg_window: list[int] | range | None = None, l2_reuse_years: int | list[int] | range | None = None, output_format: str = 'csv', intermediate_outputs: bool = False, figures: bool = True, figure_format: dict = {'dpi': 500, 'format': 'png'}, figure_options: dict[str, bool] = {'multi_method': True, 'per_method': True}, figure_external_method: dict[str, list[str]] | None = None, refresh: bool = False, _phase: PhasePrinter | NullPhasePrinter | None = None) → AllocateReport

Compute deterministic allocated shares of carrying capacities (aSoCC).

This function consumes processed MRIO matrices and processed population/GDP inputs, computes L1 or L2 allocated shares, and writes deterministic outputs under <project_name>. It renders figures when requested. Omit arguments to use their default.

Parameters:

• 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. When 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 README guidance and runnable CSV examples, then follow the imported guide 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>. For example, for project_name="demo", source="exiobase_3102_ixi", and agg_version="elec", the refreshed path is <repo>/demo/B1_asocc/exiobase_3102_ixi__elec/deterministic. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream aCC or ASR outputs are not refreshed. Defaults to False.

Returns:

AllocateReport describing deterministic aSoCC table outputs and figure outputs when figures are requested.

Raises:

ValueError – If FU code is invalid, selectors are incompatible with method_plan, required indices are missing, disallowed indices are provided, LCIA inputs are required but missing, aggregated output is requested in disallowed cases, or required MRIO/population/GDP years are unavailable.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Compute deterministic aSoCC for L2.c.b producing sector Paper and consuming region FR, using defaults where omitted:

deterministic_asocc(
    project_name="demo",
    source="exiobase_3102_ixi",
    years=2022,
    fu_code="L2.c.b",
    s_p=["Paper"],
    r_c=["FR"],
)

deterministic_ar6_cc

pyaesa.deterministic_ar6_cc(*, years: list[int] | range, harmonization: bool = True, harmonization_method: str = 'offset', category: str | list[str] = ['C1', 'C2', 'C3', 'C4'], ssp_scenario: str | list[str] = ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], emission_type: str = 'kyoto_gases', include_afolu: bool = False, emissions_mode: str = 'gross_alt', subset_version: str | None = None, output_format: str = 'csv', figures: bool = True, figure_format: dict[str, object] = {'dpi': 500, 'format': 'png'}, refresh: bool = False, _status: PhasePrinter | NullPhasePrinter | None = None) → ComputeAR6CCReport

Extract AR6 climate change pathways from process_ar6(...) outputs.

The function reads processed AR6 pathways and extracts the selected emission variable and years. Matching processed AR6 outputs are created or reused through process_ar6(...). It writes deterministic dynamic AR6 carrying capacity (CC) tables and renders figures when requested. Omit arguments to use their default.

Parameters:

• years – Study year selector provided as a consecutive year list or range(start_year, end_year + 1). The resolved years must contain at least two consecutive years with no gaps.

• 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 filter 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", "C2", "C3", "C4"], the categories aligned with the 2015 Paris Agreement.

• ssp_scenario – SSP scenario filter. Defaults to ["SSP1", "SSP2", "SSP3", "SSP4", "SSP5"]. Pass a string such as "SSP2" or a list such as ["SSP1", "SSP2"] to restrict.

• 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. Omit this argument to use every retained model-scenario pair. Defaults to None.

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

• refresh – If True, clear and recompute the resolved deterministic AR6 CC output scope for the requested study period, harmonization flag, harmonization method, emission variables, and subset version, plus the matching processed AR6 output scope selected by process_ar6(...) for that request. The cleared AR6 CC scope is the selector-specific ar6_cc deterministic output folder beside that processed AR6 scope. For example, for years 2019 to 2060, default harmonization, default Kyoto gas settings, category ["C1"], and SSP ["SSP1"], the refreshed path is <repo>/data_processed/ar6/2019-2060_harmonization_offset/ar6_cc/gross_alt_kyoto_gases_wo_afolu/C1__SSP1/deterministic. Raw downloads and downstream aCC or ASR outputs are not refreshed. Defaults to False.

Returns:

ComputeAR6CCReport describing deterministic AR6 CC table outputs and figure outputs when figures are requested. The study year table is written as results/ar6_cc.<format>. When the study period ends before 2100, the run also writes results/ar6_cc_post_study_period.<format> for figure rendering.

Raises:

• ValueError – If arguments are invalid or no pathways match the requested filters.

• RuntimeError – If processed AR6 prerequisite outputs are unavailable after calling process_ar6(...).

• FileNotFoundError – If the requested subset CSV is unavailable.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function. download_ar6(...) must have run before this function can read raw AR6 inputs. Methodological details on AR6 scenario filtering, harmonization, and dynamic carrying capacity construction are provided in data_raw/methodological_notes/methodological_note__steady_state__dynamic_cc.pdf.

Example

Extract dynamic AR6 carrying capacity pathways for one study period and a subset of model-scenario pairs:

from pyaesa import deterministic_ar6_cc

deterministic_ar6_cc(
    years=range(2019, 2061),
    category=["C1", "C2"],
    ssp_scenario=["SSP2"],
    subset_version="study_subset",
)

disaggregate_asocc

pyaesa.disaggregate_asocc(*, disaggregation_config: dict = {'disaggregation_specs': None, 'new_disagg_version_name': None, 'ref_agg_run': None, 'ref_disagg_run': None, 'target_agg_run': None}, base_asocc_args: dict = {'fu_code': None, 'group_indices': False, 'l1_l2_pairs': None, 'l1_methods': None, 'l1_reg_aggreg': 'post', 'l2_reuse_years': None, 'method_plan': 'default', 'one_step_methods': None, 'project_name': None, 'projection_mode': 'regression', 'r_c': None, 'r_f': None, 'r_p': None, 'reg_window': None, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'two_step_methods': None, 'years': None}, output_format: str = 'csv', figures: bool = True, figure_format: dict = {'dpi': 500, 'format': 'png'}, figure_external_method: dict[str, list[str]] | None = None, refresh: bool = False) → DisaggregationReport

Disaggregate non LCIA deterministic allocated shares of carrying capacities (aSoCC).

The function creates a published disaggregated aSoCC source when a target source is available at an aggregated sector resolution. It uses a reference ixi MRIO available at both that same aggregated sector resolution and the requested detailed sector resolution to distribute each target aggregated sector across the detailed sectors. For every requested year y the allocated shares are equal to target_aggregated(y) * ref_disaggregated(y) / ref_aggregated(y).

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" because OECD ICIO is an ixi MRIO. It renders figures when requested. Omit arguments to use their default.

Parameters:

• 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. When a mapping file has a weight column, weights must sum to 1 for each original label.

  • 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 README guidance and runnable CSV examples, then follow the imported guide 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>. For example, for project_name="demo" and new_disagg_version_name="oecd_electricity", the refreshed path is <repo>/demo/B1_asocc/oecd_electricity/deterministic. 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.

Returns:

DisaggregationReport describing disaggregated aSoCC table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the configuration is invalid, one prerequisite deterministic scope is unavailable, requested published output coverage is missing, or one strict disaggregation failure rule is triggered.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

• Region labels are matched strictly between the MRIO sources. Studied regions requested through r_p/r_c/r_f must use the same labels in all selected sources. Use region aggregation to update region names syntax when they do not already match.

• Disaggregation may run for any requested year whose prerequisite published outputs exist for all three selectors.

Example

Disaggregate OECD ICIO sector D into EXIOBASE electricity sector, using defaults where omitted:

disaggregate_asocc(
    disaggregation_config={
        "target_agg_run": {
            "source": "oecd_v2025",
            "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": "disagg_oecd_elec",
    },
    base_asocc_args={
        "project_name": "demo",
        "fu_code": "L2.c.b",
        "years": range(2005, 2031),
        "r_c": ["FR", "US"],
        "ssp_scenario": ["SSP2", "SSP3"],
    },
)

deterministic_io_lca

pyaesa.deterministic_io_lca(*, project_name: str, source: str, agg_reg: bool = False, agg_sec: bool = False, agg_version: str = '', years: int | list[int] | range | None = None, lcia_method: str | list[str], fu_code: str, s_p: str | list[str] | None = None, r_p: str | list[str] | None = None, r_c: str | list[str] | None = None, r_f: str | list[str] | None = None, upstream_analysis: bool = False, upstream_stages: int = 3, group_indices: bool = False, output_format: str = 'csv', figures: bool = True, figure_format: dict = {'dpi': 500, 'format': 'png'}, refresh: bool = False, _status: StatusSink | None = None) → IOLCAReport

Compute deterministic IO-LCA outputs from processed MRIO tables.

This function reads processed MRIO outputs produced by process_mrio(...) and writes deterministic IO-LCA result tables under the selected <project_name>. Optional upstream supply chain decomposition outputs are written only when upstream_analysis=True. It renders figures when requested. Omit arguments to use their default.

Parameters:

• 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"). pyaesa currently only supports EXIOBASE for LCIA characterization.

• 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. When 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.

• lcia_method – Required LCIA method(s) selected for IO-LCA results (for example "pb_lcia" or ["pb_lcia", "gwp100_lcia"]). The method(s) must have been processed for the same MRIO source with process_mrio(...). pyaesa currently supports IO-LCA 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.

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

• upstream_analysis –

  Whether upstream diagnostic outputs are written. These outputs are for user audit only and are not used by any downstream package function. Default is False.

  • False: write only main IO-LCA result tables.

  • True: also write origin tables attributing the footprint to producer sector-region pairs where impacts occur, and when supported by the FU, stage tables showing each upstream supply chain step with direct, embedded, and total impacts.

• upstream_stages – Number of upstream supply chain steps written when upstream_analysis=True. Default 3 writes n to n-3.

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

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

• refresh – If True, clear and recompute the resolved deterministic IO-LCA source and version output scope under <project>/A_lca/io_lca. For example, for project_name="demo", source="exiobase_3102_ixi", and agg_version="elec", the refreshed path is <repo>/demo/A_lca/io_lca/exiobase_3102_ixi__elec/deterministic. It is not limited to one LCIA method inside that output scope. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream ASR outputs are not refreshed. Defaults to False.

Returns:

IOLCAReport describing deterministic IO-LCA table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the source, aggregation scope, years, FU code, selectors, LCIA methods, aggregation mode, output format, or upstream settings are invalid; if aggregated prerequisites are missing; if processed MRIO assets required by the request are unavailable; or if upstream analysis is requested outside the FU routes with upstream outputs.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Compute deterministic IO-LCA for L2.c.b producing sector Paper and consuming region FR:

from pyaesa import deterministic_io_lca

deterministic_io_lca(
    project_name="demo",
    source="exiobase_3102_ixi",
    years=2019,
    lcia_method="gwp100_lcia",
    fu_code="L2.c.b",
    s_p=["Paper"],
    r_c=["FR"],
)

prepare_external_inputs

pyaesa.prepare_external_inputs(*, project_name: str) → ExternalInputPreparationReport

Import external allocated shares of carrying capacities (aSoCC) and LCA inputs.

The function writes README guidance and runnable CSV examples under project_name so expected file formats and real input folders can be inspected directly. External allocated shares of carrying capacities (aSoCC) inputs let aSoCC, allocated carrying capacity (aCC), and absolute sustainability ratio (ASR) workflows mix user provided allocated shares with package computed shares. External LCA inputs can be used as the ASR numerator instead of IO-LCA. The imported guidance and examples cover deterministic and Monte Carlo external inputs, retrospective years, and prospective SSP scenario files. Existing user staged files are preserved. Omit arguments to use their default.

Parameters:

project_name – Required project name used to build <repo>/<project_name>. External input folders are shared by the downstream aSoCC, aCC, and ASR calls that use the same project name.

Returns:

ExternalInputPreparationReport with the resolved project root and external aSoCC and external LCA scaffold locations.

Raises:

ValueError – If project_name is not a non-empty string.

Example

Prepare external input guidance and runnable examples for one project:

from pyaesa import prepare_external_inputs

prepare_external_inputs(project_name="demo")

write_asocc_weight_template

pyaesa.write_asocc_weight_template(*, base_asocc_args: dict[str, Any] = {'agg_reg': False, 'agg_sec': False, 'agg_version': '', 'fu_code': None, 'group_indices': False, 'l1_l2_pairs': None, 'l1_methods': None, 'l1_reg_aggreg': 'post', 'l2_reuse_years': None, 'lcia_method': None, 'method_plan': 'default', 'one_step_methods': None, 'project_name': None, 'projection_mode': 'regression', 'r_c': None, 'r_f': None, 'r_p': None, 'reference_years': None, 'reg_window': None, 's_p': None, 'source': None, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'two_step_methods': None, 'years': None}, external_method: dict[str, Any] | None = None, figure_format: dict[str, Any] = {'dpi': 500, 'format': 'png'}) → InterMethodTreeArtifacts

Write equal weight inter-method templates for one method scope.

The templates define custom weights for allocated shares of carrying capacities (aSoCC) inter-method uncertainty. Omit arguments to use their default.

Parameters:

• 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. When 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 README guidance and runnable CSV examples, then follow the imported README guidance 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.

Returns:

Paths and probabilities for the written editable tree CSV, guide text, and preview figure.

Raises:

ValueError – If the requested deterministic aSoCC method scope or figure settings are invalid.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Write the editable tree for L2.c.b producing sector Paper and consuming region FR:

from pyaesa import write_asocc_weight_template

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

preview_asocc_weight_tree

pyaesa.preview_asocc_weight_tree(*, base_asocc_args: dict[str, Any] = {'agg_reg': False, 'agg_sec': False, 'agg_version': '', 'fu_code': None, 'group_indices': False, 'l1_l2_pairs': None, 'l1_methods': None, 'l1_reg_aggreg': 'post', 'l2_reuse_years': None, 'lcia_method': None, 'method_plan': 'default', 'one_step_methods': None, 'project_name': None, 'projection_mode': 'regression', 'r_c': None, 'r_f': None, 'r_p': None, 'reference_years': None, 'reg_window': None, 's_p': None, 'source': None, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'two_step_methods': None, 'years': None}, version_name: str, external_method: dict[str, Any] | None = None, figure_format: dict[str, Any] = {'dpi': 500, 'format': 'png'}) → InterMethodTreeArtifacts

Validate an edited custom inter-method tree and render its preview.

The preview is built for one allocated shares of carrying capacities (aSoCC) method scope. Omit arguments to use their default.

Parameters:

• 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. When 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 README guidance and runnable CSV examples, then follow the imported README guidance 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.

Returns:

Paths and probabilities for the validated custom tree CSV, guide text, and rendered preview figure.

Raises:

ValueError – If the custom tree file no longer matches the requested method scope or if sibling edge weights fail probability validation.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Validate an edited tree for L2.c.b producing sector Paper and consuming region FR:

from pyaesa import preview_asocc_weight_tree

preview_asocc_weight_tree(
    base_asocc_args={
        "project_name": "demo",
        "source": "exiobase_3102_ixi",
        "fu_code": "L2.c.b",
        "s_p": ["Paper"],
        "r_c": ["FR"],
    },
    version_name="custom_v1",
)

uncertainty_asocc

pyaesa.uncertainty_asocc(*, base_asocc_args: dict[str, Any] = {'agg_reg': False, 'agg_sec': False, 'agg_version': '', 'fu_code': None, 'group_indices': False, 'l1_l2_pairs': None, 'l1_methods': None, 'l1_reg_aggreg': 'post', 'l2_reuse_years': None, 'lcia_method': None, 'method_plan': 'default', 'one_step_methods': None, 'project_name': None, 'projection_mode': 'regression', 'r_c': None, 'r_f': None, 'r_p': None, 'reference_years': None, 'reg_window': None, 's_p': None, 'source': None, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'two_step_methods': None, 'years': None}, uncertainty_config: dict[str, Any] = {'inter_method_uncertainty': {'active': True, 'mode': 'equal_weight'}, 'inter_mrio_uncertainty': {'active': False, 'alternate_source': None}, 'lcia_uncertainty': {'active': False, 'sector_cov_mapping': {}}, 'mc_parameters': {'convergence': {'active': True, 'convergence_statistics': ['mean'], 'max_runs': 500000, 'rtol': 0.05, 'stable_runs': 10000}, 'fixed': {'active': False, 'n_runs': 1000}}, 'projection_uncertainty': {'active': True}, 'reference_year_uncertainty': {'active': True}}, sobol_parameters: dict = {'active': False, 'convergence': {'active': True, 'max_base_samples': 1048576, 'rtol': 0.05}, 'fixed': {'active': False, 'n_base_samples': 128}, 'sobol_years': None}, external_method: dict | None = None, output_format: str = 'csv_compact', figures: bool = True, figure_format: dict = {'dpi': 500, 'format': 'png'}, figure_options: dict[str, bool] = {'inter_method': True, 'multi_method': True, 'per_method': True}, refresh: bool = False) → UncertaintyRunReport

Run allocated shares of carrying capacities (aSoCC) Monte Carlo uncertainty.

The function loads the deterministic aSoCC row universe identified by base_asocc_args and samples only the uncertainty sources requested in uncertainty_config. Deterministic prerequisite outputs are created or reused through deterministic_asocc(...) before uncertainty row loading. It writes run values, summary statistics, uncertainty source parameters, Sobol variance decomposition when enabled, and figures when requested under the aSoCC Monte Carlo output folder. Omit arguments to use their default.

Parameters:

• base_asocc_args –

  Deterministic aSoCC selector envelope. 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. When 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) 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" 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.

• uncertainty_config –

  Monte Carlo configuration dictionary. The default signature activates projection, reference year, and inter-method uncertainty. LCIA uncertainty is inactive by default because L2 LCIA rows require sector_cov_mapping: keys are output s_p labels and values are sector CoV codes from sec_cbca_covs.csv. Inter-MRIO uncertainty is inactive by default because it requires an alternate published disaggregated aSoCC source. Source blocks use an active boolean; write active=False to disable a default active source. See data_raw/methodological_notes/methodological_note__acc_uncertainty_sources.pdf for uncertainty source definitions and mathematical expressions.

  Accepted keys:

  • mc_parameters: optional dictionary with convergence and fixed mode blocks. Exactly one mode must be active.

    Nested mode blocks:

    • convergence: convergence mode block. This is the default active mode.

      Nested keys:

      • active: Whether convergence mode is active.

      • max_runs: Maximum number of Monte Carlo runs allowed before stopping.

      • rtol: Relative tolerance used to decide whether monitored summary statistics have converged.

      • stable_runs: Number of consecutive accepted runs that must remain within tolerance before the run stops.

      • convergence_statistics: Statistic monitored for convergence. Monte Carlo convergence is mean only and defaults to ["mean"].

    • fixed: fixed run count mode block.

      Nested keys:

      • active: Whether fixed mode is active.

      • n_runs: Exact number of Monte Carlo runs.

  • lcia_uncertainty: optional LCIA source block. It defaults to {"active": False, "sector_cov_mapping": {}}. Country level LCIA CoVs are resolved automatically. L2 sector resolved LCIA rows require sector_cov_mapping to map output s_p labels to sector CoV codes from sec_cbca_covs.csv, for example {"active": True, "sector_cov_mapping": {"Paper": "Paper"}}. Carbon consumption based accounts coefficients of variation (CoV) files are available under data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/. Users can inspect sec_cbca_covs.csv for sector CoV codes before choosing sector_cov_mapping values. CoV keys must match the LCIA uncertainty output domain. If agg_reg=True, region keys use reg_cbca_covs_agg_<agg_version>.csv; otherwise they use reg_cbca_covs.csv. If group_indices=True sums a region selector axis after calculation, put the full combined output region label in reg_cbca_covs_agg_<agg_version>_group_indices.csv when agg_reg=True, otherwise reg_cbca_covs_group_indices.csv. If agg_sec=True or group_indices=True, use the corresponding agg_sec output labels or combined output s_p labels as sector_cov_mapping keys. For example, with group_indices=True and s_p=["A", "B"], write sector_cov_mapping={"A, B": "Electricity"} when Electricity is the sector CoV code selected from sec_cbca_covs.csv.

    Nested keys:

    • active: Whether LCIA uncertainty is active.

    • sector_cov_mapping: Mapping from output s_p labels to sector CoV codes from sec_cbca_covs.csv.

  • projection_uncertainty: optional source block. It defaults to {"active": True}. For prospective rows using L2 historical reuse, each Monte Carlo run samples one L2 reuse year uniformly from the deterministic l2_reuse_years candidates requested for the years where reuse applies.

    Nested key:

    • active: Whether projection uncertainty is active.

  • reference_year_uncertainty: optional source block. It defaults to {"active": True}. For acquired rights (AR) routes, each Monte Carlo run samples uniformly among requested reference years admissible for the studied year (reference_year <= year). The same sampled reference year is shared across the run when admissible; years for which it is not admissible resample among their admissible reference years.

    Nested key:

    • active: Whether reference year uncertainty is active.

  • inter_mrio_uncertainty: optional source block. To activate it, write {"active": True, "alternate_source": "<disaggregated label>"}, for example {"active": True, "alternate_source": "oecd_electricity"}. It applies continuous uniform interpolation between the main MRIO source and an alternate published disaggregated aSoCC source created by disaggregate_asocc(...). It applies only to non LCIA methods.

    Nested keys:

    • active: Whether inter-MRIO uncertainty is active.

    • alternate_source: Published disaggregated aSoCC source label used as the alternate MRIO source.

  • inter_method_uncertainty: optional source block. It defaults to {"active": True, "mode": "equal_weight"}. Each Monte Carlo run samples one method leaf among the selected deterministic and external methods. Equal weight mode writes the tree CSV, README, and rendered probability tree under the run folder figures/inter_method_tree/. To prepare custom weights before running uncertainty, use write_asocc_weight_template(...); it writes equal_weights.csv, README_inter_method_weights.txt, and probability_tree__equal_weights.<ext> under B1_asocc/preview_inter_method_weights/. Use preview_asocc_weight_tree(...) to validate and render a custom probability tree before using {"mode": "custom", "version_name": "..."}.

    Nested keys:

    • active: Whether inter-method uncertainty is active.

    • mode: Inter-method sampling mode. Accepted values are "equal_weight" and "custom".

    • version_name: Custom weight version used when mode="custom".

• sobol_parameters –

  Sobol sensitivity settings. Sobol analysis estimates the contribution of active uncertainty sources to output variance and writes README_sobol.txt under results/sobol/ for interpretation. The default has active=False and writes no Sobol artifacts. To run Sobol, set active=True. With the default mode blocks, enabled Sobol uses convergence mode. To run a fixed Sobol design, set fixed.active=True and convergence.active=False. Sobol base sizes must be powers of two.

  Nested keys:

  • active: Whether Sobol sensitivity analysis is active.

  • convergence: convergence mode block. When Sobol is active, exactly one of convergence or fixed is active.

    Nested keys:

    • active: Whether convergence mode is active.

    • max_base_samples: Maximum Sobol base size.

    • rtol: Relative tolerance for monitored S1 and ST indices.

  • fixed: fixed Sobol base size mode block.

    Nested keys:

    • active: Whether fixed mode is active.

    • n_base_samples: Exact Sobol base size.

  • sobol_years: Studied output years evaluated by Sobol. When omitted, Sobol evaluates only the first and last studied years in the requested studied year set.

• 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 README guidance and runnable CSV examples, then follow the imported README guidance for external method names, selector syntax, and deterministic or Monte Carlo external aSoCC CSV preparation.

• output_format – Public uncertainty table format, either "csv_compact" or "parquet". Defaults to "csv_compact".

• 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, "inter_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.

  • inter_method: Whether to render inter-method uncertainty figures. These figures use the same method specific layout as per_method, but represent uncertainty induced by the inter method uncertainty setting rather than comparing individual allocation methods. This option is ignored when inter-method uncertainty is inactive.

• refresh – If True, refresh both the resolved deterministic aSoCC prerequisite and the resolved aSoCC Monte Carlo outputs for this uncertainty request. The deterministic refresh removes the source and version deterministic output scope described for deterministic_asocc(...). The Monte Carlo refresh removes matching run folders for the current request under the adjacent monte_carlo root. For example, for project_name="demo", source="exiobase_3102_ixi", and agg_version="elec", the refreshed deterministic path is <repo>/demo/B1_asocc/exiobase_3102_ixi__elec/deterministic and matching Monte Carlo run folders are under <repo>/demo/B1_asocc/exiobase_3102_ixi__elec/monte_carlo/mc_<generated_id>. External aSoCC inputs, processed MRIO inputs, processed population and GDP, raw downloads, and downstream aCC or ASR outputs are not refreshed. Defaults to False.

Returns:

UncertaintyRunReport describing aSoCC uncertainty table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the request, source configuration, or persisted input files are inconsistent.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Run L2.c.b for producing sector Paper and consuming region FR with LCIA uncertainty added, using defaults where omitted:

from pyaesa import uncertainty_asocc

uncertainty_asocc(
    base_asocc_args={
        "project_name": "demo",
        "source": "exiobase_3102_ixi",
        "years": range(2020, 2031),
        "fu_code": "L2.c.b",
        "s_p": ["Paper"],
        "r_c": ["FR"],
        "lcia_method": "gwp100_lcia",
    },
    uncertainty_config={
        "lcia_uncertainty": {
            "active": True,
            "sector_cov_mapping": {"Paper": "Paper"},
        },
    },
)

uncertainty_io_lca

pyaesa.uncertainty_io_lca(*, base_io_lca_args: dict[str, Any] = {'agg_reg': False, 'agg_sec': False, 'agg_version': '', 'fu_code': None, 'group_indices': False, 'lcia_method': None, 'project_name': None, 'r_c': None, 'r_f': None, 'r_p': None, 's_p': None, 'source': None, 'years': None}, uncertainty_config: dict[str, Any] = {'lcia_uncertainty': {'active': False, 'sector_cov_mapping': {}}, 'mc_parameters': {'convergence': {'active': True, 'convergence_statistics': ['mean'], 'max_runs': 500000, 'rtol': 0.05, 'stable_runs': 10000}, 'fixed': {'active': False, 'n_runs': 1000}}}, output_format: str = 'csv_compact', figures: bool = True, figure_format: dict[str, Any] = {'dpi': 500, 'format': 'png'}, refresh: bool = False) → UncertaintyRunReport

Run IO-LCA Monte Carlo uncertainty from deterministic IO-LCA outputs.

The function loads deterministic IO-LCA outputs and samples only the uncertainty sources requested in uncertainty_config (pyaesa currently only supports LCIA uncertainty). Deterministic prerequisite outputs are created or reused through deterministic_io_lca(...). It writes run values, summary statistics, uncertainty source parameters, and figures when requested under the IO-LCA Monte Carlo output folder. Omit arguments to use their default.

Parameters:

• base_io_lca_args –

  Deterministic IO-LCA selector envelope. Write nested arguments as base_io_lca_args={"project_name": "...", "source": "...", "lcia_method": "...", "fu_code": "..."}. Required keys are project_name, source, lcia_method, and 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"). pyaesa currently only supports EXIOBASE for LCIA characterization.

  • 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. When 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.

  • lcia_method: Required LCIA method(s) selected for IO-LCA results (for example "pb_lcia" or ["pb_lcia", "gwp100_lcia"]). The method(s) must have been processed for the same MRIO source with process_mrio(...). pyaesa currently supports IO-LCA 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.

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

• uncertainty_config –

  Monte Carlo configuration dictionary. It must activate lcia_uncertainty, which is the IO-LCA public uncertainty source. LCIA uncertainty is inactive by default because L2 LCIA rows require sector_cov_mapping: keys are output s_p labels and values are sector CoV codes from sec_cbca_covs.csv. Source blocks use an active boolean. See data_raw/methodological_notes/methodological_note__acc_uncertainty_sources.pdf for uncertainty source definitions and mathematical expressions.

  Accepted keys:

  • mc_parameters: optional dictionary with convergence and fixed mode blocks. Exactly one mode must be active.

    Nested mode blocks:

    • convergence: convergence mode block. This is the default active mode.

      Nested keys:

      • active: Whether convergence mode is active.

      • max_runs: Maximum number of Monte Carlo runs allowed before stopping.

      • rtol: Relative tolerance used to decide whether monitored summary statistics have converged.

      • stable_runs: Number of consecutive accepted runs that must remain within tolerance before the run stops.

      • convergence_statistics: Statistic monitored for convergence. Monte Carlo convergence is mean only and defaults to ["mean"].

    • fixed: fixed run count mode block.

      Nested keys:

      • active: Whether fixed mode is active.

      • n_runs: Exact number of Monte Carlo runs.

  • lcia_uncertainty: optional LCIA source block. It defaults to {"active": False, "sector_cov_mapping": {}}. Country level LCIA CoVs are resolved automatically. L2 sector resolved LCIA rows require sector_cov_mapping to map output s_p labels to sector CoV codes from sec_cbca_covs.csv, for example {"active": True, "sector_cov_mapping": {"Paper": "Paper"}}. Carbon consumption based accounts coefficients of variation (CoV) files are available under data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/. Users can inspect sec_cbca_covs.csv for sector CoV codes before choosing sector_cov_mapping values. CoV keys must match the LCIA uncertainty output domain. If agg_reg=True, region keys use reg_cbca_covs_agg_<agg_version>.csv; otherwise they use reg_cbca_covs.csv. If group_indices=True sums a region selector axis after calculation, put the full combined output region label in reg_cbca_covs_agg_<agg_version>_group_indices.csv when agg_reg=True, otherwise reg_cbca_covs_group_indices.csv. If agg_sec=True or group_indices=True, use the corresponding agg_sec output labels or combined output s_p labels as sector_cov_mapping keys. For example, with group_indices=True and s_p=["A", "B"], write sector_cov_mapping={"A, B": "Electricity"} when Electricity is the sector CoV code selected from sec_cbca_covs.csv.

    Nested keys:

    • active: Whether LCIA uncertainty is active.

    • sector_cov_mapping: Mapping from output s_p labels to sector CoV codes from sec_cbca_covs.csv.

• output_format – Public uncertainty table format, either "csv_compact" or "parquet". Defaults to "csv_compact".

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

• refresh – If True, refresh both the resolved deterministic IO-LCA prerequisite and the resolved IO-LCA Monte Carlo outputs for this uncertainty request. The deterministic refresh clears the selected deterministic_io_lca(...) source and version output scope under <project>/A_lca/io_lca. The Monte Carlo refresh removes matching run folders for the current request under the adjacent monte_carlo root. For example, matching IO-LCA Monte Carlo run folders are refreshed under <repo>/demo/A_lca/io_lca/exiobase_3102_ixi__elec/monte_carlo/mc_<generated_id>. Processed MRIO inputs, processed population and GDP, raw downloads, and downstream ASR outputs are not refreshed. Defaults to False.

Returns:

UncertaintyRunReport describing IO-LCA uncertainty table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the request, source configuration, or persisted input files are inconsistent.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Run IO-LCA for L2.c.b producing sector Paper and consuming region FR with LCIA uncertainty added, using defaults where omitted:

from pyaesa import uncertainty_io_lca

uncertainty_io_lca(
    base_io_lca_args={
        "project_name": "demo",
        "source": "exiobase_3102_ixi",
        "years": 2019,
        "lcia_method": "gwp100_lcia",
        "fu_code": "L2.c.b",
        "s_p": ["Paper"],
        "r_c": ["FR"],
    },
    uncertainty_config={
        "lcia_uncertainty": {
            "active": True,
            "sector_cov_mapping": {"Paper": "Paper"},
        },
    },
)

uncertainty_ar6_cc

pyaesa.uncertainty_ar6_cc(*, base_ar6_cc_args: dict[str, Any] = {'category': ['C1', 'C2', 'C3', 'C4'], 'emission_type': 'kyoto_gases', 'emissions_mode': 'gross_alt', 'harmonization': True, 'harmonization_method': 'offset', 'include_afolu': False, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'subset_version': None, 'years': None}, uncertainty_config: dict[str, Any] = {'dynamic_ar6_cc_uncertainty': {'active': True, 'category_uncertainty': False, 'sampling_method': 'srs'}, 'mc_parameters': {'convergence': {'active': True, 'convergence_statistics': ['mean'], 'max_runs': 500000, 'rtol': 0.05, 'stable_runs': 10000}, 'fixed': {'active': False, 'n_runs': 1000}}}, output_format: str = 'csv_compact', figures: bool = True, figure_format: dict[str, Any] = {'dpi': 500, 'format': 'png'}, refresh: bool = False) → UncertaintyRunReport

Run dynamic AR6 carrying capacity (CC) Monte Carlo uncertainty.

The function loads the deterministic AR6 CC row universe identified by base_ar6_cc_args and samples only the uncertainty sources requested in uncertainty_config. Deterministic prerequisite outputs are created or reused through deterministic_ar6_cc(...). It writes run values, summary statistics, uncertainty source parameters, and figures when requested under the AR6 CC Monte Carlo output folder. Omit arguments to use their default.

Parameters:

• base_ar6_cc_args –

  Deterministic AR6 CC selector envelope written as a dictionary. Required key: years. Accepted optional keys are harmonization, harmonization_method, category, ssp_scenario, emission_type, include_afolu, emissions_mode, and subset_version.

  Nested keys:

  • years: Study year selector provided as a consecutive year list or range(start_year, end_year + 1). The resolved years must contain at least two consecutive years with no gaps.

  • 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 for global warming trajectories, as a string or list, such as "C3" or ["C1", "C2"]. Valid values are "C1" through "C8". Defaults to ["C1", "C2", "C3", "C4"], the categories aligned with the 2015 Paris Agreement.

  • ssp_scenario: SSP label selector as a string, list, or None. Defaults to ["SSP1", "SSP2", "SSP3", "SSP4", "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. Defaults to None.

• uncertainty_config –

  Monte Carlo configuration dictionary. The default signature activates dynamic AR6 CC uncertainty. Category uncertainty is inactive by default. Source blocks use an active boolean; write active=False to disable dynamic AR6 CC uncertainty. See data_raw/methodological_notes/methodological_note__acc_uncertainty_sources.pdf for uncertainty source definitions and mathematical expressions.

  Accepted keys:

  • mc_parameters: optional dictionary with convergence and fixed mode blocks. Exactly one mode must be active.

    Nested mode blocks:

    • convergence: convergence mode block. This is the default active mode.

      Nested keys:

      • active: Whether convergence mode is active.

      • max_runs: Maximum number of Monte Carlo runs allowed before stopping.

      • rtol: Relative tolerance used to decide whether monitored summary statistics have converged.

      • stable_runs: Number of consecutive accepted runs that must remain within tolerance before the run stops.

      • convergence_statistics: Statistic monitored for convergence. Monte Carlo convergence is mean only and defaults to ["mean"].

    • fixed: fixed run count mode block.

      Nested keys:

      • active: Whether fixed mode is active.

      • n_runs: Exact number of Monte Carlo runs.

  • dynamic_ar6_cc_uncertainty: optional AR6 CC source block. It defaults to {"active": True, "sampling_method": "srs", "category_uncertainty": False}. sampling_method accepts "srs" for simple random sampling (samples across retained model-scenario pairs matching the requested category and SSP) or "lhs" for Latin hypercube sampling (samples among retained models first, then among retained scenarios for the selected model, category, and SSP to limit over representation of models with more AR6 submissions). The effect of this choice is visible in process_ar6(...) sampling diagnostic figures. category_uncertainty is inactive by default. If True, each Monte Carlo run first samples one retained AR6 category with equal probability in the studied SSP pool. It then applies sampling_method inside that selected category; with sampling_method="lhs", this means model first, then scenario inside that model.

    Nested keys:

    • active: Whether dynamic AR6 carrying capacity uncertainty is active.

    • sampling_method: AR6 pathway sampling method. Accepted values are "srs" and "lhs".

    • category_uncertainty: Whether each Monte Carlo run samples one retained AR6 category before applying sampling_method inside that category.

• output_format – Public uncertainty table format, either "csv_compact" or "parquet". Defaults to "csv_compact".

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

• refresh – If True, refresh the matching processed AR6 output scope selected by process_ar6(...), the resolved deterministic AR6 CC output scope, and the resolved AR6 CC Monte Carlo outputs for this uncertainty request. The Monte Carlo refresh removes matching run folders for the current request under the adjacent monte_carlo root of that deterministic output scope. For example, matching AR6 CC Monte Carlo run folders are refreshed under <repo>/data_processed/ar6/2019-2060_harmonization_offset/ar6_cc/gross_alt_kyoto_gases_wo_afolu/C1__SSP1/monte_carlo/mc_<generated_id>. Raw downloads and downstream aCC or ASR outputs are not refreshed. Defaults to False.

Returns:

UncertaintyRunReport describing AR6 CC uncertainty table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the request, source configuration, or persisted input files are inconsistent.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function. download_ar6(...) must have run before this function can read raw AR6 inputs through its deterministic AR6 CC prerequisite. Methodological details on AR6 scenario filtering, harmonization, and dynamic carrying capacity construction are provided in data_raw/methodological_notes/methodological_note__steady_state__dynamic_cc.pdf.

Example

Run dynamic AR6 CC with category uncertainty added, using defaults where omitted:

from pyaesa import uncertainty_ar6_cc

uncertainty_ar6_cc(
    base_ar6_cc_args={"years": range(2019, 2061)},
    uncertainty_config={
        "dynamic_ar6_cc_uncertainty": {
            "active": True,
            "category_uncertainty": True,
        },
    },
)

uncertainty_acc

pyaesa.uncertainty_acc(*, project_name: str, source: str, agg_reg: bool = False, agg_sec: bool = False, agg_version: str = '', years: int | list[int] | range, fu_code: str, s_p: str | list[str] | None = None, r_p: str | list[str] | None = None, r_c: str | list[str] | None = None, r_f: str | list[str] | None = None, group_indices: bool = False, lcia_method: str | list[str], base_asocc_args: dict[str, Any] = {'include_lcia_based_allocation_methods': True, 'l1_l2_pairs': None, 'l1_methods': None, 'l1_reg_aggreg': 'post', 'l2_reuse_years': None, 'method_plan': 'default', 'one_step_methods': None, 'projection_mode': 'regression', 'reference_years': None, 'reg_window': None, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'two_step_methods': None}, external_method: dict[str, Any] | None = None, base_cc_args: dict[str, Any] = {'dynamic_ar6': {'active': False, 'category': ['C1', 'C2', 'C3', 'C4'], 'emission_type': 'kyoto_gases', 'emissions_mode': 'gross_alt', 'harmonization': True, 'harmonization_method': 'offset', 'include_afolu': False, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'subset_version': None}, 'static': {'active': True, 'exclude_max_cc': False}}, uncertainty_config: dict[str, Any] = {'dynamic_ar6_cc_uncertainty': {'active': True, 'category_uncertainty': False, 'sampling_method': 'srs'}, 'inter_method_uncertainty': {'active': True, 'mode': 'equal_weight'}, 'inter_mrio_uncertainty': {'active': False, 'alternate_source': None}, 'lcia_uncertainty': {'active': False, 'sector_cov_mapping': {}}, 'mc_parameters': {'convergence': {'active': True, 'convergence_statistics': ['mean'], 'max_runs': 500000, 'rtol': 0.05, 'stable_runs': 10000}, 'fixed': {'active': False, 'n_runs': 1000}}, 'projection_uncertainty': {'active': True}, 'reference_year_uncertainty': {'active': True}}, sobol_parameters: dict[str, Any] = {'active': False, 'convergence': {'active': True, 'max_base_samples': 1048576, 'rtol': 0.05}, 'fixed': {'active': False, 'n_base_samples': 128}, 'sobol_years': None}, output_format: str = 'csv_compact', figures: bool = True, figure_format: dict[str, Any] = {'dpi': 500, 'format': 'png'}, figure_options: dict[str, bool] = {'inter_method': True, 'multi_method': True, 'per_method': True}, subfigures: bool = True, refresh: bool = False) → UncertaintyRunReport

Run allocated carrying capacity (aCC) Monte Carlo uncertainty.

The function creates or reuses upstream allocated shares of carrying capacities (aSoCC) and dynamic AR6 carrying capacity (CC) uncertainty outputs, samples only the uncertainty sources requested in uncertainty_config, and computes aCC = aSoCC * CC. It writes run values, summary statistics, uncertainty source parameters, Sobol variance decomposition when enabled, and figures when requested under the aCC Monte Carlo output folder. Omit arguments to use their default.

Parameters:

• 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. When 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.

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

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

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

• 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 branch. It is active by default unless active=False is provided.

    Nested keys:

    • active: Whether the static branch 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 branch. 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 branch 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, as a string or list, such as "C3" or ["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.

• uncertainty_config –

  Monte Carlo configuration dictionary. The default signature activates projection, reference year, inter-method, and dynamic AR6 CC uncertainty for dynamic carrying capacity branches. LCIA uncertainty is inactive by default because L2 LCIA rows require sector_cov_mapping: keys are output s_p labels and values are sector CoV codes from sec_cbca_covs.csv. Inter MRIO uncertainty is inactive by default because it requires an alternate published disaggregated aSoCC source. Source blocks use an active boolean; write active=False to disable a default active source. See data_raw/methodological_notes/methodological_note__acc_uncertainty_sources.pdf for uncertainty source definitions and mathematical expressions.

  Accepted keys:

  • mc_parameters: optional dictionary with convergence and fixed mode blocks. Exactly one mode must be active.

    Nested mode blocks:

    • convergence: convergence mode block. This is the default active mode.

      Nested keys:

      • active: Whether convergence mode is active.

      • max_runs: Maximum number of Monte Carlo runs allowed before stopping.

      • rtol: Relative tolerance used to decide whether monitored summary statistics have converged.

      • stable_runs: Number of consecutive accepted runs that must remain within tolerance before the run stops.

      • convergence_statistics: Statistic monitored for convergence. Monte Carlo convergence is mean only and defaults to ["mean"].

    • fixed: fixed run count mode block.

      Nested keys:

      • active: Whether fixed mode is active.

      • n_runs: Exact number of Monte Carlo runs.

  • lcia_uncertainty: optional LCIA source block. It defaults to {"active": False, "sector_cov_mapping": {}}. Country level LCIA CoVs are resolved automatically. L2 sector resolved LCIA rows require sector_cov_mapping to map output s_p labels to sector CoV codes from sec_cbca_covs.csv, for example {"active": True, "sector_cov_mapping": {"Paper": "Paper"}}. Carbon consumption based accounts coefficients of variation (CoV) files are available under data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/. Users can inspect sec_cbca_covs.csv for sector CoV codes before choosing sector_cov_mapping values. CoV keys must match the LCIA uncertainty output domain. If agg_reg=True, region keys use reg_cbca_covs_agg_<agg_version>.csv; otherwise they use reg_cbca_covs.csv. If group_indices=True sums a region selector axis after calculation, put the full combined output region label in reg_cbca_covs_agg_<agg_version>_group_indices.csv when agg_reg=True, otherwise reg_cbca_covs_group_indices.csv. If agg_sec=True or group_indices=True, use the corresponding agg_sec output labels or combined output s_p labels as sector_cov_mapping keys. For example, with group_indices=True and s_p=["A", "B"], write sector_cov_mapping={"A, B": "Electricity"} when Electricity is the sector CoV code selected from sec_cbca_covs.csv.

    Nested keys:

    • active: Whether LCIA uncertainty is active.

    • sector_cov_mapping: Mapping from output s_p labels to sector CoV codes from sec_cbca_covs.csv.

  • projection_uncertainty: optional source block. It defaults to {"active": True}. For prospective rows using L2 historical reuse, each Monte Carlo run samples one L2 reuse year uniformly from the deterministic l2_reuse_years candidates requested for the years where reuse applies.

    Nested key:

    • active: Whether projection uncertainty is active.

  • reference_year_uncertainty: optional source block. It defaults to {"active": True}. For acquired rights (AR) routes, each Monte Carlo run samples uniformly among requested reference years admissible for the studied year (reference_year <= year). The same sampled reference year is shared across the run when admissible; years for which it is not admissible resample among their admissible reference years.

    Nested key:

    • active: Whether reference year uncertainty is active.

  • inter_mrio_uncertainty: optional source block. To activate it, write {"active": True, "alternate_source": "<disaggregated label>"}, for example {"active": True, "alternate_source": "oecd_electricity"}. It applies continuous uniform interpolation between the main MRIO source and an alternate published disaggregated aSoCC source created by disaggregate_asocc(...). It applies only to non LCIA methods.

    Nested keys:

    • active: Whether inter-MRIO uncertainty is active.

    • alternate_source: Published disaggregated aSoCC source label used as the alternate MRIO source.

  • inter_method_uncertainty: optional source block. It defaults to {"active": True, "mode": "equal_weight"}. Each Monte Carlo run samples one method leaf among the selected deterministic and external methods. Equal weight mode writes the tree CSV, README, and rendered probability tree under the run folder figures/inter_method_tree/. To prepare custom weights before running uncertainty, use write_asocc_weight_template(...); it writes equal_weights.csv, README_inter_method_weights.txt, and probability_tree__equal_weights.<ext> under B1_asocc/preview_inter_method_weights/. Use preview_asocc_weight_tree(...) to validate and render a custom probability tree before using {"mode": "custom", "version_name": "..."}.

    Nested keys:

    • active: Whether inter-method uncertainty is active.

    • mode: Inter-method sampling mode. Accepted values are "equal_weight" and "custom".

    • version_name: Custom weight version used when mode="custom".

  • dynamic_ar6_cc_uncertainty: optional AR6 CC source block. It defaults to {"active": True, "sampling_method": "srs", "category_uncertainty": False}. sampling_method accepts "srs" for simple random sampling (samples across retained model-scenario pairs matching the requested category and SSP) or "lhs" for Latin hypercube sampling (samples among retained models first, then among retained scenarios for the selected model, category, and SSP to limit over representation of models with more AR6 submissions). The effect of this choice is visible in process_ar6(...) sampling diagnostic figures. category_uncertainty is inactive by default. If True, each Monte Carlo run first samples one retained AR6 category with equal probability in the studied SSP pool. It then applies sampling_method inside that selected category; with sampling_method="lhs", this means model first, then scenario inside that model.

    Nested keys:

    • active: Whether dynamic AR6 carrying capacity uncertainty is active.

    • sampling_method: AR6 pathway sampling method. Accepted values are "srs" and "lhs".

    • category_uncertainty: Whether each Monte Carlo run samples one retained AR6 category before applying sampling_method inside that category.

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

• base_asocc_args –

  Optional upstream aSoCC selector envelope. Write nested arguments as base_asocc_args={"method_plan": "default"}. Accepted keys are method and projection controls only. 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 README guidance and runnable CSV examples, then follow the imported README guidance for external method names, selector syntax, and deterministic or Monte Carlo external aSoCC CSV preparation.

• output_format – Public uncertainty table format, either "csv_compact" or "parquet". Defaults to "csv_compact".

• sobol_parameters –

  Sobol sensitivity settings. Sobol analysis estimates the contribution of active uncertainty sources to output variance and writes README_sobol.txt under results/sobol/ for interpretation. The default has active=False and writes no Sobol artifacts. To run Sobol, set active=True. With the default mode blocks, enabled Sobol uses convergence mode. To run a fixed Sobol design, set fixed.active=True and convergence.active=False. Sobol base sizes must be powers of two.

  Nested keys:

  • active: Whether Sobol sensitivity analysis is active.

  • convergence: convergence mode block. When Sobol is active, exactly one of convergence or fixed is active.

    Nested keys:

    • active: Whether convergence mode is active.

    • max_base_samples: Maximum Sobol base size.

    • rtol: Relative tolerance for monitored S1 and ST indices.

  • fixed: fixed Sobol base size mode block.

    Nested keys:

    • active: Whether fixed mode is active.

    • n_base_samples: Exact Sobol base size.

  • sobol_years: Studied output years evaluated by Sobol for static carrying capacity branches. When omitted, static Sobol evaluates only the first and last studied years in the requested studied year set. Dynamic AR6 carrying capacity Sobol ignores this yearly selector and evaluates cumulative aCC over the full studied period.

• 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, "inter_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.

  • inter_method: Whether to render inter-method uncertainty figures. These figures use the same method specific layout as per_method, but represent uncertainty induced by the inter method uncertainty setting rather than comparing individual allocation methods. This option is ignored when inter-method uncertainty is inactive.

• subfigures – Whether prerequisite uncertainty aSoCC and active uncertainty AR6 CC calls should render their own figures when figures=True. Default: True.

• refresh – If True, refresh the resolved aCC Monte Carlo outputs and every upstream component output scope called by this aCC uncertainty request. This can refresh deterministic and Monte Carlo aSoCC output scopes, 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. When dynamic AR6 CC uncertainty is active, this can also refresh the matching uncertainty_ar6_cc(...) output scope. For example, matching aCC Monte Carlo run folders are refreshed under <repo>/demo/B2_acc/exiobase_3102_ixi__elec/monte_carlo/mc_<generated_id>. External aSoCC inputs, static carrying capacity files, processed MRIO inputs, processed population and GDP, raw downloads, and downstream ASR outputs are not refreshed. Defaults to False.

Returns:

UncertaintyRunReport describing aCC uncertainty table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the request, source configuration, or persisted input files are inconsistent.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Run static and dynamic aCC for L2.c.b producing sector Paper and consuming region FR with LCIA uncertainty added, using defaults where omitted:

from pyaesa import uncertainty_acc

uncertainty_acc(
    project_name="demo",
    source="exiobase_3102_ixi",
    years=range(2020, 2031),
    lcia_method="gwp100_lcia",
    fu_code="L2.c.b",
    s_p=["Paper"],
    r_c=["FR"],
    base_cc_args={
        "static": {"active": True},
        "dynamic_ar6": {"active": True},
    },
    uncertainty_config={
        "lcia_uncertainty": {
            "active": True,
            "sector_cov_mapping": {"Paper": "Paper"},
        },
    },
)

uncertainty_asr

pyaesa.uncertainty_asr(*, project_name: str, source: str, agg_reg: bool = False, agg_sec: bool = False, agg_version: str = '', years: int | list[int] | range, fu_code: str, s_p: str | list[str] | None = None, r_p: str | list[str] | None = None, r_c: str | list[str] | None = None, r_f: str | list[str] | None = None, group_indices: bool = False, lcia_method: str | list[str], base_asocc_args: dict[str, Any] = {'include_lcia_based_allocation_methods': True, 'l1_l2_pairs': None, 'l1_methods': None, 'l1_reg_aggreg': 'post', 'l2_reuse_years': None, 'method_plan': 'default', 'one_step_methods': None, 'projection_mode': 'regression', 'reference_years': None, 'reg_window': None, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'two_step_methods': None}, external_method: dict[str, Any] | None = None, base_cc_args: dict[str, Any] = {'dynamic_ar6': {'active': False, 'category': ['C1', 'C2', 'C3', 'C4'], 'emission_type': 'kyoto_gases', 'emissions_mode': 'gross_alt', 'harmonization': True, 'harmonization_method': 'offset', 'include_afolu': False, 'ssp_scenario': ['SSP1', 'SSP2', 'SSP3', 'SSP4', 'SSP5'], 'subset_version': None}, 'static': {'active': True, 'exclude_max_cc': False}}, lca_args: dict[str, Any] = {'external_lca': {'active': True, 'version_name': None}, 'io_lca': {'active': False}}, uncertainty_config: dict[str, Any] = {'ar6_cc_uncertainty_sources': {'dynamic_ar6_cc_uncertainty': {'active': True, 'category_uncertainty': False, 'sampling_method': 'srs'}}, 'asocc_uncertainty_sources': {'inter_method_uncertainty': {'active': True, 'mode': 'equal_weight'}, 'inter_mrio_uncertainty': {'active': False, 'alternate_source': None}, 'lcia_uncertainty': {'active': False, 'sector_cov_mapping': {}}, 'projection_uncertainty': {'active': True}, 'reference_year_uncertainty': {'active': True}}, 'io_lca_uncertainty_sources': {'lcia_uncertainty': {'active': False, 'sector_cov_mapping': {}}}, 'mc_parameters': {'convergence': {'active': True, 'convergence_statistics': ['mean'], 'max_runs': 500000, 'rtol': 0.05, 'stable_runs': 10000}, 'fixed': {'active': False, 'n_runs': 1000}}}, sobol_parameters: dict[str, Any] = {'active': False, 'convergence': {'active': True, 'max_base_samples': 1048576, 'rtol': 0.05}, 'fixed': {'active': False, 'n_base_samples': 128}, 'sobol_years': None}, output_format: str = 'csv_compact', figures: bool = True, figure_options: dict[str, Any] = {'inter_method': True, 'multi_method': True, 'per_method': True, 'polar': {'active': True, 'polar_style': 'violin', 'polar_years': None}}, figure_format: dict[str, Any] = {'dpi': 500, 'format': 'png'}, subfigures: bool = True, refresh: bool = False) → UncertaintyRunReport

Run absolute sustainability ratio (ASR) Monte Carlo uncertainty.

The function creates or reuses upstream allocated carrying capacity (aCC) and IO-LCA uncertainty outputs, consumes staged external LCA when selected, and samples only the uncertainty sources requested in uncertainty_config. It writes run values, summary statistics, uncertainty source parameters, Sobol variance decomposition when enabled, and figures when requested under the ASR Monte Carlo output folder. Omit arguments to use their default.

Parameters:

• 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. When 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.

• lcia_method – Required LCIA method name or list of names. When upstream 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 still dynamic AR6 compatible for 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.

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

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

• 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 branch. It is active by default unless active=False is provided.

    Nested keys:

    • active: Whether the static branch 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 branch. 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 branch 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, as a string or list, such as "C3" or ["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 –

  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 are used.

    • version_name: External LCA version selected from staged files. Use prepare_external_inputs(...) to import the external LCA real input folders, README guidance, and runnable CSV examples, then follow the imported README guidance for version syntax and data input format.

  • io_lca: IO-LCA generation route block.

    Nested key:

    • active: Whether IO-LCA generation is used.

• uncertainty_config –

  Monte Carlo configuration dictionary. The default signature activates projection, reference year, and inter-method uncertainty for the aSoCC denominator, and dynamic AR6 CC uncertainty for dynamic carrying capacity branches. LCIA uncertainty is inactive by default because L2 LCIA rows require sector_cov_mapping: keys are output s_p labels and values are sector CoV codes from sec_cbca_covs.csv. Inter-MRIO uncertainty is inactive by default because it requires an alternate published disaggregated aSoCC source. IO-LCA LCIA uncertainty is inactive until requested. Source blocks use an active boolean; write active=False to disable a default active source. For external LCA Monte Carlo inputs, use prepare_external_inputs(...) and follow the imported external LCA README guidance and runnable examples. See data_raw/methodological_notes/methodological_note__acc_uncertainty_sources.pdf for uncertainty source definitions and mathematical expressions.

  Accepted keys:

  • mc_parameters: optional dictionary with convergence and fixed mode blocks. Exactly one mode must be active.

    Nested mode blocks:

    • convergence: convergence mode block. This is the default active mode.

      Nested keys:

      • active: Whether convergence mode is active.

      • max_runs: Maximum number of Monte Carlo runs allowed before stopping.

      • rtol: Relative tolerance used to decide whether monitored summary statistics have converged.

      • stable_runs: Number of consecutive accepted runs that must remain within tolerance before the run stops.

      • convergence_statistics: Statistic monitored for convergence. Monte Carlo convergence is mean only and defaults to ["mean"].

    • fixed: fixed run count mode block.

      Nested keys:

      • active: Whether fixed mode is active.

      • n_runs: Exact number of Monte Carlo runs.

  • asocc_uncertainty_sources: optional dictionary for aSoCC denominator sources. Write active=False to disable a default active source block.

    Nested source blocks:

    • lcia_uncertainty: optional LCIA source block. It defaults to {"active": False, "sector_cov_mapping": {}}. Country level LCIA CoVs are resolved automatically. L2 sector resolved LCIA rows require sector_cov_mapping to map output s_p labels to sector CoV codes from sec_cbca_covs.csv, for example {"active": True, "sector_cov_mapping": {"Paper": "Paper"}}. Carbon consumption based accounts coefficients of variation (CoV) files are available under data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/. Users can inspect sec_cbca_covs.csv for sector CoV codes before choosing sector_cov_mapping values. CoV keys must match the LCIA uncertainty output domain. If agg_reg=True, region keys use reg_cbca_covs_agg_<agg_version>.csv; otherwise they use reg_cbca_covs.csv. If group_indices=True sums a region selector axis after calculation, put the full combined output region label in reg_cbca_covs_agg_<agg_version>_group_indices.csv when agg_reg=True, otherwise reg_cbca_covs_group_indices.csv. If agg_sec=True or group_indices=True, use the corresponding agg_sec output labels or combined output s_p labels as sector_cov_mapping keys. For example, with group_indices=True and s_p=["A", "B"], write sector_cov_mapping={"A, B": "Electricity"} when Electricity is the sector CoV code selected from sec_cbca_covs.csv.

      Nested keys:

      • active: Whether LCIA uncertainty is active.

      • sector_cov_mapping: Mapping from output s_p labels to sector CoV codes from sec_cbca_covs.csv.

    • projection_uncertainty: optional source block. It defaults to {"active": True}. For prospective rows using L2 historical reuse, each Monte Carlo run samples one L2 reuse year uniformly from the deterministic l2_reuse_years candidates requested for the years where reuse applies.

      Nested key:

      • active: Whether projection uncertainty is active.

    • reference_year_uncertainty: optional source block. It defaults to {"active": True}. For acquired rights (AR) routes, each Monte Carlo run samples uniformly among requested reference years admissible for the studied year (reference_year <= year). The same sampled reference year is shared across the run when admissible; years for which it is not admissible resample among their admissible reference years.

      Nested key:

      • active: Whether reference year uncertainty is active.

    • inter_mrio_uncertainty: optional source block. To activate it, write {"active": True, "alternate_source": "<disaggregated label>"}, for example {"active": True, "alternate_source": "oecd_electricity"}. It applies continuous uniform interpolation between the main MRIO source and an alternate published disaggregated aSoCC source created by disaggregate_asocc(...). It applies only to non LCIA methods.

      Nested keys:

      • active: Whether inter-MRIO uncertainty is active.

      • alternate_source: Published disaggregated aSoCC source label used as the alternate MRIO source.

    • inter_method_uncertainty: optional source block. It defaults to {"active": True, "mode": "equal_weight"}. Each Monte Carlo run samples one method leaf among the selected deterministic and external methods. Equal weight mode writes the tree CSV, README, and rendered probability tree under the run folder figures/inter_method_tree/. To prepare custom weights before running uncertainty, use write_asocc_weight_template(...); it writes equal_weights.csv, README_inter_method_weights.txt, and probability_tree__equal_weights.<ext> under B1_asocc/preview_inter_method_weights/. Use preview_asocc_weight_tree(...) to validate and render a custom probability tree before using {"mode": "custom", "version_name": "..."}.

      Nested keys:

      • active: Whether inter-method uncertainty is active.

      • mode: Inter-method sampling mode. Accepted values are "equal_weight" and "custom".

      • version_name: Custom weight version used when mode="custom".

  • ar6_cc_uncertainty_sources: optional dictionary for dynamic AR6 CC denominator sources. Write active=False to disable a default active source block.

    Nested source block:

    • dynamic_ar6_cc_uncertainty: optional AR6 CC source block. It defaults to {"active": True, "sampling_method": "srs", "category_uncertainty": False}. sampling_method accepts "srs" for simple random sampling (samples across retained model-scenario pairs matching the requested category and SSP) or "lhs" for Latin hypercube sampling (samples among retained models first, then among retained scenarios for the selected model, category, and SSP to limit over representation of models with more AR6 submissions). The effect of this choice is visible in process_ar6(...) sampling diagnostic figures. category_uncertainty is inactive by default. If True, each Monte Carlo run first samples one retained AR6 category with equal probability in the studied SSP pool. It then applies sampling_method inside that selected category; with sampling_method="lhs", this means model first, then scenario inside that model.

      Nested keys:

      • active: Whether dynamic AR6 carrying capacity uncertainty is active.

      • sampling_method: AR6 pathway sampling method. Accepted values are "srs" and "lhs".

      • category_uncertainty: Whether each Monte Carlo run samples one retained AR6 category before applying sampling_method inside that category.

  • io_lca_uncertainty_sources: optional dictionary for package managed IO-LCA numerator sources.

    Nested source block:

    • lcia_uncertainty: optional LCIA source block. It defaults to {"active": False, "sector_cov_mapping": {}}. Country level LCIA CoVs are resolved automatically. L2 sector resolved LCIA rows require sector_cov_mapping to map output s_p labels to sector CoV codes from sec_cbca_covs.csv, for example {"active": True, "sector_cov_mapping": {"Paper": "Paper"}}. Carbon consumption based accounts coefficients of variation (CoV) files are available under data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/. Users can inspect sec_cbca_covs.csv for sector CoV codes before choosing sector_cov_mapping values. CoV keys must match the LCIA uncertainty output domain. If agg_reg=True, region keys use reg_cbca_covs_agg_<agg_version>.csv; otherwise they use reg_cbca_covs.csv. If group_indices=True sums a region selector axis after calculation, put the full combined output region label in reg_cbca_covs_agg_<agg_version>_group_indices.csv when agg_reg=True, otherwise reg_cbca_covs_group_indices.csv. If agg_sec=True or group_indices=True, use the corresponding agg_sec output labels or combined output s_p labels as sector_cov_mapping keys. For example, with group_indices=True and s_p=["A", "B"], write sector_cov_mapping={"A, B": "Electricity"} when Electricity is the sector CoV code selected from sec_cbca_covs.csv.

      Nested keys:

      • active: Whether LCIA uncertainty is active.

      • sector_cov_mapping: Mapping from output s_p labels to sector CoV codes from sec_cbca_covs.csv.

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

• base_asocc_args –

  Optional aSoCC denominator envelope. Write nested arguments as base_asocc_args={"method_plan": "default"}. Accepted keys are method and projection controls only. 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 README guidance and runnable CSV examples, then follow the imported README guidance for external method names, selector syntax, and deterministic or Monte Carlo external aSoCC CSV preparation.

• output_format – Public uncertainty table format, either "csv_compact" or "parquet". Defaults to "csv_compact".

• sobol_parameters –

  Sobol sensitivity settings. Sobol analysis estimates the contribution of active uncertainty sources to output variance and writes README_sobol.txt under results/sobol/ for interpretation. The default has active=False and writes no Sobol artifacts. To run Sobol, set active=True. With the default mode blocks, enabled Sobol uses convergence mode. To run a fixed Sobol design, set fixed.active=True and convergence.active=False. Sobol base sizes must be powers of two.

  Nested keys:

  • active: Whether Sobol sensitivity analysis is active.

  • convergence: convergence mode block. When Sobol is active, exactly one of convergence or fixed is active.

    Nested keys:

    • active: Whether convergence mode is active.

    • max_base_samples: Maximum Sobol base size.

    • rtol: Relative tolerance for monitored S1 and ST indices.

  • fixed: fixed Sobol base size mode block.

    Nested keys:

    • active: Whether fixed mode is active.

    • n_base_samples: Exact Sobol base size.

  • sobol_years: Studied output years evaluated by Sobol for static carrying capacity branches. When omitted, static Sobol evaluates only the first and last studied years in the requested studied year set. Dynamic AR6 carrying capacity Sobol ignores this yearly selector and evaluates cumulative ASR over the full studied period.

• figures – Whether to render figures. Default is True.

• figure_options –

  ASR figure options. Defaults to {"per_method": True, "multi_method": True, "inter_method": True, "polar": {"active": True, "polar_years": None, "polar_style": "violin"}}.

  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.

  • inter_method: Whether to render inter-method uncertainty figures. These figures use the same method specific layout as per_method, but represent uncertainty induced by the inter method uncertainty setting rather than comparing individual allocation methods. This option is ignored when inter-method uncertainty is inactive.

  • polar: Nested polar figure selector. The block is optional and defaults to {"active": True, "polar_years": None, "polar_style": "violin"}. Its active key enables polar figures and defaults to True. Its polar_years key selects studied output years evaluated by ASR polar figures; when omitted, polar figures use only the first and last studied years in the requested studied year set. Its polar_style key accepts "violin", "whisker", and "both".

• 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 aCC and IO-LCA uncertainty calls render their own figures when figures=True. Default is True.

• refresh – If True, refresh the resolved ASR Monte Carlo outputs and every upstream component output scope called by this ASR uncertainty request. This can refresh the matching uncertainty_acc(...) output scope and its prerequisites, including aSoCC output scopes and, when dynamic AR6 CC is used, the matching processed AR6 output scope selected by process_ar6(...), the matching deterministic_ar6_cc(...) output scope, and, when dynamic AR6 CC uncertainty is active, the matching uncertainty_ar6_cc(...) output scope. When the numerator route is IO-LCA with LCIA uncertainty active, the matching deterministic_io_lca(...) and uncertainty_io_lca(...) output scopes can also be refreshed. For example, matching ASR Monte Carlo run folders are refreshed under <repo>/demo/C_asr/exiobase_3102_ixi__elec/external_lca__test_v1/monte_carlo/mc_<generated_id>. External LCA staged inputs, processed MRIO inputs, processed population and GDP, raw downloads, and deterministic ASR outputs are not refreshed. Defaults to False.

Returns:

UncertaintyRunReport describing ASR uncertainty table outputs and figure outputs when figures are requested.

Raises:

ValueError – If the request, source configuration, or persisted input files are inconsistent.

Notes

The repository root is taken from the package default configured by set_workspace(); call set_workspace() before invoking this function.

Example

Run static ASR for L2.c.b producing sector Paper and consuming region FR with IO-LCA and LCIA uncertainty added, using defaults where omitted:

from pyaesa import uncertainty_asr

uncertainty_asr(
    project_name="demo",
    source="exiobase_3102_ixi",
    years=range(2020, 2031),
    lcia_method="gwp100_lcia",
    fu_code="L2.c.b",
    s_p=["Paper"],
    r_c=["FR"],
    lca_args={
        "external_lca": {"active": False, "version_name": None},
        "io_lca": {"active": True},
    },
    uncertainty_config={
        "asocc_uncertainty_sources": {
            "lcia_uncertainty": {
                "active": True,
                "sector_cov_mapping": {"Paper": "Paper"},
            },
        },
        "io_lca_uncertainty_sources": {
            "lcia_uncertainty": {
                "active": True,
                "sector_cov_mapping": {"Paper": "Paper"},
            },
        },
    },
)