Shared Socioeconomic Pathways (`project.ssp`)

For the 2023–2025 update process:

Project lead, lead modeler: @OFR-IIASA

Structure

The enumerations SSP_2017 and SSP_2024 contain one member from the corresponding SDMX code lists. These can be used to uniquely identify both an SSP narrative and the set in which it occurs, in applications where this distinction is meaningful:

>>> from message_ix_models.project.ssp import SSP_2017, SSP_2024
>>> x = SSP_2017["2"]
>>> y = SSP_2024["2"]
>>> str(y)
"ICONICS:SSP(2024).2"
>>> x == y
False

message_ix_models.project.ssp.SSP: alias of ICONICS:SSP(2017)

message_ix_models.project.ssp.SSP_2017: alias of ICONICS:SSP(2017)

message_ix_models.project.ssp.SSP_2024: alias of ICONICS:SSP(2024)

message_ix_models.project.ssp.generate(context: Context, base_dir: PathLike | None = None)[source]: Generate SDMX code lists containing the SSPs.

message_ix_models.project.ssp.parse(value: str | ~message_ix_models.util.sdmx.ICONICS:SSP(2017) | ~message_ix_models.util.sdmx.ICONICS:SSP(2024)) -> ~message_ix_models.util.sdmx.ICONICS:SSP(2017) | ~message_ix_models.util.sdmx.ICONICS:SSP(2024)[source]: Parse value to a member of SSP_2017 or SSP_2024.

class message_ix_models.project.ssp.ssp_field(default: ~message_ix_models.util.sdmx.ICONICS:SSP(2017) | ~message_ix_models.util.sdmx.ICONICS:SSP(2024))[source]: SSP field for use in data classes.

Data

Although free of charge, neither the 2017 or 2024 SSP data can be downloaded automatically. Both sources require that users first submit personal information to register before being able to retrieve the data. message_ix_models does not circumvent this requirement. Thus:

A copy of the data are stored in message_data.
message_ix_models contains only a ‘fuzzed’ version of the data (same structure, random values) for testing purposes.

Todo

Allow users without access to message_data to read a local copy of this data from a Config.local_data subdirectory.

`SSPOriginal`(source, source_kw)	Provider of exogenous data from the original SSP database.
`SSPUpdate`(source, source_kw)	Provider of exogenous data from the SSP Update database.

class message_ix_models.project.ssp.data.SSPOriginal(source, source_kw)[source]

Provider of exogenous data from the original SSP database.

To use data from this source, call exo_data.prepare_computer() with the arguments:

source: Any value from SSP_2017 or equivalent string, for instance “ICONICS:SSP(2017).2”. The specific SSP for which data is returned is determined from the value.
source_kw including:
- “model”: one of:
  - IIASA GDP
  - IIASA-WiC POP
  - NCAR
  - OECD Env-Growth
  - PIK GDP-32
- “measure”: The measures available differ according to the model; see the source data for details.

Example

>>> keys = prepare_computer(
...     context,
...     computer,
...     source="ICONICS:SSP(2015).3",
...     source_kw=dict(measure="POP", model="IIASA-WiC POP"),
... )
>>> result = computer.get(keys[0])

filename = 'SspDb_country_data_2013-06-12.csv.zip': Name of file containing the data.

id: str = 'SSP': Identifier for this particular source.

model_date = {'IIASA GDP': '130219', 'IIASA-WiC POP': '130115', 'NCAR': '130115', 'OECD Env-Growth': '130325', 'PIK GDP-32': '130424'}: One-to-one correspondence between “model” codes and date fragments in scenario codes.

replace = {'billion US$2005/yr': 'billion USD_2005/yr'}: Replacements to apply when loading the data.

class message_ix_models.project.ssp.data.SSPUpdate(source, source_kw)[source]

Provider of exogenous data from the SSP Update database.

To use data from this source, call exo_data.prepare_computer() with the arguments:

source: Any value from SSP_2024 or equivalent string, for instance “ICONICS:SSP(2024).2”.
release: One of “3.0.1”, “3.0”, or “preview”.

Example

>>> keys = prepare_computer(
...     context,
...     computer,
...     source="ICONICS:SSP(2024).3",
...     source_kw=dict(measure="GDP", model="IIASA GDP 2023"),
... )
>>> result = computer.get(keys[0])

filename = {'3.0': '1706548837040-ssp_basic_drivers_release_3.0_full.csv.gz', '3.0.1': '1710759470883-ssp_basic_drivers_release_3.0.1_full.csv.gz', 'preview': 'SSP-Review-Phase-1.csv.gz'}: File names containing the data, according to the release.

id: str = 'SSP update': Identifier for this particular source.

2024 update

Transport

Postprocess aviation emissions for SSP 2024.

Use mix-models ssp transport --help in.xlsx out.xlsx to invoke main(). Data are read from PATH_IN, in .xlsx or .csv format. If .xlsx, the data are first temporarily converted to .csv. Data are written to PATH_OUT; if not given, this defaults to the same path and suffix as PATH_IN, with “_out” added to the stem.

For example:

mix-models ssp transport --method=B \
  SSP_SSP2_v2.1_baseline.xlsx

…produces a file SSP_SSP2_v2.1_baseline_out.xlsx in the same directory.

As of 2025-01-25:

Method ‘B’ (that is, prepare_method_B(); see its documentation) is the preferred method.
The code is tested on .xlsx files in the (internal) directories under SharePoint > ECE > Documents > SharedSocioeconomicPathways2023 > Scenario_Vetting, for example v2.1_Internal_version_Dec13_2024/Reporting_output/SSP_SSP2_v2.1_baseline.xlsx.

message_ix_models.project.ssp.transport.DIMS = ['e', 'n', 't', 'y', 'UNIT']: Dimensions of several quantities.

