Location classes

Gridpp uses two classes for describing geographical positions of datasets. The Grid class encapsulates a 2 dimensional gridded field of locations. It can be created from 2D vectors of latitude and longitude (degrees) as follows:

grid = gridpp.Grid(lats, lons)

The Points class encapsulates a 1 dimensional vector of locations. Objects can be created from 1D vectors of latitude and longitude (degrees) as follows:

points = gridpp.Points(lats, lons)

Grid and Points are used extensively in gridpp, to represent metadata about gridded fields and observations, respectively. These objects can cost a few seconds to initialize for large datasets (millions of points), however, once they are created they can be reused many times in different function calls.

Auxillary metadata fields such as altitude [m] and land area fraction [between 0 and 1] can be added as follows:

grid = gridpp.Grid(lats, lons, altitudes, land_area_fractions)
points = gridpp.Grid(lats, lons, altitudes, land_area_fractions)

Lat/lon or Cartesian coordinates

In its default mode, Grid and Points operate with latitude,longitude coordinates. The latitude/longitude coordinates are converted to 3D spherical coordinates and distances between points are calculated in 3D space. Thus distances do not follow the curvature of the earth but are straight-line distance through the earth. To use coordinates on a flat 2D plain, pass in gridpp.Cartesian as follows:

grid = gridpp.Grid(y, x, altitudes, land_area_fractions, gridpp.Cartesian)

where y and x are gridded projection coordinates in meters. All subsequent calls to these objects will then assume that the inputs are Cartesian coordinates (for example in grid.get_nearest_neighbour() below).

For functions that expect several Grid or Points objects, all such objects must be of the same coordinate type (for example in downscaling functions. That is, you cannot mix Geodetic and Cartesian coordinates in the same function call.

Getting nearest neighbours

Both classes have efficient methods for retrieving the nearest point, the nearest N points, and all points within a specified radius. Grid and Points use the helper class KDTree, which uses the rtree implementation in boost.

index = grid.get_nearest_neighbour(lat, lon)
index = points.get_nearest_neighbour(lat, lon)

This returns an index into the lats,lons arrays that the objects were initialized with. For Grid, the index is a vector of length 2, one value for each dimension. For Points the index is scalar.

To get all locations within a radius [m], use:

indices = grid.get_neighbours(lat, lon, radius)
indices = points.get_neighbours(lat, lon, radius)

These functions return a vector of indices, one for each neighbour.

To get the num nearest locations, use:

indices = grid.get_closest_neighbours(lat, lon, num)
indices = points.get_closest_neighbours(lat, lon, num)