iris.coord_categorisation#
Cube functions for coordinate categorisation.
All the functions provided here add a new coordinate to a cube.
The function
add_categorised_coord()
performs a generic coordinate categorisation.The other functions all implement specific common cases (e.g.
add_day_of_month()
). Currently, these are all calendar functions, so they only apply to “Time coordinates”.
- iris.coord_categorisation.add_categorised_coord(cube, name, from_coord, category_function, units='1')[source]#
Add a new coordinate to a cube, by categorising an existing one.
Make a new
iris.coords.AuxCoord
from mapped values, and add it to the cube.- Parameters:
cube (Cube) – The cube containing ‘from_coord’. The new coord will be added into it.
name (str) – Name of the created coordinate.
from_coord (DimCoord | AuxCoord | str) – Coordinate in ‘cube’, or the name of one.
category_function (Callable) – Function(coordinate, value), returning a category value for a coordinate point-value. If
value
has a type hintcftime.datetime
, the coordinate points are translated tocftime.datetime
s before callingcategory_function
.units (str) – Units of the category value, typically ‘no_unit’ or ‘1’.
- Return type:
None
- iris.coord_categorisation.add_day_of_month(cube, coord, name='day_of_month')[source]#
Add a categorical day-of-month coordinate, values 1..31.
- iris.coord_categorisation.add_day_of_year(cube, coord, name='day_of_year')[source]#
Add a categorical day-of-year coordinate, values 1..365 (1..366 in leap years).
- iris.coord_categorisation.add_hour(cube, coord, name='hour')[source]#
Add a categorical hour coordinate, values 0..23.
- iris.coord_categorisation.add_month(cube, coord, name='month')[source]#
Add a categorical month coordinate, values ‘Jan’..’Dec’.
- iris.coord_categorisation.add_month_fullname(cube, coord, name='month_fullname')[source]#
Add a categorical month coordinate, values ‘January’..’December’.
- iris.coord_categorisation.add_month_number(cube, coord, name='month_number')[source]#
Add a categorical month coordinate, values 1..12.
- iris.coord_categorisation.add_season(cube, coord, name='season', seasons=('djf', 'mam', 'jja', 'son'))[source]#
Add a categorical season-of-year coordinate, with user specified seasons.
- Parameters:
cube (
iris.cube.Cube
) – The cube containing ‘coord’. The new coord will be added into it.coord (
iris.coords.Coord
or str) – Coordinate in ‘cube’, or its name, representing time.name (str, default="season") – Name of the created coordinate. Defaults to “season”.
seasons (
list
of str, optional) – List of seasons defined by month abbreviations. Each month must appear once and only once. Defaults to standard meteorological seasons (‘djf’, ‘mam’, ‘jja’, ‘son’).
- iris.coord_categorisation.add_season_membership(cube, coord, season, name='season_membership')[source]#
Add a categorical season membership coordinate for a user specified season.
The coordinate has the value True for every time that is within the given season, and the value False otherwise.
- Parameters:
cube (
iris.cube.Cube
) – The cube containing ‘coord’. The new coord will be added into it.coord (
iris.coords.Coord
or str) – Coordinate in ‘cube’, or its name, representing time.season (str) – Season defined by month abbreviations.
name (str, default="season_membership") – Name of the created coordinate. Defaults to “season_membership”.
- iris.coord_categorisation.add_season_number(cube, coord, name='season_number', seasons=('djf', 'mam', 'jja', 'son'))[source]#
Add a categorical season-of-year coordinate.
Add a categorical season-of-year coordinate, values 0..N-1 where N is the number of user specified seasons.
- Parameters:
cube (
iris.cube.Cube
) – The cube containing ‘coord’. The new coord will be added into it.coord (
iris.coords.Coord
or str) – Coordinate in ‘cube’, or its name, representing time.name (str, default="season") – Name of the created coordinate. Defaults to “season_number”.
seasons (
list
of str, optional) – List of seasons defined by month abbreviations. Each month must appear once and only once. Defaults to standard meteorological seasons (‘djf’, ‘mam’, ‘jja’, ‘son’).
- iris.coord_categorisation.add_season_year(cube, coord, name='season_year', seasons=('djf', 'mam', 'jja', 'son'), use_year_at_season_start=False)[source]#
Add a categorical year-of-season coordinate, with user specified seasons.
- Parameters:
cube (
iris.cube.Cube
) – The cube containing coord. The new coord will be added into it.coord (
iris.coords.Coord
or str) – Coordinate in cube, or its name, representing time.name (str, default="season_year") – Name of the created coordinate.
seasons (tuple of str, default=("djf", "mam", "jja", "son")) – List of seasons defined by month abbreviations. Each month must appear once and only once. Defaults to standard meteorological seasons (
djf
,mam
,jja
,son
).use_year_at_season_start (bool, default=False) – Seasons spanning the year boundary (e.g. Winter
djf
) will belong fully to the following year by default (e.g. the year of Jan and Feb). Set toTrue
for spanning seasons to belong to the preceding year (e.g. the year of Dec) instead.
- iris.coord_categorisation.add_weekday(cube, coord, name='weekday')[source]#
Add a categorical weekday coordinate, values ‘Mon’..’Sun’.
- iris.coord_categorisation.add_weekday_fullname(cube, coord, name='weekday_fullname')[source]#
Add a categorical weekday coordinate, values ‘Monday’..’Sunday’.