environmentaltools.spatiotemporal.bme.find_pairs_by_distance

environmentaltools.spatiotemporal.bme.find_pairs_by_distance(pi, plag, plagtol, *args)

Find pairs of points separated by specified distance intervals.

Identifies point pairs whose separation falls within given distance lag tolerances, optionally considering directional angles for spatial data.

Parameters:

• pi (np.ndarray) – Coordinate array (1D for temporal, 2D for spatial).

• plag (array-like) – Array of target distance lags.

• plagtol (array-like) – Array of distance tolerance values for each lag.

• *args (tuple, optional) – For directional analysis: [dlag, dlagtol] where dlag is array of target angles and dlagtol is angular tolerance.

Returns:

idxpairs – Nested list of index tuples identifying point pairs meeting distance criteria. Structure depends on whether directional analysis is included.

Return type:

list

Notes

Without directional args: Returns list of index arrays for each distance lag. With directional args: Returns 2D list organized by [distance_lag][angle_bin].