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, both the 2017 and 2024 SSP data are provided under licenses that prevent distribution with or automated retrieval by message_ix_models. Both sources require that users first submit personal information to register before being able to retrieve the data, and restrict the distribution of the complete, original files.

Thus, message_ix_models contains only a ‘fuzzed’ version of the data (same structure, random values) for testing purposes.

In order to use these data via the tools in this module, the user must obtain a copy of the files —for instance, by manually completing the registration and download steps— and place them in the directory Config.cache_path (see cache-data) or message_ix_models/data/ssp/ within the environment where message_ix_models is installed. For SSPUpdate, the specific file names required are the ones given by pooch.SOURCE:

1706548837040-ssp_basic_drivers_release_3.0_full.csv.gz
1710759470883-ssp_basic_drivers_release_3.0.1_full.csv.gz

`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.

This database is accessible from https://tntcat.iiasa.ac.at/SspDb/dsd.

To use data from this source:

Read the general documentation for project.ssp.data.
If necessary, obtain copy of the original data file(s).
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.

This database is accessible from https://data.ece.iiasa.ac.at/ssp.

To use data from this source:

Read the general documentation for project.ssp.data.
If necessary, obtain copy of the original data file(s).
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.1”, “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', '3.1': '1721734326790-ssp_basic_drivers_release_3.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.

2023–2025 update

This update is related to the Scenario Model Intercomparison Project (ScenarioMIP) for CMIP7.

Transport

Postprocess aviation emissions for SSP 2024.

There are two ways to invoke this code:

To process data from file, use mix-models ssp transport --help in.xlsx out.xlsx to invoke process_file(). 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 --platform=ixmp-dev \
  ssp transport --method=C \
  SSP_SSP2_v2.1_baseline.xlsx
```
…produces a file SSP_SSP2_v2.1_baseline_out.xlsx in the same directory.
To process an existing pandas.DataFrame from other code, call process_df(), passing the input dataframe and the method parameter.

As of 2025-03-07 / PR #309, the set of required “variable” codes handled includes:

Emissions|.*|Energy|Bunkers
Emissions|.*|Energy|Bunkers|International Aviation
Emissions|.*|Energy|Demand|Transportation
Emissions|.*|Energy|Demand|Transportation|Road Rail and Domestic Shipping

The previous set, supported as of 2025-01-25 but no longer supported, included:

Emissions|.*|Energy|Demand|Transportation|Aviation
Emissions|.*|Energy|Demand|Transportation|Aviation|International
Emissions|.*|Energy|Demand|Transportation|Road Rail and Domestic Shipping

