py_utils.utils_segmentation

Segmentation related utility functions.

The functions in this module generally assume that s_ind and e_ind are 1D arrays of the same length, and that for each i, s_ind[i] <= e_ind[i]. The segmented operations can be treated as numpy.ufunc.reduceat with custom started and ended indices. See: (https://numpy.org/doc/1.26/reference/generated/numpy.ufunc.reduceat.html)

Dependency:

• numpy_reduceat_ext

• numpy

Sliding Window Utilities

py_utils.utils_segmentation.compute_sliding_window_indices(N, window_size, same_size=True)

Compute start and end indices for sliding windows over a sequence of length N.

Parameters

• N (int) – The length of the sequence over which sliding windows are computed.

• window_size (int) – The size of each sliding window.

• same_size (bool, optional) –

  • (True) only full-sized windows are returned.

  • (False) partial windows near the boundaries are included as well.

Returns

• s_ind (np.ndarray of int) – The array of start indices for each window.

• e_ind (np.ndarray of int) – The array of end indices for each window (exclusive).

Examples

>>> s_ind, e_ind = compute_sliding_window_indices(5, 3, same_size=True)
s_ind: [0, 1, 2]
e_ind: [3, 4, 5]

>>> s_ind, e_ind = compute_sliding_window_indices(5, 4, same_size=True)
s_ind: [0, 1]
e_ind: [4, 5]

>>> s_ind, e_ind = compute_sliding_window_indices(5, 6, same_size=True)
s_ind: []
e_ind: []

>>> s_ind, e_ind = compute_sliding_window_indices(5, 3, same_size=False)
s_ind:           [0, 0, 1, 2, 3]
e_ind:           [2, 3, 4, 5, 5]
-> segment_size: [2, 3, 3, 3, 2]

>>> s_ind, e_ind = compute_sliding_window_indices(5, 4, same_size=False)
s_ind:           [0, 0, 0, 1, 2, 3]
e_ind:           [2, 3, 4, 5, 5, 5]
-> segment_size: [2, 3, 4, 4, 3, 2]

>>> s_ind, e_ind = compute_sliding_window_indices(5, 6, same_size=False)
s_ind:           [0, 0, 0, 0, 1, 2]
e_ind:           [3, 4, 5, 5, 5, 5]
-> segment_size: [3, 4, 5, 5, 4, 3]

py_utils.utils_segmentation.sliding_window(x, window_size=3, same_size=False, method='mean')

Apply sliding window operation on 1D array x. window_size & same_size control the sliding window indices, see compute_sliding_window_indices for details. method specifies the aggregation method within each window.

Parameters

• x (np.ndarray of shape (N,)) – The input 1D array.

• window_size (int, optional) –

• same_size (bool, optional) –

• method (str, optional) –

  • “argmin”: index of minimum

  • ”argmax”: index of maximum

  • ”max”: maximum

  • ”min”: minimum

  • ”count”: count of elements

  • ”sum”: summation

  • ”mean”: average

Segmented Reduction Utilities

py_utils.utils_segmentation.segmented_argmin(x, s_ind, e_ind)

Computes the argmin along segments x[s_ind:e_ind, …]

Parameters

• x (np.ndarray) –

• s_ind (np.ndarray of int) – The array of start indices for each window.

• e_ind (np.ndarray of int) – The array of end indices for each window (exclusive).

Returns

Return type

np.ndarray of int pointing global indices of x

py_utils.utils_segmentation.segmented_argmax(x, s_ind, e_ind)

Computes the argmax along segments x[s_ind:e_ind]

Parameters

• x (np.ndarray) –

• s_ind (np.ndarray of int) – The array of start indices for each window.

• e_ind (np.ndarray of int) – The array of end indices for each window (exclusive).

Returns

Return type

np.ndarray of int pointing global indices of x

py_utils.utils_segmentation.segmented_min(x, s_ind, e_ind, return_indices=False)

Computes the minimum along segments x[s_ind:e_ind, …] :returns:

• min values within each segment

• (optional) indices of these min values in the original array

py_utils.utils_segmentation.segmented_max(x, s_ind, e_ind, return_indices=False)

Computes the maximum along segments x[s_ind:e_ind, …]

Parameters

• x (np.ndarray) –

• s_ind (np.ndarray of int) – The array of start indices for each window.

• e_ind (np.ndarray of int) – The array of end indices for each window (exclusive).

• return_indices (bool, optional) – Whether to return the correspoinding indices in the original array.

Returns

• np.ndarray

• (optional) indices of these max values in the original array

py_utils.utils_segmentation.segmented_count(x, s_ind, e_ind)

Counts the number of elements along segments x[s_ind:e_ind].

Parameters

• x (np.ndarray) – The input array. (for checking max length of s_ind and e_ind)

• s_ind (np.ndarray of int) – The array of start indices for each window.

• e_ind (np.ndarray of int) – The array of end indices for each window (exclusive).

Returns

Return type

a numpy ndarray

Examples

>>> x = [1, 2, 4, 8]
>>> s_ind = [0, 1, 2]
>>> e_ind = [3, 4, 4]
>>> segmented_count(x, s_ind, e_ind)
array([3, 3, 2])

>>> x = [1, 2, 4, 8]
>>> s_ind = [0, 1, 2]
>>> e_ind = [1, 1, 4]
>>> segmented_count(x, s_ind, e_ind)
array([1, 1, 2])

py_utils.utils_segmentation.segmented_sum(x, s_ind, e_ind)

Computes the summation along segments x[s_ind:e_ind, …]

Parameters

• x (a numpy ndarray) –

• s_ind (a 1d array (n,)) –

• e_ind (a 1d array (n,)) –

Returns

Return type

a numpy ndarray

py_utils.utils_segmentation.segmented_mean(x, s_ind, e_ind)

Computes the average along segments x[s_ind:e_ind, …]

Parameters

• x (a numpy ndarray) –

• s_ind (a 1d array (n,)) –

• e_ind (a 1d array (n,)) –

Returns

Return type

a numpy ndarray

py_utils.utils_segmentation.segmented_where(x, s_ind, e_ind, values)

Computes the indices where x[s_ind:e_ind] == values within each segment.