Cube coordinate functionality — aeolus 0.4.9+9.g5a71939.dirty documentation

# Cube coordinate functionality

class aeolus.coord.CoordContainer(cubes, model=<class 'aeolus.model.base.Model'>(80 fields))

  Bases: `object`

  Coordinate container.

  {x,y,z,t}

    Coordinates in the respective dimensions

    Type

      iris.coord.Coord

  __init__(cubes, model=<class 'aeolus.model.base.Model'>(80 fields))

    Instantiate an AtmosFlow object.

    Parameters

      - cubes (iris.cube.CubeList) – Atmospheric fields with necessary coordinates.

      - model (aeolus.model.Model, optional) – Model class with relevant coordinate and variable names.

aeolus.coord.add_binned_coord(cube, coord_name, bins)

  Bin coordinate points and add them as an auxiliary coordinate to a cube.

  Parameters

    - cube (iris.cube.Cube) – Cube with the given coordinate.

    - coord_name (str or iris.coords.Coord) – Coordinate name.

    - bins (array-like) – Coordinate bins.

  Returns

  Return type

    iris.cube.Cube

aeolus.coord.add_cyclic_point_to_cube(cube, coord='longitude')

  Add a cyclic point to a cube and a corresponding coordinate.

  A wrapper for cartopy.util.add_cyclic_point(), generalising it for iris cubes.

  Parameters

    - cube (iris.cube.Cube) – An n-dimensional cube of data to add a cyclic point to.

    - coord (iris.coords.Coord or str) – A 1-dimensional coordinate which specifies the coordinate values for the dimension the cyclic point is to be added to. The coordinate values must be regularly spaced. Defaults to the “x”-coordinate.

  Returns

    The cube with a cyclic point added.

  Return type

    cyclic_cube

aeolus.coord.add_planet_calendar(cube, time_coord, days_in_year, days_in_month, days_in_day, run_start_day=0, seasons=('djf', 'mam', 'jja', 'son'), planet='planet')

  Add an auxiliary time axis with the non-Earth period lengths.

  Parameters

    - cube (iris.cube.Cube) – Input cube.

    - time_coord (iris.coords.Coord or str) – Original time coordinate of the cube.

    - days_in_year (int or float) – Number of Earth days in one year on the given planet.

    - days_in_month (int or float) – Number of Earth days in one month on the given planet.

    - days_in_day (int or float) – Number of Earth days in one day on the given planet (e.g. ~16 for Titan).

    - run_start_day (int or float, optional) – Earth day of the start of the simulation.

    - seasons (tuple, optional) – Sequences of letters corresponding to month names.

    - planet (str, optional) – Name of the planet to be used to name the new coordinate.

aeolus.coord.area_weights_cube(cube, r_planet=None, normalize=False, model=<class 'aeolus.model.base.Model'>(80 fields))

  Create a cube of area weights for an arbitrary planet.

  Parameters

    - cube (iris.cube.Cube) – Cube with longitude and latitude coordinates

    - r_planet (float, optional) – Radius of the planet (m). If not given, an attempt is made to get it from the cube metadata.

    - normalize (bool, optional) – Normalize areas.

    - model (aeolus.model.Model, optional) – Model class with relevant coordinate names.

  Returns

    Cube of area weights with the same metadata as the input cube

  Return type

    iris.cube.Cube

aeolus.coord.check_coords(cubes)

  Check the cubes coordinates for consistency.

aeolus.coord.coarsen_cube(cube, lon_bins, lat_bins, model=<class 'aeolus.model.base.Model'>(80 fields))

  Block-average cube in longitude and latitude.

  Note: no weighting is applied!

  Parameters

    - cube (iris.cube.Cube) – Cube with longitude and latitude coordinates.

    - lon_bins (array-like) – Longitude bins.

    - lat_bins (array-like) – Latitude bins.

    - model (aeolus.model.Model, optional) – Model class with relevant coordinate names.

  Returns

  Return type

    iris.cube.Cube

aeolus.coord.coord_to_cube(cube, coord, broadcast=True)

  Convert coordinate points to a cube with the same dimensions.

  Parameters

    - cube (iris.cube.Cube) – Cube containing the coordinate to be broadcast.

    - coord (str or iris.coords.Coord) – Coordinate to be broadcast.

    - broadcast (bool, optional) – Broadcast the coordinate points to the shape of the cube.

  Returns

    Cube of broadcast coordinate.

  Return type

    iris.cube.Cube

aeolus.coord.coord_delta_to_cube(cube, coord, normalize=False)

  Convert 1D coordinate spacings to a cube of the same dimension as the given cube.

  Parameters

    - cube (iris.cube.Cube) – Cube containing the coordinate to be broadcast.

    - coord (str or iris.coords.Coord) – Coordinate to be broadcast.

    - normalize (bool, optional) – Normalize the data.

  Returns

    Cube of broadcast coordinate deltas.

  Return type

    iris.cube.Cube

