TUTORIAL: Study objective B0, dynamic CC (uncertainty)

AESA Phase B: (dynamic) carrying capacities definition.

Run aSoCC Monte Carlo uncertainty on extracted AR6 climate change pathways from process_ar6(...) outputs.

Before starting…

Set workspace

Run set_workspace(...) before any later function call. It sets the active workspace root for the current Python session, creates or reuses the workspace, imports package prerequisites under data_raw/, and records setup guidance in data_raw/summary.log.

[ ]:

from pyaesa import set_workspace

# Windows example; update this path before running.
set_workspace(r"C:\Users\username\Documents\aesa_workspace")

# macOS example; update this path before running.
# set_workspace("/Users/username/Documents/aesa_workspace")

Run prerequisites

This tutorial assumes that the workspace has already been set, with all prerequisites available (downloads and processing).

If this is not your case, it is recommended to first go through the core prerequisite notebooks: tutorials/core_prerequisites/0_set_workspace.ipynb, tutorials/core_prerequisites/1_download_data.ipynb, and tutorials/core_prerequisites/2_process_data.ipynb.

Basic features of the uncertainty function

In a nutshell

The function takes necessary inputs, mainly for two purposes:

inputs for the deterministic function base_ar6_cc_args, including years, category, ssp_scenario, and dynamic carrying capacity emission route parameters.
inputs for the configuration of uncertainty analysis (Monte Carlo) through uncertainty_config. The AR6 CC uncertainty source list contains dynamic_ar6_cc_uncertainty, plus mc_parameters for the Monte Carlo run policy. dynamic_ar6_cc_uncertainty is active by default; its nested category_uncertainty option is inactive by default and must be requested explicitly.

Set category_uncertainty=True when Monte Carlo should sample one AR6 climate category uniformly across the requested categories with retained model-scenario pairs, then sample a retained model-scenario pair within that category pool.

The uncertainty output folder contains:

Monte Carlo run values and summary statistics.
results/README.txt explains 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). Use figures=False to skip them; figure_format controls the file format and resolution.
log files, including uncertainty source parameter logs.

Basic features also involve:

overwriting of existing values: use the refresh parameter.

Methodological details on AR6 scenario filtering, harmonization, gross emissions modes, and dynamic carrying capacity construction are documented in methodological_notes/methodological_note__steady_state__dynamic_cc.pdf.

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_ar6_cc(…) arguments

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

Dynamic AR6 CC Monte Carlo in default convergence mode

[ ]:

from pyaesa import uncertainty_ar6_cc

uncertainty_ar6_cc(
    base_ar6_cc_args={
        "years": range(2020, 2051),
        "category": ["C1", "C2"],
        "ssp_scenario": ["SSP2"],
    },
    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}},
        "dynamic_ar6_cc_uncertainty": {
            "category_uncertainty": True,
        },
    },
)

What to do next

Beginners

If you are a new user in the process of discovering pyaesa, it is recommend that you first discover all study objectives with the basic features available. Have a look at the other notebooks available at tutorials/study_objectives/0_study_objectives.md

Experts

If you are already familiar with pyaesa and if you want to discover advanced features available, check out examples in the next section of this tutorial !

Advanced features

Advanced features currently available include:

Changing the sampling method for the Monte Carlo simulation
Changing convergence tolerance or maximum runs

Changing the sampling method for the Monte Carlo simulation

dynamic_ar6_cc_uncertainty["sampling_method"] selects how retained AR6 model-scenario rows are sampled.

"srs" is the default simple random sampling across retained model-scenario pairs matching the requested category and SSP filters.
"lhs" samples a model first, then samples one retained scenario for that model, category, and SSP. This limits over representation of models with more AR6 submissions.

category_uncertainty=True can be combined with either sampling method. In that case each Monte Carlo run first samples one retained AR6 category, then samples a model-scenario row inside that category.

[ ]:

uncertainty_ar6_cc(
    base_ar6_cc_args={
        "years": range(2020, 2051),
        "category": ["C1", "C2"],
        "ssp_scenario": ["SSP2"],
    },
    uncertainty_config={
        "mc_parameters": {
            "fixed": {"active": True, "n_runs": 1000},
            "convergence": {"active": False},
        },
        "dynamic_ar6_cc_uncertainty": {
            "sampling_method": "lhs",
            "category_uncertainty": True,
        },
    },
)

Changing convergence tolerance or maximum runs

mc_parameters["convergence"] controls convergence mode. Omit mc_parameters when the default convergence settings are sufficient; write the block only when the study needs a different rtol or max_runs value.

[ ]:

uncertainty_ar6_cc(
    base_ar6_cc_args={
        "years": range(2020, 2051),
        "category": ["C1", "C2"],
        "ssp_scenario": ["SSP2"],
    },
    uncertainty_config={
        "mc_parameters": {
            "convergence": {
                "rtol": 0.02,
            },
        },
    },
)