Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Implement bounded time-aware acoustic episode discovery (#349)
Cinna Davis609b86a36fbd
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.ymlindex 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 experimentsrun: python -m compileall -q src scripts- name: Check benchmark instrumentation detectiondiff --git a/scripts/benchmark_real_discovery_plots.py b/scripts/benchmark_real_discovery_plots.pyindex 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.pyindex e8e6d85..c3eab4b 100644--- a/scripts/discover_audio.py+++ b/scripts/discover_audio.py@@ -11,7 +11,7 @@ from pathlib import Pathimport subprocessimport time-from dopplergeist.discovery import DiscoverySettings, discover_events+from dopplergeist.discovery import DiscoverySettings, discover_events, required_sample_ratefrom dopplergeist.intake import intake_recordingfrom 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.pynew file mode 100644index 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.pyindex 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: Ntry:from .intake import AudioIntakeError, intake_recording- from .discovery import DiscoverySettings, discover_events+ from .discovery import DiscoveryError, DiscoverySettings, discover_events, required_sample_rateexcept 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: Nif 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.metadataprogress("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.metadatastate["events"] = events@@ -142,6 +145,8 @@ def analyze(request, output_dir, config=None, progress=lambda *args, **kwargs: Nreturn 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.pyindex 7fb352b..b4abc84 100644--- a/src/dopplergeist/discovery.py+++ b/src/dopplergeist/discovery.py@@ -7,12 +7,19 @@ from dataclasses import asdict, dataclassimport jsonfrom pathlib import Pathfrom statistics import median+import hashlib+from importlib.metadata import version+import subprocess+import time+from collections import Counterimport numpy as np-from scipy import ndimage, optimize, signal+from scipy import optimize, signalfrom .audio import Spectrumfrom .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.0max_fragment_gap_s: float = 20.0max_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 = 32def __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 <= 1costs = 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 + activedef _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_supportdef _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 Noneif 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 matplotlibmatplotlib.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.pynew file mode 100644index 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 resultdiff --git a/src/dopplergeist/intake.py b/src/dopplergeist/intake.pyindex 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=400channels = 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 = Nonetry:@@ -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.pyindex 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 fundamentalneeds to be present. Groups with inconsistent ratios must be fixed by discovery.Separate paths that reuse measured peaks remain separate hypotheses, withan 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):+ continuereference = 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.jsonnew file mode 100644index 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.pynew file mode 100644index 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)