clouddrift.pairs.chance_pair

Contents

clouddrift.pairs.chance_pair#

clouddrift.pairs.chance_pair(lon1: list[float] | ndarray[float] | Series | DataArray, lat1: list[float] | ndarray[float] | Series | DataArray, lon2: list[float] | ndarray[float] | Series | DataArray, lat2: list[float] | ndarray[float] | Series | DataArray, time1: list[float] | ndarray[float] | Series | DataArray | None = None, time2: list[float] | ndarray[float] | Series | DataArray | None = None, space_distance: float = 0, time_distance: float = 0)[source]#

Given two sets of longitudes, latitudes, and times arrays, return in pairs the indices of collocated data points that are within prescribed distances in space and time. Also known as chance pairs.

Parameters#

lon1array_like

First array of longitudes in degrees.

lat1array_like

First array of latitudes in degrees.

lon2array_like

Second array of longitudes in degrees.

lat2array_like

Second array of latitudes in degrees.

time1array_like, optional

First array of times.

time2array_like, optional

Second array of times.

space_distancefloat, optional

Maximum allowable space distance in meters for a 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.

time_distancefloat, optional

Maximum allowable time distance for a pair to qualify as chance pair. If a separation is within this distance, and a 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#

indices1np.ndarray[int]

Indices within the first set of arrays that lead to chance pair.

indices2np.ndarray[int]

Indices within the second set of arrays that lead to chance pair.

Examples#

In the following example, we load the GLAD dataset, extract the first two trajectories, and find between these the array indices that satisfy the chance pair criteria of 6 km separation distance and no time separation:

>>> from clouddrift.datasets import glad
>>> from clouddrift.pairs import chance_pair
>>> from clouddrift.ragged import unpack
>>> ds = glad()
>>> lon1 = unpack(ds["longitude"], ds["rowsize"], rows=0).pop()
>>> lat1 = unpack(ds["latitude"], ds["rowsize"], rows=0).pop()
>>> time1 = unpack(ds["time"], ds["rowsize"], rows=0).pop()
>>> lon2 = unpack(ds["longitude"], ds["rowsize"], rows=1).pop()
>>> lat2 = unpack(ds["latitude"], ds["rowsize"], rows=1).pop()
>>> time2 = unpack(ds["time"], ds["rowsize"], rows=1).pop()
>>> i1, i2 = chance_pair(lon1, lat1, lon2, lat2, time1, time2, 6000, np.timedelta64(0))
>>> i1, i2
(array([177, 180, 183, 186, 189, 192]), array([166, 169, 172, 175, 178, 181]))

Check to ensure our collocation in space worked by calculating the distance between the identified pairs:

>>> sphere.distance(lon1[i1], lat1[i1], lon2[i2], lat2[i2])
array([5967.4844, 5403.253 , 5116.9136, 5185.715 , 5467.8555, 5958.4917],
      dtype=float32)

Check the collocation in time:

>>> time1[i1] - time2[i2]
<xarray.DataArray 'time' (obs: 6)>
array([0, 0, 0, 0, 0, 0], dtype='timedelta64[ns]')
Coordinates:
    time     (obs) datetime64[ns] 2012-07-21T21:30:00.524160 ... 2012-07-22T0...
Dimensions without coordinates: obs

Raises#

ValueError

If time1 and time2 are not both provided or both omitted.

Contents