Python

Installation¶

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

poetry add git+https://github.com/IAMconsortium/scenario-validation-criteria.git

Load functions¶

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 [1]:

from scenario_validation_criteria import load_criteria

load_criteria("criteria-thresholds")

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

Out[1]:

	criterion	variable	region	year	reference_data	unit	level_of_concern	lower	upper
0	Feasibility Concern|Hydropower Capacity	Capacity|Electricity|Hydro	World	2030	NaN	GW	medium	1175.37	1606.66
1	Feasibility Concern|Hydropower Capacity	Capacity|Electricity|Hydro	World	2030	NaN	GW	strong	979.43	2117.58
2	Feasibility Concern|Nuclear Capacity	Capacity|Electricity|Nuclear	World	2030	NaN	GW	medium	320.33	441.92
3	Feasibility Concern|Nuclear Capacity	Capacity|Electricity|Nuclear	World	2030	NaN	GW	strong	269.75	479.92
4	Feasibility Concern|Carbon Capture	Carbon Capture, Carbon Capture|Geological Storage	World	2030	NaN	Mt CO2/yr	medium	44.02	152.47
5	Feasibility Concern|Carbon Capture	Carbon Capture, Carbon Capture|Geological Storage	World	2030	NaN	Mt CO2/yr	strong	0.00	457.89
6	Feasibility Concern|Carbon Capture	Carbon Capture, Carbon Capture|Geological Storage	World	2035	NaN	Mt CO2/yr	medium	NaN	1300.00
7	Feasibility Concern|Carbon Capture	Carbon Capture, Carbon Capture|Geological Storage	World	2040	NaN	Mt CO2/yr	medium	NaN	4300.00
8	Feasibility Concern|Solar PV Capacity	Capacity|Electricity|Solar	World	2030	NaN	GW	medium	4350.20	8163.70
9	Feasibility Concern|Solar PV Capacity	Capacity|Electricity|Solar	World	2030	NaN	GW	strong	2683.20	10896.00
10	Feasibility Concern|Onshore Wind Capacity	Capacity|Electricity|Wind|Onshore	World	2030	NaN	GW	medium	1719.00	2853.00
11	Feasibility Concern|Onshore Wind Capacity	Capacity|Electricity|Wind|Onshore	World	2030	NaN	GW	strong	1220.00	3655.00
12	Feasibility Concern|Wind Capacity	Capacity|Electricity|Wind	World	2030	NaN	GW	medium	1719.00	NaN
13	Feasibility Concern|Wind Capacity	Capacity|Electricity|Wind	World	2030	NaN	GW	strong	1220.00	NaN
14	Historical Vetting|Emissions|CO2|Energy and In...	Emissions|CO2|Energy and Industrial Processes	World	2010, 2015	CEDS-2025	dimensionless	strong	0.75	1.25
15	Historical Vetting|Emissions|CO2|Energy and In...	Emissions|CO2|Energy and Industrial Processes	World	2020	range(CEDS-2025,CEDS-2025-COVIDaveraged)	dimensionless	strong	0.75	1.25
16	Historical Vetting|Emissions|CO2|Energy and In...	Emissions|CO2|Energy and Industrial Processes	World	2025	CEDS-2025-extrapol25	dimensionless	strong	0.75	1.25
17	Historical Vetting|Primary Energy|Coal	Primary Energy|Coal	World	2010, 2015	IEA-ESDB-20250610	dimensionless	strong	0.75	1.25
18	Historical Vetting|Primary Energy|Coal	Primary Energy|Coal	World	2020	range(IEA-ESDB-20250610,IEA-ESDB-20250610-COVI...	dimensionless	strong	0.60	1.40
19	Historical Vetting|Primary Energy|Coal	Primary Energy|Coal	World	2025	IEA-ESDB-20250610-extrapol25	dimensionless	strong	0.75	1.25
20	Historical Vetting|Primary Energy|Gas	Primary Energy|Gas	World	2010, 2015	IEA-ESDB-20250610	dimensionless	strong	0.75	1.25
21	Historical Vetting|Primary Energy|Gas	Primary Energy|Gas	World	2020	range(IEA-ESDB-20250610,IEA-ESDB-20250610-COVI...	dimensionless	strong	0.60	1.40
22	Historical Vetting|Primary Energy|Gas	Primary Energy|Gas	World	2025	IEA-ESDB-20250610-extrapol25	dimensionless	strong	0.75	1.25
23	Historical Vetting|Primary Energy|Oil	Primary Energy|Oil	World	2010, 2015	IEA-ESDB-20250610	dimensionless	strong	0.75	1.25
24	Historical Vetting|Primary Energy|Oil	Primary Energy|Oil	World	2020	range(IEA-ESDB-20250610,IEA-ESDB-20250610-COVI...	dimensionless	strong	0.60	1.40
25	Historical Vetting|Primary Energy|Oil	Primary Energy|Oil	World	2025	IEA-ESDB-20250610-extrapol25	dimensionless	strong	0.75	1.25
26	Historical Vetting|Primary Energy|Nuclear	Primary Energy|Nuclear	World	2010, 2015	IEA-ESDB-20250610	dimensionless	strong	0.75	1.25
27	Historical Vetting|Primary Energy|Nuclear	Primary Energy|Nuclear	World	2020	range(IEA-ESDB-20250610,IEA-ESDB-20250610-COVI...	dimensionless	strong	0.60	1.40
28	Historical Vetting|Primary Energy|Nuclear	Primary Energy|Nuclear	World	2025	IEA-ESDB-20250610-extrapol25	dimensionless	strong	0.75	1.25
29	Historical Vetting|Final Energy	Final Energy	World	2010, 2015	IEA-ESDB-20250610	dimensionless	strong	0.75	1.25
30	Historical Vetting|Final Energy	Final Energy	World	2020	range(IEA-ESDB-20250610,IEA-ESDB-20250610-COVI...	dimensionless	strong	0.60	1.40
31	Historical Vetting|Final Energy	Final Energy	World	2025	IEA-ESDB-20250610-extrapol25	dimensionless	strong	0.75	1.25
32	Sustainability Concern|Food Availability	Food Availability [per capita]	World	NaN	NaN	kcal/cap/day	medium	2100.00	5000.00
33	Sustainability Concern|Unsustainable Bioenergy...	Primary Energy|Biomass	World	NaN	NaN	EJ/yr	medium	NaN	100.00
34	Sustainability Concern|Unsustainable Bioenergy...	Primary Energy|Biomass	World	NaN	NaN	EJ/yr	strong	NaN	245.00
35	Sustainability Concern|Exceeding Prudent Limit...	Carbon Capture|Geological Storage	World	NaN	NaN	Gt CO2	strong	NaN	1460.00
36	Sustainability Concern|Exceeding Prudent Limit...	Carbon Capture|Geological Storage	World	NaN	NaN	Gt CO2	medium	NaN	1290.00

Multiple files can be loaded in one go.

In [2]:

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	Emissions|CO2|Energy and Industrial Processes	2010	World	Mt CO2/yr	33460.0812	CEDS-2025
1	Emissions|CO2|Energy and Industrial Processes	2015	World	Mt CO2/yr	35627.2810	CEDS-2025
2	Emissions|CO2|Energy and Industrial Processes	2020	World	Mt CO2/yr	35387.0617	CEDS-2025
3	Emissions|CO2|Energy and Industrial Processes	2020	World	Mt CO2/yr	36874.1129	CEDS-2025-COVIDaveraged
4	Emissions|CO2|Energy and Industrial Processes	2025	World	Mt CO2/yr	39383.4852	CEDS-2025-extrapol25
5	Final Energy	2010	World	EJ/yr	365.0740	IEA-ESDB-20250610
6	Final Energy	2015	World	EJ/yr	389.5650	IEA-ESDB-20250610
7	Final Energy	2020	World	EJ/yr	395.7830	IEA-ESDB-20250610
8	Primary Energy|Coal	2010	World	EJ/yr	152.6260	IEA-ESDB-20250610
9	Primary Energy|Coal	2015	World	EJ/yr	160.9780	IEA-ESDB-20250610
10	Primary Energy|Coal	2020	World	EJ/yr	157.6320	IEA-ESDB-20250610
11	Primary Energy|Gas	2010	World	EJ/yr	114.5760	IEA-ESDB-20250610
12	Primary Energy|Gas	2015	World	EJ/yr	122.4020	IEA-ESDB-20250610
13	Primary Energy|Gas	2020	World	EJ/yr	137.9970	IEA-ESDB-20250610
14	Primary Energy|Oil	2010	World	EJ/yr	175.3710	IEA-ESDB-20250610
15	Primary Energy|Oil	2015	World	EJ/yr	186.7070	IEA-ESDB-20250610
16	Primary Energy|Oil	2020	World	EJ/yr	177.5700	IEA-ESDB-20250610
17	Primary Energy|Nuclear	2010	World	EJ/yr	9.9230	IEA-ESDB-20250610
18	Primary Energy|Nuclear	2015	World	EJ/yr	9.2520	IEA-ESDB-20250610
19	Primary Energy|Nuclear	2020	World	EJ/yr	9.6350	IEA-ESDB-20250610
20	Final Energy	2020	World	EJ/yr	411.6870	IEA-ESDB-20250610-COVIDaveraged
21	Primary Energy|Coal	2020	World	EJ/yr	164.5760	IEA-ESDB-20250610-COVIDaveraged
22	Primary Energy|Gas	2020	World	EJ/yr	140.5050	IEA-ESDB-20250610-COVIDaveraged
23	Primary Energy|Oil	2020	World	EJ/yr	188.1330	IEA-ESDB-20250610-COVIDaveraged
24	Primary Energy|Nuclear	2020	World	EJ/yr	9.8440	IEA-ESDB-20250610-COVIDaveraged
25	Final Energy	2025	World	EJ/yr	442.6510	IEA-ESDB-20250610-extrapol25
26	Primary Energy|Coal	2025	World	EJ/yr	182.5010	IEA-ESDB-20250610-extrapol25
27	Primary Energy|Gas	2025	World	EJ/yr	142.4400	IEA-ESDB-20250610-extrapol25
28	Primary Energy|Oil	2025	World	EJ/yr	200.3560	IEA-ESDB-20250610-extrapol25
29	Primary Energy|Nuclear	2025	World	EJ/yr	9.6020	IEA-ESDB-20250610-extrapol25

Formatting citations and sources¶

Note that this requires the pybtex package, which can be installed via the formatting dependency option.

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

In [3]:

sources = load_criteria("sources")

sources = load_criteria("sources")

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

In [4]:

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

from scenario_validation_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 [5]:

from scenario_validation_criteria.formatting import insert_citations

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

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

from scenario_validation_criteria.formatting import insert_citations text = load_criteria("criteria-descriptions")["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.