LatLonGrid

class unifhy.LatLonGrid(latitude, longitude, latitude_bounds, longitude_bounds)

Bases: unifhy.space.Grid

This class characterises the spatial dimension for a Component as a regular grid on a spherical domain whose coordinates are latitudes and longitudes, and whose rotation axis is aligned with the North pole (EPSG:4326).

Instantiation

Parameters

latitude: one-dimensional array-like object

The array of latitude coordinates in degrees North defining a spatial dimension of the domain. May be any type that can be cast to a numpy.ndarray. Must contain numerical values. Coordinates must be ordered from South to North. Coordinates must be regularly spaced.

Parameter example:

latitude=[15, 45, 75]

Parameter example:

latitude=numpy.arange(-89.5, 90.5, 1)

longitude: one-dimensional array-like object

The array of longitude coordinates in degrees East defining a spatial dimension of the domain. May be any type that can be cast to a numpy.ndarray. Must contain numerical values. Coordinates must be ordered from West to East. Coordinates must be regularly spaced.

Parameter example:

longitude=(-150, -90, -30, 30, 90, 150)

Parameter example:

longitude=numpy.arange(-179.5, 180.5, 1)

latitude_bounds: two-dimensional array-like object

The array of latitude coordinate bounds in degrees North defining the extent of the grid cell around the coordinate. May be any type that can be cast to a numpy.ndarray. Must be two dimensional with the first dimension equal to the size of latitude and the second dimension equal to 2. Must contain numerical values.

Parameter example:

latitude_bounds=[[0, 30], [30, 60], [60, 90]]

Parameter example:

latitude_bounds=numpy.column_stack(
    (numpy.arange(-90, 90, 1), numpy.arange(-89, 91, 1))
)

longitude_bounds: two-dimensional array-like object

The array of longitude coordinate bounds in degrees East defining the extent of the grid cell around the coordinate. May be any type that can be cast to a numpy.ndarray. Must be two dimensional with the first dimension equal to the size of longitude and the second dimension equal to 2. Must contain numerical values.

Parameter example:

longitude_bounds=((-180, -120), (-120, -60), (-60, 0)
                  (0, 60), (60, 120), (120, 180))

Parameter example:

longitude_bounds=numpy.column_stack(
    (numpy.arange(-180, 180, 1),
     numpy.arange(-179, 181, 1))
)

Examples

Instantiating grid using lists:

>>> import numpy
>>> sd = LatLonGrid(
...     latitude=[15, 45, 75],
...     longitude=[30, 90, 150],
...     latitude_bounds=[[0, 30], [30, 60], [60, 90]],
...     longitude_bounds=[[0, 60], [60, 120], [120, 180]]
... )
>>> print(sd)
LatLonGrid(
    shape {Y, X}: (3, 3)
    Y, latitude (3,): [15, 45, 75] degrees_north
    X, longitude (3,): [30, 90, 150] degrees_east
    Y_bounds (3, 2): [[0, ..., 90]] degrees_north
    X_bounds (3, 2): [[0, ..., 180]] degrees_east
)

Trying to instantiate grid with latitudes from North to South:

>>> sd = LatLonGrid(
...     latitude=[75, 45, 15],
...     longitude=[30, 90, 150],
...     latitude_bounds=[[90, 60], [60, 30], [30, 0]],
...     longitude_bounds=[[0, 60], [60, 120], [120, 180]]
... )
Traceback (most recent call last):
    ...
RuntimeError: latitude dimension not directed positively

Trying to instantiate grid with latitude cells of varying width:

>>> sd = LatLonGrid(
...     latitude=[15, 45, 75],
...     longitude=[30, 90, 150],
...     latitude_bounds=[[10, 20], [20, 70], [70, 80]],
...     longitude_bounds=[[0, 60], [60, 120], [120, 180]]
... )
Traceback (most recent call last):
    ...
RuntimeError: latitude bounds space gap not constant across region

Methods

Construction

`from_extent_and_resolution`	Instantiate a `LatLonGrid` from the extent and the resolution of latitude, longitude (and optionally altitude) coordinates.
`from_field`	Instantiate a `LatLonGrid` from spatial dimension coordinates of a `cf.Field`.

Comparison

`is_space_equal_to`	Compare equality between the `Grid` and the spatial (X, Y, and Z) dimension coordinates in a `cf.Field`.
`spans_same_region_as`	Compare equality in region spanned between the grid and another instance of `Grid`.
`is_matched_in`	Determine whether the horizontal cell bounds of the grid are overlapping with the cell bounds of another instance of `Grid`.

Utility

route

Move the given values from their current location in the Grid to their downstream/downslope location according to the flow_direction property of Grid.

Attributes

`shape`	Return the size of the `Grid` dimension axes as a `tuple`.
`axes`	Return the name of the properties to use to get access to the axes defined for the `Grid` instance as a `tuple`.
`X`	Return the X-axis of the `Grid` instance as a `cf.Data` instance.
`Y`	Return the Y-axis of the `Grid` instance as a `cf.Data` instance.
`X_bounds`	Return the bounds of the X-axis of the `Grid` instance as a `cf.Data` instance.
`Y_bounds`	Return the bounds of the Y-axis of the `Grid` instance as a `cf.Data` instance.
`X_name`	Return the name of the X-axis of the `Grid` instance as a `str`.
`Y_name`	Return the name of the Y-axis of the `Grid` instance as a `str`.
`land_sea_mask`	The land-sea mask for the `Grid` of boolean/binary values (i.e.
`flow_direction`	The information necessary to move any variable laterally (i.e.
`cell_area`	The horizontal area for the grid cells of the `Grid` in square metres given as a `cf.Field` and returned as a `numpy.ndarray`.