clouddrift.pairs.chance_pairs_from_ragged

clouddrift.pairs.chance_pairs_from_ragged#

clouddrift.pairs.chance_pairs_from_ragged(lon: list[float] | ndarray[float] | Series | DataArray, lat: list[float] | ndarray[float] | Series | DataArray, rowsize: list[float] | ndarray[float] | Series | DataArray, space_distance: float = 0, time: list[float] | ndarray[float] | Series | DataArray | None = None, time_distance: float = 0) → list[tuple[tuple[int, int], tuple[ndarray, ndarray]]][source]#

Return all chance pairs of contiguous trajectories in a ragged array, and their collocated points in space and (optionally) time, given input ragged arrays of longitude, latitude, and (optionally) time, and chance pair criteria as maximum allowable distances in space and time.

If time and time_distance are omitted, the search will be done only on the spatial criteria, and the result will not include the time arrays.

If time and time_distance are provided, the search will be done on both the spatial and temporal criteria, and the result will include the time arrays.

Parameters#

lonarray_like

Array of longitudes in degrees.

latarray_like

Array of latitudes in degrees.

rowsizearray_like

Array of rowsizes.

space_distancefloat, optional

Maximum space distance in meters for the pair to qualify as chance pair. If the separation is within this distance, the pair is considered to be a chance pair. Default is 0, or no distance, i.e. the positions must be exactly the same.

timearray_like, optional

Array of times.

time_distancefloat, optional

Maximum time distance allowed for the pair to qualify as chance pair. If the separation is within this distance, and the space distance condition is satisfied, the pair is considered a chance pair. Default is 0, or no distance, i.e. the times must be exactly the same.

Returns#

pairsList[Tuple[Tuple[int, int], Tuple[np.ndarray, np.ndarray]]]

List of tuples, each tuple containing a Tuple of integer indices that corresponds to the trajectory rows in the ragged array, indicating the pair of trajectories that satisfy the chance pair criteria, and a Tuple of arrays containing the indices of the collocated points for each trajectory in the chance pair.

Examples#

In the following example, we load GLAD dataset as a ragged array dataset, subset the result to retain the first five trajectories, and finally find all trajectories that satisfy the chance pair criteria of 12 km separation distance and no time separation, as well as the indices of the collocated points for each pair.

>>> from clouddrift.datasets import glad
>>> from clouddrift.pairs import chance_pairs_from_ragged
>>> from clouddrift.ragged import subset
>>> ds = subset(glad(), {"id": ["CARTHE_001", "CARTHE_002", "CARTHE_003", "CARTHE_004", "CARTHE_005"]}, id_var_name="id")
>>> pairs = chance_pairs_from_ragged(
    ds["longitude"].values,
    ds["latitude"].values,
    ds["rowsize"].values,
    space_distance=12000,
    time=ds["time"].values,
    time_distance=np.timedelta64(0)
)
[((0, 1),
  (array([153, 156, 159, 162, 165, 168, 171, 174, 177, 180, 183, 186, 189,
          192, 195, 198, 201, 204, 207, 210, 213, 216]),
   array([142, 145, 148, 151, 154, 157, 160, 163, 166, 169, 172, 175, 178,
          181, 184, 187, 190, 193, 196, 199, 202, 205]))),
 ((3, 4),
  (array([141, 144, 147, 150, 153, 156, 159, 162, 165, 168, 171, 174, 177,
          180, 183]),
   array([136, 139, 142, 145, 148, 151, 154, 157, 160, 163, 166, 169, 172,
          175, 178])))]

The result above shows that 2 chance pairs were found.

Raises#

ValueError

If rowsize has fewer than two elements.

Contents