clouddrift.ragged.unpack

clouddrift.ragged.unpack(ragged_array: ndarray | DataArray, rowsize: ndarray | DataArray, rows: int | Iterable[int] = None, axis: int = 0) → list[ndarray | DataArray]

Unpack a ragged array into a list of regular arrays.

Unpacking a np.ndarray ragged array is about 2 orders of magnitude faster than unpacking an xr.DataArray ragged array, so unless you need a DataArray as the result, we recommend passing np.ndarray as input.

Parameters

ragged_arrayarray-like

A ragged_array to unpack

rowsizearray-like

An array of integers whose values is the size of each row in the ragged array

rowsint or Iterable[int], optional

A row or list of rows to unpack. Default is None, which unpacks all rows.

axisint, optional

The axis along which to unpack the ragged array. Default is 0.

Returns

list

A list of array-likes with sizes that correspond to the values in rowsize, and types that correspond to the type of ragged_array

Examples

Unpacking longitude arrays from a ragged Xarray Dataset: >>> from clouddrift.ragged import unpack >>> from clouddrift.datasets import gdp6h

>>> ds = gdp6h()

>>> lon = unpack(ds.lon, ds["rowsize"]) # return a list[xr.DataArray] (slower)
>>> lon = unpack(ds.lon.values, ds["rowsize"]) # return a list[np.ndarray] (faster)
>>> first_lon = unpack(ds.lon.values, ds["rowsize"], rows=0) # return only the first row
>>> first_two_lons = unpack(ds.lon.values, ds["rowsize"], rows=[0, 1]) # return first two rows

Looping over trajectories in a ragged Xarray Dataset to compute velocities for each:

>>> from clouddrift.kinematics import velocity_from_position

>>> for lon, lat, time in list(zip(
...     unpack(ds.lon.values, ds["rowsize"]),
...     unpack(ds.lat.values, ds["rowsize"]),
...     unpack(ds.time.values, ds["rowsize"])
... )):
...     u, v = velocity_from_position(lon, lat, time)