gcages.sci_june_2026

SCI components

Modules:

Name	Description
harmonisation	Harmonisation helpers for the SCI workflow
infilling	Infilling configuration and related things for the SCIJune2026 workflow.
post_processing	SCIJune2026 post-processing.
pre_processing	Pre-processing part of the SCI workflow
scm_running	SCM-running configuration and related things for the updated workflow

Classes:

Name	Description
SCIJune2026PreProcessor	Pre-processor that follows the same logic as was used in SCI

Functions:

Name	Description
create_scijune2026_harmoniser	Create an Aneris harmoniser configured for SCI June 2026 harmoniser.
create_scijune2026_infiller	Infiller that follows the same logic as was used in SCI
load_historical_emissions	Load historical emissions for harmonisation.

SCIJune2026PreProcessor

Pre-processor that follows the same logic as was used in SCI

Methods:

Name	Description
__call__	Pre-process
from_sci_june2026_config	Initialise from config that was used in the June 2026 SCI release

Attributes:

Name	Type	Description
emissions_out	tuple[str, ...]	Names of emissions that can be included in the result of pre-processing
n_processes	int | None	Number of processes to use for parallel processing.
progress	bool	Should progress bars be shown for each operation?
reclassifications	Mapping[str, tuple[str, ...]] | None	Variables that should be reclassified as being part of another variable
run_checks	bool	If True, run checks on both input and output data

Source code in src/gcages/sci_june_2026/pre_processing.py

