CamTrapTools 0.6.0__py3-none-any.whl

camtraptools/__init__.py

@@ -0,0 +1,3 @@
+"""CamTrapTools: an open-source toolkit for camera-trap projects."""
+
+__version__ = "0.6.0"

camtraptools/activity.py

@@ -0,0 +1,255 @@
+"""Daily activity patterns and the overlap between species (Ridout & Linkie 2009).
+
+Each independent event's start time is a point on the 24-hour circle. A species'
+activity curve is a kernel density on that circle with von Mises kernels, whose
+concentration follows the rule of Taylor (2008) as in the R package ``overlap``. The
+overlap coefficient Δ is the area under the lower of two curves: 0 when two species
+are never active at the same time of day, 1 when their patterns are identical.
+"""
+
+import math
+from functools import cache
+from itertools import combinations
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+ACTIVITY_FILE = "activity.csv"
+OVERLAP_FILE = "overlap.csv"
+PLOT_FILE = "activity.svg"
+DEFAULT_MIN_EVENTS = 20
+GRID_POINTS = 512
+DIRECT_LIMIT = 2_000_000
+BINS = 1440
+MAX_MOMENT = 3
+LARGE_SAMPLE = 75
+BOOTSTRAP_SAMPLES = 999
+PLOTTED_SPECIES = 6
+COLOURS = ["#0072B2", "#D55E00", "#009E73", "#CC79A7", "#E69F00", "#56B4E9"]
+
+
+def to_radians(times: pd.Series) -> np.ndarray:
+    """Return clock times as angles on the 24-hour circle, in radians."""
+    stamps = pd.to_datetime(times, format="ISO8601")
+    hours = stamps.dt.hour + stamps.dt.minute / 60 + stamps.dt.second / 3600
+    return (hours.to_numpy(dtype=float) / 24) * 2 * math.pi
+
+
+def scaled_bessel(order: int, value):
+    """Return e^(−value) · I_order(value), the modified Bessel function of the first
+    kind scaled to stay finite, from its integral form. ``value`` may be an array."""
+    theta = np.linspace(0, math.pi, 2001)
+    values = np.atleast_1d(np.asarray(value, dtype=float))
+    integrand = np.exp(values[:, None] * (np.cos(theta) - 1)) * np.cos(order * theta)
+    result = np.trapezoid(integrand, theta, axis=1) / math.pi
+    return result if np.ndim(value) else float(result[0])
+
+
+KAPPA_GRID = np.concatenate([np.linspace(0, 20, 2001), np.geomspace(20.05, 500, 400)])
+
+
+@cache
+def moment_lengths(order: int) -> np.ndarray:
+    """Return I_order(κ) / I_0(κ), the mean resultant length of the trigonometric
+    moment of ``order`` of a von Mises distribution, for every κ in ``KAPPA_GRID``."""
+    return scaled_bessel(order, KAPPA_GRID) / scaled_bessel(0, KAPPA_GRID)
+
+
+def concentration_from_moment(order: int, length: float) -> float:
+    """Return the von Mises concentration κ whose trigonometric moment of ``order`` has
+    mean resultant length ``length``, i.e. I_order(κ) / I_0(κ) = length."""
+    return float(np.interp(length, moment_lengths(order), KAPPA_GRID))
+
+
+def von_mises_concentration(angles: np.ndarray) -> float:
+    """Return the concentration κ of a von Mises distribution matching ``angles``,
+    estimated from each trigonometric moment up to order ``MAX_MOMENT`` and taking
+    the largest, so activity with two or three peaks is not mistaken for flat
+    activity (as in the R package ``overlap``)."""
+    estimates = []
+    for order in range(1, MAX_MOMENT + 1):
+        length = abs(np.exp(1j * order * angles).mean())
+        estimates.append(concentration_from_moment(order, length))
+    return max(estimates)
+
+
+def bandwidth(angles: np.ndarray) -> float:
+    """Return the concentration of the von Mises kernels for ``angles`` with the
+    plug-in rule of Taylor (2008): larger for bigger samples and sharper activity, so
+    the curve follows the data more closely."""
+    kappa = von_mises_concentration(angles)
+    if kappa == 0:
+        return 0.0
+    # I_2(2κ) / I_0(κ)² is the same for the scaled functions, as e^(2κ) cancels
+    ratio = scaled_bessel(2, 2 * kappa) / scaled_bessel(0, kappa) ** 2
+    return (3 * len(angles) * kappa**2 * ratio / (4 * math.sqrt(math.pi))) ** (2 / 5)
+
+
+def density(angles: np.ndarray, at: np.ndarray, concentration: float) -> np.ndarray:
+    """Return the circular kernel density of ``angles`` at the angles ``at``, per
+    radian, so that it integrates to 1 over the day.
+
+    Small samples are computed exactly. For large ones (more than
+    ``DIRECT_LIMIT`` kernel evaluations), times are counted in one-minute bins, the
+    kernel is applied to the bins with a fast Fourier transform, and the result is
+    interpolated, which is far faster and differs negligibly.
+    """
+    normalizer = 2 * math.pi * scaled_bessel(0, concentration)
+    if len(angles) * len(at) <= DIRECT_LIMIT:
+        differences = np.cos(at[:, None] - angles[None, :]) - 1
+        return (np.exp(concentration * differences) / normalizer).mean(axis=1)
+    step = 2 * math.pi / BINS
+    counts = np.bincount(np.floor(np.mod(angles, 2 * math.pi) / step).astype(int) % BINS, minlength=BINS)
+    centres = (np.arange(BINS) + 0.5) * step
+    kernel = np.exp(concentration * (np.cos(np.arange(BINS) * step) - 1)) / normalizer
+    smoothed = np.fft.irfft(np.fft.rfft(counts / len(angles)) * np.fft.rfft(kernel), n=BINS)
+    return np.interp(np.mod(at, 2 * math.pi), centres, smoothed, period=2 * math.pi)
+
+
+def grid() -> np.ndarray:
+    """Return evenly spaced angles around the day."""
+    return np.linspace(0, 2 * math.pi, GRID_POINTS, endpoint=False)
+
+
+def overlap(first: np.ndarray, second: np.ndarray) -> float:
+    """Return the overlap coefficient of two samples of times: Δ₄ when the smaller has
+    at least ``LARGE_SAMPLE`` events, otherwise Δ₁, as Ridout & Linkie recommend."""
+    if min(len(first), len(second)) >= LARGE_SAMPLE:
+        f_first = density(first, first, bandwidth(first))
+        g_first = density(second, first, bandwidth(second))
+        f_second = density(first, second, bandwidth(first))
+        g_second = density(second, second, bandwidth(second))
+        return 0.5 * (np.minimum(1, g_first / f_first).mean() + np.minimum(1, f_second / g_second).mean())
+    points = grid()
+    f = density(first, points, bandwidth(first) / 0.8)
+    g = density(second, points, bandwidth(second) / 0.8)
+    return float(np.minimum(f, g).mean() * 2 * math.pi)
+
+
+def overlap_interval(
+    first: np.ndarray, second: np.ndarray, samples: int = BOOTSTRAP_SAMPLES, seed: int = 0
+) -> tuple[float, float, float]:
+    """Return the overlap coefficient with a 95% percentile bootstrap interval,
+    resampling each species' events with replacement. In simulations, percentile
+    intervals held their 95% coverage where basic intervals fell to about 80%."""
+    estimate = overlap(first, second)
+    rng = np.random.default_rng(seed)
+    replicates = np.array(
+        [overlap(rng.choice(first, len(first)), rng.choice(second, len(second))) for _ in range(samples)]
+    )
+    low, high = np.quantile(replicates, [0.025, 0.975])
+    return estimate, float(low), float(high)
+
+
+def activity_curves(times: dict[str, np.ndarray]) -> pd.DataFrame:
+    """Return each species' activity curve on a grid of times of day, as the share of
+    its daily activity per hour."""
+    points = grid()
+    curves = pd.DataFrame({"hour": np.round(points / (2 * math.pi) * 24, 4)})
+    for name, angles in times.items():
+        curves[name] = density(angles, points, bandwidth(angles)) * 2 * math.pi / 24
+    return curves
+
+
+def peak_hour(curve: pd.Series, hours: pd.Series) -> str:
+    """Return the time of day at which an activity curve is highest, as HH:MM."""
+    hour = float(hours[curve.idxmax()])
+    return f"{int(hour):02d}:{round(hour % 1 * 60) % 60:02d}"
+
+
+def overlaps(times: dict[str, np.ndarray], samples: int = BOOTSTRAP_SAMPLES) -> pd.DataFrame:
+    """Return the overlap coefficient and its interval for every pair of species."""
+    rows = []
+    for first, second in combinations(times, 2):
+        estimate, low, high = overlap_interval(times[first], times[second], samples)
+        rows.append(
+            {
+                "first": first,
+                "second": second,
+                "estimator": "Δ4" if min(len(times[first]), len(times[second])) >= LARGE_SAMPLE else "Δ1",
+                "overlap": round(estimate, 2),
+                "overlapLower": round(low, 2),
+                "overlapUpper": round(high, 2),
+            }
+        )
+    columns = ["first", "second", "estimator", "overlap", "overlapLower", "overlapUpper"]
+    return pd.DataFrame(rows, columns=columns).sort_values("overlap", ascending=False, ignore_index=True)
+
+
+def plot(curves: pd.DataFrame, counts: dict[str, int]) -> str:
+    """Return an SVG line chart of the activity curves of the most recorded species."""
+    width, height, left, right, top, bottom = 720, 360, 56, 200, 20, 44
+    plotted = sorted(counts, key=counts.get, reverse=True)[:PLOTTED_SPECIES]
+    peak = max(curves[name].max() for name in plotted) * 1.1
+    inner_width, inner_height = width - left - right, height - top - bottom
+
+    def x(hour: float) -> float:
+        return left + hour / 24 * inner_width
+
+    def y(value: float) -> float:
+        return top + inner_height * (1 - value / peak)
+
+    parts = [
+        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {width} {height}" font-family="sans-serif" font-size="12">',
+        f'<rect width="{width}" height="{height}" fill="white"/>',
+    ]
+    step = next((size for size in [0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1.0] if peak / size <= 6), peak / 4)
+    for tick in np.arange(step, peak, step):
+        parts.append(
+            f'<line x1="{left}" y1="{y(tick):.1f}" x2="{left + inner_width}" y2="{y(tick):.1f}" stroke="#f0f0f0"/>'
+        )
+        parts.append(f'<text x="{left - 6}" y="{y(tick) + 4:.1f}" text-anchor="end">{tick:.0%}</text>')
+    for hour in range(0, 25, 3):
+        parts.append(
+            f'<line x1="{x(hour):.1f}" y1="{top}" x2="{x(hour):.1f}" y2="{top + inner_height}" stroke="#e5e5e5"/>'
+        )
+        parts.append(f'<text x="{x(hour):.1f}" y="{height - 24}" text-anchor="middle">{hour:02d}:00</text>')
+    parts.append(
+        f'<line x1="{left}" y1="{top + inner_height}" x2="{left + inner_width}" y2="{top + inner_height}" '
+        'stroke="#444"/>'
+    )
+    parts.append(f'<text x="{left + inner_width / 2}" y="{height - 6}" text-anchor="middle">Time of day</text>')
+    parts.append(
+        f'<text transform="translate(14 {top + inner_height / 2}) rotate(-90)" text-anchor="middle">'
+        "Share of activity per hour</text>"
+    )
+    for index, name in enumerate(plotted):
+        colour = COLOURS[index % len(COLOURS)]
+        points = " ".join(f"{x(hour):.1f},{y(value):.1f}" for hour, value in zip(curves["hour"], curves[name]))
+        points += f" {x(24):.1f},{y(curves[name].iloc[0]):.1f}"
+        parts.append(f'<polyline points="{points}" fill="none" stroke="{colour}" stroke-width="2"/>')
+        legend_y = top + 16 + index * 22
+        parts.append(
+            f'<line x1="{width - right + 16}" y1="{legend_y}" x2="{width - right + 40}" y2="{legend_y}" '
+            f'stroke="{colour}" stroke-width="3"/>'
+        )
+        label = f"{name} ({counts[name]})".replace("&", "&amp;").replace("<", "&lt;")
+        parts.append(f'<text x="{width - right + 46}" y="{legend_y + 4}" font-style="italic">{label}</text>')
+    parts.append("</svg>")
+    return "\n".join(parts)
+
+
+def run(events: pd.DataFrame, out_dir: Path, min_events: int = DEFAULT_MIN_EVENTS) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """Write activity curves (``activity.csv``), pairwise overlaps (``overlap.csv``) and
+    a chart (``activity.svg``) for every species with at least ``min_events`` events.
+
+    ``events`` has an ``eventStart`` and a ``scientificName`` column. Returns a table of
+    events and peak hour per species, and the overlaps.
+    """
+    counts = events["scientificName"].value_counts()
+    chosen = [name for name, count in counts.items() if count >= min_events]
+    times = {name: to_radians(events.loc[events["scientificName"] == name, "eventStart"]) for name in chosen}
+    out_dir.mkdir(parents=True, exist_ok=True)
+    if not times:
+        return pd.DataFrame(columns=["events", "peak"]), overlaps({})
+    curves = activity_curves(times)
+    curves.to_csv(out_dir / ACTIVITY_FILE, index=False)
+    pairs = overlaps(times)
+    pairs.to_csv(out_dir / OVERLAP_FILE, index=False)
+    (out_dir / PLOT_FILE).write_text(plot(curves, {name: len(times[name]) for name in times}), encoding="utf-8")
+    peaks = pd.DataFrame(
+        {"events": [len(times[name]) for name in times], "peak": [peak_hour(curves[name], curves["hour"]) for name in times]},
+        index=pd.Index(list(times), name="taxon"),
+    )
+    return peaks, pairs