core.grid¶
Provides classes for analyzing spatially embedded complex networks, handling multivariate data and generating time series surrogates.
-
class
pyunicorn.core.grid.
Grid
(time_seq, lat_seq, lon_seq, silence_level=0)[source]¶ Bases:
object
Encapsulates a horizontal 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
Load
(filename)[source]¶ Return a Grid object stored in a pickle file.
Parameters: filename (str) – The name of the file where Grid object is stored (including ending). Return type: Grid object Returns: Grid
instance.
-
static
LoadTXT
(filename)[source]¶ Return a Grid 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 Grid object is stored (excluding endings). Return type: Grid object Returns: Grid
instance.
-
static
RegularGrid
(time_seq, lat_grid, lon_grid, silence_level=0)[source]¶ Initialize an instance of a regular grid.
Examples:
>>> Grid.RegularGrid( ... time_seq=np.arange(2), lat_grid=np.array([0.,5.]), ... lon_grid=np.array([1.,2.]), silence_level=2).lat_sequence() array([ 0., 0., 5., 5.], dtype=float32) >>> Grid.RegularGrid( ... time_seq=np.arange(2), lat_grid=np.array([0.,5.]), ... lon_grid=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.
- lat_grid (1D Numpy array [n_lat]) – The latitudinal grid.
- lon_grid (1D Numpy array [n_lon]) – The longitudinal grid.
- silence_level (number (int)) – The inverse level of verbosity of the object.
Return type: Grid object
Returns: Grid
instance.
-
static
SmallTestGrid
()[source]¶ Return test grid of 6 spatial grid points with 10 temporal sampling points each.
Return type: Grid instance Returns: a Grid instance for testing purposes.
-
__init__
(time_seq, lat_seq, lon_seq, silence_level=0)[source]¶ Initialize an instance of Grid.
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.
-
__weakref__
¶ list of weak references to the object (if defined)
-
_calculate_angular_distance
()[source]¶ Calculate and return the angular great circle distance matrix.
No normalization applied anymore! Return values are in the range 0 to Pi.
Return type: 2D Numpy array [index, index] Returns: the angular great circle distance matrix (unit radians).
-
angular_distance
()[source]¶ Return the angular great circle distance matrix.
No normalization applied anymore! Return values are in the range 0 to Pi.
Example:
>>> rr(Grid.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
()[source]¶ Return the spatio-temporal grid boundaries.
- Structure of the returned dictionary:
- self._boundaries = {“time_min”: time_seq.min(),
- “time_max”: time_seq.max(), “lat_min”: lat_seq.min(), “lat_max”: lat_seq.max(), “lon_min”: lon_seq.min(), “lon_max”: lon_seq.max()}
Example:
>>> print(Grid.SmallTestGrid().print_boundaries()) time lat lon min 0.0 0.00 2.50 max 9.0 25.00 15.00
Return type: dictionary Returns: the spatio-temporal grid boundaries.
-
clear_cache
()[source]¶ Clean up cache.
Is reversible, since all cached information can be recalculated from basic data.
-
convert_lon_coordinates
(lon_seq)[source]¶ 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:
>>> Grid.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)[source]¶ Return the sequences of latitude and longitude for a regular and rectangular grid.
Example:
>>> Grid.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
()[source]¶ Return the sequence of cosines of latitude for all nodes.
Example:
>>> r(Grid.SmallTestGrid().cos_lat()[:2]) array([ 1. , 0.9962])
Return type: 1D Numpy array [index] Returns: the cosine of latitudes for all nodes.
-
cos_lon
()[source]¶ Return the sequence of cosines of longitude for all nodes.
Example:
>>> r(Grid.SmallTestGrid().cos_lon()[:2]) array([ 0.999 , 0.9962])
Return type: 1D Numpy array [index] Returns: the cosine of longitudes for all nodes.
-
euclidean_distance
()[source]¶ Return the euclidean distance matrix between grid points.
So far assumes that the given latitude and longitude coordinates are planar, euclidean coordinates. Approximates great circle distance well for points with a separation much smaller than the Earth’s radius.
Return type: 2D Numpy array [index, index] Returns: the euclidean distance matrix.
-
geometric_distance_distribution
(n_bins)[source]¶ Return the distribution of angular great circle distances between all pairs of grid points.
Examples:
>>> r(Grid.SmallTestGrid().geometric_distance_distribution(3)[0]) array([ 0.3333, 0.4667, 0.2 ]) >>> r(Grid.SmallTestGrid().geometric_distance_distribution(3)[1]) array([ 0. , 0.1616, 0.3231, 0.4847])
Parameters: n_bins (number (int)) – The number of histogram bins. Return type: tuple of two 1D Numpy arrays [bin] Returns: the normalized histogram and lower bin boundaries of angular great circle distances.
-
grid
()[source]¶ Return the grid’s spatio-temporal sampling points.
- Structure of the returned dictionary:
- self._grid = {“time”: time_seq.astype(“float32”),
- “lat”: lat_seq.astype(“float32”), “lon”: lon_seq.astype(“float32”)}
Examples:
>>> Grid.SmallTestGrid().grid()["lat"] array([ 0., 5., 10., 15., 20., 25.], dtype=float32) >>> Grid.SmallTestGrid().grid()["lon"][5] 15.0
Return type: dictionary Returns: the grid’s spatio-temporal sampling points.
-
grid_size
()[source]¶ Return the sizes of the grid’s spatial and temporal dimensions.
- Structure of the returned dictionary:
- self._grid_size = {“time”: len(time_seq),
- “space”: len(lat_seq)}
Example:
>>> print(Grid.SmallTestGrid().print_grid_size()) space time 6 10
Return type: dictionary Returns: the sizes of the grid’s spatial and temporal dimensions.
-
lat_sequence
()[source]¶ Return the sequence of latitudes for all nodes.
Example:
>>> Grid.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
()[source]¶ Return the sequence of longitudes for all nodes.
Example:
>>> Grid.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_coordinates
(index)[source]¶ Return the geographical latitude and longitude of node
index
.Example:
>>> Grid.SmallTestGrid().node_coordinates(3) (15.0, 10.0)
Parameters: index (number (int)) – The node index as used in node sequences. Return type: tuple of number (float) Returns: the node’s latitude and longitude coordinates.
-
node_number
(lat_node, lon_node)[source]¶ Return the index of the closest node given geographical coordinates.
Example:
>>> Grid.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.
-
region_indices
(region)[source]¶ Returns a boolean array of nodes with True values when the node is inside the region.
Example:
>>> Grid.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
(filename)[source]¶ Save the Grid object to a pickle file.
Parameters: filename (str) – The name of the file where Grid object is stored (including ending).
-
save_txt
(filename)[source]¶ Save the Grid 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).
-
static