Workflow Reference

This reference maps the main pyaesa workflows from data preparation to AESA outputs. It identifies the data sources used by each phase, the prerequisite steps to run, the public functions that produce each output, the matching tutorials, and indicative runtime and storage requirements.

Data Sources By AESA Phase

AESA phase or route	Data source	Used for
Phase A IO-LCA	EXIOBASE 3.10.2 MRIO	pyaesa owned IO-LCA results and ASR numerators.
Phase B aSoCC allocation	EXIOBASE 3.10.2 or OECD ICIO v2025 MRIO	Allocation enacting metrics, final demand, production, value added, and environmental extensions after LCIA characterization when available.
Phase B aSoCC retrospective scope	World Bank population/GDP	Historical population and GDP allocation inputs.
Phase B aSoCC prospective scope	SSP population/GDP	Future population and GDP allocation inputs.
Phase B dynamic climate change CC	AR6 climate pathways	Dynamic climate change carrying capacity pathways.

EXIOBASE is supported for ixi and pxp source variants. The examples use EXIOBASE 3.10.2 but EXIOBASE 3.9.6 is also supported.

Data Source Licenses And Terms

The GPL 3.0 license applies to pyaesa source code only. Downloaded datasets remain governed by their original providers’ terms and conditions. For all data sources, cite the original provider following the recommended citation guide.

Data source	Used in pyaesa	Terms and conditions	Link
EXIOBASE 3	EXIOBASE 3.10.2 and 3.9.6 MRIO downloads for IO-LCA and allocation inputs.	Noncommercial use: allowed for academic use under the EXIOBASE license. Commercial use: requires a commercial license.	EXIOBASE terms and conditions and Zenodo EXIOBASE record
OECD ICIO v2025	OECD ICIO MRIO downloads for allocation inputs.	Noncommercial use: allowed under OECD data terms. Commercial use: allowed under OECD data terms.	OECD ICIO page and OECD terms and conditions
World Bank population/GDP	Historical population and GDP allocation inputs.	Noncommercial use: allowed under CC BY 4.0. Commercial use: allowed under CC BY 4.0.	World Bank terms and conditions
IIASA SSP population/GDP	Prospective population and GDP allocation inputs.	Noncommercial use: allowed under the IIASA Public License. Commercial use: allowed within the licensed rights; adapted material is limited to scientific research, science communication, or policy consultancy. Reproducing substantial database portions is prohibited.	IIASA SSP terms and conditions
IIASA AR6 climate pathways	Dynamic climate change carrying capacity pathways.	Noncommercial use: allowed under the AR6 Scenario Explorer Public License. Commercial use: allowed within the licensed rights. Reproducing substantial database portions is prohibited.	IIASA AR6 license terms and conditions

Current EXIOBASE LCIA coverage is gwp100_lcia and pb_lcia. EF3.1 is available for non LCIA based allocation routes, but it is not currently available for pyaesa owned IO-LCA or LCIA based allocation methods. The process data tutorial explains the detailed process for adding LCIA methods with EXIOBASE characterization matrices and matching carrying capacity thresholds, either for private project use or for public package submission.

Core Prerequisites

Run set_workspace(...) once at the beginning of each Python session.

Run the download and processing functions needed before the selected study endpoint: MRIO processing for aSoCC and pyaesa owned IO-LCA, and population/GDP processing for allocation methods that use those inputs. Once run, they are kept on disk and can be reused across studies. For dynamic AR6 CC and downstream routes that use it, download AR6 raw inputs; the matching processed AR6 scope can be created by the downstream dynamic route when it is missing so it does not need to be run separately.

