lair.transects.transect_matrix#

lair.transects.transect_matrix(transit, point, obs, time, n_transits, n_points, max_dwell_s=None)[source]#

Average samples onto a [transit, point] matrix.

With max_dwell_s, samples at a point taken more than that long after the transit first reached the point are dropped, so a platform sitting at a stop contributes a pass, not a long time-average, to that point. Samples without a time (NaN / NaT) are skipped.

Parameters:
  • transit (np.ndarray) – Transit index per sample, from split_transits() (-1 skips the sample).

  • point (np.ndarray) – Route point per sample, from snap_to_route() (-1 skips the sample).

  • obs (np.ndarray) – Observation per sample.

  • time (array-like) – Time per sample: POSIX seconds or datetime-like.

  • n_transits (int) – Number of transits (rows).

  • n_points (int) – Number of route points (columns).

  • max_dwell_s (float or None, optional) – Longest time (seconds) after a transit first reaches a point that its samples there still count. Default None: all count.

Returns:

tuple[np.ndarray, np.ndarray, np.ndarray] – (obs, time, n): the mean observation, the mean POSIX time and the number of samples per cell, NaN where a transit has no sample at a point.

Return type:

tuple[ndarray, ndarray, ndarray]

See also

enhancement

The first metric on the matrix.

split_transits

Gives transit.

snap_to_route

Gives point.

transit_times

One time per transit from the time matrix.

Examples

An outbound transit of six samples and a return of five, with each sample snapped to the route point at its position (every 500 m, 0 to 5):

>>> import numpy as np
>>> from lair.transects import transect_matrix
>>> time = np.arange(0, 11) * 60.0
>>> transit = np.array([0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1])
>>> point = np.array([0, 0, 1, 2, 3, 4, 5, 4, 3, 2, 1])
>>> obs = np.linspace(2.0, 2.1, 11)
>>> mean, mean_time, n = transect_matrix(
...     transit, point, obs, time, n_transits=2, n_points=6
... )
>>> mean.round(3)
array([[2.005, 2.02 , 2.03 , 2.04 , 2.05 ,   nan],
       [  nan, 2.1  , 2.09 , 2.08 , 2.07 , 2.06 ]])
>>> n
array([[ 2.,  1.,  1.,  1.,  1., nan],
       [nan,  1.,  1.,  1.,  1.,  1.]])