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 (iris.cube.Cube) – The cube containing ‘from_coord’. The new coord will be added into it.
name (str) – Name of the created coordinate.
from_coord (iris.coords.Coord or str) – Coordinate in ‘cube’, or the name of one.
category_function (callable) – Function(coordinate, value), returning a category value for a coordinate point-value.
units (str, default="1") – Units of the category value, typically ‘no_unit’ or ‘1’.

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 to True 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’.

iris.coord_categorisation.add_weekday_number(cube, coord, name='weekday_number')[source]#: Add a categorical weekday coordinate, values 0..6 [0=Monday].

iris.coord_categorisation.add_year(cube, coord, name='year')[source]#: Add a categorical calendar-year coordinate.