@define
class SCIJune2026PreProcessor:
    """
    Pre-processor that follows the same logic as was used in SCI

    """

    emissions_out: tuple[str, ...]
    """
    Names of emissions that can be included in the result of pre-processing

    Not all these emissions need to be there,
    but any names which are not in this list will be removed as part of pre-processing.
    """

    reclassifications: Mapping[str, tuple[str, ...]] | None = None
    """
    Variables that should be reclassified as being part of another variable

    Form:

    ```python
    {
        variable_to_add_to: (variable_to_rename_1, variable_to_rename_2),
        ...
    }
    ```

    For example
    ```python
    {
        "Emissions|CO2|Energy and Industrial Processes": (
            "Emissions|CO2|Other",
            "Emissions|CO2|Waste",
        )
    }
    ```
    """

    run_checks: bool = True
    """
    If `True`, run checks on both input and output data

    If you are sure about your workflow,
    you can disable the checks to speed things up
    (but we don't recommend this unless you really
    are confident about what you're doing).
    """

    progress: bool = True
    """
    Should progress bars be shown for each operation?
    """

    n_processes: int | None = multiprocessing.cpu_count()
    """
    Number of processes to use for parallel processing.

    Set to `None` to process in serial.
    """

    def __call__(self, in_emissions: pd.DataFrame) -> pd.DataFrame:
        """
        Pre-process

        Parameters
        ----------
        in_emissions
            Emissions to pre-process

        Returns
        -------
        :
            Pre-processed emissions
        """
        try:
            from pandas_indexing.selectors import isin, ismatch  # noqa: PLC0415
        except ImportError as exc:
            raise MissingOptionalDependencyError(
                "SCIPreProcessor.__call__", requirement="pandas_indexing"
            ) from exc

        if self.run_checks:
            assert_index_is_multiindex(in_emissions)
            assert_data_is_all_numeric(in_emissions)
            assert_has_index_levels(in_emissions, ["variable", "unit"])

            # Negative values checking
            co2_locator = ismatch(variable="**CO2**")
            non_co2 = in_emissions.loc[~co2_locator]
            keep_condition = (non_co2 >= 0.0) | non_co2.isnull()
            rows_unexpected_negative = ~keep_condition.all(axis=1)

            if rows_unexpected_negative.any():
                negatives = (
                    non_co2.loc[rows_unexpected_negative]
                    .reset_index()[["model", "scenario", "region", "variable"]]
                    .to_string(index=False)
                )
                msg = f"Below threshold values found in: \n {negatives}"
                raise ValueError(msg)

        rp = partial(
            run_parallel_pre_processing,
            progress=self.progress,
            n_processes=self.n_processes,
        )

        if self.reclassifications is not None:
            # TODO: switch to using something like the ScenarioMIP reaggregator.
            # The reason we want to use this is that we want to check reporting
            # consistency and re-aggregation together,
            # so we can give sensible error messages.
            in_emissions = rp(  # type: ignore
                in_emissions,
                func_to_call=reclassify_variables,
                progress_bar_desc="For each model-scenario, reclassifying variables",
                reclassifications=self.reclassifications,
            )

        res: pd.DataFrame = in_emissions.loc[isin(variable=self.emissions_out)]

        # Interpolate to annual steps
        for y in range(2010, 2100 + 1):
            if y not in res:
                res.loc[:, y] = nan

        res = res.T.interpolate(method="index").T.sort_index(axis="columns")

        # Convert to gcages naming conventions
        res = rename_variables(
            res,
            from_convention=SupportedNamingConventions.CMIP7_SCENARIOMIP,
            to_convention=SupportedNamingConventions.GCAGES,
        )
        res = strip_pint_incompatible_characters_from_units(
            res, units_index_level="unit"
        )

        return res

    @classmethod
    def from_sci_june2026_config(
        cls,
        run_checks: bool = True,
        progress: bool = True,
        n_processes: int | None = multiprocessing.cpu_count(),
    ) -> SCIJune2026PreProcessor:
        """
        Initialise from config that was used in the June 2026 SCI release

        Parameters
        ----------
        run_checks
            Should checks of the input and output data be performed?

            If this is turned off, things are faster,
            but error messages are much less clear if things go wrong.

        progress
            Should a progress bar be shown for each operation?

        n_processes
            Number of processes to use for parallel processing.

            Set to `None` to process in serial.

        Returns
        -------
        :
            Initialised Pre-processor
        """
        # In the CMIP7_SCENARIOMIP naming convention,
        # i.e. what we expect to receive as input
        emissions_out = (
            "Emissions|BC",
            "Emissions|C2F6",
            "Emissions|C6F14",
            "Emissions|CF4",
            "Emissions|CO",
            # "Emissions|CO2", # Not used
            "Emissions|CO2|AFOLU",
            "Emissions|CO2|Energy and Industrial Processes",
            "Emissions|CH4",
            # "Emissions|F-Gases",  # Not used
            # "Emissions|HFC",  # Not used
            "Emissions|HFC|HFC125",
            "Emissions|HFC|HFC134a",
            "Emissions|HFC|HFC143a",
            "Emissions|HFC|HFC227ea",
            "Emissions|HFC|HFC23",
            "Emissions|HFC|HFC245fa",
            "Emissions|HFC|HFC32",
            "Emissions|HFC|HFC43-10",
            # "Emissions|Kyoto Gases",  # Not used
            "Emissions|N2O",
            "Emissions|NH3",
            "Emissions|NOx",
            "Emissions|OC",
            # "Emissions|PFC",  # Not used
            "Emissions|SF6",
            "Emissions|Sulfur",
            "Emissions|VOC",
        )
        reclassifications = {
            "Emissions|CO2|Energy and Industrial Processes": (
                "Emissions|CO2|Other",
                "Emissions|CO2|Waste",
                "Emissions|CO2|Other Capture and Removal",
                "Emissions|CO2|Product Use",
            )
        }

        return cls(
            emissions_out=emissions_out,
            reclassifications=reclassifications,
            run_checks=run_checks,
            n_processes=n_processes,
            progress=progress,
        )

emissions_out instance-attribute

emissions_out: tuple[str, ...]

Names of emissions that can be included in the result of pre-processing

Not all these emissions need to be there, but any names which are not in this list will be removed as part of pre-processing.

