Skip to content

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
rename_variables

Rename variables

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
RCMIP3

Reduced Complexity Model Intercomparison Project (RCMIP) Phase 3 naming convention
Source code in src/gcages/renaming.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
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
    """

    RCMIP3 = "rcmip3"
    """
    Reduced Complexity Model Intercomparison Project (RCMIP) Phase 3 naming convention

    See rcmip.org and https://doi.org/10.5194/egusphere-2025-5775
    """

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

RCMIP3 class-attribute instance-attribute #

RCMIP3 = 'rcmip3'

Reduced Complexity Model Intercomparison Project (RCMIP) Phase 3 naming convention

See rcmip.org and https://doi.org/10.5194/egusphere-2025-5775

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:

Name Type Description Default
variable_in str

Variable name to convert

 required
from_convention SupportedNamingConventions

Convention to convert from

 required
to_convention SupportedNamingConventions

Convention to convert to

 required
database DataFrame

Database to use for the conversions

 EMISSIONS_VARIABLES

Returns:

Type Description
str

Converted variable name

Raises:

Type Description
UnrecognisedValueError

variable_in is not a recognised value in from_convention
Source code in src/gcages/renaming.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
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])

rename_variables #

rename_variables(
    pandas_obj: P,
    from_convention: SupportedNamingConventions,
    to_convention: SupportedNamingConventions,
    index_level: str = "variable",
    copy: bool = True,
) -> P

Rename variables

This is just a convenience function that provides a slightly simpler, if less flexible interface than using convert_variable_name directly.

Parameters:

Name Type Description Default
pandas_obj P

Pandas object in which to rename variables

 required
from_convention SupportedNamingConventions

Naming convention to convert from

 required
to_convention SupportedNamingConventions

Naming convention to convert to

 required
index_level str

Index level in which variable information is stored in pandas_obj

 'variable'
copy bool

If True a copy of pandas_obj is made. Otherwise, pandas_obj is manipulated directly.

 True

Returns:

Type Description
P

pandas_obj with index_level updated to use the naming convention specified by to_convention.
Source code in src/gcages/renaming.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def rename_variables(
    pandas_obj: P,
    from_convention: SupportedNamingConventions,
    to_convention: SupportedNamingConventions,
    index_level: str = "variable",
    copy: bool = True,
) -> P:
    """
    Rename variables

    This is just a convenience function that provides a slightly simpler,
    if less flexible interface than using [convert_variable_name][(m).] directly.

    Parameters
    ----------
    pandas_obj
        Pandas object in which to rename variables

    from_convention
        Naming convention to convert from

    to_convention
        Naming convention to convert to

    index_level
        Index level in which variable information is stored in `pandas_obj`

    copy
        If `True` a copy of `pandas_obj` is made.
        Otherwise, `pandas_obj` is manipulated directly.

    Returns
    -------
    :
        `pandas_obj` with `index_level` updated
        to use the naming convention specified by `to_convention`.
    """
    return update_index_levels_func(
        pandas_obj,
        {
            index_level: partial(
                convert_variable_name,
                from_convention=from_convention,
                to_convention=to_convention,
            )
        },
        copy=copy,
    )