aeolus.coord.ensure_bounds(cube, coords=('x', 'y'), model=<class 'aeolus.model.base.Model'>(80 fields))

  Auto-generate bounds for cube coordinates.

aeolus.coord.get_cube_datetimes(cube, model=<class 'aeolus.model.base.Model'>(80 fields))

  Convert points of a cube’s time coordinate to datetimes.

  Parameters

    - cube (iris.cube.Cube) – Cube containing a time coordinate.

    - model (aeolus.model.Model, optional) – Model class with relevant coordinate names.

  Returns

    Array of datetime-like objects.

  Return type

    numpy.array

aeolus.coord.get_cube_rel_days(cube, model=<class 'aeolus.model.base.Model'>(80 fields))

  Convert points of a cube’s time coordinate to relative number of days.

  Parameters

    - cube (iris.cube.Cube) – Cube containing a time coordinate.

    - model (aeolus.model.Model, optional) – Model class with relevant coordinate names.

  Returns

    Array of relative days.

  Return type

    numpy.array

aeolus.coord.get_dim_coord(cube, axis)

  Return a coordinate from a cube based on the axis it represents.

  Uses `iris.util.guess_coord_axis()` to heuristically match a dimensional coordinate with the requested axis.

  Adapted from https://github.com/LSaffin/iris-extensions

  Parameters

    - cube (iris.cube.Cube) – Cube with the desired coordinate.

    - axis (str) – The co-ordinate axis to take from the cube. Must be one of X, Y, Z, T.

  Returns

    The dimensional coordinate matching the requested axis on the given cube.

  Return type

    iris.coords.DimCoord

  Raises

    - ArgumentError – If axis is not one of {X, Y, Z, T}.:

    - NotFoundError – If the cube does not contain a coord with the requested axis.:

aeolus.coord.get_xy_coords(cube, model=<class 'aeolus.model.base.Model'>(80 fields))

  Return X and Y coordinate tuple for a given cube using names from a given model container.

  Parameters

    - cube (iris.cube.Cube) – Input cube.

    - model (aeolus.model.Model, optional) – Model class with relevant coordinate and variable names.

aeolus.coord.isel(obj, coord, idx, skip_not_found=None)

  Slice cubes by an index of a coordinate (index-selector).

  Parameters

    - obj (iris.cube.Cube or iris.cube.CubeList) – Cube or list of cubes.

    - coord (str or iris.coords.Coord) – Coordinate for selection.

    - idx (int) – Index along the given coordinate.

    - skip_not_found (bool or str, optional) – Skip if coordinate not found. By default it is active when dealing with a cube list and inactive if dealing with a single cube.

  Returns

    Slice along the coordinate.

  Return type

    iris.cube.Cube or iris.cube.CubeList

aeolus.coord.interp_all_to_pres_lev(cubelist, levels, interpolator=None, model=<class 'aeolus.model.base.Model'>(80 fields))

  Interpolate all cubes within a cubelist to the given set of pressure levels.

  Parameters

    - cubelist (iris.cube.CubeList) – List of cubes, including a cube of pressure.

    - levels (array-like) – Sequence of pressure levels (same units as the units of pressure cube in cubelist).

    - interpolator (callable or None) – The interpolator to use when computing the interpolation. See relevel() docs for more.

    - model (aeolus.model.Model, optional) – Model class with relevant variable names.

  Returns

    List of cubes interpolated to pressure level(s).

  Return type

    iris.cube.CubeList

aeolus.coord.interp_to_cube_time(cube_src, cube_tgt, model=<class 'aeolus.model.base.Model'>(80 fields))

  Linearly interpolate cube_src to cube_tgt along the time dimension (model.t).

  Forecast period is copied from cube_tgt.

  Parameters

    - cube_src (iris.cube.Cube) – Cube to interpolate.

    - cube_tgt (iris.cube.Cube) – Cube with time dimension to interpolate to.

    - model (aeolus.model.Model, optional) – Model class with relevant variable names.

  Returns

    Cube with the time dimension equal to cube_tgt.

  Return type

    iris.cube.Cube

aeolus.coord.interp_to_pres_lev(cubelist, constraint, levels, interpolator=None, model=<class 'aeolus.model.base.Model'>(80 fields))

  Interpolate a cube to pressure level(s) using stratify relevel() function.

  Parameters

    - cubelist (iris.cube.CubeList) – List of cubes containing a cube extractable by constraint and a cube of pressure.

    - constraint (str or iris.Constraint) – Variable name or constraint to extract a cube from cubelist.

    - levels (array-like) – Sequence of pressure levels (same units as the units of pressure cube in cubelist).

    - interpolator (callable or None) – The interpolator to use when computing the interpolation. See relevel() docs for more.

    - model (aeolus.model.Model, optional) – Model class with relevant variable names.

  Returns

    Cube of varname interpolated to pressure level(s).

  Return type

    iris.cube.Cube