n_processes class-attribute instance-attribute

n_processes: int | None = cpu_count()

Number of processes to use for parallel processing.

Set to None to process in serial.

progress class-attribute instance-attribute

progress: bool = True

Should progress bars be shown for each operation?

reclassifications class-attribute instance-attribute

reclassifications: Mapping[str, tuple[str, ...]] | None = (
    None
)

Variables that should be reclassified as being part of another variable

Form:

{
    variable_to_add_to: (variable_to_rename_1, variable_to_rename_2),
    ...
}

For example

{
    "Emissions|CO2|Energy and Industrial Processes": (
        "Emissions|CO2|Other",
        "Emissions|CO2|Waste",
    )
}

run_checks class-attribute instance-attribute

run_checks: bool = True

If True, run checks on both input and output data

If you are sure about your workflow, you can disable the checks to speed things up (but we don't recommend this unless you really are confident about what you're doing).

__call__

__call__(in_emissions: DataFrame) -> DataFrame

Pre-process

Parameters:

Name	Type	Description	Default
in_emissions	DataFrame	Emissions to pre-process	required

Returns:

Type	Description
DataFrame	Pre-processed emissions

Source code in src/gcages/sci_june_2026/pre_processing.py

def __call__(self, in_emissions: pd.DataFrame) -> pd.DataFrame:
    """
    Pre-process

    Parameters
    ----------
    in_emissions
        Emissions to pre-process

    Returns
    -------
    :
        Pre-processed emissions
    """
    try:
        from pandas_indexing.selectors import isin, ismatch  # noqa: PLC0415
    except ImportError as exc:
        raise MissingOptionalDependencyError(
            "SCIPreProcessor.__call__", requirement="pandas_indexing"
        ) from exc

    if self.run_checks:
        assert_index_is_multiindex(in_emissions)
        assert_data_is_all_numeric(in_emissions)
        assert_has_index_levels(in_emissions, ["variable", "unit"])

        # Negative values checking
        co2_locator = ismatch(variable="**CO2**")
        non_co2 = in_emissions.loc[~co2_locator]
        keep_condition = (non_co2 >= 0.0) | non_co2.isnull()
        rows_unexpected_negative = ~keep_condition.all(axis=1)

        if rows_unexpected_negative.any():
            negatives = (
                non_co2.loc[rows_unexpected_negative]
                .reset_index()[["model", "scenario", "region", "variable"]]
                .to_string(index=False)
            )
            msg = f"Below threshold values found in: \n {negatives}"
            raise ValueError(msg)

    rp = partial(
        run_parallel_pre_processing,
        progress=self.progress,
        n_processes=self.n_processes,
    )

    if self.reclassifications is not None:
        # TODO: switch to using something like the ScenarioMIP reaggregator.
        # The reason we want to use this is that we want to check reporting
        # consistency and re-aggregation together,
        # so we can give sensible error messages.
        in_emissions = rp(  # type: ignore
            in_emissions,
            func_to_call=reclassify_variables,
            progress_bar_desc="For each model-scenario, reclassifying variables",
            reclassifications=self.reclassifications,
        )

    res: pd.DataFrame = in_emissions.loc[isin(variable=self.emissions_out)]

    # Interpolate to annual steps
    for y in range(2010, 2100 + 1):
        if y not in res:
            res.loc[:, y] = nan

    res = res.T.interpolate(method="index").T.sort_index(axis="columns")

    # Convert to gcages naming conventions
    res = rename_variables(
        res,
        from_convention=SupportedNamingConventions.CMIP7_SCENARIOMIP,
        to_convention=SupportedNamingConventions.GCAGES,
    )
    res = strip_pint_incompatible_characters_from_units(
        res, units_index_level="unit"
    )

    return res

from_sci_june2026_config classmethod

from_sci_june2026_config(
    run_checks: bool = True,
    progress: bool = True,
    n_processes: int | None = cpu_count(),
) -> SCIJune2026PreProcessor

