Skip to content

cmip_branded_variable_mapper.temporal_label#

Determination of the temporal label

Functions:

Name Description
get_temporal_label

Get temporal label

Attributes:

Name Type Description
TEMPORAL_LABEL_CELL_METHODS_INITIAL_TESTS_MAPPER

Mapper from sub-strings of cell methods to the temporal label
TEMPORAL_LABEL_CELL_METHODS_TIME4_TESTS_MAPPER

Mapper from sub-strings of cell methods to the temporal label for "time4" data
TEMPORAL_LABEL_DIMENSIONS_MAPPER

Mapper from dimensions to the temporal label

TEMPORAL_LABEL_CELL_METHODS_INITIAL_TESTS_MAPPER module-attribute #

TEMPORAL_LABEL_CELL_METHODS_INITIAL_TESTS_MAPPER = (
    CellMethodsSubStringMapper(
        sub_string_map={
            "time: max": "tmax",
            "time: min": "tmin",
            "time: sum": "tsum",
        }
    )
)

Mapper from sub-strings of cell methods to the temporal label

These are for the 'initial tests' i.e. the cell methods which are checked first. There is a coupling with dimensions in the logic in get_temporal_label, be careful!

TEMPORAL_LABEL_CELL_METHODS_TIME4_TESTS_MAPPER module-attribute #

TEMPORAL_LABEL_CELL_METHODS_TIME4_TESTS_MAPPER = (
    CellMethodsSubStringMapper(
        sub_string_map={
            "time: max": "tmaxavg",
            "time: min": "tminavg",
        }
    )
)

Mapper from sub-strings of cell methods to the temporal label for "time4" data

I.e. for data which has "time4" as a dimension

TEMPORAL_LABEL_DIMENSIONS_MAPPER module-attribute #

TEMPORAL_LABEL_DIMENSIONS_MAPPER = DimensionMapper(
    dimension_map={
        "time": "tavg",
        "time1": "tpt",
        "time2": "tclm",
        "time3": "tclmdc",
    }
)

Mapper from dimensions to the temporal label

get_temporal_label #

get_temporal_label(
    cell_methods: str | None,
    dimensions: tuple[str, ...],
    cell_methods_initial_mapper: CellMethodsSubStringMapper = TEMPORAL_LABEL_CELL_METHODS_INITIAL_TESTS_MAPPER,
    cell_methods_initial_required_dimension: str = "time",
    dimensions_mapper: DimensionMapper = TEMPORAL_LABEL_DIMENSIONS_MAPPER,
    cell_methods_time4_mapper: CellMethodsSubStringMapper = TEMPORAL_LABEL_CELL_METHODS_TIME4_TESTS_MAPPER,
    fallback: str = "ti",
) -> str

Get temporal label

The logic this should follow is defined in Table F1 of Taylor et al.. This was last checked on June 14 2025. If updates have been made since, this code may be out of date with the underlying specification.

Parameters:

Name Type Description Default
cell_methods str | None

Cell methods of the variable

 required
dimensions tuple[str, ...]

Dimensions of the variable

 required
cell_methods_initial_mapper CellMethodsSubStringMapper

Mapper to use to get values based on cell methods

This is for the 'initial' tests i.e. checks of cell methods which are performed before any other checks.

 TEMPORAL_LABEL_CELL_METHODS_INITIAL_TESTS_MAPPER
cell_methods_initial_required_dimension str

Dimension required for the result of using cell_methods_initial_mapper to be returned.

If this dimension is not found, then the other mapping checks are performed.

 'time'
dimensions_mapper DimensionMapper

Mapper to use to get values based on dimensions

If you include "time4" as a mapping here, you can make a mess as you will effectively disable any use of cell_methods_time4_mapper.

 TEMPORAL_LABEL_DIMENSIONS_MAPPER
cell_methods_time4_mapper CellMethodsSubStringMapper

Mapper to use to get values based on cell methods if "time4" is in dimensions

 TEMPORAL_LABEL_CELL_METHODS_TIME4_TESTS_MAPPER
fallback str

Value to return if no other conditions are matched

 'ti'

Returns:

Type Description
str

Temporal label to use for constructing the branded variable name
Source code in src/cmip_branded_variable_mapper/temporal_label.py 
 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
 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
129
130
def get_temporal_label(  # noqa: PLR0913
    cell_methods: str | None,
    dimensions: tuple[str, ...],
    cell_methods_initial_mapper: CellMethodsSubStringMapper = (
        TEMPORAL_LABEL_CELL_METHODS_INITIAL_TESTS_MAPPER
    ),
    cell_methods_initial_required_dimension: str = "time",
    dimensions_mapper: DimensionMapper = TEMPORAL_LABEL_DIMENSIONS_MAPPER,
    cell_methods_time4_mapper: CellMethodsSubStringMapper = (
        TEMPORAL_LABEL_CELL_METHODS_TIME4_TESTS_MAPPER
    ),
    fallback: str = "ti",
) -> str:
    """
    Get temporal label

    The logic this should follow is defined in Table F1 of
    [Taylor et al.](https://docs.google.com/document/d/19jzecgymgiiEsTDzaaqeLP6pTvLT-NzCMaq-wu-QoOc/edit?pli=1&tab=t.0).
    This was last checked on June 14 2025.
    If updates have been made since,
    this code may be out of date with the underlying specification.

    Parameters
    ----------
    cell_methods
        Cell methods of the variable

    dimensions
        Dimensions of the variable

    cell_methods_initial_mapper
        Mapper to use to get values based on cell methods

        This is for the 'initial' tests
        i.e. checks of cell methods which are performed
        before any other checks.

    cell_methods_initial_required_dimension
        Dimension required for the result of using `cell_methods_initial_mapper`
        to be returned.

        If this dimension is not found, then the other mapping checks are performed.

    dimensions_mapper
        Mapper to use to get values based on dimensions

        If you include "time4" as a mapping here,
        you can make a mess as you will effectively
        disable any use of `cell_methods_time4_mapper`.

    cell_methods_time4_mapper
        Mapper to use to get values based on cell methods if "time4" is in dimensions

    fallback
        Value to return if no other conditions are matched

    Returns
    -------
    :
        Temporal label to use for constructing the branded variable name
    """
    if cell_methods is not None:
        # Check cell methods first
        if (match := cell_methods_initial_mapper.get_value(cell_methods)) is not None:
            if cell_methods_initial_required_dimension in dimensions:
                return match

            # We matched cell methods but not the required dimension,
            # fall through to other tests

    if (match := dimensions_mapper.get_value(dimensions)) is not None:
        return match

    if cell_methods is not None and "time4" in dimensions:
        if (match := cell_methods_time4_mapper.get_value(cell_methods)) is not None:
            return match

    return fallback