Method ‘C’ (that is, method_C(); 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 or v2.3_v2.4_Submission_Mar01_2025/Scenario_Reporting_Files/SSP_LED_v2.3.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 = re.compile('^Emissions\|(?P<e>[^\|]+)\|Energy\|Demand\|(?P<t>(Bunkers|Transportation).*)$'): Expression used to select and extract $(e, t)$ dimension coordinates from variable codes in v_to_emi_coords().

message_ix_models.project.ssp.transport.EXPR_FE = re.compile('^Final Energy\|Transportation\|(?P<c>Liquids\|Oil)$'): Expression used to select and extract $(c)$ dimension coordinates from variable codes in v_to_fe_coords().

message_ix_models.project.ssp.transport.IAMC_KW = {'non_iso_3166': 'keep', 'query': "Model != ''", 'unique': 'MODEL SCENARIO'}: Keywords for iamc_like_data_for_query() / to_quantity().

message_ix_models.project.ssp.transport.K = <4 keys: bcast emi emi_in input>

Fixed keys prepared by get_computer() and other functions:

.bcast: the output of broadcast_t().
.input: input data from file or calling code, converted to Quantity.
.emi: computed aviation emissions.
.emi_in: input data for aviation and other transport emissions, to be adjusted or overwritten.

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

class message_ix_models.project.ssp.transport.METHOD(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Method for computing emissions.

A = 1: See method_A().

B = 2: See method_B().

C = 3: See method_C().

message_ix_models.project.ssp.transport.aviation_emi_share(ref: TQuantity) → TQuantity[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(version: Literal[1, 2], include_international: bool) → AnyQuantity[source]

Quantity to re-add the $t$ dimension.

Parameters:

version – Version of ‘variable’ names supported by the current module.
include_international – If True, include “Transportation|Aviation|International” with magnitude 1.0. Otherwise, omit.

Returns:

with dimension “t”.

If version=1, the values include:

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

If version=2, the values include:

+1.0 for t=”Bunkers” and t=”Bunkers|International Aviation”, labels with zeros in the input data file.
-1.0 for t=”Transportation” and t=”Transportation|Road Rail and Domestic Shipping”, labels with existing data from which the aviation total must 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, U N I T} = 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.finalize(q_all: TQuantity, q_update: TQuantity, model_name: str, scenario_name: str) → DataFrame[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.

Parameters:

q_all – All data. Quantity with dimensions $(n, y, U N I T, V A R I A B L E)$ .
q_update – Revised data to overwrite corresponding values in q_all. Quantity with dimensions DIMS.

message_ix_models.project.ssp.transport.get_computer(row0: pd.Series, method: METHOD, *, platform_name: str | None = None) → Computer[source]

Prepare c to process aviation emissions data.

Parameters:

row0 – A single sample row of the input data. “Model” and “Scenario” must be in the index; these are used to reconstruct the IAMC data structure.
method – Select the calculation method.
platform_name – Configured name of a Platform containing solved MESSAGEix-Transport scenarios.

Returns:

Calling c.get("target") triggers the calculation of the result.

Return type:

Computer

message_ix_models.project.ssp.transport.get_scenario_code(model_name: str, scenario_name: str) → sdmx.model.common.Code[source]

Return a specific code from CL_TRANSPORT_SCENARIO.

See get_cl_scenario(). This function handles (model_name, scenario_name) combinations seen in base model outputs as of 2025-04-02.

message_ix_models.project.ssp.transport.method_A(c: Computer) → None[source]

Prepare calculations up to K.emi using METHOD.A.

This method uses a fixed share of data for variable=``Emissions|*|Energy|Demand|Transportation``.

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_emi_share() and Emissions|*|Energy|Demand|Transportation.
Subtract (2) from: Emissions|*|Energy|Demand|Transportation|Road Rail and Domestic Shipping

message_ix_models.project.ssp.transport.method_B(c: Computer) → None[source]

Prepare calculations up to K.emi using METHOD.B.

This method uses the $y_{0}$ share of aviation in total transport final energy as indicated by IEA_EWEB, with dimensions $(c, n)$ , to disaggregate total final energy from the input data, then applies emission intensity data to compute aviation emissions.

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

From the IEA_EWEB 2024 edition, select data for $y = 2019$ .
Aggregate IEA EWEB data to align with MESSAGEix-GLOBIOM $c$ .
Compute the ratio of _1 to _2 (see web.transform_C() for how these labels are produced). This is the share of aviation in final energy.
Add the steps from method_BC_common().

message_ix_models.project.ssp.transport.method_BC_common(c: Computer, k_fe_share: Key) → None[source]

Common steps for method_B() and method_C().

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 transport-input-emi-intensity.
Multiply (k_fe_share) × (1) × (2) to compute the estimate of aviation emissions.
Estimate adjustments according to broadcast_t().

Parameters:: k_fe_share – A key with dimensions either $(c, n)$ or $(c, n, y)$ giving the share of aviation in total transport final energy.

message_ix_models.project.ssp.transport.method_C(c: Computer) → None[source]

Prepare calculations up to K.emi using METHOD.C.

This method uses a solved MESSAGEix-Transport scenario to compute the share of aviation in total transport final energy, with dimensions $(c, n, y)$ , and the proceeds similarly to method_B().

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

Identify a corresponding base scenario of MESSAGEix-Transport with a solution.
From the model solution data, compute the share of AIR in total transport final energy.
Apply the steps from method_BC_common().

message_ix_models.project.ssp.transport.process_df(data: DataFrame, *, method: METHOD = METHOD.B, platform_name: str | None = None) → DataFrame[source]

Process data.

Same as process_file(), except the data is returned as a data frame in the same structure as data.

For the meaning of parameters method and platform_name, see get_computer().

message_ix_models.project.ssp.transport.process_file(path_in: pathlib.Path, path_out: pathlib.Path, *, method: METHOD, platform_name: str | None = None) → None[source]

Process data from file.

Read input data from path_in in IAMC CSV format.
Call get_computer() and in turn one of method_A(), method_B(), or method_C() according to the value of method.
Write to path_out in the same format as (1).

Parameters:

path_in – Input data path.
path_out – Output data path.
method – One of METHOD.

message_ix_models.project.ssp.transport.v_to_emi_coords(value: Hashable) → dict[str, str] | None[source]

Match ‘variable’ names codes using EXPR_EMI.

For use with select_expand().

message_ix_models.project.ssp.transport.v_to_fe_coords(value: Hashable) → dict[str, str] | None[source]

Match ‘variable’ names codes using EXPR_FE.

For use with select_expand().

Shared Socioeconomic Pathways (project.ssp)

Structure

Data

2023–2025 update

Transport

Shared Socioeconomic Pathways (`project.ssp`)