ethograph 0.2.45__tar.gz → 0.2.46__tar.gz

{ethograph-0.2.45 → ethograph-0.2.46}/.gitignore

@@ -2,6 +2,7 @@
 projects/
 !projects/defaults/*
 spot_frames/
+*pynapple_burst_r_to_python.html
 result/
 data/
 weights/

{ethograph-0.2.45 → ethograph-0.2.46}/CLAUDE.md

@@ -61,9 +61,10 @@ ethograph/gui/
     plots_{audiotrace,spectrogram,ephystrace,lineplot,heatmap,raster,space,radial,console}.py
     video_sync.py, video_manager.py, audio_clock.py, label_drawing_mixin.py
     pose_render.py            # Pose loading (NWB + movement), PoseDisplayManager
-    pose_{annotate,fill,refine,detect,detect_preview,tagsheet,edit_mixin}.py   # keypoint labelling + fill
+    pose_{annotate,fill,detect,detect_preview,tagsheet,edit_mixin}.py   # keypoint labelling + fill
+    pose_two_view.py, pose_second_view.py, triangulation.py                    # a second camera view → 3D
     box_annotate.py, box_overlay.py, dialog_box_labelling.py                    # box labelling (OCTRON)
-    dialog_{pose_labelling,skeleton_editor,pose_refinement,tag_sheet}.py
+    dialog_{pose_labelling,skeleton_editor,tag_sheet}.py
     pose_project_mode.py, widgets_frame_extract.py, dialog_collected_data.py, pose_static_group.py   # pose-project mode
     dialog_{label_gridview,video_grid,label_table,onset_model,curation_workflow}.py
     right_context.py, main_window.py, top_bar.py, cover_page.py, table_filter.py, file_dialogs.py
@@ -110,6 +111,12 @@ ethograph/spot/               # Pixel point-event spotting (docs: docs/source/mo
     e2espot/                  # Vendored E2E-Spot in upstream's layout — see its NOTICE.md; excluded from ruff/mypy
     msagsm.py                 # MultiScaleGatedShift, written from the paper
 
+ethograph/triangulate/        # 2D points from calibrated cameras → 3D, through aniposelib
+    calibration.py            # {project}/calibration/{name}.toml (aniposelib's own file) + the DeepLabCut 3D import
+    points.py                 # triangulate_points — the one place aniposelib's triangulation is called
+    session.py                # A session's per-camera 2D points → position_3d in its .nc
+    frame.py, geometry.py     # The world frame beside a calibration; static landmarks as a space/ geometry
+
 ethograph/utils/              # io.py, xr_utils.py, sequences.py, device.py, system_check.py
     configkit.py              # Chained YAML + dotted overrides ↔ dataclass tree; segment and spot each pass a Schema
 ethograph/skeleton/           # PrecomputedRenderer, SkeletonState, config.py, shapes.py
@@ -149,7 +156,7 @@ THIRD_PARTY_NOTICES.md        # Index of every vendored tree and adapted file
 `.nwb` sources are read/edited directly; `.ethograph/alignment.nwb` sidecars exist only for non-NWB sources.
 
 - **Trial timing has one source: the alignment NWB trials table.**
-- **A session is a folder: it holds `.ethograph/alignment.nwb` or a root `.nwb`, and at most one `.nc` (its dataset).** A second root `.nc` is an old version and refused (`AmbiguousSessionError`) until `project.yaml`'s `ignore` names it; a file named explicitly is always loaded. Every session file is named by the folder through `io/session_layout.py` (`session_dir_of`, never `Path(...).parent`). Media folders are absolute and separate: the pairing table carries full paths (`discover_media` takes no root); the NWB stores basenames per trial and full paths per stream. The session record declares the individuals; a dataset's individual dim may only name a subset.
+- **A session is a folder: it holds `.ethograph/alignment.nwb` or a root `.nwb`, and at most one `.nc` (its dataset).** A second root `.nc` is an old version and refused (`AmbiguousSessionError`) until the user's `ignore_files` (`gui_settings.yaml`, global, never per project) names it; a file named explicitly is always loaded. Every session file is named by the folder through `io/session_layout.py` (`session_dir_of`, never `Path(...).parent`). Media folders are absolute and separate: the pairing table carries full paths (`discover_media` takes no root); the NWB stores basenames per trial and full paths per stream. The session record declares the individuals; a dataset's individual dim may only name a subset.
 - **A drop makes the dropped folder the session** (`.ethograph/` goes there; several source folders → one popup, `gui/session_folder.py` ranks kinds); a folder that already has an alignment without a drop record is never overwritten.
 - **Metadata is purely additive** — a tabular file joined on `trial`, resolved explicit `alignment_path` → NWB source trials → sidecar TSV, edited in the trials table and written back to the source it was read from. Media filenames are the alignment's, joined read-only onto the table's right-hand side, never written to a metadata file.
 - **The trials table's filters are the one trial filter, and every operation runs over `app_state.trials`.** No dialog gets a metadata filter of its own; the label filter is a second, session-only slot intersected after the column filters.
@@ -162,9 +169,9 @@ THIRD_PARTY_NOTICES.md        # Index of every vendored tree and adapted file
 
 `PoseRenderData` unifies file (movement) and NWB (lazy HDF5) poses; filtering acts on masks, never recreates layers. **The video overlays any catalog feature in the camera's pixels** (`io/overlay_source.py`): a time dim, a `space` dim with x/y, at most keypoint/individual dims; `position` is the default; companions by name (`confidence` filters, `shape` means boxes); a pose file is read only when the dataset has nothing in that camera's pixels. **Colour encodes one axis, chosen by the user** (`app_state.pose_color_by`); text labels carry the other.
 
-**Keypoint labelling's binding design rules live in `docs/source/advanced/keypoint_labelling/`. Read them before editing `gui/pose_*.py`, `dialog_pose_labelling.py`, `dialog_tag_sheet.py` or `table_filter.py`.** Scope: one camera, one trial.
+**Keypoint labelling's binding design rules live in `docs/source/advanced/classroom_pose_estimation/`. Read them before editing `gui/pose_*.py`, `dialog_pose_labelling.py`, `dialog_tag_sheet.py` or `table_filter.py`.** Scope: one camera, one trial per store; a second camera view is a second store beside the first, never a camera axis (`gui/pose_second_view.py`).
 
-Skeleton precedence: `skeleton_config_override` (user-drawn) > the project's `project.yaml` skeleton > NWB config; each recoloured with `skeleton_base_color`. **`project.yaml` holds study defaults** (individuals, cameras, mics, rig, pose software, skeleton); a session's record or dataset overrides them, machine paths never go in it (`gui/project.py`). Anchored shapes (`skeleton/shapes.py`) are templates bound to ≥2 control points.
+Skeleton precedence: `skeleton_config_override` (user-drawn) > the project's `config/skeleton/*.yaml` > NWB config; each recoloured with `skeleton_base_color`. **There is no `project.yaml`**: the project folder holds files (vocabulary, configs, skeletons, runs), the user's additions (`extra_individuals`, `ignore_files`) are global settings, and a legacy `project.yaml` is folded into them once (`gui/project.py`). Anchored shapes (`skeleton/shapes.py`) are templates bound to ≥2 control points.
 
 ### Panels are layout instances — no per-plot-type toggles
 
@@ -227,6 +234,14 @@ Point events learned from video with the vendored E2E-Spot, scripted like `segme
 - **The pose side is a flat `features:` list, nothing else** (ADR 0008): session variables in segment's `features.columns` spelling, written per trial to `features/{video_id}.npz` and, z-scored on the training split, fed to the model as a second GRU input (run named `{clip}_features`). `graph:`, `fuse:` and a `columns:` key are refused by name. `evaluate(zero_features=True)` measures what the features contribute; `train.features_dropout` is off by default.
 - **Inference always decodes the video straight into the model** (`stream.py`), mirroring `test_e2e.py`'s windows, padding, transform and score accumulation; the frame folder is training's alone. Worker counts are a machine property, never in the YAML. `check_vram` raises before any run the card cannot hold. `inference()` flags an out-of-order trial, never reorders.
 
+### Triangulation (`ethograph/triangulate/`)
+
+Qt-free and scripted like `segment` (`eto.triangulate`). **aniposelib does every piece of multi-view geometry; Ethograph only reads 2D points and writes the result.** The world frame is the one exception, because aniposelib has none.
+
+- **A calibration is a rig's, so it lives in the project**: `{project}/calibration/{name}.toml`, aniposelib's file untouched; one needs no choosing, several are named (`app_state.calibration_name`, per dataset). Its camera names are the alignment's.
+- **2D points are read as the overlay reads them** — a variable with a `camera` dim, else a pose file per camera — and paired on the trial clock, never by frame index.
+- **The result is an ordinary feature**: `position_3d` + `reprojection_error` in the session's `.nc`; the labelling dialog's live 3D points are never stored.
+
 ### Widget orchestration
 
 `MetaWidget` creates all widgets and wires signals; `DataWidget` is the central orchestrator. Flow: `NavigationWidget` → `trial_changed` → `DataWidget.on_trial_changed()` → everything else. The right sidebar is context-sensitive (`_CONTEXT_MAP` in `right_context.py`) with exactly one individual combo. **Guarded shortcuts are disabled while typing, never a no-op.** Neo and Phy trace panels are added on demand, never auto-loaded.

{ethograph-0.2.45 → ethograph-0.2.46}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ethograph
-Version: 0.2.45
+Version: 0.2.46
 Summary: A multimodal timeseries GUI for neuroethology
 Author-email: Akseli Ilmanen <akseli.ilmanen@gmail.com>
 License-Expression: GPL-3.0-or-later
@@ -40,6 +40,7 @@ Requires-Dist: qtpy; extra == "gui"
 Requires-Dist: pyqtgraph; extra == "gui"
 Requires-Dist: PyOpenGL; extra == "gui"
 Requires-Dist: pygfx>=0.15.3; extra == "gui"
+Requires-Dist: uharfbuzz<0.56; extra == "gui"
 Requires-Dist: pynaviz>=0.1; extra == "gui"
 Requires-Dist: rendercanvas; extra == "gui"
 Requires-Dist: wgpu; extra == "gui"
@@ -54,8 +55,9 @@ Requires-Dist: phylib>=2.6.4; extra == "gui"
 Requires-Dist: neo; extra == "gui"
 Requires-Dist: scikit-learn; extra == "gui"
 Requires-Dist: joblib; extra == "gui"
-Requires-Dist: opencv-contrib-python-headless; extra == "gui"
+Requires-Dist: opencv-python-headless<5,>=4.7; extra == "gui"
 Requires-Dist: pupil-apriltags; extra == "gui"
+Requires-Dist: rastermap; extra == "gui"
 Provides-Extra: audio
 Requires-Dist: audioio; extra == "audio"
 Requires-Dist: soundfile; extra == "audio"
@@ -67,6 +69,8 @@ Provides-Extra: dandi
 Requires-Dist: dandi; extra == "dandi"
 Provides-Extra: proxy
 Requires-Dist: imageio-ffmpeg; extra == "proxy"
+Provides-Extra: triangulate
+Requires-Dist: aniposelib>=0.8; extra == "triangulate"
 Provides-Extra: model
 Requires-Dist: tqdm; extra == "model"
 Requires-Dist: movement>=0.14; extra == "model"

{ethograph-0.2.45 → ethograph-0.2.46}/ethograph/__init__.py

@@ -40,7 +40,7 @@ from ethograph.utils.xr_utils import get_ds_duration, get_time_coord, sel_valid
 
 
 def __getattr__(name: str):
-    """Expose the model pipelines lazily — they import torch, which the base install lacks."""
+    """Expose the optional pipelines lazily — they import torch or aniposelib, which the base install lacks."""
     if name == "segment":
         import ethograph.segment as segment
 
@@ -49,6 +49,10 @@ def __getattr__(name: str):
         import ethograph.spot as spot
 
         return spot
+    if name == "triangulate":
+        import ethograph.triangulate as triangulate
+
+        return triangulate
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 

ethograph-0.2.46/ethograph/features/bursts.py

@@ -0,0 +1,312 @@
+"""Burst detection in spike trains: MaxInterval, logISI and an instantaneous-rate threshold.
+
+The two detectors that came out ahead in Cotterill et al. (2016, J Neurophysiol
+116:306, https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4969396/), as described in
+Cotterill & Eglen (2019, https://arxiv.org/abs/1802.01287), plus the birdsong
+field's definition. Checked against the R reference implementations by
+``tests/_test_burst_r_reference.py``.
+
+Every detector takes a ``Ts`` or a ``TsGroup`` and returns bursts as an
+``IntervalSet`` from first to last spike with an ``n_spikes`` metadata column
+(a dict keyed by unit for a ``TsGroup``). Detection runs within each epoch of
+the time support, so a burst never spans a gap in it.
+
+These are proposed for pynapple; once it ships them this module is an import
+of theirs.
+"""
+
+from __future__ import annotations
+
+import numbers
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+import pynapple as nap
+
+#: A run of spikes as (first, last) spike indices, both inclusive.
+Run = tuple[int, int]
+#: What a detector does with one epoch's spike times.
+_FindBursts = Callable[[np.ndarray], list[Run]]
+
+#: A void parameter at or above this separates two peaks of the log-ISI histogram.
+_VOID_THRESHOLD = 0.7
+#: A valley at or beyond this (seconds) separates bursts from pauses, not spikes within bursts.
+_MAX_VALLEY_S = 1.0
+
+
+def _check_spikes(spikes: Any) -> None:
+    if not isinstance(spikes, (nap.Ts, nap.TsGroup)):
+        raise TypeError(f"`spikes` must be `Ts` or `TsGroup`, got {type(spikes)}")
+
+
+def _check_positive(name: str, value: Any, strict: bool = True) -> None:
+    if not isinstance(value, numbers.Real):
+        raise TypeError(f"`{name}` must be a number, got {type(value)}")
+    if strict and value <= 0:
+        raise ValueError(f"`{name}` must be > 0")
+    if not strict and value < 0:
+        raise ValueError(f"`{name}` must be >= 0")
+
+
+def _check_min_spikes(name: str, value: Any) -> None:
+    if not isinstance(value, numbers.Integral):
+        raise TypeError(f"`{name}` must be an integer, got {type(value)}")
+    if value < 2:
+        raise ValueError(f"`{name}` must be >= 2, a burst has at least two spikes")
+
+
+def _find_runs(times: np.ndarray, max_isi_start: float, max_isi_burst: float) -> list[Run]:
+    """Phase 1: a run starts at the first of two spikes closer than *max_isi_start* and
+    ends at the last spike before an interval longer than *max_isi_burst*."""
+    runs: list[Run] = []
+    start: int | None = None
+    for i in range(1, len(times)):
+        isi = times[i] - times[i - 1]
+        if start is None:
+            if isi < max_isi_start:
+                start = i - 1
+        elif isi > max_isi_burst:
+            runs.append((start, i - 1))
+            start = None
+    if start is not None:
+        runs.append((start, len(times) - 1))
+    return runs
+
+
+def _merge_close_runs(times: np.ndarray, runs: list[Run], min_inter_burst_interval: float) -> list[Run]:
+    """Phase 2: consecutive runs separated by less than *min_inter_burst_interval*
+    (last spike of one to first spike of the next) become one run."""
+    merged: list[Run] = []
+    for first, last in runs:
+        if merged and times[first] - times[merged[-1][1]] < min_inter_burst_interval:
+            merged[-1] = (merged[-1][0], last)
+        else:
+            merged.append((first, last))
+    return merged
+
+
+def _drop_small_runs(
+    times: np.ndarray, runs: list[Run], min_burst_duration: float, min_spikes_in_burst: int
+) -> list[Run]:
+    """Phase 3: a run shorter than *min_burst_duration* or with fewer than
+    *min_spikes_in_burst* spikes is not a burst."""
+    return [
+        (first, last)
+        for first, last in runs
+        if times[last] - times[first] >= min_burst_duration and last - first + 1 >= min_spikes_in_burst
+    ]
+
+
+def _detect_per_epoch(spikes: nap.Ts, find_bursts: _FindBursts) -> nap.IntervalSet:
+    """Run *find_bursts* on the spikes of each epoch of the time support, so no burst
+    spans a gap in it, and return the bursts as one IntervalSet."""
+    starts, ends, n_spikes = [], [], []
+    for epoch in spikes.time_support:
+        times = spikes.restrict(epoch).t
+        for first, last in find_bursts(times):
+            # Spikes with identical timestamps span no time and cannot be an interval.
+            if times[last] == times[first]:
+                continue
+            starts.append(times[first])
+            ends.append(times[last])
+            n_spikes.append(last - first + 1)
+    return nap.IntervalSet(start=starts, end=ends, metadata={"n_spikes": n_spikes})
+
+
+def _apply(spikes: nap.Ts | nap.TsGroup, find_bursts: _FindBursts) -> nap.IntervalSet | dict[Any, nap.IntervalSet]:
+    if isinstance(spikes, nap.TsGroup):
+        return {k: _detect_per_epoch(spikes[k], find_bursts) for k in spikes}
+    return _detect_per_epoch(spikes, find_bursts)
+
+
+def detect_bursts_max_interval(
+    spikes: nap.Ts | nap.TsGroup,
+    max_isi_start: float = 0.17,
+    max_isi_burst: float = 0.3,
+    min_inter_burst_interval: float = 0.2,
+    min_burst_duration: float = 0.01,
+    min_spikes_in_burst: int = 3,
+) -> nap.IntervalSet | dict[Any, nap.IntervalSet]:
+    """Bursts by the MaxInterval method of NeuroExplorer.
+
+    A burst starts at the first of two spikes closer than *max_isi_start* and
+    continues while consecutive spikes are no further apart than
+    *max_isi_burst*. Bursts separated by less than *min_inter_burst_interval*
+    are merged; one shorter than *min_burst_duration* or with fewer than
+    *min_spikes_in_burst* spikes is discarded. All times are in seconds. The
+    parameters are those of figure 3 of Cotterill & Eglen (2019), the
+    defaults table 1 of Cotterill et al. (2016).
+    """
+    _check_spikes(spikes)
+    _check_positive("max_isi_start", max_isi_start)
+    _check_positive("max_isi_burst", max_isi_burst)
+    _check_positive("min_inter_burst_interval", min_inter_burst_interval, strict=False)
+    _check_positive("min_burst_duration", min_burst_duration, strict=False)
+    _check_min_spikes("min_spikes_in_burst", min_spikes_in_burst)
+
+    def find_bursts(times: np.ndarray) -> list[Run]:
+        runs = _find_runs(times, max_isi_start, max_isi_burst)
+        runs = _merge_close_runs(times, runs, min_inter_burst_interval)
+        return _drop_small_runs(times, runs, min_burst_duration, min_spikes_in_burst)
+
+    return _apply(spikes, find_bursts)
+
+
+def _log_isi_histogram(isi_ms: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """The interspike intervals (ms) on a logarithmic axis: 10 bin edges per decade from
+    1 ms to the decade above the longest interval, intervals under 1 ms left out.
+
+    Returns the bins' left edges (ms) and the counts normalised to sum to one.
+    """
+    decades = max(1, int(np.ceil(np.log10(isi_ms.max()))))
+    edges = np.logspace(0, decades, 10 * decades)
+    isi_ms = isi_ms[isi_ms >= 1]
+    # Bin k holds edges[k] < isi <= edges[k + 1]; 1 ms itself goes to bin 0.
+    bins = np.clip(np.searchsorted(edges, isi_ms, side="left") - 1, 0, None)
+    counts = np.bincount(bins, minlength=len(edges) - 1)
+    return edges[:-1], counts / counts.sum()
+
+
+def _find_peaks(density: np.ndarray) -> list[int]:
+    """Bins strictly higher than every bin within two bins of them, first and last bin excluded."""
+    peaks = []
+    for k in range(1, len(density) - 1):
+        neighbours = np.delete(density[max(0, k - 2) : k + 3], min(k, 2))
+        if np.all(density[k] > neighbours):
+            peaks.append(k)
+    return peaks
+
+
+def _log_isi_valley(isi_s: np.ndarray, max_cutoff: float) -> tuple[bool, float | None]:
+    """The threshold of Pasquale et al. (2010): the ISI at the first valley that separates
+    the intra-burst peak of the log-ISI histogram from a later peak.
+
+    Returns whether the histogram has an intra-burst peak at all, and the
+    threshold in seconds (``None`` without a well-separated valley).
+    """
+    isi_ms = isi_s * 1000
+    if len(isi_ms) == 0 or not np.any(isi_ms >= 1):
+        return False, None
+    edges, density = _log_isi_histogram(isi_ms)
+    peaks = _find_peaks(density)
+    intraburst = [k for k in peaks if edges[k] < max_cutoff * 1000]
+    if not intraburst:
+        return False, None
+    peak = max(intraburst, key=lambda k: density[k])
+    for later in peaks:
+        if later <= peak:
+            continue
+        between = density[peak : later + 1]
+        valley = peak + int(np.argmin(between))
+        void = 1 - between.min() / np.sqrt(density[peak] * density[later])
+        if void >= _VOID_THRESHOLD:
+            return True, float(edges[valley] / 1000)
+    return True, None
+
+
+def _interspike_intervals(spikes: nap.Ts) -> np.ndarray:
+    """The intervals between consecutive spikes, within each epoch of the time support only."""
+    # pynapple's time_diff() cannot read a train with no spikes at all.
+    if len(spikes) == 0:
+        return np.empty(0)
+    return spikes.time_diff().values
+
+
+def compute_log_isi_threshold(
+    spikes: nap.Ts | nap.TsGroup, max_cutoff: float = 0.1
+) -> float | None | dict[Any, float | None]:
+    """The burst threshold of the logISI method, in seconds.
+
+    The interval at the valley between the intra-burst peak of the log-ISI
+    histogram (its largest peak below *max_cutoff*) and the first later peak
+    well separated from it. ``None`` when the histogram has no intra-burst
+    peak or no such valley.
+    """
+    _check_spikes(spikes)
+    _check_positive("max_cutoff", max_cutoff)
+    if isinstance(spikes, nap.TsGroup):
+        return {k: _log_isi_valley(_interspike_intervals(spikes[k]), max_cutoff)[1] for k in spikes}
+    return _log_isi_valley(_interspike_intervals(spikes), max_cutoff)[1]
+
+
+def _extend_to_related_spikes(times: np.ndarray, cores: list[Run], threshold: float) -> list[Run]:
+    """Extend each core to the run of spikes with consecutive intervals no longer than
+    *threshold* that contains it; cores inside the same run become one burst."""
+    runs = _find_runs(times, threshold, threshold)
+    extended: list[Run] = []
+    for first, last in cores:
+        container = next((r for r in runs if r[0] <= first and last <= r[1]), (first, last))
+        if container not in extended:
+            extended.append(container)
+    return extended
+
+
+def detect_bursts_log_isi(
+    spikes: nap.Ts | nap.TsGroup,
+    max_cutoff: float = 0.1,
+    min_spikes_in_burst: int = 3,
+    fallback: bool = True,
+) -> nap.IntervalSet | dict[Any, nap.IntervalSet]:
+    """Bursts by the logISI method of Pasquale et al. (2010).
+
+    The threshold between intra- and inter-burst intervals is read off each
+    train's own log-ISI histogram (:func:`compute_log_isi_threshold`), over
+    every epoch; a burst is a run of at least *min_spikes_in_burst* spikes
+    with consecutive intervals no longer than it. A threshold above
+    *max_cutoff* finds burst cores at *max_cutoff*, merges cores closer than
+    the threshold and extends each to the spikes within the threshold of its
+    ends. No intra-burst peak means no bursts. No clear valley (or one at a
+    second or more) falls back to *max_cutoff* as the threshold — unless
+    *fallback* is off, which returns no bursts for such a train and is not
+    part of the published method.
+    """
+    _check_spikes(spikes)
+    _check_positive("max_cutoff", max_cutoff)
+    _check_min_spikes("min_spikes_in_burst", min_spikes_in_burst)
+    if not isinstance(fallback, bool):
+        raise TypeError(f"`fallback` must be a bool, got {type(fallback)}")
+
+    if isinstance(spikes, nap.TsGroup):
+        return {k: detect_bursts_log_isi(spikes[k], max_cutoff, min_spikes_in_burst, fallback) for k in spikes}
+
+    has_peak, threshold = _log_isi_valley(_interspike_intervals(spikes), max_cutoff)
+
+    def find_bursts(times: np.ndarray) -> list[Run]:
+        if not has_peak:
+            return []
+        if threshold is None or threshold >= _MAX_VALLEY_S:
+            if not fallback:
+                return []
+            runs = _find_runs(times, max_cutoff, max_cutoff)
+            return _drop_small_runs(times, runs, 0, min_spikes_in_burst)
+        if threshold > max_cutoff:
+            cores = _find_runs(times, max_cutoff, max_cutoff)
+            cores = _merge_close_runs(times, cores, threshold)
+            cores = _drop_small_runs(times, cores, 0, min_spikes_in_burst)
+            return _extend_to_related_spikes(times, cores, threshold)
+        runs = _find_runs(times, threshold, threshold)
+        return _drop_small_runs(times, runs, 0, min_spikes_in_burst)
+
+    return _detect_per_epoch(spikes, find_bursts)
+
+
+def detect_bursts_instantaneous_rate(
+    spikes: nap.Ts | nap.TsGroup, rate_threshold: float = 125.0, min_spikes_in_burst: int = 2
+) -> nap.IntervalSet | dict[Any, nap.IntervalSet]:
+    """Bursts as the runs of spikes over which the instantaneous rate exceeds *rate_threshold* (Hz).
+
+    The instantaneous rate between two spikes is the inverse of their
+    interval — the burst definition of the birdsong literature, 125 Hz in
+    Leonardo & Fee (2005, https://doi.org/10.1523/JNEUROSCI.3036-04.2005).
+    """
+    _check_spikes(spikes)
+    _check_positive("rate_threshold", rate_threshold)
+    _check_min_spikes("min_spikes_in_burst", min_spikes_in_burst)
+    max_isi = 1.0 / rate_threshold
+
+    def find_bursts(times: np.ndarray) -> list[Run]:
+        runs = _find_runs(times, max_isi, max_isi)
+        return _drop_small_runs(times, runs, 0, min_spikes_in_burst)
+
+    return _apply(spikes, find_bursts)

{ethograph-0.2.45 → ethograph-0.2.46}/ethograph/features/movement.py

@@ -14,7 +14,12 @@ from scipy.spatial.distance import cdist
 
 
 class Position3DCalibration:
-    """Convert 3D positions from DLC to real-world coordinates."""
+    """Convert 3D positions from DLC to real-world coordinates.
+
+    Hand-tuned for the Moll et al., 2025 rig and kept for that dataset's
+    example. A new rig gets a world frame beside its calibration instead
+    (``ethograph.triangulate.frame``).
+    """
 
     def __init__(
         self,

{ethograph-0.2.45 → ethograph-0.2.46}/ethograph/features/neural.py

@@ -1,4 +1,4 @@
-"""Compute firing rates, PCA, and PSTH from spike times using pynapple.
+"""Compute firing rates from spike times using pynapple.
 
 Assumes spike_times are in seconds and sorted ascending (standard for Kilosort/Phy).
 
@@ -26,14 +26,13 @@ session open, every time.
 """
 
 from collections.abc import Sequence
+from dataclasses import dataclass
 from typing import Any, Literal
 
 import numpy as np
 import pynapple as nap
 import xarray as xr
 
-from ethograph.io import schema
-
 
 def build_tsgroup(
     spike_times: np.ndarray,
@@ -76,6 +75,63 @@ def build_tsgroup(
     return nap.TsGroup(units, time_support=time_support)
 
 
+@dataclass(frozen=True)
+class SpikeTable:
+    """Every spike of a ``TsGroup`` in one time-sorted table.
+
+    A window of it is one binary search, however many units there are —
+    restricting the group unit by unit is one pynapple call each.
+    """
+
+    times: np.ndarray
+    units: np.ndarray
+
+    @classmethod
+    def from_tsgroup(cls, tsgroup: nap.TsGroup) -> "SpikeTable":
+        unit_ids = [int(uid) for uid in tsgroup.keys()]
+        trains = [np.asarray(tsgroup[uid].times(), dtype=np.float64) for uid in unit_ids]
+        if not trains:
+            return cls(np.empty(0, dtype=np.float64), np.empty(0, dtype=np.int64))
+        times = np.concatenate(trains)
+        units = np.repeat(np.asarray(unit_ids, dtype=np.int64), [len(train) for train in trains])
+        order = np.argsort(times, kind="stable")
+        return cls(times[order], units[order])
+
+    def window(self, t_start: float, t_stop: float) -> tuple[np.ndarray, np.ndarray]:
+        """Spike times and their unit ids inside ``[t_start, t_stop]``."""
+        i0 = int(np.searchsorted(self.times, t_start, side="left"))
+        i1 = int(np.searchsorted(self.times, t_stop, side="right"))
+        return self.times[i0:i1], self.units[i0:i1]
+
+    def count(
+        self, unit_ids: Sequence[int], t_start: float, t_stop: float, bin_size: float
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Spike counts of ``unit_ids`` in bins of ``bin_size`` seconds from ``t_start``.
+
+        Returns the counts, shape ``(n_bins, n_units)`` with the columns in
+        the order of ``unit_ids``, and the centre of each bin. Only whole bins
+        are counted; a remainder shorter than a bin is left out.
+        """
+        if bin_size <= 0:
+            raise ValueError(f"bin_size must be positive, got {bin_size}")
+        columns = np.asarray(unit_ids, dtype=np.int64)
+        n_bins = int(np.floor((t_stop - t_start) / bin_size + 1e-9))
+        centers = t_start + (np.arange(n_bins) + 0.5) * bin_size
+        if n_bins <= 0 or len(columns) == 0:
+            return np.zeros((max(n_bins, 0), len(columns)), dtype=np.int64), centers
+
+        times, units = self.window(t_start, t_start + n_bins * bin_size)
+        by_id = np.argsort(columns, kind="stable")
+        found = np.searchsorted(columns, units, sorter=by_id)
+        found[found == len(columns)] = 0
+        column = by_id[found]
+        bin_index = np.floor((times - t_start) / bin_size).astype(np.int64)
+        keep = (columns[column] == units) & (bin_index < n_bins)
+        flat = bin_index[keep] * len(columns) + column[keep]
+        counts = np.bincount(flat, minlength=n_bins * len(columns))
+        return counts.reshape(n_bins, len(columns)), centers
+
+
 def firing_rate_by_cluster(
     spike_times: np.ndarray,
     spike_clusters: np.ndarray,
@@ -114,8 +170,10 @@ def firing_rate_by_cluster(
         Cluster ID for each row, shape ``(n_clusters,)``.
     """
     if _tsgroup is not None:
-        if cluster_ids is None:
-            cluster_ids = np.array(list(_tsgroup.keys()))
+        if cluster_ids is not None:
+            # pynapple refuses a subset whose keys are not in its own (sorted) order.
+            _tsgroup = _tsgroup[np.sort(np.asarray(cluster_ids))]
+        cluster_ids = np.array(list(_tsgroup.keys()))
         if t_start is None:
             t_start = float(_tsgroup.time_support.start[0])
         if t_stop is None:
@@ -144,62 +202,6 @@ def firing_rate_by_cluster(
     return rates, bin_centers, cluster_ids
 
 
-def compute_pca(
-    firing_rate: xr.DataArray,
-    n_components: int = 3,
-    zscore: bool = True,
-) -> xr.DataArray:
-    """Project population firing rates into PCA space via SVD.
-
-    Parameters
-    ----------
-    firing_rate : xarray.DataArray
-        Firing rates with dims ``("cluster_id", "time_fr")``.
-    n_components : int
-        Number of principal components to keep.
-    zscore : bool
-        Z-score each cluster's firing rate before PCA.
-
-    Returns
-    -------
-    xarray.DataArray
-        Scores with dims ``("time_fr", "pc")``, coords
-        ``pc=["PC1", "PC2", ...]``, and ``attrs["explained_variance"]``.
-    """
-    X = firing_rate.values.T  # (time, clusters)
-
-    if zscore:
-        mean = X.mean(axis=0)
-        std = X.std(axis=0)
-        std[std == 0] = 1.0
-        X = (X - mean) / std
-
-    U, S, _ = np.linalg.svd(X, full_matrices=False)
-    scores = U[:, :n_components] * S[:n_components]
-
-    total_var = (S**2).sum()
-    explained = (S[:n_components] ** 2) / total_var
-
-    pc_labels = [f"PC{i + 1}" for i in range(n_components)]
-
-    return schema.describe(
-        xr.DataArray(
-            data=scores,
-            dims=("time_fr", "pc"),
-            coords={
-                "time_fr": firing_rate.coords["time_fr"].values,
-                "pc": pc_labels,
-            },
-            attrs={
-                "explained_variance": explained.tolist(),
-                "zscore": zscore,
-                "n_clusters": firing_rate.sizes["cluster_id"],
-            },
-        ),
-        schema.NEURAL_FEATURE,
-    )
-
-
 def firing_rate_to_xarray(
     spike_times: np.ndarray,
     spike_clusters: np.ndarray,
@@ -255,6 +257,37 @@ def firing_rate_to_xarray(
     )
 
 
+#: The instantaneous rate above which the birdsong literature calls spikes a burst:
+#: "A burst was defined as the interval over which the instantaneous firing rate
+#: exceeded a threshold of 125 Hz" — Leonardo A, Fee MS (2005). Ensemble coding of
+#: vocal control in birdsong. J Neurosci 25(3):652-661,
+#: https://doi.org/10.1523/JNEUROSCI.3036-04.2005. Other songbird studies use 100 Hz.
+#: A starting point for a threshold the user sets, tuned to RA neurons — not a constant
+#: of nature.
+BURST_INSTANTANEOUS_RATE_HZ = 125.0
+
+
+def instantaneous_rate(spike_times: np.ndarray, at: np.ndarray) -> np.ndarray:
+    """The instantaneous firing rate at each of *at*: ``1 / ISI`` of the inter-spike interval it falls in.
+
+    The birdsong field's definition — from each spike until the next, the
+    rate is the reciprocal of that interval — so the rate is a step function
+    with no bin and no smoothing, and a burst reads as high from its first
+    spike. Before the first spike and from the last one on there is no
+    interval to read, and the rate is 0. *spike_times* is sorted ascending;
+    spikes at the same instant count once.
+    """
+    spikes = np.unique(np.asarray(spike_times, dtype=np.float64))
+    at = np.asarray(at, dtype=np.float64)
+    rate = np.zeros(len(at), dtype=np.float64)
+    if len(spikes) < 2:
+        return rate
+    interval = np.searchsorted(spikes, at, side="right") - 1
+    inside = (interval >= 0) & (interval < len(spikes) - 1)
+    rate[inside] = 1.0 / np.diff(spikes)[interval[inside]]
+    return rate
+
+
 # ---------------------------------------------------------------------------
 # The segmentation pipeline's spike input: ``features.neural.transform``
 # ---------------------------------------------------------------------------