lair.transects.split_transits#

lair.transects.split_transits(time, s, max_gap_s=600.0, reversal_m=500.0, min_span_m=1000.0)[source]#

Cut a platform’s along-route coordinate into one-way transits.

A transit ends

  • at a time gap longer than max_gap_s (overnight, or the record stops), or

  • at a reversal of the direction of travel: a turning point of s with prominence of at least reversal_m (scipy.signal.find_peaks on s and on -s). GPS jitter and short shunts stay inside a transit; a turnaround at a terminus does not. A dwell at the terminus is cut at its middle, between the arriving and the departing transit (trim it with max_dwell_s in transect_matrix()).

Transits covering less than min_span_m of route are discarded. Samples without a time (NaN / NaT) are skipped like samples off the route.

Parameters:
  • time (array-like) – Sample times, sorted: POSIX seconds or datetime-like (see the module docstring).

  • s (np.ndarray) – Along-route position of each sample (meters); NaN where the sample is not on this route.

  • max_gap_s (float, optional) – Time gap (seconds) that ends a transit. Default 600.

  • reversal_m (float, optional) – Prominence (meters) of a turning point that ends a transit. Default 500.

  • min_span_m (float, optional) – Shortest stretch of route (meters) a transit must cover. Default 1000.

Returns:

tuple[np.ndarray, pd.DataFrame] – (transit, table): transit is the transit index per sample (-1 for samples not in a kept transit) and table has one row per transit, indexed by that number: direction (+1 with increasing s, -1 against it), t_start, t_end (POSIX s), s_min, s_max and n samples.

Return type:

tuple[ndarray, DataFrame]

See also

transect_matrix

Averages the samples onto [transit, point].

snap_to_route

Gives the route point of each sample.

Examples

A platform drives out along the route and back, one sample a minute. The turn at 2500 m ends the first transit (the turning sample starts the next):

>>> import numpy as np
>>> from lair.transects import split_transits
>>> time = np.arange(0, 11) * 60.0
>>> s = np.array([0, 500, 1000, 1500, 2000, 2500, 2000, 1500, 1000, 500, 0.0])
>>> transit, table = split_transits(
...     time, s, reversal_m=500, min_span_m=1000
... )
>>> transit
array([0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1])
>>> table[["direction", "s_min", "s_max", "n"]]
         direction  s_min   s_max  n
transit
0                1    0.0  2000.0  5
1               -1    0.0  2500.0  6