bordado.rolling_window

bordado.rolling_window(coordinates, window_size, overlap, *, region=None, adjust='overlap')

Split points into overlapping windows.

A window of the given size is moved across the region at a given step (specified by spacing or shape). Returns the indices of points falling inside each window step. You can use the indices to select points falling inside a given window.

Parameters:

coordinatestuple = (easting, northing, …)

Tuple of arrays with the coordinates of each point. The arrays can be n-dimensional.

window_sizefloat

The size of the windows. Units should match the units of coordinates. In case the window size is not a multiple of the region, either of them will be adjusted according to the value of the adjust argument.

overlapfloat

The amount of overlap between adjacent windows. Should be within the range 1 > overlap ≥ 0. For example, an overlap of 0.5 means 50% overlap. An overlap of 0 will be the same as block_split.

regiontuple = (W, E, S, N, …)

The boundaries of a given region in Cartesian or geographic coordinates. If region is not given, will use the bounding region of the given coordinates.

adjuststr = “overlap” or “region”

Whether to adjust the window overlap or the region, if required. Adjusting the overlap or region is required when the combination of window size and overlap is not a multiple of the region. Defaults to adjusting the overlap.

Returns:

window_coordinatestuple = (easting, northing, …)

ND coordinate arrays for the center of each window. Will have the same number of arrays as the coordinates and each array will have the number of dimensions equal to len(coordinates).

indicesarray

An array with the same shape as the window_coordinates. Each element of the array is a tuple of arrays (with the same length as coordinates) corresponding to the indices of the points that fall inside that particular window. Use these indices to index the given coordinates and select points from a window.

Examples

Generate a set of sample coordinates on a grid to make it easier to visualize the windows:

>>> import bordado as bd
>>> coordinates = bd.grid_coordinates((-5, -1, 6, 10), spacing=1)
>>> print(coordinates[0])
[[-5. -4. -3. -2. -1.]
 [-5. -4. -3. -2. -1.]
 [-5. -4. -3. -2. -1.]
 [-5. -4. -3. -2. -1.]
 [-5. -4. -3. -2. -1.]]
>>> print(coordinates[1])
[[ 6.  6.  6.  6.  6.]
 [ 7.  7.  7.  7.  7.]
 [ 8.  8.  8.  8.  8.]
 [ 9.  9.  9.  9.  9.]
 [10. 10. 10. 10. 10.]]

Get the coordinates of the centers of rolling windows with 75% overlap and an indexer that allows us to select points from each window:

>>> window_coords, indices = rolling_window(
...     coordinates, window_size=2, overlap=0.75,
... )

Window coordinates will be 2D arrays. Their shape is the number of windows in each dimension:

>>> print(window_coords[0].shape, window_coords[1].shape)
(5, 5) (5, 5)

The values of these arrays are the coordinates for the center of each rolling window:

>>> print(window_coords[0])
[[-4.  -3.5 -3.  -2.5 -2. ]
 [-4.  -3.5 -3.  -2.5 -2. ]
 [-4.  -3.5 -3.  -2.5 -2. ]
 [-4.  -3.5 -3.  -2.5 -2. ]
 [-4.  -3.5 -3.  -2.5 -2. ]]
>>> print(window_coords[1])
[[7.  7.  7.  7.  7. ]
 [7.5 7.5 7.5 7.5 7.5]
 [8.  8.  8.  8.  8. ]
 [8.5 8.5 8.5 8.5 8.5]
 [9.  9.  9.  9.  9. ]]

The indices of points falling on each window will have the same shape as the window center coordinates:

>>> print(indices.shape)
(5, 5)

Each element of the indices array is a tuple of arrays, one for each element in the coordinates:

>>> print(len(indices[0, 0]))
2

They are indices of the points that fall inside the selected window. The first element indexes the axis 0 of the coordinate arrays and so forth:

>>> print(indices[0, 0][0])
[0 0 0 1 1 1 2 2 2]
>>> print(indices[0, 0][1])
[0 1 2 0 1 2 0 1 2]
>>> print(indices[0, 1][0])
[0 0 1 1 2 2]
>>> print(indices[0, 1][1])
[1 2 1 2 1 2]
>>> print(indices[0, 2][0])
[0 0 0 1 1 1 2 2 2]
>>> print(indices[0, 2][1])
[1 2 3 1 2 3 1 2 3]

Use these indices to select the coordinates the points that fall inside a window:

>>> points_window_00 = [c[indices[0, 0]] for c in coordinates]
>>> print(points_window_00[0])
[-5. -4. -3. -5. -4. -3. -5. -4. -3.]
>>> print(points_window_00[1])
[6. 6. 6. 7. 7. 7. 8. 8. 8.]
>>> points_window_01 = [c[indices[0, 1]] for c in coordinates]
>>> print(points_window_01[0])
[-4. -3. -4. -3. -4. -3.]
>>> print(points_window_01[1])
[6. 6. 7. 7. 8. 8.]

If the coordinates are 1D, the indices will also be 1D:

>>> coordinates1d = [c.ravel() for c in coordinates]
>>> window_coords, indices = rolling_window(
...     coordinates1d, window_size=2, overlap=0.75,
... )
>>> print(len(indices[0, 0]))
1
>>> print(indices[0, 0][0])
[ 0  1  2  5  6  7 10 11 12]
>>> print(indices[0, 1][0])
[ 1  2  6  7 11 12]

The returned indices can be used in the same way as before to get the same coordinates:

>>> print(coordinates1d[0][indices[0, 0]])
[-5. -4. -3. -5. -4. -3. -5. -4. -3.]
>>> print(coordinates1d[1][indices[0, 0]])
[6. 6. 6. 7. 7. 7. 8. 8. 8.]

By default, the windows will span the entire data region. You can also control the specific region you’d like the windows to cover:

>>> coordinates = grid_coordinates((-10, 5, 0, 20), spacing=1)
>>> window_coords, indices = rolling_window(
...     coordinates, window_size=2, overlap=0.75, region=(-5, -1, 6, 10),
... )

Even though the data region is larger, our rolling windows should still be the same as before:

>>> print(coordinates[0][indices[0, 1]])
[-4. -3. -4. -3. -4. -3.]
>>> print(coordinates[1][indices[0, 1]])
[6. 6. 7. 7. 8. 8.]