core.geo_grid

Provides class for horizontal two-dimensional spatio-temporal grid.

class pyunicorn.core.geo_grid.GeoGrid(time_seq: ndarray, lat_seq: ndarray, lon_seq: ndarray, silence_level: int = 0)

Bases: Grid

Encapsulates a horizontal two-dimensional spatio-temporal grid on the sphere.

The spatial grid points can be arbitrarily distributed, which is useful for representing station data or geodesic grids.

static LoadTXT(filename)

Return a GeoGrid object stored in text files.

The latitude, longitude and time sequences are loaded from three separate text files.

Parameters:

filename (str) – The name of the files where the GeoGrid object is stored (excluding endings).

Return type:

Grid object

Returns:

GeoGrid instance.

static RegularGrid(time_seq, space_grid, silence_level=0)

Initialize an instance of a regular grid.

Examples:

>>> GeoGrid.RegularGrid(
...      time_seq=np.arange(2),
...      space_grid=(np.array([0.,5.]),
...                  np.array([1.,2.])),
...      silence_level=2).lat_sequence()
array([ 0.,  0.,  5.,  5.], dtype=float32)
>>> GeoGrid.RegularGrid(
...      time_seq=np.arange(2),
...      space_grid=(np.array([0.,5.]),
...                  np.array([1.,2.])),
...      silence_level=2).lon_sequence()
array([ 1.,  2.,  1.,  2.], dtype=float32)

Parameters:

• time_seq (1D Numpy array [time]) – The increasing sequence of temporal sampling points.

• space_grid (tuple or list of two 1D Numpy arrays ([n_lat], [n_lon])) – The spatial grid, consisting of the latitudinal and the longitudinal grid.

• silence_level (number (int)) – The inverse level of verbosity of the object.

Return type:

GeoGrid object

Returns:

GeoGrid instance.

static SmallTestGrid()

Return test grid of 6 spatial grid points with 10 temporal sampling points each.

Return type:

GeoGrid instance

Returns:

a GeoGrid instance for testing purposes.

__cache_state__() → Tuple[Hashable, ...]

Hashable tuple of mutable object attributes, which will determine the instance identity for ALL cached method lookups in this class, in addition to the built-in object id(). Returning an empty tuple amounts to declaring the object immutable in general. Mutable dependencies that are specific to a method should instead be declared via @Cached.method(attrs=(…)).

NOTE: A subclass is responsible for the consistency and cost of this state descriptor. For example, hashing a large array attribute may be circumvented by declaring it as a property, with a custom setter method that increments a dedicated mutation counter.

__init__(time_seq: ndarray, lat_seq: ndarray, lon_seq: ndarray, silence_level: int = 0)

Initialize an instance of GeoGrid.

Parameters:

• time_seq (1D Numpy array [time]) – The increasing sequence of temporal sampling points.

• lat_seq (1D Numpy array [index]) – The sequence of latitudinal sampling points.

• lon_seq (1D Numpy array [index]) – The sequence of longitudinal sampling points.

• silence_level (number (int)) – The inverse level of verbosity of the object.

__str__()

Return a string representation of the GeoGrid object.

angular_distance()

Calculate the angular great circle distance matrix.

No normalization applied anymore! Return values are in the range 0 to Pi.

Example:

>>> rr(GeoGrid.SmallTestGrid().angular_distance(), 2)
[['0'    '0.1'  '0.19' '0.29' '0.39' '0.48']
 ['0.1'  '0'    '0.1'  '0.19' '0.29' '0.39']
 ['0.19' '0.1'  '0'    '0.1'  '0.19' '0.29']
 ['0.29' '0.19' '0.1'  '0'    '0.1'  '0.19']
 ['0.39' '0.29' '0.19' '0.1'  '0'    '0.1']
 ['0.48' '0.39' '0.29' '0.19' '0.1'  '0']]

Return type:

2D Numpy array [index, index]

Returns:

the angular great circle distance matrix.

boundaries()

Return the spatio-temporal grid boundaries.

Structure of the returned dictionary:

• boundaries = {“time_min”: self._boundaries[“time_min”],

  “time_max”: self._boundaries[“time_max”], “lat_min”: self._boundaries[“space_min”][0], “lat_max”: self._boundaries[“space_max”][1], “lon_min”: self._boundaries[“space_min”][0], “lon_max”: self._boundaries[“space_max”][1]}

Return type:

dictionary

Returns:

the spatio-temporal grid boundaries.

convert_lon_coordinates(lon_seq)

Return longitude coordinates in the system -180 deg W <= lon <= +180 deg O for all nodes.

Accepts longitude coordinates in the system 0 deg <= lon <= 360 deg. 0 deg corresponds to Greenwich, England.

Example:

>>> GeoGrid.SmallTestGrid().convert_lon_coordinates(
...     np.array([10.,350.,20.,340.,170.,190.]))
array([  10.,  -10.,   20.,  -20.,  170., -170.])

Parameters:

