Skip to content

Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)

Implement bounded time-aware acoustic episode discovery (#349)

Cinna Davis609b86a36fbd
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 8912688..26db5c7 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -35,6 +35,8 @@ jobs:
python -m pip check
# The owner requires real recordings for further validation. The historical
# pytest suite generates synthetic inputs, so this workflow does not run it.
+ - name: Check acoustic episode algebra and recorded evidence
+ run: python -m pytest -q tests/test_episodes.py tests/test_real_discovery_normalization.py tests/test_real_upload_verification.py tests/test_contracts.py
- name: Compile source without executing experiments
run: python -m compileall -q src scripts
- name: Check benchmark instrumentation detection
diff --git a/scripts/benchmark_real_discovery_plots.py b/scripts/benchmark_real_discovery_plots.py
index 0495c60..7e2919f 100644
--- a/scripts/benchmark_real_discovery_plots.py
+++ b/scripts/benchmark_real_discovery_plots.py
@@ -52,10 +52,15 @@ def main():
if not events:
parser.error("The real recording contains no event diagnostics to compare")
group_ids = list(dict.fromkeys(event["harmonic_group_id"] for event in events))
- if len(group_ids) != len(diagnostics["harmonic_ridges"]):
- parser.error("Discovery groups and measured harmonic ridges do not agree")
- groups = {name: [np.asarray(points) for points in rows]
- for name, rows in zip(group_ids, diagnostics["harmonic_ridges"])}
+ if diagnostics.get("schema_version", 1) >= 2:
+ measured = {e["event_id"]: np.array([[p["time_s"],p["frequency_hz"],p.get("weight",1.)] for p in e["ridge"]]) for e in events}
+ groups = {e["proposal_id"]:[measured[c] for c in e["child_ridge_ids"]] for e in diagnostics["episodes"]}
+ events = [dict(e,harmonic_group_id=e["proposal_id"]) for e in diagnostics["episodes"]]
+ else:
+ if len(group_ids) != len(diagnostics["harmonic_ridges"]):
+ parser.error("Discovery groups and measured harmonic ridges do not agree")
+ groups = {name: [np.asarray(points) for points in rows]
+ for name, rows in zip(group_ids, diagnostics["harmonic_ridges"])}
implementations = {"baseline": _module(args.baseline.resolve()), "current": discovery}
args.output.mkdir(parents=True, exist_ok=False)
samples = {name: [] for name in implementations}
diff --git a/scripts/discover_audio.py b/scripts/discover_audio.py
index e8e6d85..c3eab4b 100644
--- a/scripts/discover_audio.py
+++ b/scripts/discover_audio.py
@@ -11,7 +11,7 @@ from pathlib import Path
import subprocess
import time
-from dopplergeist.discovery import DiscoverySettings, discover_events
+from dopplergeist.discovery import DiscoverySettings, discover_events, required_sample_rate
from dopplergeist.intake import intake_recording
from dopplergeist.resource_usage import process_peak_rss_kib
@@ -24,14 +24,21 @@ def main():
help="render the recording-level ridge overview plot")
parser.add_argument("--plot-event-details", action="store_true",
help="render one spectrogram PNG per discovered event (slower)")
+ parser.add_argument("--min-frequency-hz", type=float, default=40.0)
+ parser.add_argument("--max-frequency-hz", type=float, default=1600.0)
+ parser.add_argument("--window-s", type=float, default=2.0)
+ parser.add_argument("--hop-s", type=float, default=.5)
+ parser.add_argument("--detailed-candidates", action="store_true", help="bounded rejected-candidate measurements")
args = parser.parse_args()
+ settings = DiscoverySettings(min_frequency_hz=args.min_frequency_hz, max_frequency_hz=args.max_frequency_hz,
+ window_s=args.window_s, hop_s=args.hop_s)
output = Path(args.output)
output.mkdir(parents=True, exist_ok=False)
began = time.monotonic()
- recording = intake_recording(args.audio, output / "intake")
+ recording = intake_recording(args.audio, output / "intake", sample_rate_hz=required_sample_rate(settings))
events = discover_events(recording, output_dir=output / "discovery",
plot_summary=args.plot_summary,
- plot_event_details=args.plot_event_details)
+ plot_event_details=args.plot_event_details, settings=settings, detailed_candidates=args.detailed_candidates)
root = Path(__file__).resolve().parents[1]
sources = sorted((root / "src" / "dopplergeist").glob("*.py"))
code_hash = hashlib.sha256()
@@ -39,7 +46,8 @@ def main():
code_hash.update(path.name.encode())
code_hash.update(path.read_bytes())
result = {"recording": recording.metadata, "time_status": recording.time_status,
- "settings": asdict(DiscoverySettings()), "events_found": len(events),
+ "settings": asdict(settings), "events_found": len({e["harmonic_group_id"] for e in events}),
+ "measured_child_tracks": len(events),
"events": [{k: event[k] for k in ("event_id", "start_s", "end_s", "band_hz", "quality")} for event in events],
"runtime_s": time.monotonic() - began, "peak_rss_kib": process_peak_rss_kib(),
"code_sha256": code_hash.hexdigest(),
diff --git a/scripts/validate_acoustic_episodes.py b/scripts/validate_acoustic_episodes.py
new file mode 100644
index 0000000..ecd0189
--- /dev/null
+++ b/scripts/validate_acoustic_episodes.py
@@ -0,0 +1,77 @@
+"""Paired acoustic-only replay of a predeclared real-media manifest.
+
+No downloads, fabricated signals, source identity labels or localization inputs
+enter discovery. Each case runs in a fresh process for comparable peak RSS.
+"""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+
+
+def run_case(case, output, upper):
+ from dopplergeist.discovery import DiscoverySettings, discover_events
+ from dopplergeist.intake import intake_recording
+ from dopplergeist.resource_usage import process_peak_rss_kib
+ began = time.monotonic()
+ settings = DiscoverySettings(max_frequency_hz=upper)
+ rate = next(rate for rate in (4000, 8000, 16000, 32000) if upper <= rate * .45)
+ result = dict(case_id=case['id'], source_sha256=case['sha256'])
+ try:
+ with Path(case['path']).open('rb') as stream:
+ if hashlib.file_digest(stream, 'sha256').hexdigest() != case['sha256']:
+ raise ValueError('Real input checksum differs from frozen manifest')
+ recording = intake_recording(case['path'], output / 'intake', sample_rate_hz=rate)
+ events = discover_events(recording, output_dir=output / 'discovery', settings=settings, plot_summary=True)
+ groups = sorted({e.get('harmonic_group_id', e['event_id']) for e in events})
+ result.update(status='complete', duration_s=recording.metadata['duration_s'],
+ proposals=len(groups), child_tracks=len(events),
+ intervals=[dict(group=g, intervals_s=[[e['start_s'],e['end_s']] for e in events if e.get('harmonic_group_id',e['event_id'])==g]) for g in groups])
+ data = json.loads((output / 'discovery/discovery.json').read_text())
+ result['counts'] = data.get('counts', {})
+ result['rejections'] = data.get('rejections', {})
+ except Exception as exc:
+ result.update(status='failed', error_type=type(exc).__name__, error=str(exc))
+ result.update(runtime_s=time.monotonic()-began, peak_rss_kib=process_peak_rss_kib(),
+ output_bytes=sum(p.stat().st_size for p in (output / 'discovery').glob('*') if p.is_file()))
+ return result
+
+
+def main():
+ parser=argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--manifest',type=Path,required=True)
+ parser.add_argument('--source-root',type=Path,required=True)
+ parser.add_argument('--output',type=Path,required=True)
+ parser.add_argument('--max-frequency-hz',type=float,default=1600)
+ parser.add_argument('--case',help=argparse.SUPPRESS)
+ args=parser.parse_args()
+ cases=json.loads(args.manifest.read_text())['cases']
+ if args.case:
+ case=next(c for c in cases if c['id']==args.case)
+ print(json.dumps(run_case(case,args.output,args.max_frequency_hz),allow_nan=False))
+ return
+ args.output.mkdir(parents=True,exist_ok=False)
+ env=dict(os.environ,PYTHONPATH=str(args.source_root.resolve()/'src'),OPENBLAS_NUM_THREADS='1',OMP_NUM_THREADS='1',MPLBACKEND='Agg')
+ results=[]
+ for case in cases:
+ command=[sys.executable,str(Path(__file__).resolve()),'--manifest',str(args.manifest.resolve()),
+ '--source-root',str(args.source_root.resolve()),'--output',str(args.output.resolve()/case['id']),
+ '--max-frequency-hz',str(args.max_frequency_hz),'--case',case['id']]
+ process=subprocess.run(command,capture_output=True,text=True,env=env,timeout=600)
+ if process.returncode:
+ result=dict(case_id=case['id'],status='failed',error=process.stderr[-2000:])
+ else:
+ result=json.loads(process.stdout)
+ results.append(result)
+ with (args.output/'results.jsonl').open('a') as stream:
+ stream.write(json.dumps(result,allow_nan=False)+'\n')
+ print(case['id'],result['status'],result.get('proposals'),round(result.get('runtime_s',0),2),flush=True)
+ (args.output/'summary.json').write_text(json.dumps(results,indent=2,allow_nan=False)+'\n')
+
+
+if __name__=='__main__':
+ main()
diff --git a/src/dopplergeist/automatic.py b/src/dopplergeist/automatic.py
index 50beb22..d967071 100644
--- a/src/dopplergeist/automatic.py
+++ b/src/dopplergeist/automatic.py
@@ -19,7 +19,7 @@ def _digest(path):
def _audio_identity(request, config):
- modules = ("intake.py", "discovery.py", "audio.py", "contracts.py")
+ modules = ("intake.py", "discovery.py", "episodes.py", "audio.py", "contracts.py")
return {"request": request, "source_sha256": _digest(request["audio_path"]),
"discovery_settings": config.get("discovery", {}),
"modules": {name: _digest(Path(__file__).parent / name) for name in modules},
@@ -104,15 +104,15 @@ def analyze(request, output_dir, config=None, progress=lambda *args, **kwargs: N
try:
from .intake import AudioIntakeError, intake_recording
- from .discovery import DiscoverySettings, discover_events
+ from .discovery import DiscoveryError, DiscoverySettings, discover_events, required_sample_rate
except ImportError as exc:
return finish("failed", "component_unavailable", f"Automatic audio components are not installed: {exc}")
discovery_options = config.get("discovery", {})
search_workers = config.get("search_workers")
if search_workers is not None and (type(search_workers) is not int or search_workers < 1):
return finish("failed", "invalid_configuration", "search_workers must be a positive integer.")
- if not isinstance(discovery_options, dict) or discovery_options.keys() - {"chunk_s", "overlap_s"}:
- return finish("failed", "invalid_configuration", "Operator discovery settings support only chunk_s and overlap_s.")
+ if not isinstance(discovery_options, dict) or discovery_options.keys() - {"chunk_s", "overlap_s", "min_frequency_hz", "max_frequency_hz", "window_s", "hop_s"}:
+ return finish("failed", "invalid_configuration", "Operator discovery settings support chunk/overlap and global spectral coverage/window/hop.")
try:
discovery_settings = DiscoverySettings(**discovery_options)
except (TypeError, ValueError) as exc:
@@ -127,12 +127,15 @@ def analyze(request, output_dir, config=None, progress=lambda *args, **kwargs: N
if not resume:
progress("intake", 0.05)
try:
- recording = intake_recording(request["audio_path"], output / "intake", time_window=request.get("time_window"))
+ recording = intake_recording(request["audio_path"], output / "intake", time_window=request.get("time_window"), sample_rate_hz=required_sample_rate(discovery_settings))
except AudioIntakeError as exc:
return finish("failed", exc.code, str(exc))
state["recording"] = recording.metadata
progress("discovery", 0.15, recording=recording.metadata)
- events = [validate_event(event) for event in discover_events(recording, output_dir=output / "discovery", settings=discovery_settings)]
+ try:
+ events = [validate_event(event) for event in discover_events(recording, output_dir=output / "discovery", settings=discovery_settings)]
+ except DiscoveryError as exc:
+ return finish("failed", exc.code, str(exc))
_save_audio_checkpoint(output, request, config)
state["recording"] = recording.metadata
state["events"] = events
@@ -142,6 +145,8 @@ def analyze(request, output_dir, config=None, progress=lambda *args, **kwargs: N
return finish("needs_input", "recording_time_required", "Supply a defensible UTC window for the start of this recording. File creation and upload times are not recording clocks.", required_fields=["time_window"])
if not events:
return finish("inconclusive", "no_supported_events", "No supported moving-tone Doppler events were discovered in the recording.")
+ if not any(e.get("quality", {}).get("matching_eligible", 1) for e in events):
+ return finish("inconclusive", "brief_acoustic_evidence_only", "Brief acoustic episodes were found, with insufficient observed samples for trajectory matching.")
progress("acquisition", 0.35, **state)
def report_search_progress(fraction=0.0):
diff --git a/src/dopplergeist/discovery.py b/src/dopplergeist/discovery.py
index 7fb352b..b4abc84 100644
--- a/src/dopplergeist/discovery.py
+++ b/src/dopplergeist/discovery.py
@@ -7,12 +7,19 @@ from dataclasses import asdict, dataclass
import json
from pathlib import Path
from statistics import median
+import hashlib
+from importlib.metadata import version
+import subprocess
+import time
+from collections import Counter
import numpy as np
-from scipy import ndimage, optimize, signal
+from scipy import optimize, signal
from .audio import Spectrum
from .contracts import validate_event
+from .episodes import (Associations, DiscoveryError, Ridge, aligned, deduplicate,
+ identifier, intervals, motion, reconcile, stitch)
_HARMONIC_RATIOS = sorted({a / b for a in range(2, 9) for b in range(1, a) if a / b >= 1.2})
_NORMALIZATION_FUNCTIONS = (np.median, np.abs, np.maximum, np.clip, np.isfinite)
@@ -34,11 +41,28 @@ class DiscoverySettings:
max_gap_s: float = 2.0
max_fragment_gap_s: float = 20.0
max_peaks_per_frame: int = 60
+ provisional_min_points: int = 4
+ brief_min_observed_s: float = 3.0
+ brief_min_contrast: float = 4.5
+ max_candidates: int = 4096
+ max_measurements: int = 500000
+ max_associations: int = 200000
+ max_diagnostic_traces: int = 100
+ max_spectral_cells: int = 8000000
+ max_episode_components: int = 32
def __post_init__(self):
values = asdict(self)
if any(not np.isfinite(value) or value <= 0 for value in values.values()):
raise ValueError("Discovery settings must be finite and positive")
+ for name in ("max_peaks_per_frame", "provisional_min_points", "max_candidates", "max_measurements",
+ "max_associations", "max_diagnostic_traces", "max_spectral_cells", "max_episode_components"):
+ if type(values[name]) is not int:
+ raise ValueError(f"{name} must be an integer")
+ if self.provisional_min_points < 4 or self.chunk_s > 180 or self.window_s > 8 or self.max_frequency_hz > 14400:
+ raise ValueError("Require >=4 provisional points, chunk <=180 s, window <=8 s and upper frequency <=14400 Hz")
+ if self.min_frequency_hz < 2 / self.window_s:
+ raise ValueError("Lower frequency needs at least two cycles per spectral window")
if self.overlap_s >= self.chunk_s or self.overlap_s < self.min_duration_s + self.window_s:
raise ValueError("Overlap must cover an event acceptance window and be shorter than a chunk")
if not self.hop_s <= self.window_s < self.chunk_s or self.min_support > 1:
@@ -51,6 +75,9 @@ def _spectrum(data, sr, start, settings):
n, hop = round(sr * settings.window_s), round(sr * settings.hop_s)
if len(data) < n:
return None
+ cells = (n // 2 + 1) * (1 + (len(data) - n) // hop)
+ if cells > settings.max_spectral_cells:
+ raise DiscoveryError("spectral_budget_exceeded", f"Spectrum needs {cells} cells; limit {settings.max_spectral_cells}")
f, t, power = signal.spectrogram(data, fs=sr, window="hann", nperseg=n,
noverlap=n - hop, nfft=n, scaling="density")
keep = (f >= settings.min_frequency_hz) & (f <= min(settings.max_frequency_hz, sr * 0.48))
@@ -109,246 +136,267 @@ def _paths(spec, settings):
slopes = []
for path in active:
tail = path[-8:]
- if len(tail) >= 3:
+ if len(tail) >= 2:
slopes.append(float(median(
(right[1] - left[1]) / (right[0] - left[0])
for left, right in zip(tail, tail[1:])
)))
else:
slopes.append(0.0)
- allowed = (speed >= -np.maximum(8, last[:, 1, None] * 0.08)) & (speed <= np.maximum(1.0, last[:, 1, None] * 0.008))
+ allowed = np.abs(speed) <= np.maximum(8, last[:, 1, None] * 0.08)
predicted_delta = np.asarray(slopes)[:, None] * dt[:, None]
- costs = np.abs(delta - predicted_delta) / np.maximum(1.0, last[:, 1, None] * 0.01)
+ tolerance = 3 / settings.window_s + np.maximum(.5, np.abs(slopes)[:, None] * .5) * dt[:, None]
+ newborn = np.array([len(path) == 1 for path in active])
+ tolerance[newborn] = np.maximum(8, last[newborn, 1, None] * .08) * dt[newborn, None]
+ costs = np.abs(delta - predicted_delta) / tolerance
+ allowed &= costs <= 1
costs = np.where(allowed, costs, 1e6)
rows, cols = optimize.linear_sum_assignment(costs)
for row, col in zip(rows, cols):
if costs[row, col] < 1e6:
- active[row].append((float(time), float(frequencies[col]), float(weights[col])))
+ active[row].append((float(time), float(frequencies[col]), float(weights[col]), float(spec.db[peaks[col], column])))
used.add(col)
- active.extend([(float(time), float(frequency), float(weight))]
+ active.extend([(float(time), float(frequency), float(weight), float(spec.db[peaks[j], column]))]
for j, (frequency, weight) in enumerate(zip(frequencies, weights)) if j not in used)
return completed + active
def _usable(path, settings):
- points = np.asarray(path)
- t, f, weight = points.T
- duration = t[-1] - t[0]
- if duration < settings.min_duration_s:
- return False
- support = len(t) / (duration / settings.hop_s + 1)
- edge = max(3, len(t) // 6)
- drop = np.median(f[:edge]) - np.median(f[-edge:])
- if support < settings.min_support:
- return False
- if drop < max(settings.min_drop_hz, np.median(f) * settings.min_fractional_drop):
- return False
- # Reject stationary tracks and random wandering. Local frequency jitter is
- # permitted; no compulsory straight-flight geometry or speed bound is used.
- smooth = ndimage.median_filter(f, size=5, mode="nearest")
- monotone = np.mean(np.diff(smooth) <= 0.5)
- slopes = -np.diff(smooth) / np.diff(t)
- moving_fraction = np.mean(slopes > max(0.05, drop / duration * 0.2))
- # A path can otherwise jump between two stationary tones and manufacture
- # an apparent Doppler drop. Require distributed, resolved frequency motion.
- jump = np.max(np.abs(np.diff(smooth)))
- return bool(monotone >= 0.75 and moving_fraction >= 0.35
- and jump <= max(2 / settings.window_s, drop * 0.25)
- and np.median(np.abs(f - smooth)) <= max(1, np.median(f) * 0.01))
+ metrics, rejected = motion(np.asarray(path), settings)
+ return not rejected and metrics["observed_duration_s"] >= settings.min_duration_s and metrics["support_fraction"] >= settings.min_support
def _overlap(a, b):
- first, last = max(a[0, 0], b[0, 0]), min(a[-1, 0], b[-1, 0])
- if last <= first:
- return None
- t = np.arange(first, last + 0.001, 0.5)
- supported = np.ones(len(t), dtype=bool)
- for path in (a, b):
- following = np.clip(np.searchsorted(path[:, 0], t), 0, len(path) - 1)
- previous = np.maximum(0, following - 1)
- supported &= np.minimum(np.abs(t - path[following, 0]), np.abs(t - path[previous, 0])) <= 1.0
- t = t[supported]
- if len(t) < 3:
- return None
- return t, np.interp(t, a[:, 0], a[:, 1]), np.interp(t, b[:, 0], b[:, 1])
+ """Legacy consumer alignment. New episode logic uses effective settings."""
+ return aligned(a, b, DiscoverySettings())
-def _merge_duplicates(paths):
- merged = []
- for path in sorted(paths, key=lambda p: p[0][0]):
- current = np.asarray(path)
- for i, previous in enumerate(merged):
- shared = _overlap(current, previous)
- if shared is None:
- continue
- t, f, g = shared
- if len(t) >= 8 and np.mean(np.abs(f - g) <= max(1.0, np.median(f) * 0.006)) >= 0.85:
- points = np.concatenate((current, previous))
- # A time bin observed in both chunks retains its strongest peak.
- points = points[np.lexsort((-points[:, 2], points[:, 0]))]
- _, unique = np.unique(points[:, 0], return_index=True)
- merged[i] = points[np.sort(unique)]
- break
- else:
- merged.append(current)
- return merged
+def _stitch_fragments(paths, settings, diagnostics=None):
+ work = Associations(settings)
+ ridges = [Ridge(np.asarray(p), (identifier("raw:", np.asarray(p)),)) for p in paths]
+ result = stitch(ridges, settings, work)
+ if diagnostics is not None:
+ diagnostics.extend(work.decisions)
+ return [r.points for r in result]
-def _harmonic_groups(paths):
- groups = []
- for path in sorted(paths, key=lambda p: np.median(p[:, 1])):
- for group in groups:
- base = group[0]
- shared = _overlap(base, path)
- if shared is None:
- continue
- t, f, g = shared
- if len(t) * 0.5 < 0.6 * min(np.ptp(base[:, 0]), np.ptp(path[:, 0])):
- continue
- ratio = g / f
- # Rational ratios also cover a missing fundamental (e.g. 2f, 3f).
- harmonic = min(_HARMONIC_RATIOS, key=lambda value: abs(value - np.median(ratio)))
- if np.quantile(np.abs(ratio - harmonic) / harmonic, 0.9) < 0.008:
- group.append(path)
- break
- else:
- groups.append([path])
- return sorted(groups, key=lambda group: group[0][0, 0])
+def required_sample_rate(settings):
+ """Bound decode cost while keeping a 10% Nyquist transition guard."""
+ for rate in (4000, 8000, 16000, 32000):
+ if settings.max_frequency_hz <= .45 * rate:
+ return rate
+ raise DiscoveryError("unsupported_frequency_coverage", "Requested upper frequency exceeds bounded decoder coverage")
-def _stitch_fragments(paths, settings, diagnostics=None):
- """Join only reciprocal-unique, locally compatible tonal continuations.
+def _coverage(recording, settings):
+ sr = recording.metadata["sample_rate_hz"]
+ decode = recording.diagnostics.get("decode", {})
+ source_sr = decode.get("source_sample_rate_hz", sr)
+ upper = .45 * min(sr, source_sr)
+ if settings.max_frequency_hz > upper:
+ raise DiscoveryError("unsupported_frequency_coverage",
+ f"Requested {settings.max_frequency_hz:g} Hz exceeds usable decoded/source coverage {upper:g} Hz; decode at >= {required_sample_rate(settings)} Hz and check source rate")
+ # Align frames and chunk boundaries to exactly representable sample hops.
+ if any(abs(value * sr - round(value * sr)) > 1e-7 for value in (settings.window_s, settings.hop_s)):
+ raise DiscoveryError("unsupported_time_grid", "Window and hop must be integer sample counts")
+ step = settings.chunk_s - settings.overlap_s
+ if abs(step / settings.hop_s - round(step / settings.hop_s)) > 1e-7:
+ raise DiscoveryError("unsupported_time_grid", "Chunk step must be an integer number of spectral hops")
+ if round(settings.hop_s * sr) < 1:
+ raise DiscoveryError("unsupported_time_grid", "Hop must span at least one sample")
+ return dict(requested_hz=[settings.min_frequency_hz, settings.max_frequency_hz],
+ analyzed_hz=[float(np.ceil(settings.min_frequency_hz * settings.window_s) / settings.window_s),
+ float(np.floor(settings.max_frequency_hz * settings.window_s) / settings.window_s)],
+ decoded_sample_rate_hz=sr, source_sample_rate_hz=source_sr, usable_upper_hz=upper,
+ frequency_resolution_hz=1 / settings.window_s, time_hop_s=settings.hop_s,
+ window_s=settings.window_s, exhaustive_outside_analyzed_range=False,
+ ridge_peak_centers_hz=[float((np.ceil(settings.min_frequency_hz * settings.window_s)+1) / settings.window_s),
+ float((np.floor(settings.max_frequency_hz * settings.window_s)-1) / settings.window_s)],
+ edge_policy="outermost retained bins support interpolation but cannot be peak centers",
+ minimum_complete_window_s=settings.window_s,
+ method="single higher-rate chunked spectrum; no band boundary", nyquist_guard_fraction=.45)
- Missing samples remain missing. A stitch is an acoustic hypothesis, not a
- flight identity or an independent event. Competing continuations stay split.
- """
- paths = sorted(paths, key=lambda path: path[0, 0])
- incoming = [[] for _ in paths]
- outgoing = [[] for _ in paths]
- for i, left in enumerate(paths):
- tail = left[left[:, 0] >= left[-1, 0] - 6]
- rate_left = -np.polyfit(tail[:, 0] - tail[0, 0], tail[:, 1], 1)[0]
- for j in range(i + 1, len(paths)):
- right = paths[j]
- gap = right[0, 0] - left[-1, 0]
- if gap <= 0 or gap > settings.max_fragment_gap_s:
- continue
- if gap / (right[-1, 0] - left[0, 0]) > 0.35:
- continue
- head = right[right[:, 0] <= right[0, 0] + 6]
- rate_right = -np.polyfit(head[:, 0] - head[0, 0], head[:, 1], 1)[0]
- drop = left[-1, 1] - right[0, 1]
- rate = drop / gap
- tolerance = max(2 / settings.window_s, 0.015 * left[-1, 1])
- if min(rate_left, rate_right) <= 0.05 or drop < -tolerance or drop > left[-1, 1] * 0.3:
- continue
- if not 0.4 * min(rate_left, rate_right) - tolerance / gap <= rate <= 2.5 * max(rate_left, rate_right) + tolerance / gap:
- continue
- outgoing[i].append(j)
- incoming[j].append(i)
- following = {i: targets[0] for i, targets in enumerate(outgoing)
- if len(targets) == 1 and len(incoming[targets[0]]) == 1}
- if diagnostics is not None:
- for i, targets in enumerate(outgoing):
- for j in targets:
- accepted = following.get(i) == j
- diagnostics.append({"from_start_s": float(paths[i][0, 0]), "from_end_s": float(paths[i][-1, 0]),
- "to_start_s": float(paths[j][0, 0]), "to_end_s": float(paths[j][-1, 0]),
- "gap_s": float(paths[j][0, 0] - paths[i][-1, 0]), "accepted": accepted,
- "reason": "reciprocal_unique_continuation" if accepted else "ambiguous_continuation"})
- consumed, result = set(), []
- for first in range(len(paths)):
- if first in consumed:
- continue
- chain, current = [paths[first]], first
- while current in following:
- current = following[current]
- chain.append(paths[current])
- consumed.add(current)
- result.append(np.concatenate(chain))
- return result
-
-
-def discover_events(recording, *, output_dir=None, settings=None, plot_summary=True, plot_event_details=False):
- """Return shared DetectedEvent dictionaries from a disk-backed recording.
-
- Fixed defaults scan 40–1600 Hz in overlapping chunks; no event hints, flight
- data or truth paths are accepted. Each measured ridge gets a record; a
- shared harmonic_group_id makes those records one independent proposal.
- Optional diagnostics retain all measured harmonic ridges and chunk counts.
- Per-event spectrograms are expensive and are rendered only when requested.
+
+def _code_identity():
+ root = Path(__file__).resolve().parents[2]
+ try:
+ commit = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=root, text=True, stderr=subprocess.DEVNULL).strip()
+ except (OSError, subprocess.CalledProcessError):
+ commit = None
+ digest = hashlib.sha256()
+ for name in ("discovery.py", "episodes.py", "intake.py"):
+ digest.update((Path(__file__).parent / name).read_bytes())
+ return dict(git_commit=commit, implementation_sha256=digest.hexdigest(),
+ numpy=version("numpy"), scipy=version("scipy"))
+
+
+def discover_events(recording, *, output_dir=None, settings=None, plot_summary=True, plot_event_details=False,
+ detailed_candidates=False):
+ """Return compatible measured child events; discovery.json v2 owns episodes.
+
+ Grouping is an acoustic hypothesis with unresolved physical multiplicity.
+ Budgets/coverage failures raise DiscoveryError and write status=failed;
+ status=complete with zero episodes is a valid in-band negative result.
"""
settings = settings or DiscoverySettings()
- sr = recording.metadata["sample_rate_hz"]
- if settings.min_frequency_hz >= min(settings.max_frequency_hz, sr * 0.48):
- raise ValueError("Frequency range is above the decoded Nyquist limit")
- paths, chunks = [], []
+ began = time.monotonic()
output = Path(output_dir) if output_dir is not None else None
if output:
output.mkdir(parents=True, exist_ok=True)
if (output / "discovery.json").exists():
raise FileExistsError("Discovery output exists; use a new output directory")
- for start, data in recording.iter_chunks(settings.chunk_s, settings.overlap_s):
- spec = _spectrum(data, sr, start, settings)
- if spec is None:
- chunks.append({"start_s": start, "duration_s": len(data) / sr, "usable_paths": 0})
- continue
- found = [path for path in _paths(spec, settings) if _usable(path, settings)]
- paths.extend(found)
- chunks.append({"start_s": start, "duration_s": len(data) / sr, "usable_paths": len(found)})
- paths = _merge_duplicates(paths)
- fragment_links = []
- paths = _stitch_fragments(paths, settings, fragment_links)
- groups = _harmonic_groups(paths)
- events, event_groups = [], []
- for index, group in enumerate(groups):
- orders = {1.0}
- for harmonic in group[1:]:
- _, base_f, harmonic_f = _overlap(group[0], harmonic)
- ratio = np.median(harmonic_f / base_f)
- orders.add(min(_HARMONIC_RATIOS, key=lambda value: abs(value - ratio)))
- for harmonic_index, points in enumerate(group):
- t, f, weight = points.T
- margin = 2 / settings.window_s
- smooth = ndimage.median_filter(f, size=5, mode="nearest")
- frequency_scale = float(max(1 / settings.window_s, 1.4826 * np.median(np.abs(f - smooth))))
- event_id = f"event-{index + 1:04d}"
- if harmonic_index:
- event_id += f"-harmonic-{harmonic_index + 1}"
- event = {"event_id": event_id, "harmonic_group_id": f"harmonics-{index + 1:04d}",
- "start_s": max(0.0, float(t[0] - settings.window_s / 2)),
- "end_s": min(recording.metadata["duration_s"], float(t[-1] + settings.window_s / 2)),
- "band_hz": [max(0.01, float(f.min() - margin)), float(f.max() + margin)],
- "ridge": [{"time_s": float(a), "frequency_hz": float(b), "weight": float(c)} for a, b, c in points],
- "quality": {"median_contrast": float(np.median(weight)), "harmonic_count": float(len(orders)),
- "support_fraction": min(1.0, len(t) / (np.ptp(t) / settings.hop_s + 1)),
- "frequency_resolution_hz": 1 / settings.window_s,
- "time_uncertainty_s": settings.window_s / 2,
- "frequency_uncertainty_hz": frequency_scale,
- "frequency_sigma_hz": frequency_scale,
- "fragment_count": float(1 + np.sum(np.diff(t) > settings.max_gap_s)),
- "max_observed_gap_s": float(np.max(np.diff(t))),
- "frequency_drop_hz": float(np.median(f[:max(3, len(f) // 6)]) - np.median(f[-max(3, len(f) // 6):]))}}
- events.append(validate_event(event))
- event_groups.append(group)
+ report = dict(schema_version=2, status="running", source_sha256=recording.metadata["source_sha256"],
+ settings=asdict(settings), code=_code_identity(), events=[], episodes=[], chunks=[],
+ scope="acoustic episodes; physical motion, aircraft identity and single-source interpretation unconfirmed")
+ try:
+ events, groups = _discover(recording, settings, report, detailed_candidates)
+ report["status"] = "complete"
+ except DiscoveryError as exc:
+ report.update(status="failed", failure=dict(code=exc.code, message=str(exc)))
+ raise
+ except Exception as exc:
+ report.update(status="failed", failure=dict(code="discovery_execution_error", exception_type=type(exc).__name__, message=str(exc)))
+ raise
+ finally:
+ report["runtime_s"] = time.monotonic() - began
+ if output:
+ (output / "discovery.json").write_text(json.dumps(report, indent=2, allow_nan=False) + "\n")
if output:
- diagnostics = {"source_sha256": recording.metadata["source_sha256"], "settings": asdict(settings),
- "events": events, "chunks": chunks, "ridge_count": len(paths),
- "fragment_links": fragment_links,
- "harmonic_ridges": [[points.tolist() for points in group] for group in groups],
- "scope": "automatic acoustic moving-tone proposals; aircraft identity unconfirmed"}
- (output / "discovery.json").write_text(json.dumps(diagnostics, indent=2, allow_nan=False) + "\n")
if plot_summary:
_plot_groups(groups, output / "discovery.png", recording.metadata["duration_s"], settings.max_gap_s)
- for event, group in zip(events, event_groups):
- points = np.array([[p["time_s"], p["frequency_hz"], p["weight"]] for p in event["ridge"]])
- np.savetxt(output / f"{event['event_id']}.csv", points, delimiter=",",
- header="time_s,frequency_hz,weight", comments="")
+ for episode, group in zip(report["episodes"], groups):
if plot_event_details:
- _plot_event(recording, group, event, settings, output / f"{event['event_id']}.png")
+ _plot_event(recording, group, episode, settings, output / f"{episode['proposal_id']}.png")
return events
+def _discover(recording, settings, report, detailed):
+ report["coverage"] = _coverage(recording, settings)
+ sr = recording.metadata["sample_rate_hz"]
+ ridges, traces, counts = [], [], Counter()
+ report["counts"] = counts
+ points_retained = 0
+ rejection_ranges = {}
+ def reject(reasons, metrics=None, origins=()):
+ for reason in reasons:
+ counts[reason["reason"]] += 1
+ name, value = reason["reason"], float(reason["measured"])
+ entry = rejection_ranges.setdefault(name, dict(count=0, measured_min=value, measured_max=value,
+ threshold_min=float(reason["threshold"]), threshold_max=float(reason["threshold"]), comparison=reason["comparison"]))
+ entry["count"] += 1
+ entry["measured_min"] = min(entry["measured_min"], value)
+ entry["measured_max"] = max(entry["measured_max"], value)
+ entry["threshold_min"] = min(entry["threshold_min"], float(reason["threshold"]))
+ entry["threshold_max"] = max(entry["threshold_max"], float(reason["threshold"]))
+ if detailed and len(traces) < settings.max_diagnostic_traces:
+ traces.append(dict(origins=list(origins), measurements=metrics, rejections=reasons))
+ for chunk_index, (start, data) in enumerate(recording.iter_chunks(settings.chunk_s, settings.overlap_s)):
+ spec = _spectrum(data, sr, start, settings)
+ raw = _paths(spec, settings) if spec is not None else []
+ found = 0
+ for path in raw:
+ counts["raw_paths"] += 1
+ counts["raw_observations"] += len(path)
+ if len(path) < settings.provisional_min_points:
+ reject([dict(reason="provisional_points", measured=len(path), threshold=settings.provisional_min_points, comparison=">=")])
+ continue
+ points = np.asarray(path)
+ origin = f"chunk-{chunk_index:06d}:" + identifier("ridge-", points, recording.metadata["source_sha256"])
+ ridges.append(Ridge(points, (origin,)))
+ found += 1
+ points_retained += len(points)
+ if len(ridges) > settings.max_candidates or points_retained > settings.max_measurements:
+ raise DiscoveryError("candidate_budget_exceeded", f"Retained {len(ridges)} candidates/{points_retained} observations; limits {settings.max_candidates}/{settings.max_measurements}")
+ report["chunks"].append(dict(start_s=start, duration_s=len(data) / sr, raw_paths=len(raw), provisional_paths=found))
+ counts["provisional_paths"] = len(ridges)
+ counts["provisional_observations"] = points_retained
+ work = Associations(settings)
+ ridges = deduplicate(ridges, settings, work)
+ counts["deduplicated_tracks"] = len(ridges)
+ ridges = stitch(ridges, settings, work)
+ counts["stitched_tracks"] = len(ridges)
+ # Motion before grouping prevents stationary/noisy tracks from licensing
+ # group acceptance, but duration rejection only occurs after reconciliation.
+ moving = []
+ metrics_by_id = {}
+ for ridge in ridges:
+ metrics, reasons = motion(ridge.points, settings)
+ metrics_by_id[identifier("", ridge.points)] = metrics
+ if reasons:
+ reject(reasons, metrics, ridge.origins)
+ else:
+ moving.append(ridge)
+ reconciled = reconcile(moving, settings, work)
+ events, accepted_groups, episodes = [], [], []
+ for members, scales, orders in reconciled:
+ metrics = [metrics_by_id[identifier("", r.points)] for r in members]
+ cells = intervals(np.concatenate([r.points[:, 0] for r in members]), settings.hop_s)
+ observed = sum(b - a for a, b in cells)
+ span = cells[-1][1] - cells[0][0]
+ support = observed / span
+ long = observed >= settings.min_duration_s and support >= settings.min_support
+ # Brief observations need stronger contrast, resolution and continuity;
+ # harmonic richness alone cannot manufacture a moving event.
+ brief = (observed >= settings.brief_min_observed_s and support >= .85 and
+ any(m["median_contrast"] >= settings.brief_min_contrast and
+ m["frequency_excursion_hz"] >= 6 * m["frequency_uncertainty_hz"] and
+ m["moving_fraction"] >= .6 and m["prediction_error_q95"] <= .75 for m in metrics))
+ if not long and not brief:
+ reject([dict(reason="episode_support_or_brief_evidence", measured=observed,
+ threshold=settings.min_duration_s, comparison=">= long observed seconds; or strict brief gate")],
+ dict(observed_duration_s=observed, support_fraction=support, brief_min_observed_s=settings.brief_min_observed_s,
+ brief_min_support=.85, brief_min_contrast=settings.brief_min_contrast, child_metrics=metrics),
+ tuple(x for r in members for x in r.origins))
+ continue
+ matching_eligible = sum(len(r.points) for r in members) >= 10
+ child_ids = [identifier("ridge-", r.points, recording.metadata["source_sha256"]) for r in members]
+ proposal_id = "episode-" + hashlib.sha256((recording.metadata["source_sha256"] + "|".join(sorted(child_ids))).encode()).hexdigest()[:20]
+ children = []
+ for ridge, scale, child_id, m in zip(members, scales, child_ids, metrics):
+ points = ridge.points
+ t, f, w = points[:, :3].T
+ margin = 2 / settings.window_s
+ quality = {k: float(v) for k, v in m.items() if isinstance(v, (int, float))}
+ quality.update(harmonic_count=float(len(set(orders))) if orders else 0.0,
+ frequency_resolution_hz=1 / settings.window_s, time_uncertainty_s=settings.window_s / 2,
+ frequency_sigma_hz=m["frequency_uncertainty_hz"],
+ fragment_count=float(1 + np.sum(np.diff(t) > settings.max_gap_s)),
+ max_observed_gap_s=float(np.max(np.diff(t))),
+ frequency_drop_hz=float(np.median(f[:max(3, len(f)//6)]) - np.median(f[-max(3, len(f)//6):])),
+ episode_frequency_scale=float(scale), episode_model_version=2.0, matching_eligible=float(matching_eligible))
+ event = validate_event(dict(event_id=child_id, harmonic_group_id=proposal_id,
+ start_s=max(0., float(t[0] - settings.window_s / 2)),
+ end_s=min(recording.metadata["duration_s"], float(t[-1] + settings.window_s / 2)),
+ band_hz=[max(.01, float(f.min() - margin)), float(f.max() + margin)],
+ ridge=[dict(time_s=float(a), frequency_hz=float(b), weight=float(c)) for a,b,c in points[:, :3]], quality=quality))
+ events.append(event)
+ children.append(dict(ridge_id=child_id, raw_track_ids=list(ridge.origins), frequency_scale=float(scale),
+ amplitude_db=points[:, 3].tolist() if points.shape[1] > 3 else None,
+ observed_intervals_s=intervals(t, settings.hop_s), measurements=m))
+ episode = dict(proposal_id=proposal_id, event_id=proposal_id, child_ridge_ids=child_ids, children=children,
+ start_s=min(e["start_s"] for e in events[-len(members):]), end_s=max(e["end_s"] for e in events[-len(members):]),
+ observed_intervals_s=cells, gaps_s=[[cells[i][1], cells[i+1][0]] for i in range(len(cells)-1)],
+ observed_duration_s=observed, support_fraction=support,
+ band_hz=[float(min(r.points[:,1].min() for r in members)), float(max(r.points[:,1].max() for r in members))],
+ matching_eligible=matching_eligible,
+ matching_limitation=None if matching_eligible else "Fewer than ten observed samples; retained for acoustic review only",
+ acceptance_path="sustained" if long else "brief_strong_evidence",
+ confidence="uncalibrated_supported" if long else "uncalibrated_brief_limited",
+ physical_source_multiplicity="unresolved", physical_motion_confirmed=False,
+ model="constant frequency scales with pairwise supported common motion", integer_orders=orders,
+ limitations=["Common frequency evolution does not establish one physical source or aircraft identity"])
+ episodes.append(episode)
+ accepted_groups.append([r.points[:, :3] for r in members])
+ counts["canonical_proposals"] = len(episodes)
+ counts["measured_child_tracks"] = len(events)
+ report.update(events=events, episodes=episodes, counts=dict(counts), ridge_count=len(events),
+ rejections=dict(measured_ranges=rejection_ranges, counts={k:v for k,v in counts.items() if k not in ("raw_paths", "raw_observations", "provisional_paths", "provisional_observations", "deduplicated_tracks", "stitched_tracks", "canonical_proposals", "measured_child_tracks")},
+ traces=traces, traces_enabled=detailed, trace_limit=settings.max_diagnostic_traces),
+ association_pairs=work.count, reconciliation_counts=dict(work.decision_counts), reconciliation_decisions=work.decisions,
+ decisions_truncated=len(work.decisions) == work.trace_limit)
+ return events, accepted_groups
+
+
def _plot_groups(groups, path, duration, max_gap_s=2.0):
import matplotlib
matplotlib.use("Agg")
@@ -359,9 +407,9 @@ def _plot_groups(groups, path, duration, max_gap_s=2.0):
segments = np.split(points, np.flatnonzero(np.diff(points[:, 0]) > max_gap_s) + 1)
for segment_index, segment in enumerate(segments):
ax.plot(segment[:, 0], segment[:, 1], color=f"C{index % 10}", lw=0.8, alpha=0.8,
- label=f"Event {index + 1}" if harmonic == 0 and segment_index == 0 else None)
+ label=f"Episode {index + 1}" if harmonic == 0 and segment_index == 0 else None)
ax.set(xlim=(0, duration), xlabel="Recording-relative time (s)", ylabel="Measured frequency (Hz)",
- title="Automatic whole-recording moving-tone proposals (harmonics grouped)")
+ title="Canonical acoustic episodes (physical source identity unresolved)")
if groups:
ax.legend(loc="upper right", fontsize="small", ncols=2)
fig.savefig(path, dpi=130)
diff --git a/src/dopplergeist/episodes.py b/src/dopplergeist/episodes.py
new file mode 100644
index 0000000..7a80536
--- /dev/null
+++ b/src/dopplergeist/episodes.py
@@ -0,0 +1,372 @@
+"""Bounded reconciliation of measured tonal tracks; no physical-source inference.
+
+All time differences below are seconds. Pairwise constant-scale fits have one
+parameter; group-wide reconciliation prevents weak transitive bridges.
+"""
+from collections import Counter
+from dataclasses import dataclass
+import hashlib
+
+import numpy as np
+from scipy import ndimage
+
+
+class DiscoveryError(ValueError):
+ def __init__(self, code, message):
+ self.code = code
+ super().__init__(message)
+
+
+@dataclass
+class Ridge:
+ points: np.ndarray
+ origins: tuple
+
+
+def identifier(prefix, points, source=""):
+ # IDs depend on observations, not input enumeration or proposal count.
+ values = np.ascontiguousarray(points[:, :3], dtype="<f8")
+ return prefix + hashlib.sha256(source.encode() + values.tobytes()).hexdigest()[:20]
+
+
+def key(ridge):
+ p = ridge.points
+ return (float(p[0, 0]), float(np.median(p[:, 1])), identifier("", p))
+
+
+def intervals(times, hop):
+ """Union of observation cells, not of spectrogram-window footprints."""
+ result = []
+ for t in sorted(set(float(t) for t in times)):
+ left, right = max(0.0, t - hop / 2), t + hop / 2
+ if result and left <= result[-1][1] + 1e-8:
+ result[-1][1] = max(result[-1][1], right)
+ else:
+ result.append([left, right])
+ return result
+
+
+def uncertainty(points, settings):
+ f = points[:, 1]
+ smooth = ndimage.median_filter(f, size=min(5, len(f) // 2 * 2 + 1), mode="nearest")
+ return float(max(1 / settings.window_s, 1.4826 * np.median(np.abs(f - smooth))))
+
+
+def aligned(a, b, settings):
+ # Use measured times and interpolate only within a supported observation gap.
+ first, last = max(a[0, 0], b[0, 0]), min(a[-1, 0], b[-1, 0])
+ times = a[(a[:, 0] >= first) & (a[:, 0] <= last), 0]
+ if len(times) < 3:
+ return None
+ following = np.clip(np.searchsorted(b[:, 0], times), 0, len(b) - 1)
+ previous = np.maximum(0, following - 1)
+ exact = np.abs(b[following, 0] - times) < 1e-7
+ supported = exact | ((b[following, 0] - b[previous, 0] <= settings.max_gap_s)
+ & (times >= b[previous, 0]))
+ times = times[supported]
+ if len(times) < 3:
+ return None
+ return times, np.interp(times, a[:, 0], a[:, 1]), np.interp(times, b[:, 0], b[:, 1])
+
+
+def motion(points, settings):
+ """Evidence and explicit rejection thresholds, independent of duration gate."""
+ t, f, w = points[:, :3].T
+ cells = intervals(t, settings.hop_s)
+ observed = sum(right - left for left, right in cells)
+ span = t[-1] - t[0] + settings.hop_s
+ sigma = uncertainty(points, settings)
+ smooth = ndimage.median_filter(f, size=5, mode="nearest")
+ dt = np.diff(t)
+ # Missing intervals do not contribute to moving fraction or smoothness.
+ valid = dt <= settings.max_gap_s
+ slopes = np.diff(smooth) / dt
+ excursion = float(np.quantile(smooth, .95) - np.quantile(smooth, .05))
+ required = max(settings.min_drop_hz, float(np.median(f)) * settings.min_fractional_drop, 4 * sigma)
+ moving = valid & (np.abs(slopes) > max(.05, excursion / max(span, 1) * .2))
+ moving_fraction = float(np.sum(dt[moving]) / max(np.sum(dt[valid]), settings.hop_s))
+ # Local prediction on actual timestamps, with uncertainty in Hz and slope.
+ errors = []
+ for i in range(2, len(t)):
+ if dt[i - 1] > settings.max_gap_s:
+ continue
+ first = max(0, i - 5)
+ local_dt = np.diff(t[first:i])
+ local_good = local_dt <= settings.max_gap_s
+ rates = np.diff(f[first:i]) / local_dt
+ if not np.any(local_good):
+ continue
+ rate = float(np.median(rates[local_good]))
+ tolerance = 3 * sigma + max(.5, abs(rate) * .5) * dt[i - 1]
+ errors.append(abs(f[i] - f[i - 1] - rate * dt[i - 1]) / tolerance)
+ discontinuity = float(np.quantile(errors, .95)) if errors else 0.0
+ signs = np.sign(slopes[moving])
+ # A turn requires a sustained resolved leg; repeated reversals are modulation
+ # or unresolved wandering, not a compulsory descending-flight template.
+ runs = []
+ for sign, duration, observed in zip(np.sign(slopes), dt, valid):
+ if not observed or abs(sign) == 0:
+ continue
+ if runs and runs[-1][0] == sign:
+ runs[-1][1] += min(duration, settings.hop_s)
+ else:
+ runs.append([sign, min(duration, settings.hop_s)])
+ sustained = [sign for sign, duration in runs if duration >= max(1.5, span * .08)]
+ turns = sum(a != b for a, b in zip(sustained, sustained[1:]))
+ total_variation = float(np.sum(np.abs(np.diff(smooth))[valid]))
+ variation_ratio = total_variation / max(excursion, sigma)
+ direction = "stationary"
+ if len(signs):
+ direction = "turning" if turns else ("rising" if np.median(signs) > 0 else "falling")
+ metrics = dict(observed_duration_s=float(observed), span_s=float(span), support_fraction=float(observed / span),
+ frequency_excursion_hz=excursion, required_excursion_hz=float(required),
+ frequency_uncertainty_hz=sigma, moving_fraction=moving_fraction,
+ prediction_error_q95=discontinuity, sustained_turns=int(turns),
+ variation_ratio=float(variation_ratio), median_contrast=float(np.median(w)), direction=direction)
+ checks = [(excursion >= required, "unresolved_frequency_motion", excursion, required, ">="),
+ (moving_fraction >= .35, "insufficient_distributed_motion", moving_fraction, .35, ">="),
+ (discontinuity <= 1, "discontinuous_motion", discontinuity, 1, "<="),
+ (turns <= 1, "repeated_modulation", turns, 1, "<="),
+ (variation_ratio <= 2.8, "wandering_or_modulation", variation_ratio, 2.8, "<=")]
+ reasons = [dict(reason=name, measured=float(value), threshold=float(limit), comparison=op)
+ for passed, name, value, limit, op in checks if not passed]
+ return metrics, reasons
+
+
+class Associations:
+ def __init__(self, settings):
+ self.limit = settings.max_associations
+ self.count = 0
+ self.decisions = []
+ self.decision_counts = Counter()
+ self.trace_limit = settings.max_diagnostic_traces
+
+ def charge(self):
+ self.count += 1
+ if self.count > self.limit:
+ raise DiscoveryError("association_budget_exceeded", f"Association work exceeded {self.limit} pairs")
+
+ def record(self, kind, left, right, **evidence):
+ self.decision_counts[kind] += 1
+ if len(self.decisions) < self.trace_limit:
+ self.decisions.append(dict(kind=kind, left=list(left.origins), right=list(right.origins), **evidence))
+
+
+def combine(a, b):
+ points = np.concatenate((a.points, b.points))
+ # Deterministic tie break, strongest contrast per timestamp; no invented data.
+ points = points[np.lexsort((points[:, 1], -points[:, 2], points[:, 0]))]
+ _, keep = np.unique(points[:, 0], return_index=True)
+ return Ridge(points[np.sort(keep)], tuple(sorted(set(a.origins + b.origins))))
+
+
+def deduplicate(ridges, settings, work):
+ result = []
+ for ridge in sorted(ridges, key=key):
+ for i, previous in enumerate(result):
+ if previous.points[-1, 0] < ridge.points[0, 0]:
+ continue
+ # Tracks measured in the same chunk can be near-unison components.
+ if {x.split(":")[0] for x in ridge.origins} & {x.split(":")[0] for x in previous.origins}:
+ continue
+ if abs(np.median(ridge.points[:, 1]) - np.median(previous.points[:, 1])) > .2 * np.median(ridge.points[:, 1]):
+ continue
+ work.charge()
+ shared = aligned(ridge.points, previous.points, settings)
+ if shared is None or len(shared[0]) < 8:
+ continue
+ residual = float(np.quantile(np.abs(shared[1] - shared[2]), .95))
+ tolerance = .6 / settings.window_s
+ # Whole overlap agreement prevents reconciling paths that branch.
+ if residual <= tolerance:
+ work.record("duplicate_chunk_measurement", ridge, previous, residual_q95_hz=residual, threshold_hz=tolerance)
+ result[i] = combine(previous, ridge)
+ break
+ else:
+ result.append(ridge)
+ return sorted(result, key=key)
+
+
+def stitch(ridges, settings, work):
+ ridges = sorted(ridges, key=key)
+ incoming, outgoing = [[] for _ in ridges], [[] for _ in ridges]
+ for i, left in enumerate(ridges):
+ a = left.points
+ for j in range(i + 1, len(ridges)):
+ right, b = ridges[j], ridges[j].points
+ gap = b[0, 0] - a[-1, 0]
+ if b[0, 0] > a[-1, 0] + settings.max_fragment_gap_s:
+ break
+ if gap <= settings.hop_s * 1.1:
+ continue
+ if abs(b[0, 1] - a[-1, 1]) > .3 * a[-1, 1]:
+ continue
+ work.charge()
+ if len(a) < 4 or len(b) < 4:
+ continue
+ tail, head = a[a[:, 0] >= a[-1, 0] - 4], b[b[:, 0] <= b[0, 0] + 4]
+ if len(tail) < 3 or len(head) < 3:
+ continue
+ sa = float(np.polyfit(tail[:, 0] - tail[-1, 0], tail[:, 1], 1)[0])
+ sb = float(np.polyfit(head[:, 0] - head[0, 0], head[:, 1], 1)[0])
+ sigma = uncertainty(a, settings) + uncertainty(b, settings)
+ tolerance = 2 * sigma + .25 * min(abs(sa), abs(sb)) * gap
+ error = max(abs(b[0, 1] - a[-1, 1] - sa * gap), abs(b[0, 1] - a[-1, 1] - sb * gap))
+ # Both observed legs must move in the same direction. A turn in an
+ # unobserved gap is deliberately unresolved.
+ support = sum(y - x for x, y in intervals(np.r_[a[:, 0], b[:, 0]], settings.hop_s))
+ if (sa * sb <= 0 or min(abs(sa), abs(sb)) < .1 or
+ max(abs(sa), abs(sb)) > 3 * min(abs(sa), abs(sb)) or
+ gap > .35 * support or error > tolerance):
+ continue
+ outgoing[i].append(j)
+ incoming[j].append(i)
+ work.record("continuation_candidate", left, right, gap_s=float(gap), prediction_error_hz=float(error), threshold_hz=float(tolerance))
+ following = {i: js[0] for i, js in enumerate(outgoing) if len(js) == 1 and len(incoming[js[0]]) == 1}
+ for i, js in enumerate(outgoing):
+ for j in js:
+ work.record("stitch" if following.get(i) == j else "ambiguous_continuation", ridges[i], ridges[j])
+ consumed, result = set(), []
+ for i, ridge in enumerate(ridges):
+ if i in consumed:
+ continue
+ current, joined = i, ridge
+ while current in following:
+ current = following[current]
+ joined = combine(joined, ridges[current])
+ consumed.add(current)
+ result.append(joined)
+ return result
+
+
+def family(scales, tolerance=.006):
+ """Minimum-complexity integer family, bounded to orders 1..12.
+
+ Absence of this secondary model does not prohibit coherent nonharmonic
+ episodes, which require stronger envelope evidence instead.
+ """
+ scales = np.asarray(scales) / min(scales)
+ fits = []
+ for base in range(1, 13):
+ orders = np.rint(scales * base).astype(int)
+ if max(orders) <= 12 and np.max(np.abs(scales - orders / base) / scales) <= tolerance:
+ fits.append(orders.tolist())
+ return min(fits, key=lambda orders: (sum(orders), orders)) if fits else None
+
+
+def related(a, b, settings):
+ shared = aligned(a, b, settings)
+ if shared is None or len(shared[0]) < 8:
+ return None
+ t, f, g = shared
+ support = len(t) * settings.hop_s
+ if support < .6 * min(len(a), len(b)) * settings.hop_s:
+ return None
+ scale = float(np.exp(np.median(np.log(g / f))))
+ sigma = uncertainty(b, settings) + scale * uncertainty(a, settings)
+ error = float(np.quantile(np.abs(g - scale * f), .9))
+ # Uncertainty cannot license an arbitrary ratio fit to unresolved motion.
+ excursion = min(float(np.ptp(f)) * scale, float(np.ptp(g)))
+ if excursion < max(6 * sigma, .03 * np.median(g)) or error > min(2 * sigma, .004 * np.median(g)):
+ return None
+ corr = float(np.corrcoef(f, g)[0, 1]) if np.std(f) > 0 and np.std(g) > 0 else 0.0
+ if not np.isfinite(corr) or corr < .96:
+ return None
+ harmonic = family([1, scale])
+ envelope = None
+ if a.shape[1] > 3 and b.shape[1] > 3:
+ x, y = np.interp(t, a[:, 0], a[:, 3]), np.interp(t, b[:, 0], b[:, 3])
+ if min(np.std(x), np.std(y)) >= 1:
+ envelope = float(np.corrcoef(x, y)[0, 1])
+ if harmonic is None and (envelope is None or not np.isfinite(envelope) or envelope < .65):
+ return None
+ # Contradictory measured envelopes block even a convenient integer ratio.
+ if envelope is not None and np.isfinite(envelope) and envelope < -.25:
+ return None
+ return dict(scale=scale, residual_q90_hz=error, threshold_hz=float(min(2 * sigma, .004 * np.median(g))),
+ frequency_correlation=corr, envelope_correlation=envelope,
+ shared_observations=int(len(t)), integer_orders=harmonic)
+
+
+def reconcile(ridges, settings, work):
+ """Reconcile strong connections under one group-wide scale model.
+
+ Every member of a group of >=3 needs two resolved-motion witnesses. Every
+ overlapping pair is checked against the joint fit, even when its own span
+ is too short to establish motion. This permits partial harmonic support
+ without permitting a chain of single weak bridges.
+ """
+ ridges = sorted(ridges, key=key)
+ edges = {}
+ for i, a in enumerate(ridges):
+ for j in range(i + 1, len(ridges)):
+ b = ridges[j]
+ if b.points[0, 0] > a.points[-1, 0]:
+ break
+ work.charge()
+ evidence = related(a.points, b.points, settings)
+ if evidence:
+ edges[i, j] = evidence
+ def fit(indices):
+ work.charge()
+ if len(indices) > settings.max_episode_components:
+ return None
+ positions = {x:i for i,x in enumerate(indices)}
+ internal = []
+ for ix,x in enumerate(indices):
+ for y in indices[ix+1:]:
+ work.charge()
+ if (x,y) in edges:
+ internal.append((x,y,edges[x,y]))
+ if len(indices)>2 and any(sum(x==i or y==i for x,y,_ in internal)<2 for i in indices):
+ return None
+ matrix, values = [], []
+ for x,y,e in internal:
+ row = np.zeros(len(indices))
+ row[positions[y]], row[positions[x]] = 1., -1.
+ matrix.append(row[1:]); values.append(np.log(e["scale"]))
+ scales = np.exp(np.r_[0., np.linalg.lstsq(np.asarray(matrix),values,rcond=None)[0]])
+ for ix,x in enumerate(indices):
+ for iy in range(ix+1,len(indices)):
+ y = indices[iy]
+ work.charge()
+ shared = aligned(ridges[x].points,ridges[y].points,settings)
+ if shared is None:
+ continue
+ ratio = scales[iy]/scales[ix]
+ error = float(np.quantile(np.abs(shared[2]-ratio*shared[1]),.9))
+ sigma = uncertainty(ridges[y].points,settings)+ratio*uncertainty(ridges[x].points,settings)
+ if error > 2*sigma:
+ return None
+ return scales.tolist()
+ groups = [{i} for i in range(len(ridges))]
+ owners = {i:g for g in groups for i in g}
+ fitted = {frozenset(g):[1.] for g in groups}
+ ordered = sorted(edges.items(),key=lambda item:(item[1]["residual_q90_hz"]/item[1]["threshold_hz"],item[0]))
+ changed = True
+ while changed:
+ changed = False
+ for (i,j),evidence in ordered:
+ left, right = owners[i], owners[j]
+ if left is right:
+ continue
+ scales = fit(sorted(left|right))
+ if scales is None:
+ continue
+ work.record("joint_episode",ridges[i],ridges[j],**evidence)
+ left.update(right)
+ for member in right:
+ owners[member] = left
+ groups.remove(right)
+ fitted[frozenset(left)] = scales
+ changed = True
+ for (i,j),evidence in ordered:
+ if owners[i] is not owners[j]:
+ work.record("unresolved_episode_relation",ridges[i],ridges[j],
+ reason="insufficient_joint_witnesses_or_inconsistent_group_fit",**evidence)
+ result = []
+ for group in groups:
+ indices = sorted(group)
+ scales = fitted[frozenset(group)]
+ result.append(([ridges[x] for x in indices],scales,family(scales)))
+ return result
diff --git a/src/dopplergeist/intake.py b/src/dopplergeist/intake.py
index 83937f6..2515b24 100644
--- a/src/dopplergeist/intake.py
+++ b/src/dopplergeist/intake.py
@@ -121,7 +121,7 @@ def intake_recording(source, output_dir, *, time_window=None, sample_rate_hz=400
channels = int(audio["channels"])
downmix = "pan=mono|c0=" + "+".join(f"{1 / channels:.17g}*c{i}" for i in range(channels))
command = ["ffmpeg", "-nostdin", "-v", "error", "-xerror", "-i", str(source),
- "-map", "0:a:0", "-vn", "-sn", "-dn", "-af", downmix, "-ac", "1", "-ar", str(sample_rate_hz),
+ "-map", "0:a:0", "-vn", "-sn", "-dn", "-af", downmix + ",aresample=resampler=swr:filter_size=64:cutoff=0.95", "-ac", "1", "-ar", str(sample_rate_hz),
"-acodec", "pcm_f32le", "-f", "f32le", "pipe:1"]
temporary = None
try:
@@ -173,7 +173,9 @@ def intake_recording(source, output_dir, *, time_window=None, sample_rate_hz=400
"decode": {"decoder": "ffmpeg", "sample_format": "f32le", "channel_policy": "arithmetic channel mean",
"source_sample_rate_hz": int(audio["sample_rate"]), "source_channels": int(audio["channels"]),
"source_codec": audio.get("codec_name", "unknown"), "stream_index": int(audio["index"]),
- "audio_time_zero": "first decoded sample after codec skip/discard", "command": command},
+ "audio_time_zero": "first decoded sample after codec skip/discard", "command": command,
+ "resampling": "ffmpeg swresample, 64-tap low-pass, cutoff 0.95; timestamps start at decoded sample zero",
+ "usable_frequency_hz": [0.0, .45 * min(sample_rate_hz, int(audio["sample_rate"]))]},
}
# Exclusive creation also prevents accidental replacement on concurrent intake.
os.link(temporary, samples_path)
diff --git a/src/dopplergeist/matching.py b/src/dopplergeist/matching.py
index d2d35a0..df8eea5 100644
--- a/src/dopplergeist/matching.py
+++ b/src/dopplergeist/matching.py
@@ -454,8 +454,8 @@ def association_score(result, events):
def prepare_events(detected_events, c=343.0, max_distance_m=20000.0):
"""Adapt contract ridge points to existing search inputs without truth hints.
- Keep every ridge in a harmonic group as evidence for one pass. Rational
- harmonic ratios are normalized to its lowest observed band; no fundamental
+ Keep every ridge in a canonical group as evidence for one proposal. Measured
+ episode scales (legacy rational ratios) normalize to its lowest observed band; no fundamental
needs to be present. Groups with inconsistent ratios must be fixed by discovery.
Separate paths that reuse measured peaks remain separate hypotheses, with
an explicit conflict preventing their joint independent-support score.
@@ -471,6 +471,8 @@ def prepare_events(detected_events, c=343.0, max_distance_m=20000.0):
groups.setdefault(key, []).append(event)
settings, measurements = [], []
for members in groups.values():
+ if any(e.get("quality", {}).get("matching_eligible") == 0 for e in members):
+ continue
reference = min(members, key=lambda e: np.median([p["frequency_hz"] for p in e["ridge"]]))
reference_time = np.array([p["time_s"] for p in reference["ridge"]])
reference_frequency = np.array([p["frequency_hz"] for p in reference["ridge"]])
@@ -480,7 +482,22 @@ def prepare_events(detected_events, c=343.0, max_distance_m=20000.0):
f = np.array([p["frequency_hz"] for p in member["ridge"]], dtype=float)
w = np.array([p.get("weight", 1.0) for p in member["ridge"]], dtype=float)
harmonic = 1.0
- if member is not reference:
+ modern_scale = member.get("quality", {}).get("episode_frequency_scale")
+ reference_scale = reference.get("quality", {}).get("episode_frequency_scale")
+ if modern_scale is not None and reference_scale is not None:
+ if not np.isfinite(modern_scale) or not np.isfinite(reference_scale) or min(modern_scale, reference_scale) <= 0:
+ raise ValueError("Episode frequency scales must be finite and positive")
+ harmonic = modern_scale / reference_scale
+ if member is not reference:
+ base = np.column_stack((reference_time, reference_frequency, np.ones(len(reference_time))))
+ other = np.column_stack((t, f, w))
+ # Recheck supported scale without requiring the legacy ratio
+ # dictionary or unavailable spectral envelope in this adapter.
+ shared = _overlap(base, other)
+ sigma = _frequency_scale(member) + harmonic * _frequency_scale(reference)
+ if shared is not None and np.quantile(np.abs(shared[2] - harmonic * shared[1]), .9) > 2 * sigma:
+ raise ValueError("Episode members disagree with their measured frequency scales")
+ elif member is not reference:
base = np.column_stack((reference_time, reference_frequency))
shared = _overlap(base, np.column_stack((t, f)))
if shared is None or len(shared[0]) * 0.5 < 0.6 * min(np.ptp(reference_time), np.ptp(t)):
diff --git a/tests/fixtures/real_episode_children.json b/tests/fixtures/real_episode_children.json
new file mode 100644
index 0000000..a984591
--- /dev/null
+++ b/tests/fixtures/real_episode_children.json
@@ -0,0 +1,1593 @@
+{
+ "source_sha256": "36164d8f88d3a67da0efb2a9a8934a27f7991e3d1eddebe1757fc8eee30b823f",
+ "source_url": "https://zenodo.org/records/10215080",
+ "license": "CC BY-NC 4.0; derived frequency measurements only",
+ "case_id": "case-0001",
+ "events": [
+ {
+ "event_id": "ridge-e89a6abd10d83ec9cd4c",
+ "harmonic_group_id": "episode-a6d12cb1836824b9d245",
+ "start_s": 6.5,
+ "end_s": 53.5,
+ "band_hz": [
+ 229.80869354307652,
+ 268.39455457776785
+ ],
+ "ridge": [
+ {
+ "time_s": 7.5,
+ "frequency_hz": 265.893697462976,
+ "weight": 2.8702125549316406
+ },
+ {
+ "time_s": 8.0,
+ "frequency_hz": 265.88738889992237,
+ "weight": 3.952934741973877
+ },
+ {
+ "time_s": 8.5,
+ "frequency_hz": 266.10178504884243,
+ "weight": 4.215429782867432
+ },
+ {
+ "time_s": 9.0,
+ "frequency_hz": 266.35302144289017,
+ "weight": 3.503683567047119
+ },
+ {
+ "time_s": 9.5,
+ "frequency_hz": 266.75,
+ "weight": 3.0041587352752686
+ },
+ {
+ "time_s": 10.0,
+ "frequency_hz": 266.3987051695585,
+ "weight": 3.315380811691284
+ },
+ {
+ "time_s": 10.5,
+ "frequency_hz": 266.40230705589056,
+ "weight": 3.876256227493286
+ },
+ {
+ "time_s": 11.0,
+ "frequency_hz": 266.2951227873564,
+ "weight": 4.1858344078063965
+ },
+ {
+ "time_s": 11.5,
+ "frequency_hz": 265.99336407193914,
+ "weight": 3.4852869510650635
+ },
+ {
+ "time_s": 13.0,
+ "frequency_hz": 265.54330468550324,
+ "weight": 3.0196096897125244
+ },
+ {
+ "time_s": 13.5,
+ "frequency_hz": 265.5635628402233,
+ "weight": 3.7102291584014893
+ },
+ {
+ "time_s": 14.0,
+ "frequency_hz": 265.52349775470793,
+ "weight": 3.7067620754241943
+ },
+ {
+ "time_s": 14.5,
+ "frequency_hz": 264.64372228085995,
+ "weight": 2.7892963886260986
+ },
+ {
+ "time_s": 15.0,
+ "frequency_hz": 264.456978879869,
+ "weight": 3.885702610015869
+ },
+ {
+ "time_s": 15.5,
+ "frequency_hz": 264.7133097797632,
+ "weight": 4.0595269203186035
+ },
+ {
+ "time_s": 16.0,
+ "frequency_hz": 264.75,
+ "weight": 3.9535281658172607
+ },
+ {
+ "time_s": 16.5,
+ "frequency_hz": 264.88494454324245,
+ "weight": 4.2389140129089355
+ },
+ {
+ "time_s": 17.0,
+ "frequency_hz": 265.07401683181524,
+ "weight": 4.840713024139404
+ },
+ {
+ "time_s": 17.5,
+ "frequency_hz": 265.2078526467085,
+ "weight": 4.636460781097412
+ },
+ {
+ "time_s": 18.0,
+ "frequency_hz": 265.0923702418804,
+ "weight": 4.013065814971924
+ },
+ {
+ "time_s": 18.5,
+ "frequency_hz": 264.2320262491703,
+ "weight": 3.8274621963500977
+ },
+ {
+ "time_s": 19.0,
+ "frequency_hz": 264.0536385923624,
+ "weight": 5.342143535614014
+ },
+ {
+ "time_s": 19.5,
+ "frequency_hz": 264.07788674533367,
+ "weight": 5.286107540130615
+ },
+ {
+ "time_s": 20.0,
+ "frequency_hz": 264.25,
+ "weight": 4.64359188079834
+ },
+ {
+ "time_s": 20.5,
+ "frequency_hz": 264.57993776351213,
+ "weight": 4.408074378967285
+ },
+ {
+ "time_s": 21.0,
+ "frequency_hz": 265.0112698273733,
+ "weight": 4.60521936416626
+ },
+ {
+ "time_s": 21.5,
+ "frequency_hz": 265.25,
+ "weight": 4.138296127319336
+ },
+ {
+ "time_s": 23.5,
+ "frequency_hz": 267.39455457776785,
+ "weight": 4.942116737365723
+ },
+ {
+ "time_s": 24.0,
+ "frequency_hz": 266.0794253125787,
+ "weight": 3.9987869262695312
+ },
+ {
+ "time_s": 24.5,
+ "frequency_hz": 265.75,
+ "weight": 4.601227283477783
+ },
+ {
+ "time_s": 25.0,
+ "frequency_hz": 265.6446843147278,
+ "weight": 4.407943248748779
+ },
+ {
+ "time_s": 25.5,
+ "frequency_hz": 265.2886489778757,
+ "weight": 3.562363386154175
+ },
+ {
+ "time_s": 26.0,
+ "frequency_hz": 264.88216771930456,
+ "weight": 3.722468852996826
+ },
+ {
+ "time_s": 26.5,
+ "frequency_hz": 264.4911299161613,
+ "weight": 4.115077972412109
+ },
+ {
+ "time_s": 27.0,
+ "frequency_hz": 264.25,
+ "weight": 3.849958896636963
+ },
+ {
+ "time_s": 27.5,
+ "frequency_hz": 262.9776369035244,
+ "weight": 2.7589681148529053
+ },
+ {
+ "time_s": 28.0,
+ "frequency_hz": 261.75,
+ "weight": 3.3370003700256348
+ },
+ {
+ "time_s": 28.5,
+ "frequency_hz": 260.95766696706414,
+ "weight": 4.527085781097412
+ },
+ {
+ "time_s": 29.0,
+ "frequency_hz": 260.81496392190456,
+ "weight": 4.041392803192139
+ },
+ {
+ "time_s": 29.5,
+ "frequency_hz": 261.16839389503,
+ "weight": 3.757441520690918
+ },
+ {
+ "time_s": 30.0,
+ "frequency_hz": 260.93155448138714,
+ "weight": 3.162980079650879
+ },
+ {
+ "time_s": 31.5,
+ "frequency_hz": 260.4243943542242,
+ "weight": 3.19456148147583
+ },
+ {
+ "time_s": 32.0,
+ "frequency_hz": 260.15643948316574,
+ "weight": 3.5665555000305176
+ },
+ {
+ "time_s": 32.5,
+ "frequency_hz": 259.9673990942538,
+ "weight": 4.023197174072266
+ },
+ {
+ "time_s": 33.0,
+ "frequency_hz": 259.79910442233086,
+ "weight": 3.250487804412842
+ },
+ {
+ "time_s": 33.5,
+ "frequency_hz": 259.63699163496494,
+ "weight": 2.8238630294799805
+ },
+ {
+ "time_s": 34.0,
+ "frequency_hz": 259.38297382742167,
+ "weight": 2.546142101287842
+ },
+ {
+ "time_s": 34.5,
+ "frequency_hz": 259.0724954456091,
+ "weight": 3.2085657119750977
+ },
+ {
+ "time_s": 36.0,
+ "frequency_hz": 258.75,
+ "weight": 2.5667824745178223
+ },
+ {
+ "time_s": 36.5,
+ "frequency_hz": 257.93862621858716,
+ "weight": 2.6985340118408203
+ },
+ {
+ "time_s": 37.0,
+ "frequency_hz": 258.0844503566623,
+ "weight": 2.5680809020996094
+ },
+ {
+ "time_s": 37.5,
+ "frequency_hz": 257.75,
+ "weight": 2.7436294555664062
+ },
+ {
+ "time_s": 38.0,
+ "frequency_hz": 257.23403495550156,
+ "weight": 3.7086358070373535
+ },
+ {
+ "time_s": 38.5,
+ "frequency_hz": 256.9483249038458,
+ "weight": 3.851073741912842
+ },
+ {
+ "time_s": 39.0,
+ "frequency_hz": 256.75,
+ "weight": 3.6053123474121094
+ },
+ {
+ "time_s": 39.5,
+ "frequency_hz": 256.23586194217205,
+ "weight": 4.15222692489624
+ },
+ {
+ "time_s": 40.0,
+ "frequency_hz": 255.67744110524654,
+ "weight": 4.94516134262085
+ },
+ {
+ "time_s": 40.5,
+ "frequency_hz": 255.25,
+ "weight": 4.965686321258545
+ },
+ {
+ "time_s": 41.0,
+ "frequency_hz": 254.7889089435339,
+ "weight": 4.947263717651367
+ },
+ {
+ "time_s": 41.5,
+ "frequency_hz": 254.69872830808163,
+ "weight": 5.088859558105469
+ },
+ {
+ "time_s": 42.0,
+ "frequency_hz": 253.75,
+ "weight": 4.362147331237793
+ },
+ {
+ "time_s": 42.5,
+ "frequency_hz": 253.03253949806094,
+ "weight": 3.986814260482788
+ },
+ {
+ "time_s": 43.0,
+ "frequency_hz": 252.4999441885484,
+ "weight": 3.9838473796844482
+ },
+ {
+ "time_s": 43.5,
+ "frequency_hz": 251.75,
+ "weight": 4.729279041290283
+ },
+ {
+ "time_s": 44.0,
+ "frequency_hz": 251.25,
+ "weight": 4.761523246765137
+ },
+ {
+ "time_s": 44.5,
+ "frequency_hz": 250.40872818231583,
+ "weight": 3.7738192081451416
+ },
+ {
+ "time_s": 45.0,
+ "frequency_hz": 249.09530125558376,
+ "weight": 2.9875125885009766
+ },
+ {
+ "time_s": 45.5,
+ "frequency_hz": 248.42104403674603,
+ "weight": 2.6722540855407715
+ },
+ {
+ "time_s": 46.5,
+ "frequency_hz": 245.04550002887845,
+ "weight": 2.742079973220825
+ },
+ {
+ "time_s": 48.0,
+ "frequency_hz": 241.75,
+ "weight": 2.560699224472046
+ },
+ {
+ "time_s": 48.5,
+ "frequency_hz": 239.43308974057436,
+ "weight": 4.04846715927124
+ },
+ {
+ "time_s": 49.0,
+ "frequency_hz": 238.8747150450945,
+ "weight": 4.119458198547363
+ },
+ {
+ "time_s": 49.5,
+ "frequency_hz": 236.25,
+ "weight": 4.030309677124023
+ },
+ {
+ "time_s": 50.0,
+ "frequency_hz": 235.79518741369247,
+ "weight": 4.3580169677734375
+ },
+ {
+ "time_s": 50.5,
+ "frequency_hz": 234.59660302102566,
+ "weight": 3.722860097885132
+ },
+ {
+ "time_s": 51.0,
+ "frequency_hz": 233.10784021764994,
+ "weight": 4.794473648071289
+ },
+ {
+ "time_s": 51.5,
+ "frequency_hz": 232.34278132021427,
+ "weight": 5.202602863311768
+ },
+ {
+ "time_s": 52.5,
+ "frequency_hz": 230.80869354307652,
+ "weight": 4.731462478637695
+ }
+ ],
+ "quality": {
+ "observed_duration_s": 1.0,
+ "span_s": 45.5,
+ "support_fraction": 0.02197802197802198,
+ "frequency_excursion_hz": 30.688407830893993,
+ "required_excursion_hz": 7.828338321726769,
+ "frequency_uncertainty_hz": 0.5,
+ "moving_fraction": 0.8111111111111111,
+ "prediction_error_q95": 0.5626173708521982,
+ "sustained_turns": 0.0,
+ "variation_ratio": 1.2986135076942191,
+ "median_contrast": 3.953231453895569,
+ "harmonic_count": 5.0,
+ "frequency_resolution_hz": 0.5,
+ "time_uncertainty_s": 1.0,
+ "frequency_sigma_hz": 0.5,
+ "fragment_count": 1.0,
+ "max_observed_gap_s": 2.0,
+ "frequency_drop_hz": 27.11864902684465,
+ "episode_frequency_scale": 1.0,
+ "episode_model_version": 2.0,
+ "matching_eligible": 1.0
+ }
+ },
+ {
+ "event_id": "ridge-9834a3c314c9474690ee",
+ "harmonic_group_id": "episode-a6d12cb1836824b9d245",
+ "start_s": 18.5,
+ "end_s": 53.0,
+ "band_hz": [
+ 173.40806325525045,
+ 201.8136682510376
+ ],
+ "ridge": [
+ {
+ "time_s": 19.5,
+ "frequency_hz": 198.11842729896307,
+ "weight": 2.620070457458496
+ },
+ {
+ "time_s": 20.0,
+ "frequency_hz": 198.30453960597515,
+ "weight": 2.9748706817626953
+ },
+ {
+ "time_s": 20.5,
+ "frequency_hz": 198.52784807793796,
+ "weight": 3.140181541442871
+ },
+ {
+ "time_s": 21.0,
+ "frequency_hz": 198.75296200811863,
+ "weight": 3.496051549911499
+ },
+ {
+ "time_s": 21.5,
+ "frequency_hz": 198.7945864647627,
+ "weight": 3.059128522872925
+ },
+ {
+ "time_s": 23.5,
+ "frequency_hz": 200.8136682510376,
+ "weight": 3.8962454795837402
+ },
+ {
+ "time_s": 24.0,
+ "frequency_hz": 200.25,
+ "weight": 2.5027506351470947
+ },
+ {
+ "time_s": 24.5,
+ "frequency_hz": 199.0572420693934,
+ "weight": 2.533817768096924
+ },
+ {
+ "time_s": 26.5,
+ "frequency_hz": 198.54571484029293,
+ "weight": 3.018122434616089
+ },
+ {
+ "time_s": 28.0,
+ "frequency_hz": 197.0396712757647,
+ "weight": 3.4193077087402344
+ },
+ {
+ "time_s": 28.5,
+ "frequency_hz": 195.7558722794056,
+ "weight": 3.996349811553955
+ },
+ {
+ "time_s": 29.0,
+ "frequency_hz": 195.76713171601295,
+ "weight": 4.0002851486206055
+ },
+ {
+ "time_s": 29.5,
+ "frequency_hz": 196.25,
+ "weight": 4.313448905944824
+ },
+ {
+ "time_s": 30.0,
+ "frequency_hz": 196.61574576050043,
+ "weight": 4.547061443328857
+ },
+ {
+ "time_s": 30.5,
+ "frequency_hz": 196.35941223800182,
+ "weight": 4.323495388031006
+ },
+ {
+ "time_s": 31.0,
+ "frequency_hz": 195.95648815482855,
+ "weight": 4.985681533813477
+ },
+ {
+ "time_s": 31.5,
+ "frequency_hz": 195.6579132080078,
+ "weight": 4.691498279571533
+ },
+ {
+ "time_s": 32.0,
+ "frequency_hz": 195.25,
+ "weight": 4.848968982696533
+ },
+ {
+ "time_s": 32.5,
+ "frequency_hz": 195.10370553284883,
+ "weight": 5.468665599822998
+ },
+ {
+ "time_s": 33.0,
+ "frequency_hz": 194.973903182894,
+ "weight": 5.038476467132568
+ },
+ {
+ "time_s": 33.5,
+ "frequency_hz": 194.75,
+ "weight": 4.858774662017822
+ },
+ {
+ "time_s": 34.0,
+ "frequency_hz": 194.59892375022173,
+ "weight": 4.848712921142578
+ },
+ {
+ "time_s": 34.5,
+ "frequency_hz": 194.3624382764101,
+ "weight": 5.136556148529053
+ },
+ {
+ "time_s": 35.0,
+ "frequency_hz": 194.33115002512932,
+ "weight": 4.160106182098389
+ },
+ {
+ "time_s": 35.5,
+ "frequency_hz": 194.39950488507748,
+ "weight": 3.8391308784484863
+ },
+ {
+ "time_s": 36.0,
+ "frequency_hz": 194.1603628695011,
+ "weight": 4.687252521514893
+ },
+ {
+ "time_s": 36.5,
+ "frequency_hz": 193.93071124702692,
+ "weight": 4.970529556274414
+ },
+ {
+ "time_s": 37.0,
+ "frequency_hz": 193.75,
+ "weight": 4.518451690673828
+ },
+ {
+ "time_s": 37.5,
+ "frequency_hz": 193.4612184613943,
+ "weight": 4.253635883331299
+ },
+ {
+ "time_s": 38.0,
+ "frequency_hz": 193.18367390334606,
+ "weight": 2.8927106857299805
+ },
+ {
+ "time_s": 40.0,
+ "frequency_hz": 191.43944944813848,
+ "weight": 3.314002275466919
+ },
+ {
+ "time_s": 40.5,
+ "frequency_hz": 191.3570603132248,
+ "weight": 4.468647480010986
+ },
+ {
+ "time_s": 41.0,
+ "frequency_hz": 191.11094457656145,
+ "weight": 4.871123790740967
+ },
+ {
+ "time_s": 41.5,
+ "frequency_hz": 191.10496609658003,
+ "weight": 5.0356125831604
+ },
+ {
+ "time_s": 42.0,
+ "frequency_hz": 190.5745730996132,
+ "weight": 3.9210546016693115
+ },
+ {
+ "time_s": 42.5,
+ "frequency_hz": 189.77832560241222,
+ "weight": 4.070233345031738
+ },
+ {
+ "time_s": 43.0,
+ "frequency_hz": 189.23329646885395,
+ "weight": 4.379164695739746
+ },
+ {
+ "time_s": 43.5,
+ "frequency_hz": 188.75,
+ "weight": 5.182953357696533
+ },
+ {
+ "time_s": 44.0,
+ "frequency_hz": 188.3975451514125,
+ "weight": 5.1537675857543945
+ },
+ {
+ "time_s": 44.5,
+ "frequency_hz": 187.78356432914734,
+ "weight": 4.392264366149902
+ },
+ {
+ "time_s": 45.0,
+ "frequency_hz": 187.08445523679256,
+ "weight": 3.466244697570801
+ },
+ {
+ "time_s": 45.5,
+ "frequency_hz": 185.89950885623693,
+ "weight": 3.585481882095337
+ },
+ {
+ "time_s": 46.0,
+ "frequency_hz": 184.48985742777586,
+ "weight": 4.506937503814697
+ },
+ {
+ "time_s": 46.5,
+ "frequency_hz": 184.13456040620804,
+ "weight": 4.335684299468994
+ },
+ {
+ "time_s": 47.0,
+ "frequency_hz": 183.25,
+ "weight": 3.9673798084259033
+ },
+ {
+ "time_s": 47.5,
+ "frequency_hz": 182.02884119562805,
+ "weight": 3.897047281265259
+ },
+ {
+ "time_s": 48.0,
+ "frequency_hz": 181.12525229156017,
+ "weight": 3.909757137298584
+ },
+ {
+ "time_s": 48.5,
+ "frequency_hz": 180.08909215778112,
+ "weight": 4.9228034019470215
+ },
+ {
+ "time_s": 49.0,
+ "frequency_hz": 179.3139194995165,
+ "weight": 4.643064975738525
+ },
+ {
+ "time_s": 49.5,
+ "frequency_hz": 177.75,
+ "weight": 3.9700183868408203
+ },
+ {
+ "time_s": 50.0,
+ "frequency_hz": 176.75,
+ "weight": 3.8310418128967285
+ },
+ {
+ "time_s": 50.5,
+ "frequency_hz": 175.62817291915417,
+ "weight": 3.8143906593322754
+ },
+ {
+ "time_s": 51.0,
+ "frequency_hz": 175.0178051814437,
+ "weight": 4.733550071716309
+ },
+ {
+ "time_s": 51.5,
+ "frequency_hz": 174.57537572085857,
+ "weight": 4.194712162017822
+ },
+ {
+ "time_s": 52.0,
+ "frequency_hz": 174.40806325525045,
+ "weight": 3.0503222942352295
+ }
+ ],
+ "quality": {
+ "observed_duration_s": 1.0,
+ "span_s": 33.0,
+ "support_fraction": 0.030303030303030304,
+ "frequency_excursion_hz": 23.428320548310865,
+ "required_excursion_hz": 5.8125,
+ "frequency_uncertainty_hz": 0.5,
+ "moving_fraction": 0.7846153846153846,
+ "prediction_error_q95": 0.45248814320990016,
+ "sustained_turns": 0.0,
+ "variation_ratio": 1.0921821532964346,
+ "median_contrast": 4.194712162017822,
+ "harmonic_count": 5.0,
+ "frequency_resolution_hz": 0.5,
+ "time_uncertainty_s": 1.0,
+ "frequency_sigma_hz": 0.5,
+ "fragment_count": 1.0,
+ "max_observed_gap_s": 2.0,
+ "frequency_drop_hz": 22.00296200811863,
+ "episode_frequency_scale": 0.7504015144844179,
+ "episode_model_version": 2.0,
+ "matching_eligible": 1.0
+ }
+ },
+ {
+ "event_id": "ridge-41f68eae800cafb36acc",
+ "harmonic_group_id": "episode-a6d12cb1836824b9d245",
+ "start_s": 22.0,
+ "end_s": 60.0,
+ "band_hz": [
+ 105.07778882235289,
+ 134.8890943825245
+ ],
+ "ridge": [
+ {
+ "time_s": 23.0,
+ "frequency_hz": 133.8890943825245,
+ "weight": 6.737265586853027
+ },
+ {
+ "time_s": 23.5,
+ "frequency_hz": 133.75,
+ "weight": 6.489849090576172
+ },
+ {
+ "time_s": 24.0,
+ "frequency_hz": 133.25,
+ "weight": 5.391107082366943
+ },
+ {
+ "time_s": 24.5,
+ "frequency_hz": 132.81725907325745,
+ "weight": 5.680244445800781
+ },
+ {
+ "time_s": 25.0,
+ "frequency_hz": 132.7134250253439,
+ "weight": 5.773349761962891
+ },
+ {
+ "time_s": 25.5,
+ "frequency_hz": 132.60458973050117,
+ "weight": 5.782063961029053
+ },
+ {
+ "time_s": 26.0,
+ "frequency_hz": 132.50190484977793,
+ "weight": 5.871440887451172
+ },
+ {
+ "time_s": 26.5,
+ "frequency_hz": 132.25,
+ "weight": 6.160818576812744
+ },
+ {
+ "time_s": 27.0,
+ "frequency_hz": 132.13466522097588,
+ "weight": 6.358359336853027
+ },
+ {
+ "time_s": 27.5,
+ "frequency_hz": 131.95150547847152,
+ "weight": 6.328005313873291
+ },
+ {
+ "time_s": 28.0,
+ "frequency_hz": 131.65711458027363,
+ "weight": 5.884696006774902
+ },
+ {
+ "time_s": 28.5,
+ "frequency_hz": 130.75,
+ "weight": 6.112754821777344
+ },
+ {
+ "time_s": 29.0,
+ "frequency_hz": 130.48039501160383,
+ "weight": 5.936465740203857
+ },
+ {
+ "time_s": 29.5,
+ "frequency_hz": 130.75,
+ "weight": 6.3497209548950195
+ },
+ {
+ "time_s": 30.0,
+ "frequency_hz": 131.00440991809592,
+ "weight": 7.075647354125977
+ },
+ {
+ "time_s": 30.5,
+ "frequency_hz": 130.9285822585225,
+ "weight": 7.613493919372559
+ },
+ {
+ "time_s": 31.0,
+ "frequency_hz": 130.6837365180254,
+ "weight": 8.380424499511719
+ },
+ {
+ "time_s": 31.5,
+ "frequency_hz": 130.38835594803095,
+ "weight": 8.019461631774902
+ },
+ {
+ "time_s": 32.0,
+ "frequency_hz": 130.11785735189915,
+ "weight": 8.367355346679688
+ },
+ {
+ "time_s": 32.5,
+ "frequency_hz": 130.07916074991226,
+ "weight": 8.903495788574219
+ },
+ {
+ "time_s": 33.0,
+ "frequency_hz": 130.02267597429454,
+ "weight": 8.015593528747559
+ },
+ {
+ "time_s": 33.5,
+ "frequency_hz": 129.83330582082272,
+ "weight": 7.487475872039795
+ },
+ {
+ "time_s": 34.0,
+ "frequency_hz": 129.74087378382683,
+ "weight": 7.005758762359619
+ },
+ {
+ "time_s": 34.5,
+ "frequency_hz": 129.61440055072308,
+ "weight": 7.483412265777588
+ },
+ {
+ "time_s": 35.0,
+ "frequency_hz": 129.54676150903106,
+ "weight": 6.4369049072265625
+ },
+ {
+ "time_s": 35.5,
+ "frequency_hz": 129.56602542847395,
+ "weight": 6.23375129699707
+ },
+ {
+ "time_s": 36.0,
+ "frequency_hz": 129.45566534623504,
+ "weight": 7.571045398712158
+ },
+ {
+ "time_s": 36.5,
+ "frequency_hz": 129.30102379620075,
+ "weight": 7.516002655029297
+ },
+ {
+ "time_s": 37.0,
+ "frequency_hz": 129.13479802012444,
+ "weight": 7.357361316680908
+ },
+ {
+ "time_s": 37.5,
+ "frequency_hz": 128.84337666630745,
+ "weight": 7.517699241638184
+ },
+ {
+ "time_s": 38.0,
+ "frequency_hz": 128.62653371691704,
+ "weight": 7.004787445068359
+ },
+ {
+ "time_s": 38.5,
+ "frequency_hz": 128.48712304700166,
+ "weight": 6.1183648109436035
+ },
+ {
+ "time_s": 39.0,
+ "frequency_hz": 128.4237556234002,
+ "weight": 5.430800914764404
+ },
+ {
+ "time_s": 39.5,
+ "frequency_hz": 128.08058597892523,
+ "weight": 6.134977340698242
+ },
+ {
+ "time_s": 40.0,
+ "frequency_hz": 127.81261344254017,
+ "weight": 6.753001689910889
+ },
+ {
+ "time_s": 40.5,
+ "frequency_hz": 127.68687784671783,
+ "weight": 7.105392932891846
+ },
+ {
+ "time_s": 41.0,
+ "frequency_hz": 127.49084884021431,
+ "weight": 6.623341083526611
+ },
+ {
+ "time_s": 41.5,
+ "frequency_hz": 127.37184834480286,
+ "weight": 6.466814041137695
+ },
+ {
+ "time_s": 42.0,
+ "frequency_hz": 127.11038967221975,
+ "weight": 5.739862442016602
+ },
+ {
+ "time_s": 42.5,
+ "frequency_hz": 126.5157764479518,
+ "weight": 5.355622291564941
+ },
+ {
+ "time_s": 43.0,
+ "frequency_hz": 126.20902845263481,
+ "weight": 5.65873384475708
+ },
+ {
+ "time_s": 43.5,
+ "frequency_hz": 125.99792540702038,
+ "weight": 5.920466899871826
+ },
+ {
+ "time_s": 44.0,
+ "frequency_hz": 125.43461908400059,
+ "weight": 5.911413192749023
+ },
+ {
+ "time_s": 44.5,
+ "frequency_hz": 125.20826065540314,
+ "weight": 5.217926502227783
+ },
+ {
+ "time_s": 45.0,
+ "frequency_hz": 124.62139445543289,
+ "weight": 4.2175116539001465
+ },
+ {
+ "time_s": 45.5,
+ "frequency_hz": 123.75,
+ "weight": 4.806180000305176
+ },
+ {
+ "time_s": 46.0,
+ "frequency_hz": 123.15982104837894,
+ "weight": 4.884687423706055
+ },
+ {
+ "time_s": 46.5,
+ "frequency_hz": 122.61205680668354,
+ "weight": 5.67014741897583
+ },
+ {
+ "time_s": 47.0,
+ "frequency_hz": 122.07682789862156,
+ "weight": 5.6944260597229
+ },
+ {
+ "time_s": 47.5,
+ "frequency_hz": 121.51553484704345,
+ "weight": 5.775753021240234
+ },
+ {
+ "time_s": 48.0,
+ "frequency_hz": 120.8539083302021,
+ "weight": 5.623732089996338
+ },
+ {
+ "time_s": 48.5,
+ "frequency_hz": 120.3434753715992,
+ "weight": 5.741275310516357
+ },
+ {
+ "time_s": 49.0,
+ "frequency_hz": 119.6298301666975,
+ "weight": 4.899613857269287
+ },
+ {
+ "time_s": 49.5,
+ "frequency_hz": 118.96821855008602,
+ "weight": 4.171494960784912
+ },
+ {
+ "time_s": 50.0,
+ "frequency_hz": 117.59306278079748,
+ "weight": 4.294402599334717
+ },
+ {
+ "time_s": 50.5,
+ "frequency_hz": 117.08258166909218,
+ "weight": 4.646002292633057
+ },
+ {
+ "time_s": 51.0,
+ "frequency_hz": 116.39913462847471,
+ "weight": 5.3450140953063965
+ },
+ {
+ "time_s": 51.5,
+ "frequency_hz": 116.14998346567154,
+ "weight": 5.252270221710205
+ },
+ {
+ "time_s": 52.0,
+ "frequency_hz": 115.75,
+ "weight": 4.892366886138916
+ },
+ {
+ "time_s": 52.5,
+ "frequency_hz": 114.75,
+ "weight": 4.657271862030029
+ },
+ {
+ "time_s": 53.0,
+ "frequency_hz": 114.02019721083343,
+ "weight": 5.055095195770264
+ },
+ {
+ "time_s": 53.5,
+ "frequency_hz": 113.34410624206066,
+ "weight": 5.492178440093994
+ },
+ {
+ "time_s": 54.0,
+ "frequency_hz": 112.80171176791191,
+ "weight": 5.599684238433838
+ },
+ {
+ "time_s": 54.5,
+ "frequency_hz": 112.3064832687378,
+ "weight": 5.982992172241211
+ },
+ {
+ "time_s": 55.0,
+ "frequency_hz": 111.44376991316676,
+ "weight": 6.134244441986084
+ },
+ {
+ "time_s": 55.5,
+ "frequency_hz": 110.83241407573223,
+ "weight": 6.62202262878418
+ },
+ {
+ "time_s": 56.0,
+ "frequency_hz": 109.25,
+ "weight": 6.647563934326172
+ },
+ {
+ "time_s": 56.5,
+ "frequency_hz": 109.11767356097698,
+ "weight": 7.809727668762207
+ },
+ {
+ "time_s": 57.0,
+ "frequency_hz": 108.58678123354912,
+ "weight": 6.734163284301758
+ },
+ {
+ "time_s": 57.5,
+ "frequency_hz": 108.13941513001919,
+ "weight": 6.583103656768799
+ },
+ {
+ "time_s": 58.0,
+ "frequency_hz": 107.69068390130997,
+ "weight": 6.297852993011475
+ },
+ {
+ "time_s": 58.5,
+ "frequency_hz": 106.97243337146938,
+ "weight": 5.162389755249023
+ },
+ {
+ "time_s": 59.0,
+ "frequency_hz": 106.07778882235289,
+ "weight": 5.134810447692871
+ }
+ ],
+ "quality": {
+ "observed_duration_s": 1.0,
+ "span_s": 36.5,
+ "support_fraction": 0.0273972602739726,
+ "frequency_excursion_hz": 24.347123852372164,
+ "required_excursion_hz": 4.0,
+ "frequency_uncertainty_hz": 0.5,
+ "moving_fraction": 0.8611111111111112,
+ "prediction_error_q95": 0.31941581200381564,
+ "sustained_turns": 0.0,
+ "variation_ratio": 1.142282995264836,
+ "median_contrast": 6.112754821777344,
+ "harmonic_count": 5.0,
+ "frequency_resolution_hz": 0.5,
+ "time_uncertainty_s": 1.0,
+ "frequency_sigma_hz": 0.5,
+ "fragment_count": 1.0,
+ "max_observed_gap_s": 0.5,
+ "frequency_drop_hz": 23.36941050965106,
+ "episode_frequency_scale": 0.5001721650324792,
+ "episode_model_version": 2.0,
+ "matching_eligible": 1.0
+ }
+ },
+ {
+ "event_id": "ridge-af2d2e7c0b20d7fec4c2",
+ "harmonic_group_id": "episode-a6d12cb1836824b9d245",
+ "start_s": 23.5,
+ "end_s": 42.5,
+ "band_hz": [
+ 317.25441271066666,
+ 333.2795720696449
+ ],
+ "ridge": [
+ {
+ "time_s": 24.5,
+ "frequency_hz": 332.2795720696449,
+ "weight": 2.542895793914795
+ },
+ {
+ "time_s": 25.0,
+ "frequency_hz": 332.0822596177459,
+ "weight": 3.0261921882629395
+ },
+ {
+ "time_s": 25.5,
+ "frequency_hz": 331.5404234789312,
+ "weight": 3.040437936782837
+ },
+ {
+ "time_s": 26.0,
+ "frequency_hz": 331.2852519005537,
+ "weight": 2.7835745811462402
+ },
+ {
+ "time_s": 27.5,
+ "frequency_hz": 330.08813816308975,
+ "weight": 2.9520630836486816
+ },
+ {
+ "time_s": 29.5,
+ "frequency_hz": 326.5148300444707,
+ "weight": 2.96875
+ },
+ {
+ "time_s": 30.0,
+ "frequency_hz": 327.75,
+ "weight": 2.895812511444092
+ },
+ {
+ "time_s": 30.5,
+ "frequency_hz": 327.2305840998888,
+ "weight": 2.951028347015381
+ },
+ {
+ "time_s": 31.0,
+ "frequency_hz": 326.3581150621176,
+ "weight": 3.393730640411377
+ },
+ {
+ "time_s": 31.5,
+ "frequency_hz": 325.9737631082535,
+ "weight": 3.4011247158050537
+ },
+ {
+ "time_s": 32.0,
+ "frequency_hz": 325.5719983354211,
+ "weight": 3.5858471393585205
+ },
+ {
+ "time_s": 32.5,
+ "frequency_hz": 325.2572627365589,
+ "weight": 3.8350489139556885
+ },
+ {
+ "time_s": 33.0,
+ "frequency_hz": 324.9351560547948,
+ "weight": 3.9779558181762695
+ },
+ {
+ "time_s": 33.5,
+ "frequency_hz": 324.54934203997254,
+ "weight": 3.901181697845459
+ },
+ {
+ "time_s": 34.0,
+ "frequency_hz": 324.3413196504116,
+ "weight": 3.6561551094055176
+ },
+ {
+ "time_s": 34.5,
+ "frequency_hz": 323.8668796867132,
+ "weight": 3.813960313796997
+ },
+ {
+ "time_s": 35.0,
+ "frequency_hz": 323.89932768791914,
+ "weight": 3.1305484771728516
+ },
+ {
+ "time_s": 35.5,
+ "frequency_hz": 324.15193881094456,
+ "weight": 2.918452262878418
+ },
+ {
+ "time_s": 36.0,
+ "frequency_hz": 323.75,
+ "weight": 3.671071767807007
+ },
+ {
+ "time_s": 36.5,
+ "frequency_hz": 323.1899628043175,
+ "weight": 3.2560737133026123
+ },
+ {
+ "time_s": 37.0,
+ "frequency_hz": 323.03986144810915,
+ "weight": 2.8661656379699707
+ },
+ {
+ "time_s": 38.5,
+ "frequency_hz": 321.3909229785204,
+ "weight": 2.591815948486328
+ },
+ {
+ "time_s": 40.5,
+ "frequency_hz": 318.69002301990986,
+ "weight": 2.615626335144043
+ },
+ {
+ "time_s": 41.0,
+ "frequency_hz": 318.4048224762082,
+ "weight": 2.898038864135742
+ },
+ {
+ "time_s": 41.5,
+ "frequency_hz": 318.25441271066666,
+ "weight": 3.0719497203826904
+ }
+ ],
+ "quality": {
+ "observed_duration_s": 1.0,
+ "span_s": 17.5,
+ "support_fraction": 0.05714285714285714,
+ "frequency_excursion_hz": 13.512029805034388,
+ "required_excursion_hz": 9.748054681643843,
+ "frequency_uncertainty_hz": 0.5,
+ "moving_fraction": 0.9705882352941176,
+ "prediction_error_q95": 0.8518435656734631,
+ "sustained_turns": 0.0,
+ "variation_ratio": 1.0379757565182914,
+ "median_contrast": 3.040437936782837,
+ "harmonic_count": 5.0,
+ "frequency_resolution_hz": 0.5,
+ "time_uncertainty_s": 1.0,
+ "frequency_sigma_hz": 0.5,
+ "fragment_count": 1.0,
+ "max_observed_gap_s": 2.0,
+ "frequency_drop_hz": 13.263918800279498,
+ "episode_frequency_scale": 1.2506598317686233,
+ "episode_model_version": 2.0,
+ "matching_eligible": 1.0
+ }
+ },
+ {
+ "event_id": "ridge-e4492d9b7e99ae1549c9",
+ "harmonic_group_id": "episode-a6d12cb1836824b9d245",
+ "start_s": 27.0,
+ "end_s": 47.0,
+ "band_hz": [
+ 370.25,
+ 396.4902655137703
+ ],
+ "ridge": [
+ {
+ "time_s": 28.0,
+ "frequency_hz": 395.4902655137703,
+ "weight": 2.5581576824188232
+ },
+ {
+ "time_s": 29.0,
+ "frequency_hz": 391.32592721283436,
+ "weight": 3.2589056491851807
+ },
+ {
+ "time_s": 29.5,
+ "frequency_hz": 391.6656939536333,
+ "weight": 3.8855831623077393
+ },
+ {
+ "time_s": 30.0,
+ "frequency_hz": 391.6948543339968,
+ "weight": 3.4343252182006836
+ },
+ {
+ "time_s": 30.5,
+ "frequency_hz": 391.7779882848263,
+ "weight": 3.411339044570923
+ },
+ {
+ "time_s": 31.0,
+ "frequency_hz": 391.54184939339757,
+ "weight": 3.6563305854797363
+ },
+ {
+ "time_s": 31.5,
+ "frequency_hz": 391.1419853270054,
+ "weight": 2.9315481185913086
+ },
+ {
+ "time_s": 32.0,
+ "frequency_hz": 390.558022454381,
+ "weight": 3.071195125579834
+ },
+ {
+ "time_s": 32.5,
+ "frequency_hz": 390.25,
+ "weight": 3.4644784927368164
+ },
+ {
+ "time_s": 33.0,
+ "frequency_hz": 389.4713966548443,
+ "weight": 3.3766894340515137
+ },
+ {
+ "time_s": 33.5,
+ "frequency_hz": 389.2653615027666,
+ "weight": 4.0590338706970215
+ },
+ {
+ "time_s": 34.0,
+ "frequency_hz": 389.18294091522694,
+ "weight": 3.9475643634796143
+ },
+ {
+ "time_s": 34.5,
+ "frequency_hz": 388.5289353430271,
+ "weight": 3.6705775260925293
+ },
+ {
+ "time_s": 35.0,
+ "frequency_hz": 388.6320478916168,
+ "weight": 3.907896041870117
+ },
+ {
+ "time_s": 35.5,
+ "frequency_hz": 388.86555102467537,
+ "weight": 3.6264963150024414
+ },
+ {
+ "time_s": 36.0,
+ "frequency_hz": 388.8926433175802,
+ "weight": 3.5140655040740967
+ },
+ {
+ "time_s": 36.5,
+ "frequency_hz": 387.6339865475893,
+ "weight": 3.6657822132110596
+ },
+ {
+ "time_s": 37.0,
+ "frequency_hz": 387.3912725970149,
+ "weight": 4.023021221160889
+ },
+ {
+ "time_s": 37.5,
+ "frequency_hz": 386.66791842877865,
+ "weight": 4.052284240722656
+ },
+ {
+ "time_s": 38.0,
+ "frequency_hz": 385.95921156555414,
+ "weight": 3.544545888900757
+ },
+ {
+ "time_s": 38.5,
+ "frequency_hz": 385.5949132591486,
+ "weight": 3.4719676971435547
+ },
+ {
+ "time_s": 39.0,
+ "frequency_hz": 384.98633785918355,
+ "weight": 3.503868818283081
+ },
+ {
+ "time_s": 39.5,
+ "frequency_hz": 384.75,
+ "weight": 3.5155296325683594
+ },
+ {
+ "time_s": 40.0,
+ "frequency_hz": 383.848258420825,
+ "weight": 3.0750317573547363
+ },
+ {
+ "time_s": 41.0,
+ "frequency_hz": 382.25,
+ "weight": 2.6304726600646973
+ },
+ {
+ "time_s": 41.5,
+ "frequency_hz": 382.2031724900007,
+ "weight": 3.2006404399871826
+ },
+ {
+ "time_s": 42.0,
+ "frequency_hz": 380.09025564044714,
+ "weight": 3.186986207962036
+ },
+ {
+ "time_s": 42.5,
+ "frequency_hz": 379.25,
+ "weight": 3.6549510955810547
+ },
+ {
+ "time_s": 43.0,
+ "frequency_hz": 378.8361281603575,
+ "weight": 3.9785633087158203
+ },
+ {
+ "time_s": 43.5,
+ "frequency_hz": 377.25,
+ "weight": 4.113250732421875
+ },
+ {
+ "time_s": 44.0,
+ "frequency_hz": 376.5523437783122,
+ "weight": 3.978457450866699
+ },
+ {
+ "time_s": 45.0,
+ "frequency_hz": 373.75,
+ "weight": 4.190529823303223
+ },
+ {
+ "time_s": 45.5,
+ "frequency_hz": 371.62624230980873,
+ "weight": 4.72190523147583
+ },
+ {
+ "time_s": 46.0,
+ "frequency_hz": 371.25,
+ "weight": 3.6271650791168213
+ }
+ ],
+ "quality": {
+ "observed_duration_s": 1.0,
+ "span_s": 18.5,
+ "support_fraction": 0.05405405405405406,
+ "frequency_excursion_hz": 18.688169525563694,
+ "required_excursion_hz": 11.625378887169063,
+ "frequency_uncertainty_hz": 0.5,
+ "moving_fraction": 0.8055555555555556,
+ "prediction_error_q95": 0.824160755626597,
+ "sustained_turns": 0.0,
+ "variation_ratio": 1.2970914824275237,
+ "median_contrast": 3.585521101951599,
+ "harmonic_count": 5.0,
+ "frequency_resolution_hz": 0.5,
+ "time_uncertainty_s": 1.0,
+ "frequency_sigma_hz": 0.5,
+ "fragment_count": 1.0,
+ "max_observed_gap_s": 1.0,
+ "frequency_drop_hz": 17.944854333996773,
+ "episode_frequency_scale": 1.5003203522715636,
+ "episode_model_version": 2.0,
+ "matching_eligible": 1.0
+ }
+ },
+ {
+ "event_id": "ridge-4b9a927849f08dd061ac",
+ "harmonic_group_id": "episode-a6d12cb1836824b9d245",
+ "start_s": 43.0,
+ "end_s": 53.0,
+ "band_hz": [
+ 288.9733549300581,
+ 314.75
+ ],
+ "ridge": [
+ {
+ "time_s": 44.0,
+ "frequency_hz": 313.75,
+ "weight": 3.447657346725464
+ },
+ {
+ "time_s": 44.5,
+ "frequency_hz": 312.10574892908335,
+ "weight": 2.5066726207733154
+ },
+ {
+ "time_s": 46.5,
+ "frequency_hz": 307.25,
+ "weight": 2.52113938331604
+ },
+ {
+ "time_s": 48.0,
+ "frequency_hz": 301.75,
+ "weight": 2.893303155899048
+ },
+ {
+ "time_s": 48.5,
+ "frequency_hz": 300.6912498027086,
+ "weight": 2.978280544281006
+ },
+ {
+ "time_s": 50.0,
+ "frequency_hz": 294.5911628380418,
+ "weight": 2.6498687267303467
+ },
+ {
+ "time_s": 50.5,
+ "frequency_hz": 294.3700035959482,
+ "weight": 2.547456979751587
+ },
+ {
+ "time_s": 51.0,
+ "frequency_hz": 291.75,
+ "weight": 3.1324539184570312
+ },
+ {
+ "time_s": 51.5,
+ "frequency_hz": 290.2054081261158,
+ "weight": 3.5063889026641846
+ },
+ {
+ "time_s": 52.0,
+ "frequency_hz": 289.9733549300581,
+ "weight": 3.3261404037475586
+ }
+ ],
+ "quality": {
+ "observed_duration_s": 1.0,
+ "span_s": 8.5,
+ "support_fraction": 0.11764705882352941,
+ "frequency_excursion_hz": 22.93230814980342,
+ "required_excursion_hz": 8.929236189611256,
+ "frequency_uncertainty_hz": 0.5,
+ "moving_fraction": 0.875,
+ "prediction_error_q95": 0.6241862431226375,
+ "sustained_turns": 0.0,
+ "variation_ratio": 1.0368186627627232,
+ "median_contrast": 2.935791850090027,
+ "harmonic_count": 5.0,
+ "frequency_resolution_hz": 0.5,
+ "time_uncertainty_s": 1.0,
+ "frequency_sigma_hz": 0.5,
+ "fragment_count": 1.0,
+ "max_observed_gap_s": 2.0,
+ "frequency_drop_hz": 21.90034080296755,
+ "episode_frequency_scale": 1.2508756687097755,
+ "episode_model_version": 2.0,
+ "matching_eligible": 1.0
+ }
+ }
+ ]
+}
diff --git a/tests/test_episodes.py b/tests/test_episodes.py
new file mode 100644
index 0000000..ba2fc55
--- /dev/null
+++ b/tests/test_episodes.py
@@ -0,0 +1,211 @@
+"""Bookkeeping and mathematical properties, without audio synthesis.
+
+Coordinate arrays here exercise association algebra, not signal detection or
+empirical accuracy. Signal tests below use only the existing real PCM fixture.
+"""
+import base64
+from dataclasses import replace
+import itertools
+import json
+from pathlib import Path
+
+import numpy as np
+import pytest
+import soundfile as sf
+
+from dopplergeist.discovery import DiscoverySettings, _spectrum, discover_events, required_sample_rate
+from dopplergeist.episodes import (Associations, DiscoveryError, Ridge, deduplicate, identifier,
+ intervals, motion, reconcile, stitch)
+from dopplergeist.intake import AudioIntakeError, intake_recording
+from dopplergeist.matching import prepare_events
+
+
+def coordinates(start=0, stop=20, scale=1, rising=False, envelope=True):
+ t = np.arange(start, stop, .5)
+ f = 200 + (2 if rising else -2) * t
+ p = np.column_stack((t, scale*f, np.full(len(t), 6.)))
+ if envelope:
+ p = np.column_stack((p, -20 + .8*t))
+ return p
+
+
+def track(points, chunk='a'):
+ return Ridge(points, (chunk+':'+identifier('raw-',points),))
+
+
+def test_cells_count_observations_without_spanning_missing_time():
+ cells=intervals([0,.5,1,10,10.5],.5)
+ assert cells==[[0.,1.25],[9.75,10.75]]
+ assert sum(b-a for a,b in cells)==2.25
+
+
+def test_deterministic_complete_link_grouping_and_noninteger_scales():
+ paths=[track(coordinates(scale=scale),str(i)) for i,scale in enumerate([1,2,3.14159])]
+ s=DiscoverySettings()
+ identities=[]
+ for permutation in itertools.permutations(paths):
+ groups=reconcile(permutation,s,Associations(s))
+ assert len(groups)==1
+ members,scales,orders=groups[0]
+ assert orders is None
+ assert scales==pytest.approx([1,2,3.14159])
+ identities.append([identifier('',r.points) for r in members])
+ assert all(x==identities[0] for x in identities)
+
+
+def test_weak_bridge_cannot_join_inconsistent_groups(monkeypatch):
+ s=DiscoverySettings()
+ paths=[track(coordinates(scale=k),str(k)) for k in (1,2,3)]
+ from dopplergeist import episodes
+ original=episodes.related
+ def graph(a,b,settings):
+ # Bookkeeping graph A-B-C has no joint A-C witness.
+ if max(np.median(a[:,1]),np.median(b[:,1]))/min(np.median(a[:,1]),np.median(b[:,1]))>2.5:
+ return None
+ return original(a,b,settings)
+ monkeypatch.setattr(episodes,'related',graph)
+ groups=reconcile(paths,s,Associations(s))
+ assert len(groups)==2
+ assert sorted(len(g[0]) for g in groups)==[1,2]
+
+
+def test_later_witnesses_reconcile_without_a_single_base_comparison(monkeypatch):
+ from dopplergeist import episodes
+ s=DiscoverySettings()
+ paths=[track(coordinates(scale=k),str(k)) for k in (1,2,3,4)]
+ original=episodes.related
+ def graph(a,b,settings):
+ if max(np.median(a[:,1]),np.median(b[:,1]))/min(np.median(a[:,1]),np.median(b[:,1]))>3.5:
+ return None
+ return original(a,b,settings)
+ monkeypatch.setattr(episodes,'related',graph)
+ for order in [paths,paths[::-1]]:
+ assert len(reconcile(order,s,Associations(s)))==1
+
+
+def test_overlap_alone_does_not_merge_independent_evolution():
+ s=DiscoverySettings()
+ paths=[track(coordinates(), 'a'),track(coordinates(scale=1.5,rising=True),'b')]
+ assert len(reconcile(paths,s,Associations(s)))==2
+
+
+def test_near_unison_same_chunk_is_not_discarded_as_duplicate():
+ s=DiscoverySettings()
+ a=coordinates(); b=a.copy(); b[:,1]+=.2
+ assert len(deduplicate([track(a),track(b)],s,Associations(s)))==2
+ copies=[track(a,'chunk1'),track(a.copy(),'chunk2')]
+ for order in [copies,copies[::-1]]:
+ merged=deduplicate(order,s,Associations(s))
+ assert len(merged)==1 and len(merged[0].origins)==2
+ assert np.array_equal(merged[0].points,a)
+
+
+def test_subthreshold_fragments_stitch_before_duration_gate_and_keep_gap():
+ s=DiscoverySettings()
+ first=track(coordinates(0,8),'a'); second=track(coordinates(10,18),'b')
+ assert motion(first.points,s)[0]['observed_duration_s']<s.min_duration_s
+ merged=stitch([second,first],s,Associations(s))
+ assert len(merged)==1
+ assert not any(8<=t<10 for t in merged[0].points[:,0])
+ metric,rejected=motion(merged[0].points,s)
+ assert not rejected
+ assert metric['observed_duration_s']<metric['span_s']
+ competitor=track(coordinates(10.5,18.5),'c')
+ assert len(stitch([first,second,competitor],s,Associations(s)))==3
+ assert len(stitch([first,track(coordinates(30,38),'c')],s,Associations(s)))==2
+
+
+def test_time_aware_discontinuity_and_symmetric_directions():
+ s=DiscoverySettings()
+ for rising in [False,True]:
+ p=coordinates(0,40,rising=rising)
+ # Irregular observations on the same line retain elapsed-time motion.
+ p=np.delete(p,np.arange(5,len(p),6),axis=0)
+ metric,rejected=motion(p,s)
+ assert not rejected
+ assert metric['direction']==('rising' if rising else 'falling')
+ p=coordinates(0,40)
+ p[:,1]=200+2*np.abs(p[:,0]-20)
+ metric,rejected=motion(p,s)
+ assert not rejected and metric['direction']=='turning'
+ stationary=coordinates(0,40);stationary[:,1]=200
+ assert any(r['reason']=='unresolved_frequency_motion' for r in motion(stationary,s)[1])
+ switching=stationary.copy();switching[len(switching)//2:,1]=180
+ assert any(r['reason']=='insufficient_distributed_motion' for r in motion(switching,s)[1])
+
+
+def test_association_budget_and_rate_bounds_are_explicit():
+ s=replace(DiscoverySettings(),max_associations=1)
+ work=Associations(s);work.charge()
+ with pytest.raises(DiscoveryError,match='exceeded'):
+ work.charge()
+ assert required_sample_rate(DiscoverySettings(max_frequency_hz=6000))==16000
+ with pytest.raises(ValueError):
+ DiscoverySettings(max_frequency_hz=20000)
+ with pytest.raises(ValueError,match='two cycles'):
+ DiscoverySettings(min_frequency_hz=.1)
+
+
+def real_recording(tmp_path):
+ fixture=json.loads((Path(__file__).parent/'fixtures/real_discovery_normalization.json').read_text())
+ excerpt=fixture['excerpts'][0]
+ data=np.frombuffer(base64.b64decode(excerpt['pcm_f32le_base64']),dtype='<f4')
+ source=tmp_path/'real.wav'
+ sf.write(source,data,fixture['sample_rate_hz'],subtype='FLOAT')
+ return intake_recording(source,tmp_path/'intake')
+
+
+def test_real_short_recording_is_a_valid_zero_and_unsupported_coverage_fails(real_recording,tmp_path):
+ # A <window excerpt has no complete spectral observation; not a noise claim.
+ real_recording.metadata['duration_s']=.5
+ with real_recording.samples_path.open('r+b') as stream:
+ stream.truncate(round(.5*real_recording.metadata['sample_rate_hz'])*4)
+ assert discover_events(real_recording,output_dir=tmp_path/'zero',plot_summary=False)==[]
+ report=json.loads((tmp_path/'zero/discovery.json').read_text())
+ assert report['status']=='complete' and report['counts']['canonical_proposals']==0
+ with pytest.raises(DiscoveryError,match='coverage'):
+ discover_events(real_recording,settings=DiscoverySettings(max_frequency_hz=6000),output_dir=tmp_path/'unsupported')
+ assert json.loads((tmp_path/'unsupported/discovery.json').read_text())['status']=='failed'
+
+
+def test_real_spectrum_budget_is_checked_before_allocation(real_recording):
+ data=next(real_recording.iter_chunks())[1]
+ with pytest.raises(DiscoveryError,match='cells'):
+ _spectrum(data,real_recording.metadata['sample_rate_hz'],0,replace(DiscoverySettings(),max_spectral_cells=1))
+
+
+def test_corrupt_input_is_execution_failure(tmp_path):
+ source=tmp_path/'corrupt.mp3';source.write_bytes(b'not an audio stream')
+ with pytest.raises(AudioIntakeError) as exc:
+ intake_recording(source,tmp_path/'intake')
+ assert exc.value.code=='invalid_media'
+
+
+def test_measured_real_children_adapt_once_per_canonical_episode():
+ fixture=json.loads((Path(__file__).parent/'fixtures/real_episode_children.json').read_text())
+ from dopplergeist.contracts import validate_event
+ events=[validate_event(e) for e in fixture['events']]
+ prepared,measurements=prepare_events(events)
+ assert len(prepared)==len({e['harmonic_group_id'] for e in events})==1
+ assert len(measurements[0][1])==sum(len(e['ridge']) for e in events)
+ assert len(prepared[0]['event_ids'])==len(events)
+ # Canonical IDs and consumers are invariant to child enumeration.
+ other,_=prepare_events(events[::-1])
+ assert set(other[0]['event_ids'])==set(prepared[0]['event_ids'])
+
+
+def test_acoustic_only_brief_evidence_does_not_break_matching_adapter():
+ fixture=json.loads((Path(__file__).parent/'fixtures/real_episode_children.json').read_text())
+ events=fixture['events']
+ for event in events:
+ event['quality']['matching_eligible']=0.
+ assert prepare_events(events)==([],[])
+
+
+def test_repeated_reversals_are_not_a_single_supported_turn():
+ # Mathematical triangle path; no waveform or empirical signal claim.
+ p=coordinates(0,80)
+ p[:,1]=200+2*np.abs((p[:,0]%20)-10)
+ _,reasons=motion(p,DiscoverySettings())
+ assert any(r['reason'] in {'repeated_modulation','wandering_or_modulation'} for r in reasons)