Function	What it computes or prepares and writes	Disk space	Runtime
set_workspace()	Creates the workspace, output root, and packaged prerequisite files.	2 MB	<1 min
download_mrio()	Downloads raw MRIO files for the selected source and years.	See MRIO tables	See MRIO tables
download_pop_gdp()	Downloads raw World Bank and SSP population/GDP files.	1 MB	1 min
download_ar6()	Downloads raw AR6 climate pathway and historical baseline files.	210 MB	1 min
process_mrio()	Builds processed MRIO matrices, optional region or sector aggregation and disaggregation scopes, metadata, economic enacting metrics such as final demand and value added, and environmental enacting metrics after LCIA characterization. These outputs are reused by aSoCC allocation methods and pyaesa owned IO-LCA.	See MRIO tables	See MRIO tables
process_pop_gdp()	Builds harmonized historical and SSP population/GDP tables, aligns country coverage to the supported MRIO scopes, records missing value treatment, and harmonizes GDP PPP units. These outputs are reused by retrospective and prospective aSoCC allocation methods.	2 MB	<1 min
process_ar6()	Builds retained and optionally harmonized AR6 pathway workbooks for dynamic climate change CC, including Kyoto gases and CO2 variables with and without AFOLU, category and SSP budget summaries, logs, and optional diagnostic figures.	14 MB without figures; 63 MB with figures	1 min without figures; figures add about 2 min

MRIO Storage And Runtime

Raw MRIO download storage and runtime by source:

Source	Disk space	Runtime
EXIOBASE 3.10.2 ixi	260 MB for one year; 7.5 GB for 1995 to 2024	20 s for one year; 10 min for all years
EXIOBASE 3.10.2 pxp	230 MB for one year; 6.7 GB for 1995 to 2024	20 s for one year; 10 min for all years
OECD ICIO v2025	470 MB for one bundle, for example 1995 to 2000; 2.2 GB for 1995 to 2022	1 min for one bundle, for example 1995 to 2000; 4 min for all years

Processed MRIO output storage and runtime by source:

Source	Disk space	Runtime
EXIOBASE 3.10.2 ixi	230 MB for one year; 6.7 GB for 1995 to 2024	1 min for one year; 25 min for all years
EXIOBASE 3.10.2 pxp	280 MB for one year; 8.2 GB for 1995 to 2024	1 min for one year; 36 min for all years
OECD ICIO v2025	210 MB for one year; 5.8 GB for 1995 to 2022	<1 min for one year; 5 min for all years

The measurements were taken on Windows 11 with Python 3.14, an 11th Gen Intel Core i7 1165G7 CPU, 32 GB RAM.

AESA Functions

Phase	Mode	Function	What it computes and writes
A	deterministic	deterministic_io_lca()	Computes pyaesa owned IO-LCA result tables from processed EXIOBASE assets and figures.
A	uncertainty	uncertainty_io_lca()	Monte Carlo IO-LCA run tables, summaries, source logs, and figures.
B	deterministic	deterministic_asocc()	Allocated shares of carrying capacity (aSoCC) tables and figures.
B	uncertainty	uncertainty_asocc()	aSoCC Monte Carlo run tables, summaries, source logs, figures by default, and Sobol outputs when requested.
B	deterministic	deterministic_ar6_cc()	Dynamic AR6 climate change carrying capacity (CC) pathway tables and figures.
B	uncertainty	uncertainty_ar6_cc()	AR6 CC Monte Carlo trajectory run tables, summaries, source logs, and figures.
B	deterministic	deterministic_acc()	Allocated carrying capacity (aCC) tables as aSoCC * CC and figures.
B	uncertainty	uncertainty_acc()	aCC Monte Carlo run tables, summaries, source logs, figures by default, and Sobol outputs when requested.
C	deterministic	deterministic_asr()	Absolute sustainability ratio (ASR) tables as LCA / aCC and figures.
C	uncertainty	uncertainty_asr()	ASR Monte Carlo run tables, summaries, source logs, figures by default, and Sobol outputs when requested.

Support Functions

Function	What it prepares or writes
disaggregate_asocc()	Published disaggregated aSoCC source outputs and optional figures for matching sector resolution between MRIO sources. Use the disaggregation tutorial for the required deterministic prerequisite chain.
prepare_external_inputs()	Project scoped external aSoCC and external LCA folders, guidance files, and templates for user provided data.
write_asocc_weight_template()	Editable inter-method weights tree, guide, and preview figure for the aSoCC inter-method uncertainty source.
preview_asocc_weight_tree()	Validated inter-method tree and preview figure for proposed custom weights.

