clouddrift.ragged.chunk

Contents

clouddrift.ragged.chunk#

clouddrift.ragged.chunk(x: list | ndarray | DataArray | Series, length: int, overlap: int = 0, align: str = 'start') → ndarray[source]#

Divide an array x into equal chunks of length length. The result is a 2-dimensional NumPy array of shape (num_chunks, length). The resulting number of chunks is determined based on the length of x, length, and overlap.

chunk can be combined with apply_ragged() to chunk a ragged array.

Parameters#

xlist or array-like

Array to divide into chunks.

lengthint

The length of each chunk.

overlapint, optional

The number of overlapping array elements across chunks. The default is 0. Must be smaller than length. For example, if length is 4 and overlap is 2, the chunks of [0, 1, 2, 3, 4, 5] will be np.array([[0, 1, 2, 3], [2, 3, 4, 5]]). Negative overlap can be used to offset chunks by some number of elements. For example, if length is 2 and overlap is -1, the chunks of [0, 1, 2, 3, 4, 5] will be np.array([[0, 1], [3, 4]]).

alignstr, optional [“start”, “middle”, “end”]

If the remainder of the length of x divided by the chunk length is a number N different from zero, this parameter controls which part of the array will be kept into the chunks. If align="start", the elements at the beginning of the array will be part of the chunks and N points are discarded at the end. If align=”middle”, floor(N/2) and ceil(N/2) elements will be discarded from the beginning and the end of the array, respectively. If align="end", the elements at the end of the array will be kept, and the N first elements are discarded. The default is “start”.

Returns#

np.ndarray

2-dimensional array of shape (num_chunks, length).

Examples#

Chunk a simple list; this discards the end elements that exceed the last chunk:

>>> chunk([1, 2, 3, 4, 5], 2)
array([[1, 2],
       [3, 4]])

To discard the starting elements of the array instead, use align="end":

>>> chunk([1, 2, 3, 4, 5], 2, align="end")
array([[2, 3],
       [4, 5]])

To center the chunks by discarding both ends of the array, use align="middle":

>>> chunk([1, 2, 3, 4, 5, 6, 7, 8], 3, align="middle")
array([[2, 3, 4],
       [5, 6, 7]])

Specify overlap to get overlapping chunks:

>>> chunk([1, 2, 3, 4, 5], 2, overlap=1)
array([[1, 2],
       [2, 3],
       [3, 4],
       [4, 5]])

Use apply_ragged to chunk a ragged array by providing the row sizes; notice that you must pass the array to chunk as an array-like, not a list:

>>> x = np.array([1, 2, 3, 4, 5])
>>> rowsize = [2, 1, 2]
>>> apply_ragged(chunk, x, rowsize, 2)
array([[1, 2],
       [4, 5]])

Raises#

ValueError

If length < 0.

ValueError

If align not in ["start", "middle", "end"].

ZeroDivisionError

if length == 0.

Contents