gcages.renaming

Renaming between naming conventions

At present, the naming convention for both sides is implicit. We are considering adding the concept of controlled vocabularies to help clarify this, but have not done so yet.

Classes:

Name	Description
SupportedNamingConventions	Supported naming conventions

Functions:

Name	Description
convert_variable_name	Convert a variable name to another naming convention

SupportedNamingConventions

Bases: StrEnum

Supported naming conventions

Attributes:

Name	Type	Description
AR6_CFC_INFILLING_DB		The naming convention used in AR6's CFC infilling database
CMIP7_SCENARIOMIP		The naming convention used during preparation of ScenarioMIP for CMIP7
GCAGES		This package's naming convention
IAMC		Integrated Assessment Modelling Consortium (IAMC) naming convention
OPENSCM_RUNNER		OpenSCM-Runner naminv convention
RCMIP		Reduced Complexity Model Intercomparison Project (RCMIP) naming convention

Source code in src/gcages/renaming.py

class SupportedNamingConventions(StrEnum):
    """Supported naming conventions"""

    GCAGES = "gcages"
    """This package's naming convention"""

    AR6_CFC_INFILLING_DB = "ar6_cfc_infilling_db"
    """
    The naming convention used in AR6's CFC infilling database

    Somehow this ended up being different to all the other conventions.
    """

    IAMC = "iamc"
    """
    Integrated Assessment Modelling Consortium (IAMC) naming convention

    Not a perfect definition so the implementation here is a bit of a guess
    based on experience.
    https://github.com/IAMconsortium/common-definitions
    is a better source of truth, but it also moves more quickly,
    is not used universally and covers many more variables
    than we care about within the gcages context.
    """

    CMIP7_SCENARIOMIP = "cmip7_scenariomip"
    """
    The naming convention used during preparation of ScenarioMIP for CMIP7
    """

    OPENSCM_RUNNER = "openscm_runner"
    """
    OpenSCM-Runner naminv convention

    Used by the package which actually runs simple climate models (SCMs),
    see https://github.com/openscm/openscm-runner
    """

    RCMIP = "rcmip"
    """
    Reduced Complexity Model Intercomparison Project (RCMIP) naming convention

    See rcmip.org and e.g.

    - https://rcmip-protocols-au.s3-ap-southeast-2.amazonaws.com/v5.1.0/rcmip-emissions-annual-means-v5-1-0.csv
    - https://rcmip-protocols-au.s3-ap-southeast-2.amazonaws.com/v5.1.0/rcmip-concentrations-annual-means-v5-1-0.csv
    - https://rcmip-protocols-au.s3-ap-southeast-2.amazonaws.com/v5.1.0/rcmip-radiative-forcing-annual-means-v5-1-0.csv
    """

AR6_CFC_INFILLING_DB class-attribute instance-attribute

AR6_CFC_INFILLING_DB = 'ar6_cfc_infilling_db'

The naming convention used in AR6's CFC infilling database

Somehow this ended up being different to all the other conventions.

CMIP7_SCENARIOMIP class-attribute instance-attribute

CMIP7_SCENARIOMIP = 'cmip7_scenariomip'

The naming convention used during preparation of ScenarioMIP for CMIP7

GCAGES class-attribute instance-attribute

GCAGES = 'gcages'

This package's naming convention

IAMC class-attribute instance-attribute

IAMC = 'iamc'

Integrated Assessment Modelling Consortium (IAMC) naming convention

Not a perfect definition so the implementation here is a bit of a guess based on experience. https://github.com/IAMconsortium/common-definitions is a better source of truth, but it also moves more quickly, is not used universally and covers many more variables than we care about within the gcages context.

OPENSCM_RUNNER class-attribute instance-attribute

OPENSCM_RUNNER = 'openscm_runner'

OpenSCM-Runner naminv convention

Used by the package which actually runs simple climate models (SCMs), see https://github.com/openscm/openscm-runner

RCMIP class-attribute instance-attribute

RCMIP = 'rcmip'

Reduced Complexity Model Intercomparison Project (RCMIP) naming convention

See rcmip.org and e.g.

• https://rcmip-protocols-au.s3-ap-southeast-2.amazonaws.com/v5.1.0/rcmip-emissions-annual-means-v5-1-0.csv
• https://rcmip-protocols-au.s3-ap-southeast-2.amazonaws.com/v5.1.0/rcmip-concentrations-annual-means-v5-1-0.csv
• https://rcmip-protocols-au.s3-ap-southeast-2.amazonaws.com/v5.1.0/rcmip-radiative-forcing-annual-means-v5-1-0.csv

convert_variable_name

convert_variable_name(
    variable_in: str,
    from_convention: SupportedNamingConventions,
    to_convention: SupportedNamingConventions,
    database: DataFrame = EMISSIONS_VARIABLES,
) -> str

Convert a variable name to another naming convention

Parameters

variable_in Variable name to convert

from_convention Convention to convert from

to_convention Convention to convert to

database Database to use for the conversions

Returns

: Converted variable name

Raises

UnrecognisedValueError variable_in is not a recognised value in from_convention

Source code in src/gcages/renaming.py

def convert_variable_name(
    variable_in: str,
    from_convention: SupportedNamingConventions,
    to_convention: SupportedNamingConventions,
    database: pd.DataFrame = gcages.databases.EMISSIONS_VARIABLES,
) -> str:
    """
    Convert a variable name to another naming convention

    Parameters
    ----------
    variable_in
        Variable name to convert

    from_convention
        Convention to convert from

    to_convention
        Convention to convert to

    database
        Database to use for the conversions

    Returns
    -------
    :
        Converted variable name

    Raises
    ------
    UnrecognisedValueError
        `variable_in` is not a recognised value in `from_convention`
    """
    from_key = str(from_convention)
    to_key = str(to_convention)

    res_l = database.loc[database[from_key] == variable_in, to_key].tolist()

    if len(res_l) < 1:
        raise UnrecognisedValueError(
            unrecognised_value=variable_in,
            name=f"the {from_convention} naming convention",
            known_values=sorted(list(database[from_key].tolist())),
        )

    if len(res_l) > 1:  # pragma: no cover
        raise AssertionError(res_l)

    return cast(str, res_l[0])