aeolus.coord.interp_to_single_pres_lev(cubelist, constraint, p_ref_frac=0.5, const=None, interpolator=None, model=<class 'aeolus.model.base.Model'>(80 fields))

  Interpolate the field defined by constraint to a single pressure level.

  The level is found from the given fraction of the reference surface pressure.

  Parameters

    - cubelist (iris.cube.CubeList) – Input cubelist.

    - constraint (str or iris.Constraint) – Variable name or constraint to extract a cube from cubelist.

    - p_ref_frac (float, optional) – Fraction of reference surface pressure at which the estimate is made. The default value is 0.1, which for an Earth-like atmosphere means 100 hPa.

    - const (aeolus.const.const.ConstContainer, optional) – If not given, constants are attempted to be retrieved from attributes of a cube in the cube list.

    - interpolator (callable or None) – The interpolator to use when computing the interpolation. See relevel() docs for more.

    - model (aeolus.model.Model, optional) – Model class with relevant variable names.

  Returns

    Cube on a single pressure level.

  Return type

    iris.cube.Cube

aeolus.coord.nearest_coord_value(cube, coord_name, val)

  Get the nearest value of a coordinate.

  Parameters

    - cube (iris.cube.Cube) – Cube with the coordinate

    - coord_name (str or iris.coords.Coord) – Coordinate where to look the nearest point up

    - val (int or float) – The value to find

  Returns

    Element of the coordinate array closest to the given val.

  Return type

    int or float

aeolus.coord.not_equal_coord_axes(cube1, cube2)

  Given 2 cubes, return axes of unequal dimensional coordinates.

aeolus.coord.regrid_3d(cube, target, model=<class 'aeolus.model.base.Model'>(80 fields))

  Regrid a cube in the horizontal and in the vertical on to coordinates of the target cube.

  Adapted from https://github.com/LSaffin/iris-extensions

  Parameters

    - cube (iris.cube.Cube) – The cube to be regridded.

    - target (iris.cube.Cube) – The cube to regrid to.

    - model (aeolus.model.Model, optional) – Model class with relevant coordinate names.

  Returns

  Return type

    iris.cube.Cube

aeolus.coord.replace_z_coord(cube, model=<class 'aeolus.model.base.Model'>(80 fields))

  Replace dimensional vertical coordinate.

  Parameters

    - cube (iris.cube.Cube) – Input cube.

    - model (aeolus.model.Model, optional) – Model class with relevant coordinate names.

  Returns

    Copy of the input cube with a new vertical coordinate.

  Return type

    iris.cube.Cube

aeolus.coord.roll_cube_0_360(cube_in, model=<class 'aeolus.model.base.Model'>(80 fields))

  Take a cube spanning -180…180 degrees in longitude and roll it to 0…360 degrees.

  Works with global model output, and in some cases for regional.

  Parameters

    - cube (iris.cube.Cube) – Cube with longitude and latitude coordinates.

    - model (aeolus.model.Model, optional) – Model class with a relevant longitude coordinate name.

  Returns

  Return type

    iris.cube.Cube

  See also

  `aeolus.coord.roll_cube_pm180`

aeolus.coord.roll_cube_pm180(cube_in, model=<class 'aeolus.model.base.Model'>(80 fields))

  Take a cube spanning 0…360 degrees in longitude and roll it to -180…180 degrees.

  Works with global model output, and in some cases for regional.

  Parameters

    - cube (iris.cube.Cube) – Cube with longitude and latitude coordinates.

    - model (aeolus.model.Model, optional) – Model class with a relevant longitude coordinate name.

  Returns

  Return type

    iris.cube.Cube

  See also

  `aeolus.coord.roll_cube_0_360`

aeolus.coord.vertical_cross_section_area(cube2d, r_planet=None)

  Create a cube of vertical cross-section areas in metres.

aeolus.coord.volume_weights_cube(cube, r_planet=None, normalize=False, model=<class 'aeolus.model.base.Model'>(80 fields))

  Create a cube of volume weights from a grid of a given cube.

  Parameters

    - cube (iris.cube.Cube) – Cube with longitude, latitude and height coordinates

    - r_planet (float, optional) – Radius of the planet (m). If not given, an attempt is made to get it from the cube metadata.

    - normalize (bool, optional) – Normalize the data.

    - model (aeolus.model.Model, optional) – Model class with relevant coordinate names.

  Returns

    Cube of area weights with the same metadata as the input cube

  Return type

    iris.cube.Cube