Initialise from config that was used in the June 2026 SCI release

Parameters:

Name	Type	Description	Default
run_checks	bool	Should checks of the input and output data be performed? If this is turned off, things are faster, but error messages are much less clear if things go wrong.	True
progress	bool	Should a progress bar be shown for each operation?	True
n_processes	int | None	Number of processes to use for parallel processing. Set to None to process in serial.	cpu_count()

Returns:

Type	Description
SCIJune2026PreProcessor	Initialised Pre-processor

Source code in src/gcages/sci_june_2026/pre_processing.py

@classmethod
def from_sci_june2026_config(
    cls,
    run_checks: bool = True,
    progress: bool = True,
    n_processes: int | None = multiprocessing.cpu_count(),
) -> SCIJune2026PreProcessor:
    """
    Initialise from config that was used in the June 2026 SCI release

    Parameters
    ----------
    run_checks
        Should checks of the input and output data be performed?

        If this is turned off, things are faster,
        but error messages are much less clear if things go wrong.

    progress
        Should a progress bar be shown for each operation?

    n_processes
        Number of processes to use for parallel processing.

        Set to `None` to process in serial.

    Returns
    -------
    :
        Initialised Pre-processor
    """
    # In the CMIP7_SCENARIOMIP naming convention,
    # i.e. what we expect to receive as input
    emissions_out = (
        "Emissions|BC",
        "Emissions|C2F6",
        "Emissions|C6F14",
        "Emissions|CF4",
        "Emissions|CO",
        # "Emissions|CO2", # Not used
        "Emissions|CO2|AFOLU",
        "Emissions|CO2|Energy and Industrial Processes",
        "Emissions|CH4",
        # "Emissions|F-Gases",  # Not used
        # "Emissions|HFC",  # Not used
        "Emissions|HFC|HFC125",
        "Emissions|HFC|HFC134a",
        "Emissions|HFC|HFC143a",
        "Emissions|HFC|HFC227ea",
        "Emissions|HFC|HFC23",
        "Emissions|HFC|HFC245fa",
        "Emissions|HFC|HFC32",
        "Emissions|HFC|HFC43-10",
        # "Emissions|Kyoto Gases",  # Not used
        "Emissions|N2O",
        "Emissions|NH3",
        "Emissions|NOx",
        "Emissions|OC",
        # "Emissions|PFC",  # Not used
        "Emissions|SF6",
        "Emissions|Sulfur",
        "Emissions|VOC",
    )
    reclassifications = {
        "Emissions|CO2|Energy and Industrial Processes": (
            "Emissions|CO2|Other",
            "Emissions|CO2|Waste",
            "Emissions|CO2|Other Capture and Removal",
            "Emissions|CO2|Product Use",
        )
    }

    return cls(
        emissions_out=emissions_out,
        reclassifications=reclassifications,
        run_checks=run_checks,
        n_processes=n_processes,
        progress=progress,
    )

create_scijune2026_harmoniser

create_scijune2026_harmoniser(
    historical_emissions_file: Path,
    aneris_overrides_file: Path,
    harmonisation_year: int = 2023,
    run_checks: bool = True,
    progress: bool = True,
    n_processes: int | None = cpu_count(),
) -> AnerisHarmoniser

Create an Aneris harmoniser configured for SCI June 2026 harmoniser.

Parameters:

Name	Type	Description	Default
historical_emissions_file	Path	File containing CMIP7 ScenarioMIP historical emissions.	required
aneris_overrides_file	Path	File containing aneris overrides for the global workflow.	required
harmonisation_year	int	Year in which to harmonise	2023
run_checks	bool	Should checks of input and output data be performed?	True
progress	bool	Should progress bars be shown?	True
n_processes	int | None	Number of processes to use for parallel processing.	cpu_count()

Returns:

Type	Description
AnerisHarmoniser	Harmoniser that will behave in line with CMIP7 ScenarioMIP's global workflow