lon_seq (1D Numpy array [index]) – Sequence of longitude coordinates.

Return type:

1D Numpy array [index]

Returns:

the converted longitude coordinates for all nodes.

static coord_sequence_from_rect_grid(lat_grid, lon_grid)

Return the sequences of latitude and longitude for a regular and rectangular grid.

Example:

>>> GeoGrid.coord_sequence_from_rect_grid(
...     lat_grid=np.array([0.,5.]), lon_grid=np.array([1.,2.]))
(array([ 0.,  0.,  5.,  5.]), array([ 1.,  2.,  1.,  2.]))

Parameters:

• lat_grid (1D Numpy array [lat]) – The grid’s latitudinal sampling points.

• lon_grid (1D Numpy array [lon]) – The grid’s longitudinal sampling points.

Return type:

tuple of two 1D Numpy arrays [index]

Returns:

the coordinates of all nodes in the grid.

cos_lat()

Return the sequence of cosines of latitude for all nodes.

Example:

>>> r(GeoGrid.SmallTestGrid().cos_lat()[:2])
array([ 1. , 0.9962])

Return type:

1D Numpy array [index]

Returns:

the cosine of latitudes for all nodes.

cos_lon()

Return the sequence of cosines of longitude for all nodes.

Example:

>>> r(GeoGrid.SmallTestGrid().cos_lon()[:2])
array([ 0.999 , 0.9962])

Return type:

1D Numpy array [index]

Returns:

the cosine of longitudes for all nodes.

distance()

Calculate and return the standard distance matrix of the corresponding grid type

Return type:

2D Numpy array [index, index]

Returns:

the distance matrix.

grid()

Return the grid’s spatio-temporal sampling points.

Structure of the returned dictionary:

• grid = {“time”: self._grid[“time”],

  “lat”: self._grid[“space”][0], “lon”: self._grid[“space”][1]}

Examples:

>>> Grid.SmallTestGrid().grid()["space"][0]
array([  0.,   5.,  10.,  15.,  20.,  25.], dtype=float32)
>>> Grid.SmallTestGrid().grid()["space"][0][5]
15.0

Return type:

dictionary

Returns:

the grid’s spatio-temporal sampling points.

lat_sequence()

Return the sequence of latitudes for all nodes.

Example:

>>> GeoGrid.SmallTestGrid().lat_sequence()
array([  0.,   5.,  10.,  15.,  20.,  25.], dtype=float32)

Return type:

1D Numpy array [index]

Returns:

the sequence of latitudes for all nodes.

lon_sequence()

Return the sequence of longitudes for all nodes.

Example:

>>> GeoGrid.SmallTestGrid().lon_sequence()
array([  2.5,   5. ,   7.5,  10. ,  12.5,  15. ], dtype=float32)

Return type:

1D Numpy array [index]

Returns:

the sequence of longitudes for all nodes.

node_number(lat_node, lon_node)

Return the index of the closest node given geographical coordinates.

Example:

>>> GeoGrid.SmallTestGrid().node_number(lat_node=14., lon_node=9.)
3

Parameters:

• lat_node (number (float)) – The latitude coordinate.

• lon_node (number (float)) – The longitude coordinate.

Return type:

number (int)

Returns:

the closest node’s index.

print_boundaries()

Pretty print the spatio-temporal grid boundaries.

Example:

>>> print(GeoGrid.SmallTestGrid().print_boundaries())
         time     lat     lon
   min    0.0    0.00    2.50
   max    9.0   25.00   15.00

Return type:

string

Returns:

printable string for the spatio-temporal grid boundaries

static region(name)

Return some standard regions.

region_indices(region)

Returns a boolean array of nodes with True values when the node is inside the region.

Example:

>>> GeoGrid.SmallTestGrid().region_indices(
...     np.array([0.,0.,0.,11.,11.,11.,11.,0.])).astype(int)
array([0, 1, 1, 0, 0, 0])

Parameters:

region (1D Numpy array [n_polygon_nodes]) – array of lon, lat, lon, lat, … [-80.2, 5., -82.4, 5.3, …] as copied from Google Earth Polygon file

Return type:

1D bool array [index]

Returns:

bool array with True for nodes inside region

save_txt(filename)

Save the GeoGrid object to text files.

The latitude, longitude and time sequences are stored in three separate text files.

Parameters:

filename (str) – The name of the files where Grid object is stored (excluding ending).

sin_lat()

Return the sequence of sines of latitude for all nodes.

Example:

>>> r(GeoGrid.SmallTestGrid().sin_lat()[:2])
array([ 0. , 0.0872])

Return type:

1D Numpy array [index]

Returns:

the sine of latitudes for all nodes.

sin_lon()

Return the sequence of sines of longitude for all nodes.

Example:

>>> r(GeoGrid.SmallTestGrid().sin_lon()[:2])
array([ 0.0436, 0.0872])

Return type:

1D Numpy array [index]

Returns:

the sine of longitudes for all nodes.