core.grid

Provides class for spatio-temporal grids.

class pyunicorn.core.grid.Grid(time_seq: ndarray, space_seq: ndarray, silence_level: int = 0)

Bases: Cached

Encapsulates a spatio-temporal grid.

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

static Load(filename)

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.

N

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

static RegularGrid(time_seq, space_grid, silence_level=0)

Initialize an instance of a regular grid.

Examples:

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

Parameters:

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

• space_grids (list of 1D Numpy arrays [dim, n]) – The spatial grid.

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

Return type:

Grid object

Returns:

Grid instance.

static SmallTestGrid()

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.

__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, space_seq: ndarray, silence_level: int = 0)

Initialize an instance of Grid.

Parameters:

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

• space_seq (2D Numpy array [dim, index]) – The sequences of spatial sampling points.

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

__str__()

Return a string representation of the Grid object.

boundaries()

Return the spatio-temporal grid boundaries.

Structure of the returned dictionary:

• self._boundaries = {“time_min”: time_seq.min(),

  “time_max”: time_seq.max(), “space_min”: np.amax(space_seq, axis=1), “space_max”: np.amin(space_seq, axis=1)}

Return type:

dictionary

Returns:

the spatio-temporal grid boundaries.

static coord_sequence_from_rect_grid(space_grid)

Return the sequences of coordinates for a regular and rectangular grid.

Example:

>>> Grid.coord_sequence_from_rect_grid(
...     space_grid=[np.array([0.,5.]), np.array([1.,2.])]
[array([ 0.,  0.,  5.,  5.]), array([ 1.,  2.,  1.,  2.])]

Parameters:

space_grid (list of 1D Numpy arrays [dim, n]) – The grid’s sampling points.

Return type:

list of 1D Numpy arrays [index]

Returns:

the coordinates of all nodes in the grid.

distance()

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

Return type:

2D Numpy array [index, index]

Returns:

the distance matrix.

euclidean_distance()

Return the euclidean distance matrix between grid points.

Example:

>>> Grid.SmallTestGrid().euclidean_distance().round(2)
[[ 0.    5.59 11.18 16.77 22.36 27.95]
 [ 5.59  0.    5.59 11.18 16.77 22.36]
 [11.18  5.59  0.    5.59 11.18 16.77]
 [16.77 11.18  5.59  0.    5.59 11.18]
 [22.36 16.77 11.18  5.59  0.    5.59]
 [27.95 22.36 16.77 11.18  5.59  0.  ]]

Return type:

2D Numpy array [index, index]

Returns:

the euclidean distance matrix.

geometric_distance_distribution(n_bins)

Return the distribution of distances between all pairs of grid points.

Examples:

>>> Grid.SmallTestGrid().geometric_distance_distribution(3)[0].round(2)
array([0.33, 0.47, 0.2 ])
>>> Grid.SmallTestGrid().geometric_distance_distribution(3)[1].round(2)
array([ 0.  ,  9.32, 18.63, 27.95], dtype=float32)

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 distances.

grid()

Return the grid’s spatio-temporal sampling points.

Structure of the returned dictionary:

• self._grid = {“time”: time_seq.astype(“float32”),

  “space”: space_seq.astype(“float32”)}

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.

grid_size()

Return the sizes of the grid’s spatial and temporal dimensions.

Structure of the returned dictionary:

• self._grid_size = {“time”: len(time_seq),

  “space”: space_seq.shape[1]}

Example:

>>> print(Grid2D.SmallTestGrid().print_grid_size())
   space    time
       6      10

Return type:

dictionary

Returns:

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

n_grid_points

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

node_coordinates(index)

Return the position 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 coordinates.

node_number(x)

Return the index of the closest node given euclidean coordinates.

Example:

>>> Grid.SmallTestGrid().node_number(x=(14., 9.))
3

Parameters:

• x (number (float)) – The x coordinate.

• y (number (float)) – The y coordinate.

Return type:

number (int)

Returns:

the closest node’s index.

print_grid_size()

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

save(filename)

Save the Grid object to a pickle file.

Parameters:

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

sequence(dimension)

Return the positional sequence for all nodes for the specified dimension.

Example:

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

Parameters:

dimension (integer) – The number of the dimension

Return type:

1D Numpy array [index]

Returns:

the sequence of positions in the specified dimension for all nodes.

silence_level

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