iris.coord_categorisation.add_season_year_preceding() #4877
Description
✨ Feature Request
Add an alternative to iris.coord_categorisation.add_season_year() which assigns seasons which span two years to the preceding year instead of the following year.
Motivation
iris.coord_categorisation.add_season_year() is an excellent feature and very handy for comparing multiple timeseries datasets. However, it has an inherent assumption that a season which spans two years (i.e. includes December and January) will be assigned to the later rather than the earlier year. We have had a usecase where we want to compare the effects of monthly climate indices to several months of meteorological data after the climate index month (since we know that specific climate indices affect the weather variables we are analysing).
Proposed change
Proposed change/addition to iris.coord_categorisation (which essentially just removes the use of _month_year_adjusts()):
def add_season_year_preceding(
cube, coord, name="season_year", seasons=("djf", "mam", "jja", "son")
):
"""
Add a categorical year-of-season coordinate, with user specified
seasons. Any season spanning two years will be assigned the preceding year.
Args:
* cube (:class:`iris.cube.Cube`):
The cube containing 'coord'. The new coord will be added into
it.
* coord (:class:`iris.coords.Coord` or string):
Coordinate in 'cube', or its name, representing time.
Kwargs:
* name (string):
Name of the created coordinate. Defaults to "season_year".
* seasons (:class:`list` of strings):
List of seasons defined by month abbreviations. Each month must
appear once and only once. Defaults to standard meteorological
seasons ('djf', 'mam', 'jja', 'son').
"""
# Check that the seasons are valid.
_validate_seasons(seasons)
# Define a categorisation function.
def _season_year(coord, value):
dt = _pt_date(coord, value)
year = dt.year
return year
# Apply the categorisation.
add_categorised_coord(cube, name, coord, _season_year)