message_ix_models.project.ssp.transport.EXPR_EMI = '^Emissions\\|(?P<e>[^\\|]+)\\|Energy\\|Demand\\|Transportation(?:\\|(?P<t>.*))?$': Expression for IAMC ‘variable’ names used in main().

message_ix_models.project.ssp.transport.FLOWS = ['AVBUNK', 'DOMESAIR', 'TOTTRANS']: IEA_EWEB flow codes used in the current file.

message_ix_models.project.ssp.transport.L = 'AIR emi': Common label / Key.name

message_ix_models.project.ssp.transport.aviation_share(ref: AnyQuantity) → AnyQuantity[source]

Return (dummy) data for the share of aviation in emissions.

Currently this returns exactly the value 0.2.

Parameters:: ref – Reference quantity. The dimensions and coordinates $(n, e, y)$ of the returned value exactly match ref.
Returns:: with dimensions $(n, e, y)$.
Return type:: genno.Quantity

message_ix_models.project.ssp.transport.broadcast_t(include_international: bool) → AnyQuantity[source]

Quantity to re-add the $t$ dimension.

Parameters:

include_international – If True, include “Aviation|International” with magnitude 1.0. Otherwise, omit

Returns:

with dimension “t” and the values:

+1.0 for t=”Aviation”, a label with missing data.
-1.0 for t=”Road Rail and Domestic Shipping”, a label with existing data from which the aviation total should be subtracted.

Return type:

genno.Quantity

message_ix_models.project.ssp.transport.e_UNIT(cl_emission: sdmx.model.common.Codelist) → AnyQuantity[source]

Return a quantity for broadcasting.

Returns:

with one value $Q_{e, UNIT} = 1.0$ for every label |e| in cl_emission, with “UNIT” being the unit expression to be used with IAMC- structured data.

Values are everywhere 1.0, except for species such as N2O that must be reported in kt rather than Mt.

Return type:

genno.Quantity

message_ix_models.project.ssp.transport.extract_dims(qty: AnyQuantity, dim_expr: dict, *, drop: bool = True, fillna: str = '_T') → AnyQuantity[source]: Extract dimensions from IAMC-like ‘variable’ names using regular expressions.

message_ix_models.project.ssp.transport.extract_dims1(qty: AnyQuantity, dim: dict) → AnyQuantity[source]: Extract dimensions from IAMC-like ‘variable’ names expressions.

Note

This incomplete, non-working version of extract_dims() uses xarray semantics.

message_ix_models.project.ssp.transport.finalize(q_all: AnyQuantity, q_update: AnyQuantity, model_name: str, scenario_name: str, path_out: pathlib.Path) → None[source]

Finalize output.

Reattach “Model” and “Scenario” labels.
Reassemble the “Variable” dimension/coords of q_update; drop “e” and “t”.
Convert both q_all and q_update to pandas.Series; update the former with the contents of the latter. This retains all other, unmodified data in q_all.
Adjust to IAMC ‘wide’ structure and write to path_out.

Parameters:

q_all – All data. Quantity with dimensions $(n, y, UNIT, VARIABLE)$.
q_update – Revised data to overwrite corresponding values in q_all. Quantity with dimensions DIMS.

message_ix_models.project.ssp.transport.main(path_in: pathlib.Path, path_out: pathlib.Path, method: str) → None[source]

Postprocess aviation emissions for SSP 2024.

Read input data from path_in.
Call either prepare_method_A() or prepare_method_B() according to the value of method.
Write to path_out.

Parameters:

path_in – Input data path.
path_out – Output data path.
method – Either ‘A’ or ‘B’.

message_ix_models.project.ssp.transport.prepare_method_A(c: Computer, k_input: Key, k_emi_in: Key) → Key[source]

Prepare calculations using method ‘A’.

Select data with variable names matching EXPR_EMI.
Calculate (identical) values for:
- Emissions|*|Energy|Demand|Transportation|Aviation
- Emissions|*|Energy|Demand|Transportation|Aviation|International
…as the product of aviation_share() and Emissions|*|Energy|Demand|Transportation.
Subtract (2) from: Emissions|*|Energy|Demand|Transportation|Road Rail and Domestic Shipping

message_ix_models.project.ssp.transport.prepare_method_B(c: Computer, k_input: Key, k_emi_in: Key) → Key[source]

Prepare calculations using method ‘B’.

Excluding data transformations, units, and other manipulations for alignment:

From the IEA_EWEB 2024 edition, select data for $y = 2019$ and the FLOWS.
Aggregate IEA EWEB to align with MESSAGEix-GLOBIOM $c$.
Reverse the sign of values for flow=AVBUNK. These are negative in the source data, but their absolute value must be added to values for flow=DOMESAIR.
Compute the ratio $(AVBUNK + DOMESAIR) / TOTTRANS$, the share of aviation in final energy.
From the input data (k_input), select the values matching EXPR_FE, that is, final energy use by aviation.
Load emissions intensity of aviation final energy use from the file emi-intensity.csv → emissions intensity:t-c-e:transport.
Multiply (4) × (5) × (6) to compute the estimate of Emissions|*|Energy|Demand|Transportation|Aviation.
Estimate Emissions|*|Energy|Demand|Transportation|Road Rail and Domestic Shipping as the negative of (7).
Adjust k_emi_in by adding (7) and (8).

message_ix_models.project.ssp.transport.select_re(qty: AnyQuantity, indexers: dict) → AnyQuantity[source]: Select from qty using regular expressions for each dimension.

Shared Socioeconomic Pathways (project.ssp)

Structure

Data

2024 update

Transport

Shared Socioeconomic Pathways (`project.ssp`)