Python

Installation¶

While the Python package has not been released yet, you have to install it from GitHub source using:

# When using poetry.
poetry add git+https://github.com:PhilippVerpoort/scenario-vetting-criteria.git

# When using pip.
pip install git+https://github.com:PhilippVerpoort/scenario-vetting-criteria.git

Releases¶

The package contains definition files for the criteria for different releases. You can import the releases set from the root of the package to see what releases are available.

In [1]:

from scenario_vetting_criteria import releases

print("\n".join(releases))

from scenario_vetting_criteria import releases print("\n".join(releases))

2026-02-01
2026-06-01

Load functions¶

Instead of loading the data from these files manually, it is recommended to use the built-in load functions from the package via load_criteria. For instance, the following will load the definition of the thresholds values.

In [2]:

from scenario_vetting_criteria import load_criteria

load_criteria("criteria-thresholds")

from scenario_vetting_criteria import load_criteria load_criteria("criteria-thresholds")

Out[2]:

	criterion	variable	region	year	reference_data	unit	level_of_concern	lower	upper
0	Historical Vetting|Population	Population	World	2010, 2015, 2020, 2025	range(WDI-2025, WDI-2025-extrapol25, WDI-2025-...	dimensionless	strong	0.75	1.25
1	Historical Vetting|Population	Population	All Countries	2010, 2015, 2020, 2025	range(WDI-2025, WDI-2025-extrapol25, WDI-2025-...	dimensionless	strong	0.65	1.35
2	Historical Vetting|GDP|PPP	GDP|PPP	World	2010, 2015, 2020, 2025	range(WDI-2025, WDI-2025-extrapol25, WDI-2025-...	dimensionless	strong	0.75	1.25
3	Historical Vetting|GDP|PPP	GDP|PPP	All Countries	2010, 2015, 2020, 2025	range(WDI-2025, WDI-2025-extrapol25, WDI-2025-...	dimensionless	strong	0.65	1.35
4	Historical Vetting|Emissions|AFOLU	Emissions|CO2|AFOLU	World	2010, 2015, 2020	range(EDGAR-2024, FAO-2025, PRIMAP-2020-HISTCR...	dimensionless	strong	0.80	1.20
...	...	...	...	...	...	...	...	...	...
92	Sustainability Concern|Deforestation	Forest Area Change|Deforestation	World	2030	NaN	million ha/yr	medium	NaN	0.00
93	Sustainability Concern|Deforestation	Forest Area Change|Deforestation|Primary	World	2030	NaN	million ha/yr	medium	NaN	0.00
94	Sustainability Concern|Unsustainable Bioenergy...	Primary Energy|Biomass	World	NaN	NaN	EJ/yr	medium	NaN	100.00
95	Sustainability Concern|Unsustainable Bioenergy...	Primary Energy|Biomass	World	NaN	NaN	EJ/yr	strong	NaN	245.00
96	Sustainability Concern|Unsustainable Hydropowe...	Capacity|Electricity|Hydro	World	NaN	NaN	GW	strong	NaN	1500.00

97 rows × 9 columns

Multiple files can be loaded in one go.

In [3]:

criteria = load_criteria(["criteria-thresholds", "reference-data"])
display(criteria["reference-data"])

criteria = load_criteria(["criteria-thresholds", "reference-data"]) display(criteria["reference-data"])

	variable	year	region	unit	value	reference_data
0	Primary Energy|Coal	2010	ABW	EJ/yr	0.0001	BP
1	Primary Energy|Coal	2010	AFG	EJ/yr	0.0862	BP
2	Primary Energy|Coal	2010	AGO	EJ/yr	0.0062	BP
3	Primary Energy|Coal	2010	AIA	EJ/yr	0.0000	BP
4	Primary Energy|Coal	2010	ALA	EJ/yr	0.0000	BP
...	...	...	...	...	...	...
20634	Population	2025	World	million	8208.8956	WDI-2025-extrapol25
20635	Population	2025	YEM	million	41.7266	WDI-2025-extrapol25
20636	Population	2025	ZAF	million	64.8804	WDI-2025-extrapol25
20637	Population	2025	ZMB	million	21.8662	WDI-2025-extrapol25
20638	Population	2025	ZWE	million	16.8842	WDI-2025-extrapol25

20639 rows × 6 columns

Formatting citations and sources¶

Loading the reference sources from the BibTeX file will return a pybtex object.

In [4]:

sources = load_criteria("sources")

sources = load_criteria("sources")

The entries in this object can be formatted according to some predefined style.

In [5]:

from scenario_vetting_criteria.formatting import format_sources
sources_formatted = format_sources(sources)
display(sources_formatted["Creutzig-2014"])

from scenario_vetting_criteria.formatting import format_sources sources_formatted = format_sources(sources) display(sources_formatted["Creutzig-2014"])

{'cite_auth': 'Creutzig',
 'cite_year': '2014',
 'cite': 'Creutzig (2014)',
 'citep': '(Creutzig, 2014)',
 'bib': 'Felix Creutzig, N. H. Ravindranath, Göran Berndes, Simon Bolwig, Ryan Bright, Francesco Cherubini, Helena Chum, Esteve Corbera, Mark Delucchi, Andre Faaij, Joseph Fargione, Helmut Haberl, Garvin Heath, Oswaldo Lucon, Richard Plevin, Alexander Popp, Carmenza Robledo?Abad, Steven Rose, Pete Smith, Anders Stromman, Sangwon Suh, and Omar Masera. Bioenergy and climate change mitigation: an assessment. GCB Bioenergy, 7(5):916–944, July 2014.',
 'doi': '10.1111/gcbb.12205',
 'url_doi': 'https://doi.org/10.1111/gcbb.12205',
 'url': 'https://doi.org/10.1111/gcbb.12205',
 'pdf': 'https://onlinelibrary.wiley.com/doi/epdf/10.1111/gcbb.12205'}

The insert_citations function can be used to insert citations into text with citation patterns.

In [6]:

from scenario_vetting_criteria.formatting import insert_citations

text = load_criteria("criteria-metadata")["Sustainability Concern|Unsustainable Bioenergy Use"]["justification_threshold"]
text_inserted = insert_citations(text, sources_formatted)

print(text[:50], "...   →  ", text_inserted[:43], "...")

from scenario_vetting_criteria.formatting import insert_citations text = load_criteria("criteria-metadata")["Sustainability Concern|Unsustainable Bioenergy Use"]["justification_threshold"] text_inserted = insert_citations(text, sources_formatted) print(text[:50], "... → ", text_inserted[:43], "...")

{{cite:Creutzig-2014}} have derived an upper limit ...   →   Creutzig (2014) have derived an upper limit ...

Apply vetting criteria to scenarios¶

A tutorial on how to apply the vetting criteria to a list of scenarios based on the IAMC Nomenclature package will be made available later.