Source code in src/gcages/sci_june_2026/harmonisation.py

def create_scijune2026_harmoniser(  # noqa: PLR0913
    historical_emissions_file: Path,
    aneris_overrides_file: Path,
    harmonisation_year: int = 2023,
    run_checks: bool = True,
    progress: bool = True,
    n_processes: int | None = multiprocessing.cpu_count(),
) -> AnerisHarmoniser:
    """
    Create an Aneris harmoniser configured for SCI June 2026 harmoniser.

    Parameters
    ----------
    historical_emissions_file
        File containing CMIP7 ScenarioMIP historical emissions.

    aneris_overrides_file
        File containing aneris overrides for the global workflow.

    harmonisation_year
        Year in which to harmonise

    run_checks
        Should checks of input and output data be performed?

    progress
        Should progress bars be shown?

    n_processes
        Number of processes to use for parallel processing.

    Returns
    -------
    :
        Harmoniser that will behave in line with CMIP7 ScenarioMIP's global workflow
    """
    historical_emissions = load_historical_emissions(
        historical_emissions_file,
    )

    aneris_overrides = load_aneris_overrides_file(aneris_overrides_file)
    aneris_overrides_df = aneris_overrides.to_frame(name="method")

    updated_df = rename_variables(
        aneris_overrides_df,
        from_convention=SupportedNamingConventions.CMIP7_SCENARIOMIP,
        to_convention=SupportedNamingConventions.GCAGES,
    )
    aneris_overrides = updated_df["method"]

    return AnerisHarmoniser(
        historical_emissions=historical_emissions,
        harmonisation_year=harmonisation_year,
        aneris_overrides=aneris_overrides,
        run_checks=run_checks,
        progress=progress,
        n_processes=n_processes,
    )

create_scijune2026_infiller

create_scijune2026_infiller(
    infilling_leader_emissions_file: Path,
    ghg_inversions_file: Path,
    historical_emissions_file: Path,
    harmonisation_year: int = 2023,
    pre_industrial_year: int = 1750,
    run_checks: bool = True,
    ur: UnitRegistry | None = None,
) -> CMIP7ScenarioMIPInfiller

Infiller that follows the same logic as was used in SCI

Parameters:

Name	Type	Description	Default
infilling_leader_emissions_file	Path	Infilling leaders database file for infilling leader emissions.	required
ghg_inversions_file	Path	Green house gasses inversion dataframe file.	required
historical_emissions_file	Path	Historical emissions file used for harmonisation	required
harmonisation_year	int	Year in which to harmonise	2023
pre_industrial_year	int	Pre-Industrial year	1750
run_checks	bool	If True, run checks on both input and output data If you are sure about your workflow, you can disable the checks to speed things up (but we don't recommend this unless you really are confident about what you're doing).	True
ur	UnitRegistry | None	UnitRegistry	None

Returns:

Type	Description
CMIP7ScenarioMIPInfiller

Source code in src/gcages/sci_june_2026/infilling.py

