"""
Metrics on mobile-platform transect matrices.
A *transect matrix* is a 2-D array ``obs[transit, point]`` of a species measured on
repeated transits of a fixed route, resampled onto fixed along-route points (NaN where a
transit has no data at a point). Persistence questions are answered per point:
- :func:`enhancement` — obs minus each transit's own low percentile (removes the
boundary-layer / background cycle transit by transit)
- :func:`detection_frequency` — fraction of transits enhanced above a threshold
- :func:`magnitude` — mean or median enhancement, over detected transits or all
- :func:`transit_times` — one representative timestamp per transit
- :func:`profile` — detection frequency and magnitude binned by hour / weekday / month
- :func:`along_route_distance` — cumulative geodesic distance of the points [km]
Building the matrix from a georeferenced time series (the *transect builder*, after
Mitchell et al. 2018's algorithm):
- :func:`lag_positions` — put each sample where the sampled air was taken in (inlet lag)
- :func:`snap_to_route` — nearest fixed route point of each sample
- :func:`split_transits` — cut the along-route coordinate into one-way transits at the
reversals of travel and at time gaps
- :func:`transect_matrix` — average the samples onto ``[transit, point]``
Everything is plain numpy; the platform-specific file formats live in the calling package
(e.g. ``slv.measurements.mobile`` for TRAX). Times are POSIX seconds (float) or
datetime-like (datetime64, or pandas times with or without a time zone; naive times
follow :ref:`the UTC rule <utc-rule>`). The builder skips samples without a time (NaN / NaT).
"""
from __future__ import annotations
import numpy as np
import pandas as pd
__all__ = [
"enhancement",
"robust_z",
"detection_frequency",
"magnitude",
"transit_times",
"profile",
"along_route_distance",
"merge_route_points",
"pool_routes",
"lag_positions",
"snap_to_route",
"split_transits",
"transect_matrix",
]
[docs]
def enhancement(obs: np.ndarray, baseline_q: float = 5.0) -> np.ndarray:
"""
Enhancement above each transit's own ``baseline_q``-th percentile along the route.
Parameters
----------
obs : np.ndarray
Transect matrix ``obs[transit, point]``.
baseline_q : float, optional
Percentile (0 to 100) of each transit's values taken as its baseline.
Default 5.
Returns
-------
np.ndarray
``obs`` minus each transit's baseline, the same shape. Transits with no
finite values are NaN throughout.
See Also
--------
robust_z : The enhancement as a score against its own transit.
detection_frequency : How often each point is enhanced.
magnitude : How much each point is enhanced.
Examples
--------
Three transits over four points; with ``baseline_q=0`` each transit's
lowest value is its baseline:
>>> import numpy as np
>>> from lair.transects import enhancement
>>> obs = np.array(
... [[2.0, 2.1, 2.6, 2.0], [2.2, 2.2, 2.3, 2.9], [2.0, np.nan, 2.5, 2.0]]
... )
>>> enhancement(obs, baseline_q=0).round(2)
array([[0. , 0.1, 0.6, 0. ],
[0. , 0. , 0.1, 0.7],
[0. , nan, 0.5, 0. ]])
"""
obs = np.asarray(obs, dtype=float)
ok = np.isfinite(obs).any(axis=1)
base = np.full((obs.shape[0], 1), np.nan)
base[ok, 0] = np.nanpercentile(obs[ok], baseline_q, axis=1)
return obs - base
[docs]
def robust_z(enh: np.ndarray, min_points: int = 20) -> np.ndarray:
"""
Per-transit robust z-score of the enhancement.
The score is ``(enh - median) / (1.4826 * MAD)``, with the median and MAD taken
along each transit's route points.
A point is then judged against the rest of *its own transit*, so a night with the whole
route elevated does not read as detections everywhere.
Parameters
----------
enh : np.ndarray
Enhancement matrix ``enh[transit, point]``, as from :func:`enhancement`.
min_points : int, optional
Fewest finite points a transit needs for a score. Default 20.
Returns
-------
np.ndarray
The scores, the same shape as ``enh``. Transits with fewer than
``min_points`` finite points, or zero MAD, are NaN.
See Also
--------
enhancement : The enhancement matrix.
detection_frequency : Counts the transits above a threshold at each point.
Examples
--------
The first transit has one point far above its own median, which scores
about 33; the second is the same everywhere (zero MAD), so it has no score:
>>> import numpy as np
>>> from lair.transects import robust_z
>>> enh = np.array([[0.0, 0.1, 0.0, 5.0, 0.1], [1.0, 1.0, 1.0, 1.0, 1.0]])
>>> robust_z(enh, min_points=3).round(2)
array([[-0.67, 0. , -0.67, 33.05, 0. ],
[ nan, nan, nan, nan, nan]])
"""
enh = np.asarray(enh, dtype=float)
import warnings
with warnings.catch_warnings():
warnings.simplefilter("ignore", RuntimeWarning)
med = np.nanmedian(enh, axis=1, keepdims=True)
mad = np.nanmedian(np.abs(enh - med), axis=1, keepdims=True) * 1.4826
n = np.isfinite(enh).sum(axis=1, keepdims=True)
ok = (n >= min_points) & (mad > 0)
with np.errstate(invalid="ignore", divide="ignore"):
z = (enh - med) / mad
return np.where(ok, z, np.nan)
[docs]
def detection_frequency(
enh: np.ndarray, threshold: float, min_transits: int = 10
) -> np.ndarray:
"""
Fraction of transits (with data at the point) whose enhancement exceeds ``threshold``.
Parameters
----------
enh : np.ndarray
Enhancement matrix ``enh[transit, point]``, as from :func:`enhancement`.
threshold : float
Enhancement above which a transit counts as a detection.
min_transits : int, optional
Fewest transits with data a point needs. Default 10.
Returns
-------
np.ndarray
The fraction per point. Points sampled by fewer than ``min_transits``
transits are NaN.
See Also
--------
magnitude : The enhancement of the detected transits.
profile : Both, binned by hour, weekday or month.
Examples
--------
With the enhancement of the example in :func:`enhancement`, the third point
is enhanced by more than 0.2 in two of three transits:
>>> import numpy as np
>>> from lair.transects import detection_frequency
>>> enh = np.array(
... [[0.0, 0.1, 0.6, 0.0], [0.0, 0.0, 0.1, 0.7], [0.0, np.nan, 0.5, 0.0]]
... )
>>> detection_frequency(enh, threshold=0.2, min_transits=2).round(3)
array([0. , 0. , 0.667, 0.333])
"""
enh = np.asarray(enh, dtype=float)
n = np.isfinite(enh).sum(axis=0)
det = (enh > threshold).sum(axis=0)
with np.errstate(invalid="ignore", divide="ignore"):
f = det / n
f = np.where(n >= min_transits, f, np.nan)
return f
[docs]
def magnitude(
enh: np.ndarray,
threshold: float | None = None,
stat: str = "median",
min_transits: int = 10,
) -> np.ndarray:
"""
Per-point enhancement magnitude.
It is ``stat`` over detected transits (``enh > threshold``) or over all
transits with data (``threshold=None``).
Parameters
----------
enh : np.ndarray
Enhancement matrix ``enh[transit, point]``, as from :func:`enhancement`.
threshold : float or None, optional
Enhancement above which a transit counts as a detection; None (the
default) uses every transit with data.
stat : str, optional
``"median"`` (the default) or ``"mean"``.
min_transits : int, optional
Fewest transits with data (before thresholding) a point needs. Default 10.
Returns
-------
np.ndarray
The magnitude per point. Points sampled by fewer than ``min_transits``
transits are NaN; so are points with no detection at all.
See Also
--------
detection_frequency : How often each point is enhanced.
Examples
--------
>>> import numpy as np
>>> from lair.transects import magnitude
>>> enh = np.array(
... [[0.0, 0.1, 0.6, 0.0], [0.0, 0.0, 0.1, 0.7], [0.0, np.nan, 0.5, 0.0]]
... )
>>> magnitude(enh, threshold=0.2, min_transits=2)
array([ nan, nan, 0.55, 0.7 ])
"""
enh = np.asarray(enh, dtype=float)
n = np.isfinite(enh).sum(axis=0)
if threshold is not None:
enh = np.where(enh > threshold, enh, np.nan)
func = {"median": np.nanmedian, "mean": np.nanmean}[stat]
with np.errstate(invalid="ignore"):
import warnings
with warnings.catch_warnings():
warnings.simplefilter("ignore", RuntimeWarning)
m = func(enh, axis=0)
return np.where(n >= min_transits, m, np.nan)
[docs]
def transit_times(time: np.ndarray, stat: str = "median") -> pd.DatetimeIndex:
"""
One timestamp per transit from a ``time[transit, point]`` matrix.
Parameters
----------
time : np.ndarray
Time matrix ``time[transit, point]``, in POSIX seconds or datetime64, as
from :func:`transect_matrix`.
stat : str, optional
How to reduce each transit's times: ``"median"`` (the default), ``"min"``
or ``"max"``.
Returns
-------
pd.DatetimeIndex
One naive (UTC) time per transit; transits with no data get NaT.
See Also
--------
profile : Bins the metrics by these times.
transect_matrix : Gives the time matrix.
Examples
--------
Two transits of three points; the second has a point without a time, which
the median skips:
>>> import numpy as np
>>> from lair.transects import transit_times
>>> time = np.array([[0, 60, 120.0], [3600, 3660, np.nan]])
>>> list(transit_times(time).strftime("%H:%M:%S"))
['00:01:00', '01:00:30']
>>> list(transit_times(time, "max").strftime("%H:%M:%S"))
['00:02:00', '01:01:00']
"""
t = np.asarray(time)
if np.issubdtype(t.dtype, np.datetime64):
t = t.astype("datetime64[s]").astype(float)
t[np.isnat(np.asarray(time))] = np.nan
func = {"median": np.nanmedian, "min": np.nanmin, "max": np.nanmax}[stat]
import warnings
with warnings.catch_warnings():
warnings.simplefilter("ignore", RuntimeWarning)
rep = func(t.astype(float), axis=1)
return pd.to_datetime(rep, unit="s")
[docs]
def profile(
enh: np.ndarray,
times: pd.DatetimeIndex,
by: str = "hour",
threshold: float = 0.0,
min_transits: int = 10,
tz_offset_hours: float = 0.0,
) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
"""
Return the detection frequency and median magnitude per point, binned by time.
Parameters
----------
enh : np.ndarray
Enhancement matrix ``enh[transit, point]``, as from :func:`enhancement`.
times : pd.DatetimeIndex
One time per transit, as from :func:`transit_times`. A naive time is
UTC; a time-zone-aware time is converted to UTC first, so
``tz_offset_hours`` is the only shift.
by : str, optional
The bins: ``"hour"`` (the default), ``"weekday"`` or ``"month"`` of the
transit time.
threshold : float, optional
Enhancement above which a transit counts as a detection. Default 0.
min_transits : int, optional
Fewest transits with data a point needs in a bin. Default 10.
tz_offset_hours : float, optional
Hours added to the UTC times before binning, to bin by local time (e.g.
-7 for MST). Default 0.
Returns
-------
tuple[np.ndarray, np.ndarray, np.ndarray]
``(bins, freq, mag)``: the bin values, and ``freq[bin, point]`` and
``mag[bin, point]`` from :func:`detection_frequency` and :func:`magnitude`
(median) on the transits of each bin.
See Also
--------
transit_times : Gives ``times``.
detection_frequency : The frequency it computes in each bin.
magnitude : The magnitude it computes in each bin.
Examples
--------
One transit an hour for a day, with point 0 enhanced before noon only. Each
hour has one transit, so ``min_transits=1``:
>>> import numpy as np
>>> import pandas as pd
>>> from lair.transects import profile
>>> enh = np.array([[1.0, 0.0]] * 12 + [[0.0, 0.0]] * 12)
>>> times = pd.date_range("2024-01-15 00:00", periods=24, freq="1h")
>>> bins, freq, mag = profile(enh, times, min_transits=1)
>>> freq[[0, 12]]
array([[1., 0.],
[0., 0.]])
>>> mag[[0, 12]]
array([[ 1., nan],
[nan, nan]])
A time with a time zone is converted to UTC first, so the same moments give
the same bins:
>>> local = times.tz_localize("UTC").tz_convert("America/Denver")
>>> bins, freq_local, mag_local = profile(enh, local, min_transits=1)
>>> bool(np.array_equal(freq, freq_local, equal_nan=True))
True
"""
if times.tz is not None:
times = times.tz_convert("UTC").tz_localize(None)
t = times + pd.Timedelta(hours=tz_offset_hours)
key = {"hour": t.hour, "weekday": t.day_of_week, "month": t.month}[by]
bins = {"hour": np.arange(24), "weekday": np.arange(7), "month": np.arange(1, 13)}[
by
]
key = np.asarray(key, dtype=float)
freq = np.full((len(bins), enh.shape[1]), np.nan)
mag = np.full_like(freq, np.nan)
for i, b in enumerate(bins):
sel = key == b
if sel.sum() == 0:
continue
freq[i] = detection_frequency(enh[sel], threshold, min_transits)
mag[i] = magnitude(enh[sel], threshold, "median", min_transits)
return bins, freq, mag
[docs]
def along_route_distance(lon: np.ndarray, lat: np.ndarray) -> np.ndarray:
"""
Cumulative geodesic distance along the ordered route points.
Parameters
----------
lon, lat : np.ndarray
Longitude and latitude of the route points, in order along the route.
Returns
-------
np.ndarray
Distance from the first point on the WGS84 ellipsoid (km), starting at 0.
See Also
--------
lair.geo.haversine : The distance between two points on a sphere.
Notes
-----
Needs the ``geo`` extra (pyproj).
Examples
--------
Three points 0.01 degrees of latitude apart, about 1.11 km:
>>> import numpy as np
>>> from lair.transects import along_route_distance
>>> lon = np.array([-111.9, -111.9, -111.9])
>>> lat = np.array([40.70, 40.71, 40.72])
>>> along_route_distance(lon, lat).round(2) # doctest: +SKIP
array([0. , 1.11, 2.22])
"""
from pyproj import Geod
seg = Geod(ellps="WGS84").line_lengths(np.asarray(lon), np.asarray(lat))
return np.concatenate([[0.0], np.cumsum(seg)]) / 1000.0
[docs]
def merge_route_points(
routes_xy: list[np.ndarray], tol: float
) -> tuple[np.ndarray, list[np.ndarray]]:
"""
Merge the fixed points of several routes into one network point set.
Points of the first route are kept; a point of a later route is added only if it is
farther than ``tol`` from every point already in the set, otherwise it is snapped to
the nearest existing one. Shared track thus maps to shared network points.
Parameters
----------
routes_xy : list[np.ndarray]
One ``(n_i, 2)`` array of projected coordinates (meters) per route.
tol : float
Distance (meters) within which a point joins an existing network point.
Returns
-------
tuple[np.ndarray, list[np.ndarray]]
``(network_xy, index)``: the network points, and per route the network
point of each of its points (``index[i][k]`` for route ``i``'s point ``k``).
See Also
--------
pool_routes : Stacks the routes' matrices onto the network points.
Examples
--------
The second route shares two points with the first (within 50 m) and adds one:
>>> import numpy as np
>>> from lair.transects import merge_route_points
>>> r1 = np.array([[0, 0], [1000, 0], [2000, 0.0]])
>>> r2 = np.array([[1000, 10], [2000, 5], [2000, 1000.0]])
>>> network, index = merge_route_points([r1, r2], tol=50) # doctest: +SKIP
>>> network # doctest: +SKIP
array([[ 0., 0.],
[1000., 0.],
[2000., 0.],
[2000., 1000.]])
>>> index # doctest: +SKIP
[array([0, 1, 2]), array([1, 2, 3])]
"""
from scipy.spatial import cKDTree
network = np.asarray(routes_xy[0], dtype=float).copy()
index = [np.arange(len(network))]
for xy in routes_xy[1:]:
xy = np.asarray(xy, dtype=float)
d, near = cKDTree(network).query(xy)
new = d > tol
idx = near.copy()
idx[new] = len(network) + np.arange(new.sum())
network = np.vstack([network, xy[new]])
index.append(idx)
return network, index
[docs]
def pool_routes(
matrices: list[np.ndarray], index: list[np.ndarray], n_network: int
) -> np.ndarray:
"""
Stack per-route ``[transit, point]`` matrices onto the network points.
Where two route points of one route snap to the same network point, the last one
wins.
Parameters
----------
matrices : list[np.ndarray]
One ``[transit, point]`` matrix per route.
index : list[np.ndarray]
Per route, the network point of each of its points, from
:func:`merge_route_points`.
n_network : int
Number of network points.
Returns
-------
np.ndarray
A ``[sum of transits, n_network]`` matrix, NaN where a route has no point
(or no data) at a network point.
See Also
--------
merge_route_points : Gives ``index`` and the network points.
Examples
--------
One transit on each of the two routes of :func:`merge_route_points`:
>>> import numpy as np
>>> from lair.transects import pool_routes
>>> index = [np.array([0, 1, 2]), np.array([1, 2, 3])]
>>> matrices = [np.array([[1.0, 2.0, 3.0]]), np.array([[10.0, 20.0, 30.0]])]
>>> pool_routes(matrices, index, n_network=4)
array([[ 1., 2., 3., nan],
[nan, 10., 20., 30.]])
"""
rows = sum(m.shape[0] for m in matrices)
out = np.full((rows, n_network), np.nan)
r0 = 0
for m, idx in zip(matrices, index, strict=True):
m = np.asarray(m, dtype=float)
out[r0 : r0 + m.shape[0], idx] = m
r0 += m.shape[0]
return out
# ---------------------------------------------------------------------------
# Transect builder: from a georeferenced time series to [transit, point]
# ---------------------------------------------------------------------------
TRANSIT_COLUMNS = ["direction", "t_start", "t_end", "s_min", "s_max", "n"]
def _time_seconds(time) -> np.ndarray:
"""
POSIX seconds (float) from numeric or datetime-like input; NaN for NaT.
Datetime-like input goes through pandas, which handles tz-aware times (an object
array to numpy) and NaT. Naive times are taken as UTC.
"""
t = np.asarray(time)
if t.dtype.kind in "biuf":
return t.astype(float)
dt = pd.DatetimeIndex(pd.to_datetime(t, utc=True))
return ((dt - pd.Timestamp(0, tz="UTC")) / pd.Timedelta(seconds=1)).to_numpy(float)
def _runs(t: np.ndarray, max_gap_s: float) -> np.ndarray:
"""Run index per sample; a new run starts after a gap longer than ``max_gap_s``."""
new = np.ones(len(t), bool)
new[1:] = np.diff(t) > max_gap_s
return np.cumsum(new) - 1
[docs]
def lag_positions(time, xy: np.ndarray, lag_s, max_gap_s: float = 600.0) -> np.ndarray:
"""
Positions where the air of each sample was actually taken in.
A sample logged at time *t* is air that entered the inlet ``lag_s`` seconds earlier, so
it belongs at the platform's position at ``t - lag``. Positions are interpolated
linearly in time along ``xy``.
The record is cut into runs at gaps longer than ``max_gap_s``, and ``t - lag`` is not
allowed to reach back before the start of the sample's own run: the first seconds of a
run keep its first position instead of being interpolated across the gap to wherever
the previous run ended.
Parameters
----------
time : array-like
Sample times, sorted: POSIX seconds or datetime-like (see the module
docstring).
xy : np.ndarray
Logged positions, ``(n, 2)``, planar or lon/lat.
lag_s : float or array-like
Inlet lag (seconds), a scalar or one value per sample (the lag differs by
instrument epoch).
max_gap_s : float, optional
Time gap (seconds) that starts a new run. Default 600.
Returns
-------
np.ndarray
The positions, ``(n, 2)``. Samples without a time (NaN / NaT) get a NaN
position and are left out of the interpolation for the others.
See Also
--------
snap_to_route : The next step, the route point of each position.
Examples
--------
A platform logging one position a minute, with the inlet 60 s behind: each
sample belongs where the platform was a minute earlier (the first keeps its
own position):
>>> import numpy as np
>>> from lair.transects import lag_positions
>>> time = np.arange(0, 6) * 60.0
>>> x = np.array([0, 500, 1000, 1500, 2000, 2500.0])
>>> xy = np.column_stack([x, np.zeros_like(x)])
>>> lag_positions(time, xy, lag_s=60.0)[:, 0]
array([ 0., 0., 500., 1000., 1500., 2000.])
"""
t = _time_seconds(time)
xy = np.asarray(xy, dtype=float)
lag = np.broadcast_to(np.asarray(lag_s, dtype=float), t.shape)
out = np.full_like(xy, np.nan)
has_t = np.isfinite(t)
if not has_t.any():
return out
t, lag, xy_t = t[has_t], lag[has_t], xy[has_t]
run = _runs(t, max_gap_s)
starts = np.flatnonzero(np.r_[True, np.diff(run) != 0])
t_lag = np.maximum(t - lag, t[starts][run])
for k in range(xy.shape[1]):
out[has_t, k] = np.interp(t_lag, t, xy_t[:, k])
return out
[docs]
def snap_to_route(
xy: np.ndarray, route_xy: np.ndarray, max_dist: float
) -> tuple[np.ndarray, np.ndarray]:
"""
Find the nearest route point of each sample, within ``max_dist``.
Parameters
----------
xy : np.ndarray
Sample positions, ``(n, 2)``, in projected meters.
route_xy : np.ndarray
Route points, ``(m, 2)``, in the same projected meters.
max_dist : float
Distance (meters) beyond which a sample is off the route.
Returns
-------
tuple[np.ndarray, np.ndarray]
``(index, distance)``: the route point of each sample (-1 beyond
``max_dist``) and its distance. A sample with a NaN position (e.g. no time
in :func:`lag_positions`) gets index -1 and distance NaN.
See Also
--------
transect_matrix : Averages the samples onto ``[transit, point]``.
lag_positions : Gives the positions to snap.
merge_route_points : Joins the points of several routes.
Examples
--------
Six route points 500 m apart along x; the sample at 700 m is 200 m from the
nearest, beyond ``max_dist``:
>>> import numpy as np
>>> from lair.transects import snap_to_route
>>> route = np.column_stack([np.arange(0, 2501, 500.0), np.zeros(6)])
>>> xy = np.array([[10.0, 0.0], [1010.0, 5.0], [700.0, 0.0]])
>>> index, distance = snap_to_route(xy, route, max_dist=100) # doctest: +SKIP
>>> index # doctest: +SKIP
array([ 0, 2, -1])
>>> distance.round(1) # doctest: +SKIP
array([ 10. , 11.2, 200. ])
"""
from scipy.spatial import cKDTree
xy = np.asarray(xy, dtype=float)
d = np.full(len(xy), np.nan)
idx = np.full(len(xy), -1)
finite = np.isfinite(xy).all(axis=1)
if finite.any():
d[finite], idx[finite] = cKDTree(np.asarray(route_xy, dtype=float)).query(
xy[finite]
)
return np.where(d <= max_dist, idx, -1), d
def _empty_transit_table() -> pd.DataFrame:
return pd.DataFrame(columns=TRANSIT_COLUMNS, index=pd.Index([], name="transit"))
[docs]
def split_transits(
time,
s: np.ndarray,
max_gap_s: float = 600.0,
reversal_m: float = 500.0,
min_span_m: float = 1000.0,
) -> tuple[np.ndarray, pd.DataFrame]:
"""
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 :func:`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.
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
... ) # doctest: +SKIP
>>> transit # doctest: +SKIP
array([0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1])
>>> table[["direction", "s_min", "s_max", "n"]] # doctest: +SKIP
direction s_min s_max n
transit
0 1 0.0 2000.0 5
1 -1 0.0 2500.0 6
"""
from scipy.signal import find_peaks
t = _time_seconds(time)
s = np.asarray(s, dtype=float)
transit = np.full(len(t), -1, dtype=int)
idx_on = np.flatnonzero(np.isfinite(s) & np.isfinite(t))
if len(idx_on) == 0:
return transit, _empty_transit_table()
t_on, s_on = t[idx_on], s[idx_on]
run = _runs(t_on, max_gap_s)
run_starts = np.flatnonzero(np.r_[True, np.diff(run) != 0])
run_ends = np.r_[run_starts[1:], len(run)]
rows = []
k = 0
for a0, b0 in zip(run_starts, run_ends, strict=True):
sr = s_on[a0:b0]
if len(sr) < 2:
continue
hi, _ = find_peaks(sr, prominence=reversal_m)
lo, _ = find_peaks(-sr, prominence=reversal_m)
cuts = np.unique(np.r_[0, hi, lo, len(sr)])
for a, b in zip(cuts[:-1], cuts[1:], strict=True):
seg = idx_on[a0 + a : a0 + b]
ss = s[seg]
if ss.max() - ss.min() < min_span_m:
continue
transit[seg] = k
rows.append(
(
k,
1 if ss[-1] >= ss[0] else -1,
t[seg[0]],
t[seg[-1]],
ss.min(),
ss.max(),
len(seg),
)
)
k += 1
if not rows:
return transit, _empty_transit_table()
table = pd.DataFrame(rows, columns=["transit", *TRANSIT_COLUMNS]).set_index(
"transit"
)
return transit, table
[docs]
def transect_matrix(
transit: np.ndarray,
point: np.ndarray,
obs: np.ndarray,
time,
n_transits: int,
n_points: int,
max_dwell_s: float | None = None,
) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
"""
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 :func:`split_transits` (-1 skips the sample).
point : np.ndarray
Route point per sample, from :func:`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.
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.]])
"""
t = _time_seconds(time)
obs = np.asarray(obs, dtype=float)
ok = (transit >= 0) & (point >= 0) & np.isfinite(obs) & np.isfinite(t)
df = pd.DataFrame(
{"transit": transit[ok], "point": point[ok], "obs": obs[ok], "t": t[ok]}
)
if max_dwell_s is not None:
first = df.groupby(["transit", "point"])["t"].transform("min")
df = df[(df["t"] - first) <= max_dwell_s]
agg = df.groupby(["transit", "point"]).agg(
obs=("obs", "mean"), t=("t", "mean"), n=("obs", "size")
)
out_obs = np.full((n_transits, n_points), np.nan)
out_t = np.full_like(out_obs, np.nan)
out_n = np.full_like(out_obs, np.nan)
ti = agg.index.get_level_values("transit").to_numpy()
pi = agg.index.get_level_values("point").to_numpy()
out_obs[ti, pi] = agg["obs"].to_numpy()
out_t[ti, pi] = agg["t"].to_numpy()
out_n[ti, pi] = agg["n"].to_numpy(dtype=float)
return out_obs, out_t, out_n