cf.DimensionCoordinate.get_bounds

DimensionCoordinate.get_bounds(create=False, insert=False, bound=None, cellsize=None, flt=0.5, max=None, min=None, copy=True)[source]

Get or create the cell bounds.

Either return its existing bounds or, if there are none, optionally create bounds based on the coordinate array values.

Parameters:
create: bool, optional

If True then create bounds if and only if the the dimension coordinate does not already have them. Bounds for Voronoi cells are created unless bound or cellsize is set.

insert: bool, optional

If True then insert the created bounds into the coordinate in place. By default the created bounds are not inserted. Ignored if create is not True.

bound: optional

If set to a value larger (smaller) than the largest (smallest) coordinate value then bounds are created which include this value and for which each coordinate is in the centre of its bounds. Ignored if create is False.

cellsize: optional

Define the exact size of each cell that is created. Created cells are allowed to overlap do not have to be contigious. Ignored if create is False. The cellsize parameter may be one of:

  • A data-like scalar (see below) that defines the cell size, either in the same units as the coordinates or in the units provided. Note that in this case, the position of each coordinate within the its cell is controlled by the flt parameter.

    Example:

    To specify cellsizes of 10, in the same units as the coordinates: cellsize=10.

    Example:

    To specify cellsizes of 1 day: cellsize=cf.Data(1, 'day') (see cf.Data for details).

    Example:

    For coordinates 1, 2, 10, setting cellsize=1 will result in bounds of (0.5, 1.5), (1.5, 2.5), (9.5, 10.5).

    Example:

    For coordinates 1, 2, 10 kilometres, setting cellsize=cf.Data(5000, 'm') will result in bounds of (-1.5, 3.5), (-0.5, 4.5), (7.5, 12.5) (see cf.Data for details).

    Example:

    For decreasing coordinates 2, 0, -12 setting, cellsize=2 will result in bounds of (3, 1), (1, -1), (-11, -13).

  • A cf.TimeDuration defining the cell size. Only applicable to reference time coordinates. It is possible to “anchor” the cell bounds via the cf.TimeDuration parameters. For example, to specify cell size of one calendar month, starting and ending on the 15th day: cellsize=cf.M(day=15) (see cf.M for details). Note that the flt parameter is ignored in this case.

    Example:

    For coordinates 1984-12-01 12:00, 1984-12-02 12:00, 2000-04-15 12:00 setting, cellsize=cf.D() will result in bounds of (1984-12-01, 1984-12-02), (1984-12-02, 1984-12-03), (2000-05-15, 2000-04-16) (see cf.D for details).

    Example:

    For coordinates 1984-12-01, 1984-12-02, 2000-04-15 setting, cellsize=cf.D() will result in bounds of (1984-12-01, 1984-12-02), (1984-12-02, 1984-12-03), (2000-05-15, 2000-04-16) (see cf.D for details).

    Example:

    For coordinates 1984-12-01, 1984-12-02, 2000-04-15 setting, cellsize=cf.D(hour=12) will result in bounds of (1984-11:30 12:00, 1984-12-01 12:00), (1984-12-01 12:00, 1984-12-02 12:00), (2000-05-14 12:00, 2000-04-15 12:00) (see cf.D for details).

    Example:

    For coordinates 1984-12-16 12:00, 1985-01-16 12:00 setting, cellsize=cf.M() will result in bounds of (1984-12-01, 1985-01-01), (1985-01-01, 1985-02-01) (see cf.M for details).

    Example:

    For coordinates 1984-12-01 12:00, 1985-01-01 12:00 setting, cellsize=cf.M() will result in bounds of (1984-12-01, 1985-01-01), (1985-01-01, 1985-02-01) (see cf.M for details).

    Example:

    For coordinates 1984-12-01 12:00, 1985-01-01 12:00 setting, cellsize=cf.M(day=20) will result in bounds of (1984-11-20, 1984-12-20), (1984-12-20, 1985-01-20) (see cf.M for details).

    Example:

    For coordinates 1984-03-01, 1984-06-01 setting, cellsize=cf.Y() will result in bounds of (1984-01-01, 1985-01-01), (1984-01-01, 1985-01-01) (see cf.Y for details). Note that in this case each cell has the same bounds. This because cf.Y() is equivalent to cf.Y(month=1, day=1) and the closest 1st January to both coordinates is 1st January 1984.

A data-like scalar object is any object containing scalar data which could be used to create a cf.Data object.

Example:

Instances, x, of following types are all examples of scalar data-like objects (because cf.Data(x) creates a valid cf.Data object): int, float, str, and scalar-valued numpy.ndarray, cf.Data, cf.Coordinate, cf.Field.

flt: float, optional

When creating cells with sizes specified by the cellsize parameter, define the fraction of the each cell which is less its coordinate value. By default flt is 05, so that each cell has its coordinate at it’s centre. Ignored if cellsize is not set.

Example:

For coordinates 1, 2, 10, setting cellsize=1, flt=0.5 will result in bounds of (0.5, 1.5), (1.5, 2.5), (9.5, 10.5).

Example:

For coordinates 1, 2, 10, setting cellsize=1, flt=0.25 will result in bounds of (0.75, 1.75), (1.75, 2.75), (9.75, 10.75).

Example:

For decreasing coordinates 2, 0, -12, setting cellsize=6, flt=0.9 will result in bounds of (2.6, -3.4), (0.6, -5.4), (-11.4, -17.4).

min: optional

Limit the created bounds to be no less than this number.

Example:

To ensure that all latitude bounds are at least -90: min=-90.

max: optional

Limit the created bounds to be no more than this number.

Example:

To ensure that all latitude bounds are at most 90: max=90.

copy: bool, optional

If False then the returned bounds are not independent of the existing bounds, if any, or those inserted, if create and insert are both True. By default the returned bounds are independent.

Returns:
out: cf.Bounds

The existing or created bounds.

Examples:
>>> c.get_bounds()
>>> c.get_bounds(create=True)
>>> c.get_bounds(create=True, bound=60)
>>> c.get_bounds(create=True, insert=True)
>>> c.get_bounds(create=True, bound=-9000.0, insert=True, copy=False)