def create_scijune2026_infiller(  # noqa: PLR0913
    infilling_leader_emissions_file: Path,
    ghg_inversions_file: Path,
    historical_emissions_file: Path,
    harmonisation_year: int = 2023,
    pre_industrial_year: int = 1750,
    run_checks: bool = True,
    ur: UnitRegistry | None = None,
) -> CMIP7ScenarioMIPInfiller:
    """
    Infiller that follows the same logic as was used in SCI

    Parameters
    ----------
    infilling_leader_emissions_file
        Infilling leaders database file for infilling leader emissions.

    ghg_inversions_file
        Green house gasses inversion dataframe file.

    historical_emissions_file
        Historical emissions file used for harmonisation

    harmonisation_year
        Year in which to harmonise

    pre_industrial_year
        Pre-Industrial year

    run_checks
        If `True`, run checks on both input and output data

        If you are sure about your workflow,
        you can disable the checks to speed things up
        (but we don't recommend this unless you really
        are confident about what you're doing).

    ur
        UnitRegistry

    Returns
    -------
    :
    """
    if ur is None:
        try:
            import openscm_units  # noqa: PLC0415

            ur = openscm_units.unit_registry
        except ImportError as exc:
            raise MissingOptionalDependencyError(
                "openscm_units",
                requirement="openscm_units",
            ) from exc

    infilling_leader_emissions = load_timeseries_csv(
        infilling_leader_emissions_file,
        lower_column_names=True,
        index_columns=["model", "scenario", "region", "variable", "unit"],
        out_columns_type=int,
    )
    # CMIP7 GHG inversions
    ghg_inversions = load_timeseries_csv(
        ghg_inversions_file,
        lower_column_names=True,
        index_columns=["model", "scenario", "region", "variable", "unit"],
        out_columns_type=int,
    )
    # History
    historical_emissions = load_historical_emissions(
        historical_emissions_file=historical_emissions_file,
    )
    # Use gcages naming convention.
    infilling_leader_emissions = rename_variables(
        infilling_leader_emissions,
        from_convention=SupportedNamingConventions.CMIP7_SCENARIOMIP,
        to_convention=SupportedNamingConventions.GCAGES,
    )
    ghg_inversions = rename_variables(
        ghg_inversions,
        from_convention=SupportedNamingConventions.OPENSCM_RUNNER,
        to_convention=SupportedNamingConventions.GCAGES,
    )

    if run_checks:
        assert_harmonised(
            infilling_leader_emissions,
            history=historical_emissions.reset_index(
                level=[
                    lvl
                    for lvl in ["model", "scenario"]
                    if lvl in historical_emissions.index.names
                ],
                drop=True,
            ),
            harmonisation_time=harmonisation_year,
            history_unit_level="unit",
            ur=ur,
        )

    # Notes: currently this uses RMSClosest under the hood.
    # That's probably not a bad decision, and avoids the OC-BC decoupling from AR6.
    # Can be investigated more in future in other applications.
    return CMIP7ScenarioMIPInfiller(
        infilling_db=infilling_leader_emissions,
        historical_emissions=historical_emissions,
        cmip7_ghg_inversions=ghg_inversions,
        harmonisation_year=harmonisation_year,
        pre_industrial_year=pre_industrial_year,
        run_checks=run_checks,
        # TODO: add something like this back in
        # progress=progress,
        ur=ur,
    )

load_historical_emissions

load_historical_emissions(
    historical_emissions_file: Path,
) -> DataFrame

Load historical emissions for harmonisation.

Parameters:

Name	Type	Description	Default
historical_emissions_file	Path	Path from which to load the file	required

Returns:

Type	Description
DataFrame	Historical emissions in GCAGES format

Source code in src/gcages/sci_june_2026/harmonisation.py

def load_historical_emissions(
    historical_emissions_file: Path,
) -> pd.DataFrame:
    """
    Load historical emissions for harmonisation.

    Parameters
    ----------
    historical_emissions_file
        Path from which to load the file

    Returns
    -------
    :
        Historical emissions in GCAGES format
    """
    historical_emissions = load_timeseries_csv(
        historical_emissions_file,
        lower_column_names=True,
        index_columns=["model", "scenario", "region", "variable", "unit"],
        out_columns_type=int,
    )

    # Drop out the model and scenario levels
    historical_emissions = historical_emissions.reset_index(
        historical_emissions.index.names.difference(["variable", "region", "unit"]),  # type: ignore # pandas-stubs out of date
        drop=True,
    )

    # Use gcages naming to match pre-processed outputs.
    historical_emissions = rename_variables(
        historical_emissions,
        from_convention=SupportedNamingConventions.CMIP7_SCENARIOMIP,
        to_convention=SupportedNamingConventions.GCAGES,
    )

    return historical_emissions