Study Objectives And Routes

Study objectives are study endpoints from the user perspective. A study objective corresponds to an expected output.

Choose the study objective, i.e. the endpoint, and call the corresponding deterministic or uncertainty function directly. pyaesa automatically runs upstream computations needed to produce that endpoint, i.e. to ensure that all previous outputs are available before running the downstream function providing the endpoint.

Study objective	Corresponding output
A	Life-cycle assessment (LCA/IO-LCA)
B.0	Dynamic carrying capacity (CC)
B.1	Assigned share of carrying capacities (aSoCC)
B.2	Assigned carrying capacities (aCC)
C	Absolute sustainability ratio (ASR)

Route setup:

1. Run set_workspace() once for the workspace.

2. Download the raw data families needed by the study endpoint.

3. Run process_mrio() and process_pop_gdp() when the endpoint needs processed MRIO or population/GDP assets. Direct process_ar6() runs are optional for dynamic AR6 CC, aCC, and ASR endpoints because those routes can provision the matching processed AR6 scope when it is missing.

Set Of Tutorials

The tutorial notebooks are split into reusable prerequisite data preparation notebooks, study endpoint notebooks, and optional workflow notebooks.

Core prerequisites tutorials

Key	Notebook
Workspace	tutorials/core_prerequisites/0_set_workspace.ipynb
Download	tutorials/core_prerequisites/1_download_data.ipynb
Process	tutorials/core_prerequisites/2_process_data.ipynb

Study objectives tutorials

Key	Notebook
Study objectives	tutorials/study_objectives/0_study_objectives.md
Functional units and allocation methods	tutorials/study_objectives/1_functional_units_and_allocation_methods.md
Phase A IO-LCA	tutorials/study_objectives/(A) LCA/Phase_A_iolca_deterministic.ipynb tutorials/study_objectives/(A) LCA/Phase_A_iolca_uncertainty.ipynb
Phase B.0 dynamic AR6 CC	tutorials/study_objectives/(B.0) CC/Phase_B0_dynamic_CC_ar6_deterministic.ipynb tutorials/study_objectives/(B.0) CC/Phase_B0_dynamic_CC_ar6_uncertainty.ipynb
Phase B.1 aSoCC	tutorials/study_objectives/(B.1) aSoCC/Phase_B1_asocc_deterministic.ipynb tutorials/study_objectives/(B.1) aSoCC/Phase_B1_asocc_uncertainty.ipynb
Phase B.2 aCC	tutorials/study_objectives/(B.2) aCC/Phase_B2_acc_deterministic.ipynb tutorials/study_objectives/(B.2) aCC/Phase_B2_acc_uncertainty.ipynb
Phase C ASR	tutorials/study_objectives/(C) ASR/Phase_C_asr_deterministic.ipynb tutorials/study_objectives/(C) ASR/Phase_C_asr_uncertainty.ipynb

Optional tutorials

Main use	Notebook
disaggregation	tutorials/optional_workflows/disaggregate_asocc_mrio_sectors.ipynb
inter-method weights	tutorials/optional_workflows/custom_asocc_method_weights.ipynb
external aSoCC and external LCA input staging	tutorials/optional_workflows/external_asocc_lca_input_staging.ipynb

Methodological References

Location	Notes
methodological_notes/methodological_note__asocc_fus_allocation_methods.pdf	Functional units and allocation methods.
methodological_notes/methodological_note__acc_prospective.pdf	Prospective allocation.
methodological_notes/methodological_note__acc_uncertainty_sources.pdf	Uncertainty sources.
methodological_notes/methodological_note__steady_state__dynamic_cc.pdf	Definition of steady state and dynamic carrying capacities.

set_workspace() copies these methodological references into the active workspace under data_raw/methodological_notes/.

Use the API reference for exact signatures and parameter contracts. Use the tutorial page for the notebook index and complete tutorial content.