pyaesa 1.2.4

pyaesa is a Python package for absolute environmental sustainability assessment (AESA), covering data download and processing, deterministic and uncertainty assessment, and figure generation.

Documentation: pyaesa.readthedocs.io reproduces the documentation of this GitHub repository.

Beta status: pyaesa is currently in beta testing. Please report bugs, unexpected behavior, documentation gaps, and installation or workflow issues on the GitHub Issues page.

pyaesa is a Python package for absolute environmental sustainability assessment (AESA) workflows. It supports data download, data processing, deterministic calculations, figure rendering, Monte Carlo uncertainty and Sobol variance.

The package follows the three AESA phases described in the JRC guidance. The calculation chain is:

1. Phase A builds life cycle assessment (LCA) results.
2. Phase B builds allocated carrying capacity (aCC) results: aCC = aSoCC * CC.
3. Phase C builds absolute sustainability ratio (ASR) results: ASR = LCA / aCC.

aSoCC means allocated share of carrying capacity. CC means carrying capacity. CC can be static, for example with LCIA methods PB-LCIA or EF3.1, or dynamic through AR6 climate change pathways.

License

pyaesa source code is distributed under the GPL 3.0 license. Downloaded datasets remain governed by their original providers' terms and conditions documented in the Data Source Licenses And Terms section.

Community

Contributing to pyaesa

pyaesa uses the GitHub Discussions Ideas category to collect feature ideas and development priorities from users.

Use Ideas to propose new features, request additional allocation methods, upvote existing proposals, and comment with your use case, data source, expected workflow, or implementation constraints.

To propose direct code modifications, for example implementing new allocation methods or other features, see CONTRIBUTING.md.

Sharing Reproducible Case Studies

Users are encouraged to share AESA case studies developed with pyaesa in the AESA_case_studies repository. This supports the AESA community by making case studies easier to understand, inspect, reproduce, compare, and extend.

Installation

Install the package from PyPI:

python -m pip install pyaesa

For local development from a repository clone, install in editable mode:

python -m pip install -e .

pyaesa requires at least 4 GB of available RAM to run.

High-level overview of the package

The figure below provides a high-level overview of the package, including main data sources, high-level public functions and study objectives supported by the package. More details are provided in the next sections.

Example Output Figures

pyaesa produces result tables and figures. The example below illustrates some of the 83 figure families available with pyaesa. For steady-state carrying capacities, it shows allocated carrying capacity (aCC) trajectories and a single-year ASR polar figure. For dynamic climate change carrying capacities based on AR6 pathways, it shows global carrying capacity (CC) and allocated carrying capacity (aCC) trajectories and cumulative budgets.

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.

Current EXIOBASE LCIA coverage is gwp100_lcia and pb_lcia. Therefore in pyaesa 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. tutorials/core_prerequisites/2_process_data.ipynb 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.

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

Public Workflow Function Map

Core Prerequisites To Run Once

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 table below.	See table below.
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 table below.	See table below.
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

MRIO raw 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

MRIO processed 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(...)	Computes Monte Carlo IO-LCA run tables, summaries, source logs, and figures.
B	deterministic	deterministic_asocc(...)	Computes allocated shares of carrying capacity (aSoCC) tables and figures.
B	uncertainty	uncertainty_asocc(...)	Computes aSoCC Monte Carlo run tables, summaries, source logs, figures by default, and Sobol outputs when requested.
B	deterministic	deterministic_ar6_cc(...)	Computes dynamic AR6 climate change carrying capacity (CC) pathway tables and figures.
B	uncertainty	uncertainty_ar6_cc(...)	Computes AR6 CC Monte Carlo trajectory run tables, summaries, source logs, and figures.
B	deterministic	deterministic_acc(...)	Computes allocated carrying capacity (aCC) tables as aSoCC * CC and figures.
B	uncertainty	uncertainty_acc(...)	Computes aCC Monte Carlo run tables, summaries, source logs, figures by default, and Sobol outputs when requested.
C	deterministic	deterministic_asr(...)	Computes absolute sustainability ratio (ASR) tables as LCA / aCC and figures.
C	uncertainty	uncertainty_asr(...)	Computes ASR Monte Carlo run tables, summaries, source logs, figures by default, and Sobol outputs when requested.

Support Functions

Support 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 dedicated disaggregation notebook for the required deterministic prerequisite chain.
prepare_external_inputs(...)	Project scoped external aSoCC and external LCA folders, README 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 recommended routes

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.

4. Choose a study objective that fit your application. Study objectives are study endpoints from the user perspective. A study objective corresponds to an expected output for the user. In pyaesa, five study objectives are currently available:

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)

5. Once your have chosen the study objective (i.e., the endpoint), call the corresponding deterministic or uncertainty function directly. It is very important for the user to understand that to reach a desired study objective, pyaesa automatically runs upstream computations needed to produce the desired endpoint, i.e., to ensure that all previous outputs are available before running the downstream function providing the endpoint. This is illustrated via the green arrows (automatic nesting) in the figure above. Consequently, the user must focus solely on the desired study objective, and run the single relevant function.

Check out tutorials/study_objectives/0_study_objectives.md to understand how to select and reach study objectives in pyaesa.

Set of tutorials

The README is the tutorial navigator. 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 in docs/api.rst for exact signatures and parameter contracts. Use docs/tutorial.rst for the notebook index.

Use of generative AI

Generative AI tools were used during the development of pyaesa. As the development of the package took several months from the initial ideation to the first release, several tools were used including OpenAI Codex models 5.3 to 5.5, Codex Spark 5.3, Anthropic Claude Opus 4.6 and Sonnet 4.6, and GitHub Copilot.

These tools were used to support implementation tasks, including code generation, refactoring, debugging, test design, documentation drafting, code review, computing time optimization, memory use reduction, and figure rendering workflows.

The development of AESA methodology and workflow, mathematical expressions, software architecture and the figures conception were defined by the authors. Generative AI outputs were used as implementation drafts, checked and modified where needed, and retained only after review and testing by human intelligence.