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 cPickle 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.
N = None

(number (int)) - The number of spatial grid points / nodes.

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.
__str__()[source]

Return a string representation of the Grid 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())
[['0'      '0.0975' '0.1949' '0.292'  '0.3887' '0.4847']
 ['0.0975' '0'      '0.0974' '0.1945' '0.2911' '0.3872']
 ['0.1949' '0.0974' '0.0003' '0.0971' '0.1938' '0.2898']
 ['0.292'  '0.1945' '0.0971' '0.0005' '0.0967' '0.1928']
 ['0.3887' '0.2911' '0.1938' '0.0967' '0'      '0.0961']
 ['0.4847' '0.3872' '0.2898' '0.1928' '0.0961' '0.0005']]
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.
n_grid_points = None

(number (int)) - The total number of data points / samples.

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.

print_boundaries()[source]

Pretty print the spatio-temporal grid boundaries.

print_grid_size()[source]

Pretty print the sizes of the grid’s spatial and temporal dimensions.

static region(name)[source]

Return some standard regions.

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.]))
array([False,  True,  True, False, False, False], dtype=bool)
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 cPickle 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).
silence_level = None

(number (int)) - The inverse level of verbosity of the object.

sin_lat()[source]

Return the sequence of sines of latitude for all nodes.

Example:

>>> r(Grid.SmallTestGrid().sin_lat()[:2])
array([ 0. , 0.0872])
Return type:1D Numpy array [index]
Returns:the sine of latitudes for all nodes.
sin_lon()[source]

Return the sequence of sines of longitude for all nodes.

Example:

>>> r(Grid.SmallTestGrid().sin_lon()[:2])
array([ 0.0436, 0.0872])
Return type:1D Numpy array [index]
Returns:the sine of longitudes for all nodes.