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

Raw file paths¶

The package contains definition files for the criteria. The paths to those files are contained in file_paths.

In [1]:

from scenario_vetting_criteria import file_paths

for component_id, component_path in file_paths.items():
    print(f"{component_id}:  ...{str(component_path)[-40:]}")

from scenario_vetting_criteria import file_paths for component_id, component_path in file_paths.items(): print(f"{component_id}: ...{str(component_path)[-40:]}")

operations:  ...io_vetting_criteria/data/operations.yaml
criteria-thresholds:  ...ng_criteria/data/criteria-thresholds.csv
criteria-types:  ...etting_criteria/data/criteria-types.yaml
reference-data:  ...vetting_criteria/data/reference-data.csv
reference-sources:  ...ting_criteria/data/reference-sources.bib
criteria-metadata:  ...ing_criteria/data/criteria-metadata.yaml

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

					threshold_type	lower			upper
					threshold_severity	very_strong	strong	medium	medium	strong	very_strong
criterion	region	period	variable	reference_source	unit
hist_pop	Model Native Regions	2010, 2015, 2020	Population	WDI-2024	dimensionless	0.65	0.75	NaN	NaN	1.25	1.35
	World	2010, 2015, 2020	Population	WDI-2024	dimensionless	0.75	0.85	NaN	NaN	1.15	1.25
hist_gdp	Model Native Regions	2010, 2015	GDP|PPP	WDI-2024	dimensionless	0.65	0.75	NaN	NaN	1.25	1.35
		2020	GDP|PPP	WDI-2024	dimensionless	0.50	0.60	NaN	NaN	1.40	1.50
	World	2010, 2015	GDP|PPP	WDI-2024	dimensionless	0.75	0.85	NaN	NaN	1.15	1.25
...	...	...	...	...	...	...	...	...	...	...	...
sustainable_deforestation	World	2030	Forest Area Change|Deforestation	NaN	million ha/yr	NaN	NaN	NaN	0.0	NaN	NaN
sustainable_primary_deforestation	World	2030	Forest Area Change|Deforestation|Primary	NaN	million ha/yr	NaN	NaN	NaN	0.0	NaN	NaN
sustainable_biodiversity_intactness	World	2030	Terrestrial Biodiversity|BII, Terrestrial Biodiversity|Biodiversity Intactness Index	NaN	%/yr	NaN	NaN	NaN	0.0	NaN	NaN
sustainable_bioenergy	World	2025, 2030, 2035, 2040, 2045, 2050	Primary Energy|Biomass	NaN	EJ/yr	NaN	NaN	NaN	NaN	100.00	NaN
sustainable_hydropower	World	2050	Capacity|Electricity|Hydro	NaN	GW	NaN	NaN	NaN	NaN	1500.00	NaN

77 rows × 6 columns

Multiple files can be loaded in one go.

In [3]:

criteria = load_criteria(['criteria-thresholds', 'operations'])
display(criteria['operations'])

criteria = load_criteria(['criteria-thresholds', 'operations']) display(criteria['operations'])

[{'criterion_type': 'historical',
  'threshold_severity': 'very_strong',
  'threshold_type': ['upper', 'lower'],
  'operation': 'drop'},
 {'criterion_type': 'historical',
  'threshold_severity': 'strong',
  'threshold_type': ['upper', 'lower'],
  'operation': 'flag',
  'colour': 'red'},
 {'criterion_type': 'historical',
  'threshold_severity': 'strong',
  'threshold_type': ['upper', 'lower'],
  'operation': 'flag',
  'colour': 'red'},
 {'criterion_type': 'near_term_feasibility',
  'threshold_severity': 'strong',
  'threshold_type': ['upper', 'lower'],
  'operation': 'flag',
  'colour': 'red'},
 {'criterion_type': 'near_term_feasibility',
  'threshold_severity': 'medium',
  'threshold_type': ['upper', 'lower'],
  'operation': 'flag',
  'colour': 'yellow'},
 {'criterion_type': 'long_term_feasibility',
  'threshold_severity': 'strong',
  'threshold_type': ['upper', 'lower'],
  'operation': 'flag',
  'colour': 'red'},
 {'criterion_type': 'long_term_feasibility',
  'threshold_severity': 'medium',
  'threshold_type': ['upper', 'lower'],
  'operation': 'flag',
  'colour': 'yellow'},
 {'criterion_type': 'sustainability',
  'threshold_severity': 'strong',
  'threshold_type': ['upper', 'lower'],
  'operation': 'flag',
  'colour': 'purple'}]

Formatting citations and sources¶

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

In [4]:

reference_srcs = load_criteria('reference-sources')

reference_srcs = load_criteria('reference-sources')

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

In [5]:

from scenario_vetting_criteria.formatting import format_sources
reference_srcs_formatted = format_sources(reference_srcs)
display(reference_srcs_formatted['Creutzig14'])

from scenario_vetting_criteria.formatting import format_sources reference_srcs_formatted = format_sources(reference_srcs) display(reference_srcs_formatted['Creutzig14'])

---------------------------------------------------------------------------
KeyError                                  Traceback (most recent call last)
Cell In[5], line 3
      1 from scenario_vetting_criteria.formatting import format_sources
      2 reference_srcs_formatted = format_sources(reference_srcs)
----> 3 display(reference_srcs_formatted['Creutzig14'])

KeyError: 'Creutzig14'

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')['sustainable_bioenergy']['justification_threshold']
text_inserted = insert_citations(text, reference_srcs_formatted)

print(text[:30], '...   →  ', text_inserted[:30], '...')

from scenario_vetting_criteria.formatting import insert_citations text = load_criteria('criteria-metadata')['sustainable_bioenergy']['justification_threshold'] text_inserted = insert_citations(text, reference_srcs_formatted) print(text[:30], '... → ', text_inserted[:30], '...')

{{cite:Creutzig-2014}} have de ...   →   Creutzig (2014) have derived a ...

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.