- {
- “cells”: [
- {
“cell_type”: “markdown”, “id”: “80bf05f6”, “metadata”: {}, “source”: [
“# TUTORIAL Prerequisites 2: Processing downloaded archives to prepare data for the workflown”
]
}, {
“cell_type”: “code”, “execution_count”: 1, “id”: “93db96fe”, “metadata”: {}, “outputs”: [], “source”: [
“from pyaesa import set_workspace, process_pop_gdp, process_mrio, process_ar6”
]
}, {
“cell_type”: “markdown”, “id”: “120e4a5b”, “metadata”: {}, “source”: [
“All of the following processing prepares input data before starting the AESA workflow.n”, “Once the required processed assets exist on disk, continue directly to the notebook that matches then”, “study endpoint (aSoCC, IO-LCA, aCC, ASR in [tutorials/study_objectives](../study_objectives/0_study_objectives.md)) rather than manually callingn”, “one by one every downstream function in sequence.n”, “n”, “Once processed outputs are on disk they are reused by all subsequent AESA studies as long as whatn”, “has been processed (regarding years + MRIO aggregation and disaggregation options and LCIA methods) corresponds to then”, “study’s perimeter. Therefore once processing has been done once subsequent uses of <span class="pyaesa-brand-py" style="color:#366e9c"><strong>py</strong></span><span class="pyaesa-brand-aesa" style="color:#c83737"><strong>aesa</strong></span> willn”, “considerably reduce computing time.”
]
}, {
“cell_type”: “markdown”, “id”: “88d871f2”, “metadata”: {}, “source”: [
“# Before starting…”
]
}, {
“cell_type”: “markdown”, “id”: “2e807670”, “metadata”: {}, “source”: [
“## Prerequisites 0: Set workspacen”
]
}, {
“cell_type”: “markdown”, “id”: “188f1a5c”, “metadata”: {}, “source”: [
“Every tutorial notebook repeats set_workspace(…) as all function calls always assume it hasn”, “already run in the current Python session. It defines paths for outputs.n”
]
}, {
“cell_type”: “code”, “execution_count”: null, “id”: “8422c23e”, “metadata”: {}, “outputs”: [], “source”: [
“# Windows example; update this path before running.n”, “set_workspace(r"C:\Users\username\Documents\aesa_workspace")n”, “n”, “# macOS example; update this path before running.n”, “# set_workspace("/Users/username/Documents/aesa_workspace")”
]
}, {
“cell_type”: “markdown”, “id”: “d01cf2ee”, “metadata”: {}, “source”: [
“## Prerequisites 1: Download data”
]
}, {
“cell_type”: “markdown”, “id”: “c628aac3”, “metadata”: {}, “source”: [
“Make sure you ran the notebook [tutorials/core_prerequisites/1_download_data.ipynb](1_download_data.ipynb) in the same workspace.n”
]
}, {
“cell_type”: “markdown”, “id”: “72f17b28”, “metadata”: {}, “source”: [
“# Prerequisites 2: Process datan”
]
}, {
“cell_type”: “markdown”, “id”: “77c7f940”, “metadata”: {}, “source”: [
“n”, “Processing converts the raw files downloaded by the download functions into tables and matrices thatn”, “AESA workflow functions can reuse deterministically accross case studies.n”
]
}, {
“cell_type”: “markdown”, “id”: “cad14974”, “metadata”: {}, “source”: [
“This notebook covers the full Process family:n”, “n”, “- process_pop_gdp(…)n”, “- process_mrio(…)n”, “- process_ar6(…)n”, “n”, “Downstream reuse summary:n”, “n”, “| Function | Main outputs | Reused later by |\n", "| — | — | — |\n", "| process_pop_gdp | harmonized historical and prospective SSP population/GDP tables | deterministic_asocc(…) and uncertainty workflows built on allocation outputs |\n", "| process_mrio | processed MRIO tables, optional regional and sectoral MRIO aggregation and disaggregation, optional LCIA characterization | deterministic_asocc(…), deterministic_io_lca(…), uncertainty_io_lca(…) |\n", "| process_ar6 | harmonized dynamic climate change carrying capacity pathways | deterministic_ar6_cc(…), uncertainty_ar6_cc(…), dynamic aCC / ASR workflows |”
]
}, {
“cell_type”: “markdown”, “id”: “a578687c”, “metadata”: {}, “source”: [
“## Population and GDP PPP data: process_pop_gdp(…)”
]
}, {
“cell_type”: “markdown”, “id”: “b47a8c27”, “metadata”: {}, “source”: [
“### Description”
]
}, {
“cell_type”: “markdown”, “id”: “72e7770d”, “metadata”: {}, “source”: [
“#### What the function does and what later functions reuse from itn”
]
}, {
“cell_type”: “markdown”, “id”: “ec4ea6fe”, “metadata”: {}, “source”: [
“process_pop_gdp(…) harmonizes the raw historical and SSP population / GDP inputs into then”, “processed tables later reused by allocation and projection workflows whenever the selectedn”, “allocation methods depend on population, GDP, or GDP per capita drivers.n”, “n”, “Some World Bank and SSP entities are aggregated under their "parent country" so that they are treatedn”, “consistently within their corresponding EXIOBASE/OECD "parent country", rather than as part ofn”, “Rest of the World (RoW) regions.n”, “n”, “This adjustment ensures coherence between World Bank/SSP datasets and EXIOBASE/OECD coverage,n”, “following the list of countries within EXIOBASE RoW regions described by Bjelle et al. (2020).n”, “Without this aggregation, several countries would incorrectly appear as belonging to RoW, although theyn”, “are already accounted for within their parent country.n”, “n”, “The "parent child" relationships used for this aggregation are defined in the matching files throughn”, “the columns `agg_parent` and `parent_iso3_code`.n”, “n”, “Referencen”, “n”, “- Bjelle, E. L., Tobben, J., Stadler, K., Kastner, T., Theurl, M. C., Erb, K. H., Olsen, K. S.,n”, “ Wiebe, K. S., & Wood, R. (2020). Adding country resolution to EXIOBASE: Impacts on land usen”, “ embodied in trade. Journal of Economic Structures, 9(1), 1-25.”
]
}, {
“cell_type”: “markdown”, “id”: “414b8a99”, “metadata”: {}, “source”: [
“##### Historical data (World Bank)n”
]
}, {
“cell_type”: “markdown”, “id”: “bd1fa122”, “metadata”: {}, “source”: [
“For World Bank data, the relevant "parent country" matching files are wb_exiobase_matching.csvn”, “and wb_oecd_matching.csv.n”, “n”, “Missing data in the World Bank database are completed via log linear regression using all availablen”, “years (logs are produced to report it).n”, “n”, “In the World Bank database, Taiwan (TWN) is included within China (CHN) while reported separately in SSP scenarios. Therefore, to ensure consistency across datasets, Taiwan is added via the International Monetary Fund [World Economic Outlook database](https://www.imf.org/external/datamapper/profile/TWN), and removed from China (CHN) in the World Bank database.n”, “n”, “Unit harmonization (GDP PPP base year rebasing): World Bank GDP series are retrieved as GDP, PPPn”, “constant 2021 international dollars. To ensure unit consistency with SSP projections expressed inn”, “constant 2017 international $, all World Bank GDP values are rebased from 2021 to 2017 internationaln”, “dollars by applying a single scalar conversion factor derived from the United States GDP deflatorn”, “(World Bank indicator NY.GDP.DEFL.KD.ZG) compounded over 2018 to 2021.”
]
}, {
“cell_type”: “markdown”, “id”: “69ec14b7”, “metadata”: {}, “source”: [
“##### Prospective data (SSP)”
]
}, {
“cell_type”: “markdown”, “id”: “1a00fa9e”, “metadata”: {}, “source”: [
“For SSP scenarios, the relevant "parent country" matching files are ssp_exiobase_matching.csvn”, “and ssp_oecd_matching.csv.n”, “n”, “As SSP data are provided at five year intervals, intermediate years are estimated through linearn”, “interpolation.”
]
}, {
“cell_type”: “markdown”, “id”: “64781899”, “metadata”: {}, “source”: [
“#### Public argument checklistn”, “The table lists all arguments; the same definitions are available in the function docstring.n”, “n”, “<div class="pyaesa-argument-legend">n”, “<div class="pyaesa-default-block" style="color:#087f5b"><strong>Green items = default if omitted.</strong></div>n”, “</div>n”, “n”, “Do not write green items when the default is intended.n”, “n”, “<details open>n”, “<summary><code>process_pop_gdp(…)</code> arguments</summary>n”, “n”, “<table>n”, “<thead><tr><th>Argument</th><th>Description</th></tr></thead>n”, “<tbody>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>past_years</code></td><td>If <code>True</code>, build the historical (World Bank + IMF)<br> processed output. <strong>Default</strong> <code>True</code> includes the historical output.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>future_years</code></td><td>If <code>True</code>, build the SSP processed output.<br> <strong>Default</strong> <code>True</code> includes the prospective output.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>refresh</code></td><td>If <code>True</code>, clear and recompute only the selected processed population and GDP tables under <code>data_processed/pop_gdp</code>. <code>past_years=True</code> refreshes <code>wb_processed.csv</code>, its metadata, and the World Bank fill log. <code>future_years=True</code> refreshes <code>ssp_processed.csv</code> and its metadata. Raw downloads and project outputs are not refreshed. <strong>Defaults to</strong> <code>False</code>.</td></tr>n”, “</tbody>n”, “</table>n”, “n”, “</details>n”
]
}, {
“cell_type”: “markdown”, “id”: “58e32255”, “metadata”: {}, “source”: [
“### Running process_pop_gdp(…)”
]
}, {
“cell_type”: “code”, “execution_count”: null, “id”: “c4f04f0f”, “metadata”: {}, “outputs”: [], “source”: [
“# Process both historical and future population / GDP inputs.n”, “process_pop_gdp()”
]
}, {
“cell_type”: “markdown”, “id”: “1964f845”, “metadata”: {}, “source”: [
“## MRIO data: process_mrio(…)”
]
}, {
“cell_type”: “markdown”, “id”: “6590b61b”, “metadata”: {}, “source”: [
“### Description”
]
}, {
“cell_type”: “markdown”, “id”: “9e912cf3”, “metadata”: {}, “source”: [
“#### What the function does and what later functions reusen”
]
}, {
“cell_type”: “markdown”, “id”: “55082658”, “metadata”: {}, “source”: [
“n”, “process_mrio(…) parses the raw downloaded MRIO archives, computes AESA specific metrics andn”, “responsibility propagation matrices, optionally applies MRIO aggregation and disaggregation, and optionally performs LCIAn”, “characterization for EXIOBASE sources.n”, “n”, “The processed MRIO archives are used by:n”, “n”, “- deterministic_asocc(…) reuses processed MRIO outputs for allocated sharesn”, “- deterministic_io_lca(…) and uncertainty_io_lca(…) reuse processed MRIO outputs for IO-LCAn”, “ computation and later ASR LCA workflowsn”, “- deterministic and uncertainty aCC / ASR workflows depend on those same upstream outputs whenevern”, “ they reuse allocation and/or IO-LCA results.n”, “n”
]
}, {
“cell_type”: “markdown”, “id”: “acae37d3”, “metadata”: {}, “source”: [
“#### Methodn”
]
}, {
“cell_type”: “markdown”, “id”: “fabe0287”, “metadata”: {}, “source”: [
“##### MRIO parsing and AESA enacting metric processingn”
]
}, {
“cell_type”: “markdown”, “id”: “fcc4d248”, “metadata”: {}, “source”: [
“MRIO archives are parsed with the Python library PyMRIO (Stadler, 2021).n”, “n”, “The baseline processing option computes UNCASExt metrics (see Appendix A in de Bantel et al., 2026)n”, “later used by allocation:n”, “n”, “- utility enacting metrics: final demand (FD) and gross value added (GVA)n”, “- utility propagation matrices: x_to_rc, kappa, and omega_regn”, “- EXIOBASE LCIA enacting metrics when lcia_method is requested: consumption based (CBA) andn”, “ production based (PBA) accountingn”, “n”, “Before enacting metric computation, clipped non negativity rules are applied to:n”, “n”, “- FD (Y after summing across final demand categories and producing regions)n”, “- GVA (factor_inputs.F after summing across value added categories)n”, “n”, “Negative totals are clipped to zero, and clipping diagnostics are written undern”, “data_processed/logs/mrio_logs/.n”, “n”, “Referencen”, “n”, “- Stadler, K. (2021). Pymrio - A Python Based Multi Regional Input Output Analysis Toolbox. Journal of Open Research Software, 9(1). <https://doi.org/10.5334/jors.251>n”, “n”
]
}, {
“cell_type”: “markdown”, “id”: “7399e2e0”, “metadata”: {}, “source”: [
“##### Optional persistence outputsn”
]
}, {
“cell_type”: “markdown”, “id”: “f0c1fa78”, “metadata”: {}, “source”: [
“n”, “The following processing options are optional and default to False in process_mrio(…). They are notn”, “required by the allocation workflow and should usually remain disabled to reduce on disk output sizen”, “and processing time.n”, “n”, “- keep_intermediate_uncasext=Truen”, “ - needed only by deterministic_io_lca(…, upstream_analysis=True) to compute diagnostic upstreamn”, “ supply chain decomposition of impact sourcesn”, “ - keeps UNCASExt post clip core matrices at the year root (A, G, L, Z)n”, “ - keeps characterized LCIA extension matrices used by UNCASExt LCIA computations (S, M) undern”, “ extensions/<method>/n”, “ - increases one year processed MRIO storage by about +1.9 GB for EXIOBASE 3.10.2 ixin”, “ (about 9.4x total), +2.9 GB for EXIOBASE 3.10.2 pxp (about 11.3x total), andn”, “ +500 MB for OECD ICIO v2025 (about 3.4x total)n”, “- pymrio_calc_all=True (never used by downstream <span class="pyaesa-brand-py" style="color:#366e9c"><strong>py</strong></span><span class="pyaesa-brand-aesa" style="color:#c83737"><strong>aesa</strong></span> public functions)n”, “ - computes and stores the full PyMRIO calc_all payload under preclip/n”, “ - stores preclip core matrices and LCIA related matrices when LCIA method(s) are requestedn”, “n”, “When both are enabled, both are written in addition to the baseline UNCASExt enacting metrics andn”, “propagation matrices. Enabling either processing option increases I/O, and enabling pymrio_calc_all=True alson”, “increases compute time substantially.n”, “n”
]
}, {
“cell_type”: “markdown”, “id”: “101ce34d”, “metadata”: {}, “source”: [
“##### Optional MRIO aggregation and disaggregation (regions / sectors)n”
]
}, {
“cell_type”: “markdown”, “id”: “c78a83e8”, “metadata”: {}, “source”: [
“n”, “Depending on the study objective, users may need to reclassify native regions and/or sectors. A mapping can keep native labels, aggregate several native labels into one target label, or disaggregate one native label into several target labels with weights.n”, “n”, “The same instructions are reproduced in README_aggregation.txt in the activen”, “data_raw/mrio/<source>/aggregation folder.n”, “n”, “Workflow:n”, “n”, “1. Copy the appropriate aggregation template from the MRIO aggregation foldern”, “ data_raw/mrio/<source>/aggregation in the workspace.n”, “n”, “ - Sector templates:n”, “ - OECD: data_raw/mrio/oecd_v2025/aggregation/agg_sec_template.csvn”, “ - EXIOBASE ixi: data_raw/mrio/exiobase_3/aggregation/ixi/agg_sec_template.csvn”, “ - EXIOBASE pxp: data_raw/mrio/exiobase_3/aggregation/pxp/agg_sec_template.csvn”, “n”, “ N.B.: A detailed description of sectors provided by EXIOBASE is reproduced:n”, “ data_raw/mrio/exiobase_3/sector_classification.xlsxn”, “n”, “ - Region templates:n”, “ - OECD: data_raw/mrio/oecd_v2025/aggregation/agg_reg_template.csvn”, “ - EXIOBASE: data_raw/mrio/exiobase_3/aggregation/agg_reg_template.csvn”, “n”, “2. Save the copied file as agg_reg_<name>.csv and/or agg_sec_<name>.csv.n”, “n”, “3. Edit the aggregated_mrio column.n”, “ - No blank values are allowed.n”, “ - Each row maps one original region or sector label to one target label in aggregated_mrio.n”, “ - For aggregation, several original labels can share the same target label.n”, “ - For disaggregation, repeat the same original label on several rows, assign each row a differentn”, “ target label, and provide a weight column whose weights sum to 1 for that original label.n”, “ - If a label should stay unchanged, repeat its original name in aggregated_mrio.n”, “n”, “4. Run process_mrio(…) with MRIO aggregation and disaggregation enabled:n”, “n”, “
`python\n", "agg_reg = True # for regional MRIO aggregation and disaggregation\n", "agg_sec = True # for sector MRIO aggregation and disaggregation\n", "agg_version = \"<name>\"\n", "`n”, “n”, “If both region and sector mappings are used, both mapping CSVs should share the same <name>. Whenn”, “loading processed MRIOs in that custom classification later, use agg_version="<name>" consistently.n”, “n”, “—n”, “n”, “Packaged aggregation examples shipped with the packagen”, “n”, “The MRIO aggregation folders include ready to use region and sector aggregation examples. Inspect each CSV in data_raw/mrio/<source>/aggregation/ before using it so the selected agg_version and output aggregated_mrio labels are clear.n”, “n”, “Region aggregation examplesn”, “n”, “`agg_reg_eu27`n”, “n”, “Aggregates all EU member states into a single region EU27.n”, “All other regions remain unchanged.n”, “n”, “It can be called in processing via:n”, “n”, “`python\n", "agg_reg = True\n", "agg_version = \"eu27\"\n", "`n”, “n”, “`agg_reg_world`n”, “n”, “Aggregates all regions into a single region World.n”, “n”, “It can be called in processing via:n”, “n”, “`python\n", "agg_reg = True\n", "agg_version = \"world\"\n", "`n”, “n”, “EXIOBASE ixi sector aggregation examplesn”, “n”, “`agg_sec_elec`n”, “n”, “Aggregates EXIOBASE ixi electricity sectors together.n”, “n”, “`agg_sec_oecd_d`n”, “n”, “Aggregates EXIOBASE ixi electricity, gas, and water sectors to match OECD ICIO sector D resolution.n”, “n”, “LCIA uncertainty CoV companions for aggregated EXIOBASE regionsn”, “n”, “For EXIOBASE LCIA uncertainty with the packaged agg_reg regional mappings, matching reg_cbca_covs_agg_eu27.csv and reg_cbca_covs_agg_world.csv files are shipped in data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/. Follow README_agg_reg_and_group_indices_lcia_covs.txt in the same folder when writing a custom MRIO agg_reg or group_indices CoV file.n”]
}, {
“cell_type”: “markdown”, “id”: “6c726258”, “metadata”: {}, “source”: [
“##### Optional LCIA characterizationn”
]
}, {
“cell_type”: “markdown”, “id”: “dee44a61”, “metadata”: {}, “source”: [
“n”, “lcia_method accepts one method name or a list of method names, for examplen”, “lcia_method=["pb_lcia", "gwp100_lcia"]. If no lcia_method is provided, no LCIA characterizationn”, “is computed.n”, “n”, “Additional LCIA methods can be considered by the package. See the tutorial section below.”
]
}, {
“cell_type”: “markdown”, “id”: “f970b2a8”, “metadata”: {}, “source”: [
“###### pb_lcian”
]
}, {
“cell_type”: “markdown”, “id”: “86e1b44f”, “metadata”: {}, “source”: [
“The Planetary Boundary life cycle impact assessment method (PB-LCIA) was introduced by Ryberg et al.n”, “(2018). The package characterization matrices combine that method family with updates from Yang &n”, “Paulillo (2025, 2026) and the BI FD implementation from Galan Martin et al. (2021).n”, “n”, “Modified compared to the cited sourcesn”, “n”, “- For the Biosphere Integrity planetary boundary, the Functional Diversity control variable via then”, “ Biodiversity Intactness Index is selected (BI FD). BI FD implementation follows Galan Martin etn”, “ al. (2021). This control variable is also available for process based LCA in the ASR route.n”, “n”, “N.B.n”, “n”, “- In this package, the BI FD control variable is divided into BI FD GHG and BI FD LAND ton”, “ distinguish climate and land use related components. This separation is necessary to ensure thatn”, “ historical responsibility is calculated consistently for each driver. For climate change,n”, “ cumulative GHG emissions over time must be considered. In contrast, the land use indicatorn”, “ measures annual area occupied, not newly converted area, meaning that the same land appears everyn”, “ year if it remains in use. Therefore, summing land occupation values over multiple years wouldn”, “ result in double counting the same area. In the final results, both are then summed back togethern”, “ to form a single BI FD control variable.n”, “- For BI FD GHG, the PB-LCIA characterization matrix proposed in this package uses an updated GHGn”, “ list and characterization factors aligned with EF 3.1, as proposed by Yang & Paulillo (2025,n”, “ 2026). The added greenhouse gas stressors are documented in the packaged characterization matrix.n”, “- For BI FD LAND, cropland stressors are mapped to the former Occupation, annual crop stressor.n”, “ Infrastructure land is represented through artificial surfaces for the Occupation, urbann”, “ stressor.n”, “n”, “Referencesn”, “n”, “- Yang, Q., & Paulillo, A. (2026). Quantifying environmental impacts on planetary boundaries: A refined and validated impact assessment method. Environmental Impact Assessment Review, 119, 108355. https://doi.org/10.1016/j.eiar.2026.108355n”, “n”, “- Yang, Q., & Paulillo, A. (2025). Advancing Planetary Boundaries Allocation: Systematic Comparison of Sharing Principles for National Level Absolute Environmental Sustainability Assessments. Procedia CIRP, 135, 875-880. https://doi.org/10.1016/j.procir.2024.12.087n”, “n”, “- Vazquez, D., Galan Martin, A., Tulus, V., & Guillen Gosalbez, G. (2023). Level of decoupling between economic growth and environmental pressure on Earth system processes. Sustainable Production and Consumption, 43, 217-229. https://doi.org/10.1016/j.spc.2023.11.001n”, “n”, “- Galan Martin, A., Tulus, V., Diaz, I., Pozo, C., Perez Ramirez, J., & Guillen Gosalbez, G. (2021). Sustainability footprints of a renewable carbon transition for the petrochemical sector within planetary boundaries. One Earth, 4(4), 565-583. https://doi.org/10.1016/j.oneear.2021.04.001”
]
}, {
“cell_type”: “markdown”, “id”: “834dd7bb”, “metadata”: {}, “source”: [
“###### gwp100_lcia”
]
}, {
“cell_type”: “markdown”, “id”: “31ac6906”, “metadata”: {}, “source”: [
“This LCIA method characterizes greenhouse gas stressors with factors aligned with EF 3.1, followingn”, “Yang & Paulillo (2025, 2026).n”, “n”, “Referencesn”, “n”, “- Yang, Q., & Paulillo, A. (2026). Quantifying environmental impacts on planetary boundaries: A refined and validated impact assessment method. Environmental Impact Assessment Review, 119, 108355. https://doi.org/10.1016/j.eiar.2026.108355n”, “n”, “- Yang, Q., & Paulillo, A. (2025). Advancing Planetary Boundaries Allocation: Systematic Comparison of Sharing Principles for National Level Absolute Environmental Sustainability Assessments. Procedia CIRP, 135, 875-880. https://doi.org/10.1016/j.procir.2024.12.087”
]
}, {
“cell_type”: “markdown”, “id”: “999989d9”, “metadata”: {}, “source”: [
“###### Adding additional LCIA methodsn”
]
}, {
“cell_type”: “markdown”, “id”: “27d70639”, “metadata”: {}, “source”: [
“The instructions for adding custom EXIOBASE LCIA characterization matrices are reproduced inn”, “data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/README_add_custom_lcia_characterization_matrices.txt.n”, “n”, “Proposition of new publicly available LCIA methodsn”, “n”, “Users are encouraged to propose additional publicly available LCIA methods via a pull request son”, “they can be integrated into the package list of supported lcia_method and made available to alln”, “users.n”, “n”, “Tutorial: adding new LCIA methods (for personal use and/or to prepare a public release)n”, “n”, “1. Characterization matrix used directly for EXIOBASE characterizationn”, “n”, “- These instructions are reproduced inn”, “ data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/README_add_custom_lcia_characterization_matrices.txt.n”, “- Add the characterization matrix asn”, “ data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/<method>.csvn”, “- Two characterization template families are accepted:n”, “ - standard template: name_lcia_template.csvn”, “ - planetary boundary template: name_lcia_planetary_boundary_template.csvn”, “- The method name must match the filename stem because the package resolves the characterizationn”, “ file as data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/<method>.csvn”, “- This is the file used directly when lcia_method="<method>" is requested in process_mrio(…),n”, “ deterministic_io_lca(…), or deterministic_asocc(…)n”, “- Direct characterization uses the impact rows, not impact_parent, for the characterizationn”, “ algebra itselfn”, “- Even so, if the method may later be used with historical responsibility allocation method,n”, “ structure the characterization matrix from the beginning with the final parent category inn”, “ impact_parent and the specific split sub impact in impactn”, “ - when no split is needed, write the same label in both columnsn”, “ - this keeps the characterization matrix aligned with the later <method>_rps.csv mapping andn”, “ with parent level impact unit trackingn”, “- Use the standard template when a generic impact_full_name label is sufficientn”, “- Use the planetary boundary template only when the file should preserve explicit Planetaryn”, “ boundary / Control variable vocabularyn”, “ - for concrete patterns, see name_lcia_template.csv, name_lcia_planetary_boundary_template.csv, andn”, “ the PB-LCIA note above regarding BI FDn”, “- All the following EXIOBASE extension families can be characterized: land, employment, material,n”, “ air emissions, water, factor inputs, nutrientsn”, “n”, “2. Responsibility period table used only by historical responsibility allocation method (PR-HR atn”, “country level)n”, “n”, “- These instructions are reproduced inn”, “ data_raw/mrio/exiobase_3/lcia/responsibility_periods/README_add_custom_lcia_responsibility_periods.txt.n”, “- Add the responsibility period table asn”, “ data_raw/mrio/exiobase_3/lcia/responsibility_periods/<method>_rps.csvn”, “- Two responsibility period template families are accepted:n”, “ - standard template: name_lcia_rps_template.csvn”, “ - planetary boundary template: name_lcia_rps_planetary_boundary_template.csvn”, “- This table is needed only for applying the historical responsibility allocation methodn”, “- The package resolves it as data_raw/mrio/exiobase_3/lcia/responsibility_periods/<method>_rps.csvn”, “- Reuse the same impact / impact_parent structure as in the characterization matrixn”, “- This is where the specific responsibility period is actually defined for each impact, whilen”, “ later aggregation back to the parent category follows impact_parentn”, “- Use the standard template when a generic impact_full_name label is sufficientn”, “- Use the planetary boundary template only when the file should preserve explicit Planetaryn”, “ boundary / Control variable vocabulary and detailed duration or citation notesn”, “ - for concrete patterns, see name_lcia_template.csv, name_lcia_planetary_boundary_template.csv,n”, “ name_lcia_rps_template.csv, name_lcia_rps_planetary_boundary_template.csv, and the PB-LCIA noten”, “ above regarding BI FDn”, “n”, “3. Static carrying capacity file used by denominator workflowsn”, “n”, “- These instructions are reproduced inn”, “ data_raw/carrying_capacities/README_add_custom_carrying_capacities.txt.n”, “- If the new LCIA method should also support package static carrying capacity workflows, addn”, “ pyaesa/workspace_initialisation/prerequisites/carrying_capacities/<method>_cc_steady_state.csvn”, “- Two template families are accepted:n”, “ - standard template: name_lcia_cc_steady_state_template.csvn”, “ - planetary boundary template: name_lcia_cc_steady_state_planetary_boundary_template.csvn”, “- Use the standard template when the file should expose the generic label columnn”, “ impact_full_namen”, “- Use the planetary boundary template only when the file should preserve explicit Planetaryn”, “ boundary / Control variable vocabularyn”, “- This template choice does not change the computations. The package normalizes both schemas ton”, “ the same internal contract for validation, figure metadata, aCC, ASR, and external file checks.n”, “ The difference is only the accepted column vocabulary and the resulting display labelsn”, “- The standard schema requires impact_full_name, impact, impact_unit, min_cc, and max_ccn”, “- The planetary boundary schema requires Planetary boundary, Control variable, impact,n”, “ impact_unit, min_cc, and max_ccn”, “- Most new LCIA methods can be added by files only once the characterization matrix, the optionaln”, “ responsibility period table, and the optional static carrying capacity CSV existn”, “- Dynamic AR6 carrying capacity workflows can use any LCIA method whose static carryingn”, “ capacity CSV contains an impact row equal to GWP_100; other impact categories remainn”, “ steady state.n”
]
}, {
“cell_type”: “markdown”, “id”: “35e183e0”, “metadata”: {}, “source”: [
“#### Available MRIO sourcesn”
]
}, {
“cell_type”: “markdown”, “id”: “a448de7f”, “metadata”: {}, “source”: [
“| Source key | Historical temporal coverage | Notes |\n", "| — | — | — |\n", "| exiobase_3102_ixi | 1995-2024 | EE MRIO: EXIOBASE ixi option; 2023 and 2024 are nowcasted |\n", "| exiobase_3102_pxp | 1995-2024 | EE MRIO: EXIOBASE pxp option; 2023 and 2024 are nowcasted |\n", "| oecd_v2025 | 1995-2022 | MRIO: OECD ICIO ixi |\n", "\n", "*EXIOBASE 3.9.6 is also available as `exiobase_396_ixi` and `exiobase_396_pxp` for 1995-2022.*\n", "\n", "Approximate `process_mrio(...)` first run storage and runtime:\n", "\n", "| Source | One year | All years |\n", "| — | — | — |\n", "| exiobase_3102_ixi | 230 MB, 1 min | 6.7 GB and 25 min for 1995-2024 |\n", "| exiobase_3102_pxp | 280 MB, 1 min | 8.2 GB and 36 min for 1995-2024 |\n", "| oecd_v2025 | 210 MB, <1 min | 5.8 GB and 5 min for 1995-2022 |n”, “n”, “Measurements use original classification, `keep_intermediate_uncasext=False`, and `pymrio_calc_all=False`. EXIOBASE measurements use `lcia_method="pb_lcia"`. They were taken on Windows 11 with Python 3.14, an 11th Gen Intel Core i7 1165G7 CPU, 32 GB RAM.n”
]
}, {
“cell_type”: “markdown”, “id”: “916252e0”, “metadata”: {}, “source”: [
“#### Public argument checklistn”, “The table lists all arguments; the same definitions are available in the function docstring.n”, “n”, “<div class="pyaesa-argument-legend">n”, “<div class="pyaesa-default-block" style="color:#087f5b"><strong>Green items = default if omitted.</strong></div>n”, “<div class="pyaesa-optional-block" style="color:#c45f00"><strong>Orange items = optional feature skipped if omitted.</strong></div>n”, “</div>n”, “n”, “Do not write green or orange items when that behavior is intended.n”, “n”, “<details open>n”, “<summary><code>process_mrio(…)</code> arguments</summary>n”, “n”, “<table>n”, “<thead><tr><th>Argument</th><th>Description</th></tr></thead>n”, “<tbody>n”, “<tr><td style="vertical-align:top; white-space:nowrap;"><code>source</code></td><td>MRIO source key (<code>"exiobase_396_ixi"</code>,<br> <code>"exiobase_396_pxp"</code>, <code>"exiobase_3102_ixi"</code>,<br> <code>"exiobase_3102_pxp"</code>, or <code>"oecd_v2025"</code>).</td></tr>n”, “<tr><td style="vertical-align:top; white-space:nowrap;"><code>years</code></td><td>Studied years. Accepts a single year, list, or range. If<br> <strong>omitted</strong>, all available MRIO<br> years for the selected source and <code>agg_version</code> are used.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>refresh</code></td><td>If <code>True</code>, clear and recompute only the requested processed MRIO year folders inside the resolved source and classification output scope. The output scope is <code>data_processed/mrio/<source>/<version_tag></code>, where <code>version_tag</code> is <code>original_class</code> for native source classification or <code>custom_class_<agg_version></code> 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. <strong>Defaults to</strong> <code>False</code>.</td></tr>n”, “<tr class="pyaesa-optional-row" style="color:#c45f00;"><td style="vertical-align:top; white-space:nowrap;"><code>lcia_method</code></td><td>LCIA method(s) used to characterize MRIO<br> environmental stressors into the selected method(s) impact<br> categories (for example <code>"pb_lcia"</code> or<br> <code>["pb_lcia", "gwp100_lcia"]</code>). <code>None</code> skips LCIA<br> characterization. <strong>Defaults to</strong> <code>None</code>. <span class="pyaesa-brand-py" style="color:#366e9c"><strong>py</strong></span><span class="pyaesa-brand-aesa" style="color:#c83737"><strong>aesa</strong></span> currently supports<br> LCIA characterization only for EXIOBASE sources. To add a custom<br> LCIA method, follow<br> <code>README_add_custom_lcia_characterization_matrices.txt</code> in<br> <code>data_raw/mrio/exiobase_3/lcia/characterization_factors_matrices/</code><br> and pass the custom method file stem here.</td></tr>n”, “<tr class="pyaesa-optional-row" style="color:#c45f00;"><td style="vertical-align:top; white-space:nowrap;"><code>agg_reg</code></td><td>If <code>True</code>, reclassify MRIO regions with the <code>agg_reg_<agg_version>.csv</code> 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 <code>weight</code> column is provided.<br> <strong>Default</strong> <code>False</code> keeps native source regions.</td></tr>n”, “<tr class="pyaesa-optional-row" style="color:#c45f00;"><td style="vertical-align:top; white-space:nowrap;"><code>agg_sec</code></td><td>If <code>True</code>, reclassify MRIO sectors with the <code>agg_sec_<agg_version>.csv</code> 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 <code>weight</code> column is provided.<br> <strong>Default</strong> <code>False</code> keeps native source sectors.</td></tr>n”, “<tr class="pyaesa-optional-row" style="color:#c45f00;"><td style="vertical-align:top; white-space:nowrap;"><code>agg_version</code></td><td>Name token used to resolve the matching <code>agg_reg_<agg_version>.csv</code> and/or <code>agg_sec_<agg_version>.csv</code> MRIO aggregation and disaggregation mapping files in <code>data_raw/mrio/<source>/aggregation</code>. Required when <code>agg_reg</code> or <code>agg_sec</code> is True.<br> <strong>Defaults to</strong> 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 <code>weight</code> column, weights must sum to <code>1</code> for each original label. If custom regional classification outputs are later<br> used with LCIA uncertainty, also follow<br> <code>README_agg_reg_and_group_indices_lcia_covs.txt</code> in<br> <code>data_raw/mrio/exiobase_3/lcia/carbon_accounts_covs/</code>.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>keep_intermediate_uncasext</code></td><td>If <code>True</code>, keep intermediate UNCASExt<br> matrices. These outputs are not used by downstream public<br> functions, except by <code>deterministic_io_lca(…)</code> when upstream<br> supply chain analysis is requested with <code>upstream_analysis=True</code>.<br> Written files are the post clip core matrices (<code>A</code>, <code>G</code>, <code>L</code>,<br> <code>Z</code>, <code>unit</code>), plus characterized LCIA <code>extensions/</code> payloads.<br> This increases one year processed MRIO storage by about +1.9 GB for<br> EXIOBASE 3.10.2 ixi (about 9.4x total), +2.9 GB for EXIOBASE<br> 3.10.2 pxp (about 11.3x total), and +500 MB for OECD ICIO v2025<br> (about 3.4x total). <strong>Default</strong> <code>False</code> writes only the<br> public processed outputs.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>pymrio_calc_all</code></td><td>If <code>True</code>, write PyMRIO function <code>calc_all</code><br> outputs. These outputs are not used by downstream public<br> functions. The written payload is PyMRIO <code>calc_all</code> on original<br> matrices without clipping negative values, stored under<br> <code>preclip/</code> and <code>preclip/extensions/</code>. <strong>Default</strong> <code>False</code> skips<br> this diagnostic payload.</td></tr>n”, “</tbody>n”, “</table>n”, “n”, “</details>n”
]
}, {
“cell_type”: “markdown”, “id”: “ff8757ca”, “metadata”: {}, “source”: [
“### Running process_mrio(…)”
]
}, {
“cell_type”: “markdown”, “id”: “92cd4b70”, “metadata”: {}, “source”: [
“#### Example 1 - EXIOBASE 3.10.2 IXI with LCIA characterization”
]
}, {
“cell_type”: “code”, “execution_count”: null, “id”: “f5fb83f6”, “metadata”: {}, “outputs”: [], “source”: [
“process_mrio(n”, “ source="exiobase_3102_ixi",n”, “ lcia_method=["pb_lcia", "gwp100_lcia"],n”, “)”
]
}, {
“cell_type”: “markdown”, “id”: “f815364d”, “metadata”: {}, “source”: [
“#### Example 2 - EXIOBASE 3.10.2 PXP with LCIA characterization”
]
}, {
“cell_type”: “markdown”, “id”: “8ab4d709”, “metadata”: {}, “source”: [
“Uncomment and run the next cell only if you need to process EXIOBASE in pxp version.”
]
}, {
“cell_type”: “code”, “execution_count”: null, “id”: “84e49fe1”, “metadata”: {}, “outputs”: [], “source”: [
“# process_mrio(n”, “# source="exiobase_3102_pxp",n”, “# lcia_method=["pb_lcia", "gwp100_lcia"],n”, “# )”
]
}, {
“cell_type”: “markdown”, “id”: “385953a1”, “metadata”: {}, “source”: [
“#### Example 3 - aggregated EXIOBASE 3.10.2 IXI with aggregation of EU27 countries”
]
}, {
“cell_type”: “code”, “execution_count”: null, “id”: “68973309”, “metadata”: {}, “outputs”: [], “source”: [
“process_mrio(n”, “ source="exiobase_3102_ixi",n”, “ lcia_method=["pb_lcia", "gwp100_lcia"],n”, “ agg_reg=True,n”, “ agg_version="eu27",n”, “)”
]
}, {
“cell_type”: “markdown”, “id”: “6ef7d2e9”, “metadata”: {}, “source”: [
“## Dynamic climate change carrying capacities via IPCC AR6 scenario data: process_ar6(…)n”
]
}, {
“cell_type”: “markdown”, “id”: “d1577e6c”, “metadata”: {}, “source”: [
“Use this section only when the study needs dynamic climate change carrying capacities. Staticn”, “carrying capacity workflows do not need AR6 processing.n”, “n”, “Downstream dynamic AR6 CC, aCC, and ASR functions create or reuse the matching process_ar6(…)n”, “scope automatically when they need it. Run process_ar6(…) directly only when you want to preparen”, “or inspect the broad retained pathway table, logs, budget summaries, and diagnostic figures beforen”, “calling a study endpoint function.n”, “n”, “download_ar6(…) must have run before this function can read raw AR6 inputs. “
]
}, {
“cell_type”: “markdown”, “id”: “f692d43f”, “metadata”: {}, “source”: [
“### Description”
]
}, {
“cell_type”: “markdown”, “id”: “0a8a6cc6”, “metadata”: {}, “source”: [
“#### What the function does and what later functions reuse”
]
}, {
“cell_type”: “markdown”, “id”: “c28da570”, “metadata”: {}, “source”: [
“process_ar6(…) processes the downloaded AR6 Scenario Explorer pathways to produce variables for both GHG (Kyoto gases) emissions and CO2 emissions. This includes net, gross, and gross_alt emissions (all including and excluding AFOLU emissions) for the requested AR6 climate categories and SSPs SSP1-SSP5. The default category selector is C1 to C4, the categories aligned with the 2015 Paris Agreement; C5 to C8 are available when explicitly requested:n”, “- Kyoto Gases emissions:n”, “ - Emissions(net)|Kyoto Gases, Emissions(net)|Kyoto Gases|WO AFOLUn”, “ - Emissions(gross)|Kyoto Gases, Emissions(gross)|Kyoto Gases|WO AFOLUn”, “ - Emissions(gross_alt)|Kyoto Gases, Emissions(gross_alt)|Kyoto Gases|WO AFOLUn”, “- CO2 emissions:n”, “ - Emissions(net)|CO2, Emissions(net)|CO2|WO AFOLUn”, “ - Emissions(gross)|CO2, Emissions(gross)|CO2|WO AFOLUn”, “ - Emissions(gross_alt)|CO2, Emissions(gross_alt)|CO2|WO AFOLUn”, “n”, “Carbon sequestration emissions variables are also produced as companion for the gross and gross_alt emissions:n”, “- Carbon sequestration:n”, “ - Carbon Sequestration|Subtotal_seqn”, “ - Carbon Sequestration|Totaln”, “n”, “Outputs are later reused by:n”, “n”, “- deterministic_ar6_cc(…)n”, “- uncertainty_ar6_cc(…)n”, “- dynamic deterministic_acc(…)n”, “- dynamic uncertainty_acc(…)n”, “- dynamic deterministic_asr(…)n”, “- dynamic uncertainty_asr(…)n”, “n”, “—n”, “n”, “The AR6 category filter is there to define dynamic climate change carrying capacity budgets alignedn”, “with the 2015 Paris Agreement with different underlying risk levels and overshoot profiles:n”, “n”, “- C1: limit warming to 1.5 degrees C (>50%) with no or limited overshootn”, “- C2: return warming to 1.5 degrees C (>50%) after a high overshootn”, “- C3: limit warming to 2 degrees C (>67%)n”, “- C4: limit warming to 2 degrees C (>50%)n”, “n”, “Categories C5 to C8 are also available in processed outputs when requested explicitly.n”, “n”, “At this processing stage the selected categories and all five SSP families are kept for the selectedn”, “study window. Later deterministic_ar6_cc(…) and uncertainty_ar6_cc(…) calls can then eithern”, “restrict the study to a subset of categories / SSP families or combine several selected categories /n”, “SSP families in the same study scope depending on the study objective.n”, “n”, “The requested years selector defines the study window that drives every later filtering andn”, “harmonization decision: retained variable-scenario combinations must cover the full requested windown”, “at both ends (years in between are interpolated when missing), and harmonization offsets pathwaysn”, “given historical emissions observed until the study start year vs. what originally considered byn”, “pathways.”
]
}, {
“cell_type”: “markdown”, “id”: “1d86d0ce”, “metadata”: {}, “source”: [
“#### Methodn”
]
}, {
“cell_type”: “markdown”, “id”: “c6d53c67”, “metadata”: {}, “source”: [
“A high-level graphical overview is provided below to summarize the different steps implemented in process_ar6(…) to define dynamic carrying capacities. Methodologicaln”, “details on AR6 scenario filtering, harmonization, and dynamic carrying capacity construction aren”, “provided inn”, “<a href="../../methodological_notes/methodological_note_steady_state_dynamic_cc.pdf">methodological_notes/methodological_note_steady_state_dynamic_cc.pdf</a>.”
]
}, {
“cell_type”: “markdown”, “id”: “2807c1e8”, “metadata”: {}, “source”: [
“<img src="https://raw.githubusercontent.com/AESAtoolkit/pyaesa/main/images/fig-dynamic-carrying-capacities-definition.svg" alt="Dynamic carrying capacities definition" width="620" style="max-width: 100%; height: auto;">n”
]
}, {
“cell_type”: “markdown”, “id”: “c96abd0b”, “metadata”: {}, “source”: [
“##### Harmonization and pathway constructionn”
]
}, {
“cell_type”: “markdown”, “id”: “bd8182ed”, “metadata”: {}, “source”: [
“For each AR6 category/SSP bucket, the function applies the same processing chain:n”, “n”, “ Raw filtering and yearly normalizationn”, “ - Rows are filtered from the downloaded public explorer for one Category / SSP bucketn”, “ and reshaped onto the package yearly grid 2000-2100.n”, “ - Only AR6-vetted model-scenarios are considered. n”, “ - Internal missing years are linearly interpolated (AR6 scenarios are provided at 5-year or 10-yearn”, “ intervals), but truncated starts and truncated ends are kept as missing values. The functionn”, “ therefore fills only inside existing reported spans; it does not extrapolate before the firstn”, “ reported year or after the last reported year.n”, “ - An additional filtering ensures that Emissions|CO2 can be reconstructed via all its subcontributions Emissions|CO2|… with a reconstruction error below 0.001% of cumulative emissions on the scenario time horizon.n”, “n”, “ AFOLU handling and variable constructionn”, “ - The raw explorer provides direct Emissions(net)|Kyoto Gases and Emissions(net)|CO2 totals, plus AFOLUn”, “ component rows.n”, “ - Emissions(net)|CO2|WO AFOLU is derived by subtracting Emissions(net)|CO2|AFOLU from total CO2.n”, “ - Emissions(net)|Kyoto Gases|AFOLU is rebuilt from the available AFOLU gas components in then”, “ explorer all converted to CO2-eq GWP100 :n”, “ Emissions(net)|CO2|AFOLU + Emissions|CH4|AFOLU + Emissions|N2O|AFOLU.n”, “ - Emissions(net)|Kyoto Gases|WO AFOLU is then derived by subtracting that reconstructed AFOLUn”, “ subtotal from total Kyoto Gases.n”, “ - If the required AFOLU component rows are incomplete for certain AR6 scenarios, the packagen”, “ keeps the directly reported total (Emissions(net)|CO2 or Emissions(net)|Kyoto Gases) and logs then”, “ derived …|WO AFOLU row as not produced.n”, “n”, “ Study window eligibilityn”, “ - After interpolation and AFOLU handling, a row is retained only if it has a finite value at bothn”, “ the study start year and the study end year.n”, “ - This is how the function enforces temporal comparability: pathways that start after then”, “ requested start year or stop before the requested end year are excluded.n”, “n”, “ Historical baseline and harmonizationn”, “ - When harmonization=True, the function aligns AR6 pathways to observed historical emissionsn”, “ between pathways starting years and requested study start year while preserving each scenarion”, “ cumulative emissions budget, following Gidden et al. (2018). Note that emissions infilling is n”, “ not performed here.n”, “ - Historical emissions are collected by download_ar6 from PRIMAP and Global Carbon Budget forn”, “ bunker CO2 additions (see output folder for reference citations .txt).n”, “n”, “ - harmonization_method currently supports only "offset". Under this method, the pathway isn”, “ anchored to the historical baseline at the harmonization year, the cumulative differencen”, “ between pathway and historical emissions over the harmonization window is computed, and thatn”, “ delta is redistributed as one uniform annual correction from the year after harmonization to an”, “ row specific horizon so the scenario cumulative budget is preserved.n”, “ - constant_offset is used when the pathway never becomes negative. The uniform annualn”, “ correction is applied from after the study start year through the last available pathwayn”, “ year.n”, “ - reduced_offset is used when the pathway reaches negative emissions. The uniform annualn”, “ correction is applied only up to the model net zero proxy year, defined as the yearn”, “ immediately before the first negative emissions year, rather than through the full remainingn”, “ pathway horizon.n”, “ - Following the UNCASExt framework (de Bantel et al., 2026), <span class="pyaesa-brand-py" style="color:#366e9c"><strong>py</strong></span><span class="pyaesa-brand-aesa" style="color:#c83737"><strong>aesa</strong></span> can further shorten the effectiven”, “ harmonization horizon when needed so the correction does not create an earlier negativen”, “ emissions year than in the original pathway.n”, “n”, “ Estimation of gross and gross_alt emissionsn”, “ - Harmonized net emissions are then used to estimate gross and gross_alt emissions for GHG and CO2 variables. This ensuresn”, “ that the dynamic carrying capacities is always positive, which is necessary to apply justice distributive theory with currentlyn”, “ available sharing principles.n”, “ - Based the AR6 data, carbon sequestrations are extracted for each model-scenarios and two variables are defined:n”, “ - Carbon Sequestration|Subtotal_seq, as the sum of all carbon sequestrations except carbon capture and storage (CCS).n”, “ This is motivated by the fact that CCS is a different form of sequestration as it acts at the source of emissions, whereasn”, “ other carbon sequestration variables in the AR6 remove carbon from the atmosphere.n”, “ - Carbon Sequestration|Total, as the sum of all carbon sequestration contributions, including CCS.n”, “ - Gross emissions are then computed by removing carbon sequestration from net emissions. This yields respectively gross_alt n”, “ and gross variables. A final check filters out model-scenarios for which gross_alt and gross emissions are not alwaysn”, “ positive.n”, “n”, “ Final tables writtenn”, “ - ORIGINAL_AR6 keeps the post interpolation, post AFOLU source table before harmonization.n”, “ - The final pathways sheet keeps either harmonized retained pathways or non harmonized retainedn”, “ pathways.n”, “ - The budget statistics sheet summarizes retained rows by AR6 category and by category/SSPn”, “ bucket.n”, “ - Harmonized runs also write a separate harmonization log workbook with row level correctionn”, “ diagnostics.n”, “n”, “Referencesn”, “n”, “- Gidden, M. J., Fujimori, S., van den Berg, M., Klein, D., Smith, S. J., van Vuuren, D. P., &n”, “ Riahi, K. (2018). A methodology and implementation of automated emissions harmonization for use inn”, “ Integrated Assessment Models. Environmental Modelling & Software, 105, 187-200.n”, “- de Bantel, E. I., Pirson, T., Puig-Samper, G., Hartmann, J. M., Bol, D., Bouillass, G., Yannou, B., Jankovic, M., & Hauschild, M. Z. UNCASExt – A Systematic Computational Framework for Uncertainty Propagation and Scope Consistency in Absolute Environmental Sustainability Assessments (AESA) [Manuscript submitted for publication].n”
]
}, {
“cell_type”: “markdown”, “id”: “7efa25df”, “metadata”: {}, “source”: [
“##### Optional diagnostic figuresn”
]
}, {
“cell_type”: “markdown”, “id”: “ef6a6b43”, “metadata”: {}, “source”: [
“When figures=True, figures are generated only for harmonized runs because the figure workflown”, “depends on the harmonized pathways, the historical baseline, and the harmonization log. The figuren”, “set is diagnostic only, not necessary for any subsequent workflow. It includes:n”, “n”, “- a historical baseline figure showing the PRIMAP + GCP series used for harmonizationn”, “- pathway comparison figures showing retained original pathways versus retained harmonizedn”, “ pathways by output variablen”, “- harmonization diagnostics showing yearly correction sizes, pathway versus historicaln”, “ cumulative ratios, and timing diagnostics around the harmonization horizon / net zero behaviorn”, “- budget figures showing pathway panels plus study period and remaining budget distributions byn”, “ category and by category/SSP bucketn”, “- a warming figure showing the distribution of the AR6 field Median warming in 2100n”, “ (MAGICCv7.5.3) for the retained model-scenario pairsn”, “- a sequestration figure showing the carbon sequestrations subcontributions for all model-scenariosn”, “ included, sorted by categories.n”, “- figure only Monte Carlo sampling comparison figures comparing two pathway rendering methods usedn”, “ in later uncertainty workflows: seeded simple random sampling (SRS), where each run samplesn”, “ retained pathways with equal probability, and package labelled Latin hypercube sampling (LHS),n”, “ where runs are stratified (first IAM model is rendered then within Scenario)n”, “ - The SRS versus LHS figure is only a diagnostic figure. The purpose is to show the effect ofn”, “ choosing one pathway rendering method or the other before selecting the Monte Carlo approach forn”, “ the study endpoint of interest (dynamic climate change AR6 carrying capacity, aCC, or ASR)”
]
}, {
“cell_type”: “markdown”, “id”: “56095120”, “metadata”: {}, “source”: [
“#### When this processing option is neededn”
]
}, {
“cell_type”: “markdown”, “id”: “b457d60e”, “metadata”: {}, “source”: [
“Use this processing option only if the study needs dynamic climate change carrying capacities.n”, “n”, “process_ar6(…) writes the broad retained pathway table for the selected study years. Latern”, “dynamic AR6 CC functions can then narrow the saved table by category, SSP family, or model-scenarion”, “subset, depending on the study objective. The processed workbook includes a README worksheet,n”, “and the model-scenario subset template is documented byn”, “data_processed/ar6/<processed_scope>/README_model_scenario_subset.txt.”
]
}, {
“cell_type”: “markdown”, “id”: “1dd04127”, “metadata”: {}, “source”: [
“#### Public argument checklistn”, “The table lists all arguments; the same definitions are available in the function docstring.n”, “n”, “<div class="pyaesa-argument-legend">n”, “<div class="pyaesa-default-block" style="color:#087f5b"><strong>Green items = default if omitted.</strong></div>n”, “</div>n”, “n”, “Do not write green items when the default is intended.n”, “n”, “<details open>n”, “<summary><code>process_ar6(…)</code> arguments</summary>n”, “n”, “<table>n”, “<thead><tr><th>Argument</th><th>Description</th></tr></thead>n”, “<tbody>n”, “<tr><td style="vertical-align:top; white-space:nowrap;"><code>years</code></td><td>Study year selector provided as a consecutive year<br> list or <code>range(start_year, end_year + 1)</code>. The resolved years<br> must contain at least two consecutive years with no gaps.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>figures</code></td><td>Whether to render figures.<br> <strong>Default is</strong> <code>True</code>.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>harmonization</code></td><td>Whether to harmonize retained AR6 pathways to the<br> historical baseline. <strong>Defaults to</strong> <code>True</code>. If <code>True</code>, write<br> <code>harmonized_ar6_public.xlsx</code> plus<br> the separate harmonization log workbook<br> <code>harmonized_ar6_public_log.xlsx</code>. If <code>False</code>, apply the same<br> required CO2 coverage and derived variable construction filters,<br> write <code>filtered_original_ar6_public.xlsx</code>, and <strong>omit</strong> the<br> harmonization log workbook. When required component inputs are<br> missing for a derived retained variable, the package omits that<br> derived row and records the omission in the AR6 row issue log. The<br> required CO2 coverage, CO2 reconstruction, sequestration, and gross<br> emissions filters are shared with the harmonized mode. Figure<br> generation is available for harmonized runs.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>harmonization_method</code></td><td>Harmonization method applied only when<br> <code>harmonization=True</code>. <strong>Defaults to</strong> <code>"offset"</code>. The only<br> supported value is currently <code>"offset"</code>.<br> Ignored when <code>harmonization=False</code>.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>category</code></td><td>AR6 category classification selector for global warming<br> trajectories. Accepts a string such as <code>"C3"</code> or a list such as<br> <code>["C1", "C2"]</code>. Valid values are <code>"C1"</code> through <code>"C8"</code>.<br> <strong>Defaults to</strong> <code>["C1", "C2", "C3", "C4"]</code>, the categories<br> aligned with the 2015 Paris Agreement.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>refresh</code></td><td>If <code>True</code>, clear and recompute only the resolved processed AR6 output scope for the requested study period, harmonization flag, and harmonization method. Raw downloads and downstream AR6 CC, aCC, or ASR outputs are not refreshed. <strong>Defaults to</strong> <code>False</code>.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>figure_format</code></td><td>Figure render settings mapping. <strong>Defaults to</strong><br> <code>{"format": "png", "dpi": 500}</code>.<br>  <br> Nested keys:<br>  <br> • <code>format</code>: Figure file format. Accepted values are <code>"png"</code>,<br> <code>"pdf"</code>, and <code>"svg"</code>.<br> • <code>dpi</code>: Positive integer figure resolution used for raster<br> outputs.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>figure_convergence_tol</code></td><td>Relative convergence tolerance used only by the<br> SRS/LHS figure sampling diagnostics when <code>figures=True</code>. The <strong>default<br> is</strong> <code>5e-2</code>, i.e. a <code>5%</code> maximum relative change between successive<br> checkpoint summaries for each monitored summary statistic. Figure<br> sampling is accepted only after <code>3</code> consecutive stable checkpoint<br> comparisons. Because the figure workflow evaluates those<br> comparisons every <code>10000</code> runs per bucket, the earliest accepted<br> convergence checkpoint is <code>40000</code> completed runs per bucket.</td></tr>n”, “<tr class="pyaesa-default-row" style="color:#087f5b;"><td style="vertical-align:top; white-space:nowrap;"><code>figure_convergence_max_runs</code></td><td>Maximum per bucket run count allowed for the<br> SRS/LHS figure sampling convergence loop when <code>figures=True</code> before<br> figure generation fails. <strong>Default</strong>: <code>20000000</code>.</td></tr>n”, “</tbody>n”, “</table>n”, “n”, “</details>n”
]
}, {
“cell_type”: “markdown”, “id”: “285839b9”, “metadata”: {}, “source”: [
“### Running process_ar6(…)n”
]
}, {
“cell_type”: “markdown”, “id”: “52c1c9be”, “metadata”: {}, “source”: [
“#### Example 1: default harmonization method (offset)n”, “n”, “Currently the only supported method is offset, so the argument can be omitted to use it by default.n”
]
}, {
“cell_type”: “code”, “execution_count”: null, “id”: “741e5b24”, “metadata”: {}, “outputs”: [], “source”: [
“process_ar6(n”, “ years=range(2019, 2061),n”, “)”
]
}, {
“cell_type”: “markdown”, “id”: “cell-07c7673ffe”, “metadata”: {}, “source”: [
“# What to do nextn”
]
}, {
“cell_type”: “markdown”, “id”: “cell-3f020a77db”, “metadata”: {}, “source”: [
“You have now been through the three prerequisites notebooks, congratulations!n”, “n”, “It is now time to dive into the next batch of tutorials to discover study objectives and functional units in <span class="pyaesa-brand-py" style="color:#366e9c"><strong>py</strong></span><span class="pyaesa-brand-aesa" style="color:#c83737"><strong>aesa</strong></span>: these are two central concepts.n”, “n”, “Start with [tutorials/study_objectives/0_study_objectives.md](../study_objectives/0_study_objectives.md).”
]
}
], “metadata”: {
- “kernelspec”: {
“display_name”: “env-pyaesa-test”, “language”: “python”, “name”: “python3”
}, “language_info”: {
- “codemirror_mode”: {
“name”: “ipython”, “version”: 3
}, “file_extension”: “.py”, “mimetype”: “text/x-python”, “name”: “python”, “nbconvert_exporter”: “python”, “pygments_lexer”: “ipython3”, “version”: “3.13.13”
}
}, “nbformat”: 4, “nbformat_minor”: 5
}