TUTORIAL: Study objective C (uncertainty)
Before starting…
Set workspace
Run set_workspace(...) before any later function call. It sets the active workspace root for the current Python session, creates or reuses the workspace, imports package prerequisites under data_raw/, and records setup guidance in data_raw/summary.log.
[ ]:
from pyaesa import set_workspace
# Windows example; update this path before running.
set_workspace(r"C:\Users\username\Documents\aesa_workspace")
# macOS example; update this path before running.
# set_workspace("/Users/username/Documents/aesa_workspace")
Run prerequisites
Functional units and selectors
The example in this tutorial uses the functional unit L2.c.b with the following selectors: one producing sector s_p="Paper" and one consuming region r_c="FR".
Use tutorials/study_objectives/1_functional_units_and_allocation_methods.md to choose the FU and required selectors. Use methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf for detailed FU definitions and mathematical expressions.
[ ]:
project_name_ = "SO_C_demo_paper_fr"
source_ = "exiobase_3102_ixi"
fu_code_ = "L2.c.b"
study_period_ = range(2017, 2021)
s_p_ = ["Paper"]
r_c_ = ["FR"]
lcia_method_ = "pb_lcia"
Basic features of the uncertainty function
In a nutshell
The function takes necessary inputs, mainly for five purposes:
public scope arguments, such as
project_name,source,years,lcia_method,fu_codeand the relevant selectors (heres_pandr_c) for the selected functional unit.lcia_methodselects the carrying capacity reference used by aCC. Package prerequisites includepb_lcia,gwp100_lcia, andef_3.1.inputs for the LCA numerator route in the
lca_argsblock, such asexternal_lcaandio_lca. The numerator route must match the selected FU boundary.denominator aSoCC choices through the
base_asocc_argsblock. These choices include allocation method and enacting metric settings.carrying capacity choices through the
base_cc_argsblock. Thestaticblock selects static carrying capacities. Thedynamic_ar6block selects dynamic carrying capacity parameters. Dynamic AR6 carrying capacity is available for any selected method whose static carrying capacity CSV contains an impact row equal toGWP_100.inputs for uncertainty analysis through
uncertainty_config. The ASR uncertainty source list contains the aSoCC denominator sourceslcia_uncertainty,projection_uncertainty,reference_year_uncertainty,inter_mrio_uncertainty, andinter_method_uncertainty; the carrying capacity sourcedynamic_ar6_cc_uncertainty; and the IO-LCA numerator sourceio_lca_uncertainty_sources.lcia_uncertaintywhen the IO-LCA numerator route is used. It also containsmc_parametersfor the Monte Carlo run policy andsobol_parametersfor Sobol analysis. By default,projection_uncertainty,reference_year_uncertainty,inter_method_uncertainty, anddynamic_ar6_cc_uncertaintyare active when their deterministic routes are in scope; LCIA uncertainty blocks andinter_mrio_uncertaintyare inactive because they require user provided elements (sector_cov_mappingwhere needed, or an alternate disaggregated aSoCC source). The nestedcategory_uncertaintyoption for dynamic AR6 CC is inactive by default.
The list of uncertainty sources and their mathematical expressions are documented in methodological_notes/methodological_note__acc_uncertainty_sources.pdf.
The uncertainty output folder contains:
Monte Carlo run values and summary statistics, and Sobol variance decomposition outputs for uncertainty source contributions when Sobol is active. Sobol analysis writes
README_sobol.txtwith the results for interpretation.results/README.txtexplains the public row identity tables, run value fragments, run interval indexes, summary tables, source method logs, and compact CSV or Parquet reading contract.Figures are rendered by default (
figures=True). Usefigures=Falseto skip them;figure_formatcontrols the file format and resolution.figure_optionscan restrict figure families.log files, including uncertainty source parameter logs.
Basic features also involve:
MRIO aggregation and disaggregation of sectors and/or regions: use the
agg_sec,agg_reg, andagg_versionparameters. The MRIO aggregation folder includes packagedagg_reg_eu27.csvandagg_reg_world.csvexamples; inspect them indata_raw/mrio/<source>/aggregation/and followREADME_aggregation.txtbefore writing a custom MRIO aggregation and disaggregation mapping CSV.allocation methods: by default, the aSoCC denominator uses all allocation methods available for the selected FU. If a study uses a smaller denominator method set, justify that normative choice and pass
method_plan,l1_methods,one_step_methods,two_step_methods, andl1_l2_pairsinsidebase_asocc_args. Available methods per FU are listed in tutorials/study_objectives/1_functional_units_and_allocation_methods.md; definitions and mathematical expressions are in methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf.overwriting of existing values: use the
refreshparameter.
Public argument checklist
The table lists all arguments; the same definitions are available in the function docstring.
Green items = default if omitted.
Orange items = optional feature skipped if omitted.
Do not write green or orange items when that behavior is intended.
uncertainty_asr(…) arguments
Argument | Description |
|---|---|
project_name | Required project name used to build <repo>/<project_name>. |
source | MRIO source key (“exiobase_396_ixi”, “exiobase_396_pxp”, “exiobase_3102_ixi”, “exiobase_3102_pxp”, or “oecd_v2025”), or “iso3” for ISO3 only mode (L1 EG/PR(GDPcap) only). |
agg_reg | If True, reclassify MRIO regions with the agg_reg_<agg_version>.csv MRIO aggregation and disaggregation mapping. The mapping can keep native labels, aggregate several native regions into one target label, or disaggregate one native region across several target labels when a weight column is provided. Default False keeps native source regions. |
agg_sec | If True, reclassify MRIO sectors with the agg_sec_<agg_version>.csv MRIO aggregation and disaggregation mapping. The mapping can keep native labels, aggregate several native sectors into one target label, or disaggregate one native sector across several target labels when a weight column is provided. Default False keeps native source sectors. |
agg_version | Name token used to resolve the matching agg_reg_<agg_version>.csv and/or agg_sec_<agg_version>.csv MRIO aggregation and disaggregation mapping files in data_raw/mrio/<source>/aggregation. Required when agg_reg or agg_sec is True. Defaults to an empty string for native source classification. Use the same token in downstream calls that should reuse the processed classification. If a mapping file has a weight column, weights must sum to 1 for each original label. |
years | Studied years. Accepts a single year, list, or range. If omitted, all available MRIO years for the selected source and agg_version are used. |
fu_code | Required functional unit code (for example “L1.a”, “L2.c.b”). See data_raw/methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf for all available functional unit codes and the system boundaries each represents. |
s_p | Producing sector filter(s), single string or list. If this is a required axis for fu_code and the argument is omitted, the run expands to all valid producing sectors. To identify valid sector names, see the first column of the relevant data_raw/mrio/…/aggregation/…/agg_sec_template.csv file. For EXIOBASE sector definitions, see data_raw/mrio/exiobase_3/sector_classification.xlsx; EXIOBASE ixi and pxp use different sector lists. |
r_p | Producing region filter(s), single string or list. If this is a required axis for fu_code and the argument is omitted, the run expands to all valid producing regions. To identify valid region names, see the first column of the relevant data_raw/mrio/…/aggregation/agg_reg_template.csv file. |
r_c | Consuming region filter(s), single string or list. If this is a required axis for fu_code and the argument is omitted, the run expands to all valid consuming regions. To identify valid region names, see the first column of the relevant data_raw/mrio/…/aggregation/agg_reg_template.csv file. |
r_f | Final demand region filter(s), single string or list. If this is a required axis for fu_code and the argument is omitted, the run expands to all valid final demand regions. To identify valid region names, see the first column of the relevant data_raw/mrio/…/aggregation/agg_reg_template.csv file. |
group_indices | Whether multiple selected region or sector filter values are kept as separate result rows or summed into one result row after the function calculation has been performed. • False (default): keep selected values as independent rows. • True: sum selected values into one result row. The function refuses to run when group_indices=True is used with L2.a.b, L2.b.b, or L2.c.b because summing output rows for CBA total demand boundaries can double count. For these functional units, change the upstream MRIO aggregation and disaggregation scope with agg_reg, agg_sec, and agg_version before running the study. |
lcia_method | 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 dynamic AR6 compatible through its “GWP_100” impact category. Dynamic AR6 CC is available for any selected method whose static carrying capacity CSV contains an impact row equal to “GWP_100”. Custom static CC methods also require a matching file in data_raw/carrying_capacities/; follow README_add_custom_carrying_capacities.txt. When upstream allocated shares of carrying capacities (aSoCC) LCIA based methods or IO-LCA generation is in scope, custom EXIOBASE MRIO LCIA methods must be prepared with data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/README_add_custom_lcia_characterization_matrices.txt and processed with process_mrio(…). base_asocc_args[“include_lcia_based_allocation_methods”] controls whether LCIA based allocation methods are included. When it is False, upstream aSoCC keeps only non LCIA dependent methods, so the requested lcia_method may be non MRIO when the matching carrying capacity and selected LCA numerator prerequisites exist. |
base_asocc_args | Optional aSoCC 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 runnable CSV examples and README_external_asocc_templates.txt, then follow that README for external method names, selector syntax, and deterministic or Monte Carlo external aSoCC CSV preparation. |
base_cc_args | Carrying capacity family envelope. The package default is static active and dynamic AR6 inactive. Provide a dynamic_ar6 block to add dynamic AR6 carrying capacities. Set static.active=False for dynamic only runs. Nested keys: • static: Static carrying capacity route. It is active by default unless active=False is provided. Nested keys: • active: Whether the static route is active. Defaults to True. • exclude_max_cc: Whether to use only min_cc. Defaults to False. False keeps the paired min_cc plus max_cc interpretation when max_cc is present. True uses only min_cc. • dynamic_ar6: Dynamic AR6 carrying capacity route. It is inactive when omitted. When the block is provided, it is active unless active=False is provided. It uses top level years and requires at least two consecutive years. Nested keys: • active: Whether the dynamic AR6 route is active. • harmonization: Whether to harmonize retained AR6 pathways to the historical baseline. Defaults to True. • harmonization_method: Harmonization method applied only when harmonization=True. Defaults to “offset”. The only supported value is currently “offset”. Ignored when harmonization=False. • category: AR6 category classification selector for global warming trajectories. Accepts a string such as “C3” or a list such as [“C1”, “C2”]. Valid values are “C1” through “C8”. Defaults to C1 to C4, the categories aligned with the 2015 Paris Agreement. • ssp_scenario: Canonical SSP selector as a string, list, or None, such as “SSP2” or [“SSP1”, “SSP2”]. Defaults to SSP1 to SSP5. • emission_type: Dynamic AR6 emission type. Accepted values are “kyoto_gases” (default) and “co2”. emission_type=”kyoto_gases” uses the GWP100 Kyoto Gases aggregate; emission_type=”co2” uses direct CO2 pathways. • include_afolu: Whether AFOLU emissions are included inside the selected emission_type. Defaults to False. • emissions_mode: Dynamic AR6 emissions mode. Accepted values are “net”, “gross”, and “gross_alt”. Defaults to “gross_alt”. “net” uses net AR6 emissions pathways directly. “gross” removes all sequestration sources from net emissions. “gross_alt” removes all sequestration sources except CCS. CCS is retained because IPCC AR6 treats CCS as capture at fossil or industrial point sources rather than direct removal of CO2 from the atmosphere, so it is kept separate from net negative sequestration. Gross modes write positive emissions rows and signed negative sequestration companion rows; downstream aCC and ASR consume only the positive emissions rows. See data_raw/methodological_notes/methodological_note__steady_state__dynamic_cc.pdf for the methodological explanation. • subset_version: Optional selector for a subset of AR6 model-scenario pairs. Follow data_processed/ar6/<processed_scope>/README_model_scenario_subset.txt to create the subset CSV. |
lca_args | 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, runnable CSV examples, and README_external_lca_templates.txt, then follow that README for version syntax and data input format. • io_lca: IO-LCA generation route block. Nested key: • active: Whether IO-LCA generation is used. |
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 routes. 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 README_external_lca_templates.txt and the 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. 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_inter_method_weights.txt, 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 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. 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. |
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. |
output_format | Public uncertainty table format, either “csv_compact” or “parquet”. Defaults to “csv_compact”. |
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 figures are rendered 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. External LCA staged inputs, processed MRIO inputs, processed population and GDP, raw downloads, and deterministic ASR outputs are not refreshed. Defaults to False. |
ASR Monte Carlo with IO-LCA numerator and static pb_lcia aCC in default convergence mode
[ ]:
from pyaesa import uncertainty_asr
uncertainty_asr(
project_name=project_name_,
source=source_,
years=study_period_,
fu_code=fu_code_,
s_p=s_p_,
r_c=r_c_,
lcia_method="pb_lcia",
lca_args={
"io_lca": {},
},
figure_options={"per_method": False},
uncertainty_config={
# mc_parameters is omitted, so Monte Carlo uses convergence mode defaults.
# To change convergence tolerance or maximum run count, add for example:
# "mc_parameters": {"convergence": {"rtol": 0.02, "max_runs": 100000}},
"asocc_uncertainty_sources": {
"lcia_uncertainty": {
"sector_cov_mapping": {"Paper": "Paper"},
},
},
"io_lca_uncertainty_sources": {
"lcia_uncertainty": {
"sector_cov_mapping": {"Paper": "Paper"},
},
},
},
)
ASR Monte Carlo with EF 3.1 static aCC and external LCA numerator
Run this after staging the external LCA Monte Carlo files with prepare_external_inputs(...). For file layout and version naming, use tutorials/optional_workflows/external_asocc_lca_input_staging.ipynb; it writes README_external_lca_templates.txt under A_lca/external_lca/templates/. The packaged external LCA example is ready to run with version_name="template", but its numeric values are dummy demonstration
values and must be replaced by project specific external LCA values before interpreting ASR results.
This example uses the EF 3.1 route: ef_3.1 has no EXIOBASE LCIA characterization matrix in pyaesa, so LCIA based native allocation methods are disabled with base_asocc_args["include_lcia_based_allocation_methods"] = False. The call uses fixed mode with 100 runs.
[ ]:
from pyaesa import prepare_external_inputs
prepare_external_inputs(project_name=project_name_)
uncertainty_asr(
project_name=project_name_,
source=source_,
years=range(2019, 2031),
fu_code=fu_code_,
s_p=s_p_,
r_c=r_c_,
lcia_method="ef_3.1",
base_asocc_args={
# ef_3.1 has no EXIOBASE LCIA characterization matrix in pyaesa.
# Hence "include_lcia_based_allocation_methods" is False.
# This excludes LCIA based allocation methods, such as acquired rights (AR),
# because they require an EXIOBASE LCIA characterization matrix.
"include_lcia_based_allocation_methods": False,
"ssp_scenario": ["SSP2"],
},
lca_args={
"external_lca": {
"version_name": "template",
},
},
uncertainty_config={
"mc_parameters": {
"fixed": {"active": True, "n_runs": 100},
"convergence": {"active": False},
},
},
)
ASR Monte Carlo with dynamic AR6 aCC in default convergence mode
By default, all figures are rendered by the function. In this case, this can lead to a significant number of figures (several hundreds), as one figure will be generated for each model-scenario. The figures parameter is hence set to False given the large number of model-scenarios. With a subset of model-scenarios selected, figure rendering is useful in deterministic mode.
[ ]:
uncertainty_asr(
project_name=f"{project_name_}_prosp",
source=source_,
years=study_period_,
fu_code=fu_code_,
s_p=s_p_,
r_c=r_c_,
lcia_method="gwp100_lcia",
base_asocc_args={
"ssp_scenario": ["SSP2"],
},
base_cc_args={
"static": {"active": False},
"dynamic_ar6": {
"category": ["C1", "C2"],
"ssp_scenario": ["SSP2"],
},
},
lca_args={
"io_lca": {},
},
uncertainty_config={
# mc_parameters is omitted, so Monte Carlo uses convergence mode defaults.
# To change convergence tolerance or maximum run count, add for example:
# "mc_parameters": {"convergence": {"rtol": 0.02, "max_runs": 100000}},
"asocc_uncertainty_sources": {
"lcia_uncertainty": {
"sector_cov_mapping": {"Paper": "Paper"},
},
},
"ar6_cc_uncertainty_sources": {
"dynamic_ar6_cc_uncertainty": {
"category_uncertainty": True,
},
},
"io_lca_uncertainty_sources": {
"lcia_uncertainty": {
"sector_cov_mapping": {"Paper": "Paper"},
},
},
},
figure_options={"per_method": False, "multi_method": False},
)
What to do next
Beginners
If you are a new user in the process of discovering pyaesa, it is recommend that you first discover all study objectives with the basic features available. Have a look at the other notebooks available at tutorials/study_objectives/0_study_objectives.md
Experts
If you are already familiar with pyaesa and if you want to discover advanced features available, check out examples in the next section of this tutorial !
Advanced features
Advanced features currently available include:
LCIA uncertainty CoVs for MRIO
agg_*andgroup_indiceshandlingCustom external LCA numerator
Custom external aSoCC
Custom inter-method weights
Changing convergence tolerance or maximum runs
Sobol sensitivity analysis
LCIA uncertainty CoVs for MRIO agg_* and group_indices handling
ASR can use LCIA uncertainty in the aSoCC denominator and, for the IO-LCA numerator, in io_lca_uncertainty_sources. For aggregated region runs, use the packaged agg_reg_eu27.csv or agg_reg_world.csv examples by setting agg_reg=True and agg_version="eu27" or "world". Matching reg_cbca_covs_agg_eu27.csv and reg_cbca_covs_agg_world.csv files are provided in data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/. Sector resolved rows still use sector_cov_mapping,
with output sector labels as keys and sec_cbca_covs.csv codes as values.
For LCIA uncertainty on group_indices outputs, prepare CoV files whose region and sector labels match the combined labels written by the selected public result scope. Packaged workspace templates include matching CoV files for EU27 and World region aggregation.
Custom external aSoCC
Use external_method when the aCC denominator should include staged external aSoCC methods. Prepare those files with tutorials/optional_workflows/external_asocc_lca_input_staging.ipynb. That optional workflow explains README_external_asocc_templates.txt, filename syntax, and deterministic or Monte Carlo staging folders. External aSoCC Monte Carlo inputs are staged with prepare_external_inputs(...) and selected with
external_method.
The packaged external aSoCC Monte Carlo examples include the one step CO(S) route and the two step AR(E)::UT(S) route. In this EF 3.1 example, CO(S) is non LCIA specific, while AR(E)::UT(S) is supplied directly as an external EF 3.1 LCIA specific method. Native LCIA based allocation methods remain disabled for the same reason as above. The call below uses fixed mode with 100 runs. The packaged external aSoCC and LCA values are dummy demonstration values only and must be replaced
before interpreting results.
[ ]:
prepare_external_inputs(project_name=project_name_)
uncertainty_asr(
project_name=project_name_,
source=source_,
years=range(2019, 2031),
fu_code=fu_code_,
s_p=s_p_,
r_c=r_c_,
lcia_method="ef_3.1",
base_asocc_args={
# ef_3.1 has no EXIOBASE LCIA characterization matrix in pyaesa.
# Hence "include_lcia_based_allocation_methods" is False.
# This excludes native LCIA based allocation methods because they require
# an EXIOBASE LCIA characterization matrix. The external AR(E)::UT(S)
# rows below are supplied directly by external input files.
"include_lcia_based_allocation_methods": False,
"ssp_scenario": ["SSP2"],
},
external_method={
"one_step_methods": ["CO(S)"],
"l1_l2_pairs": ["AR(E)::UT(S)"],
},
lca_args={
"external_lca": {
"version_name": "template",
},
},
uncertainty_config={
"mc_parameters": {
"fixed": {"active": True, "n_runs": 100},
"convergence": {"active": False},
},
},
)
Custom inter-method weights
Inter-method custom weights are prepared with write_asocc_weight_template(...) and documented in README_inter_method_weights.txt.
Changing convergence tolerance or maximum runs
The default convergence examples above omit mc_parameters. To change convergence controls, add "mc_parameters": {"convergence": {"rtol": 0.02, "max_runs": 100000}} under uncertainty_config. Omit nested values that should keep their defaults.
Sobol sensitivity analysis
Use sobol_parameters when Sobol variance decomposition is required. The argument checklist above gives the available mode fields and output year selector.
The example below keeps ordinary Monte Carlo and Sobol in fixed mode to make tutorial runtime predictable; the fixed Monte Carlo run count is not a Sobol convergence setting.
[ ]:
uncertainty_asr(
project_name=f"{project_name_}_sobol",
source=source_,
years=study_period_,
fu_code=fu_code_,
s_p=s_p_,
r_c=r_c_,
lcia_method="pb_lcia",
lca_args={
"io_lca": {},
},
uncertainty_config={
"mc_parameters": {
"fixed": {"active": True, "n_runs": 1000},
"convergence": {"active": False},
},
"asocc_uncertainty_sources": {
"lcia_uncertainty": {
"sector_cov_mapping": {"Paper": "Paper"},
},
},
"io_lca_uncertainty_sources": {
"lcia_uncertainty": {
"sector_cov_mapping": {"Paper": "Paper"},
},
},
},
sobol_parameters={
"active": True,
# For Sobol convergence with the default rtol, keep only "active": True.
# To set another convergence rtol, replace fixed mode with:
# "convergence": {"rtol": 0.02},
"fixed": {"active": True, "n_base_samples": 128},
"convergence": {"active": False},
},
figure_options={"per_method": False},
)