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
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
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 
 80
 81
 82
 83
 84
 85
 86
 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
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 
131
132
133
134
135
136
137
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
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,
    )