Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Screen fixed-clock event pairs before association expansion
Cinna Davis0156d83bbf6e
diff --git a/src/dopplergeist/matching.py b/src/dopplergeist/matching.pyindex 7c27a95..e9c5ab9 100644--- a/src/dopplergeist/matching.py+++ b/src/dopplergeist/matching.py@@ -153,7 +153,8 @@ def predict_fitted_ridge(track, observer, receive_times_s, diagnostics, c=343.0)def association_candidates(table, events, offset_tolerance_s=5.0, time_origin=None,time_tolerance_s=5.0, silence=None, min_events=1,- max_events=None, max_candidates=20000, anchor_window=None):+ max_events=None, max_candidates=20000, anchor_window=None,+ pair_screen=None):"""Bounded subset hypotheses, retaining explicitly unmatched proposals.Default to every independent group. Intersect shared-clock intervals before@@ -162,6 +163,9 @@ def association_candidates(table, events, offset_tolerance_s=5.0, time_origin=NoExceeding it fails visibly so the outer driver reports incomplete coverage.An optional half-open anchor window selects the first matched passage'simplied recording start without clipping the shared-clock fit interval.+ ``pair_screen`` may remove an event/flight/receiver row only when its caller+ supplies supported rejection evidence for the fixed shared recording clock;+ its bounded report is returned with the candidate counts."""from .search import filter_association_eventmax_events = max(min_events, len(events)) if max_events is None else max_events@@ -172,6 +176,7 @@ def association_candidates(table, events, offset_tolerance_s=5.0, time_origin=Noanchor_window[0] >= anchor_window[1]):raise ValueError("Anchor window must be an increasing half-open interval")candidates, examined, work = [], 0, 0+ pair_screen_reports = []def reserve(units):nonlocal workwork += units@@ -181,9 +186,20 @@ def association_candidates(table, events, offset_tolerance_s=5.0, time_origin=Notable = table.reset_index(drop=True)records = table.to_dict("records")grouped, survivors = [], []- for event in events:+ for event_index, event in enumerate(events):frame = filter_association_event(table, event, offset_tolerance_s, time_origin, time_tolerance_s)reserve(len(frame))+ before_screen = len(frame)+ if pair_screen is not None and len(frame):+ frame, report = pair_screen(event_index, event, frame)+ if (not hasattr(frame, "index") or len(frame) > before_screen+ or not frame.index.isin(table.index).all()):+ raise ValueError("Pair screen must return rows from the supplied CPA table")+ if not isinstance(report, dict):+ raise ValueError("Pair screen must return an evidence dictionary")+ pair_screen_reports.append({"event_index": event_index, "before": before_screen,+ "after": len(frame), **report})+ reserve(before_screen - len(frame))survivors.append(len(frame))groups = {}tolerance = event.get("quality", {}).get("cpa_tolerance_s", 0) + offset_tolerance_s/2@@ -279,7 +295,8 @@ def association_candidates(table, events, offset_tolerance_s=5.0, time_origin=Noreturn candidates, {"per_event_survivors": survivors, "survivors": len(candidates),"hypotheses_examined": examined, "work_units": work, "max_matched_events": max_events,"event_cap_limited": max_events < len(events),- "unmatched_proposals_allowed": True}+ "unmatched_proposals_allowed": True,+ "event_pair_screen": pair_screen_reports}def association_score(result, events):diff --git a/src/dopplergeist/tiled_search.py b/src/dopplergeist/tiled_search.pyindex 18fdb7a..d7a2854 100644--- a/src/dopplergeist/tiled_search.py+++ b/src/dopplergeist/tiled_search.py@@ -257,9 +257,74 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, stif start_window is not None and kwargs["time_origin"] is None:kwargs["time_origin"], kwargs["time_tolerance_s"] = _association_clock_window(start_window, parameters.get("time_sweep_s", 5.0))+ pair_screen = None+ fixed_clock = (parameters.get("mode") == "robust_ridge" and parameters.get("time_origin") is not None+ and parameters.get("time_sweep_s", 5.0) == 0)+ if fixed_clock:+ from .matching import _frequency_scale, association_score, score_ridges+ from .search import _ridge_trial_classification+ screen_budget = budget.max_candidates_per_tile+ screen_counts = {"checked": 0, "rejected": 0, "unknown": 0,+ "budget_exhausted": False, "rejections": []}++ def pair_screen(event_index, event, frame):+ keep = np.ones(len(frame), dtype=bool)+ initial_checked = screen_counts["checked"]+ initial_rejected = screen_counts["rejected"]+ initial_unknown = screen_counts["unknown"]+ rejection_start = len(screen_counts["rejections"])+ exhausted_before = screen_counts["budget_exhausted"]+ for (point_id, flight_id), indices in frame.groupby(["point_id", "flight_id"], sort=False).groups.items():+ if screen_counts["checked"] >= screen_budget:+ screen_counts["budget_exhausted"] = True+ break+ screen_counts["checked"] += 1+ point = lookup.get(point_id)+ track = track_lookup.get(flight_id)+ if point is None or track is None:+ screen_counts["unknown"] += 1+ continue+ try:+ result = score_ridges([track], [event], [measurements[event_index]],+ ecef(point.lat, point.lon, point.elev_m), kwargs["time_origin"],+ parameters.get("c", 343.0))+ result = association_score(result, [event])+ classification, reason = _ridge_trial_classification(result, [event], True)+ except AcousticSupportError:+ classification, reason, result = "unknown", "unsupported_acoustic_model", {}+ if classification == "rejected":+ positions = frame.index.get_indexer_for(indices)+ keep[positions] = False+ screen_counts["rejected"] += 1+ diagnostics = result.get("event_diagnostics", [{}])+ score = result.get("event_scores", [None])[0]+ limit = 3 * _frequency_scale(event)+ screen_counts["rejections"].append({+ "event_index": event_index, "event_id": event.get("event_id", str(event_index)),+ "point_id": int(point_id), "flight_id": str(flight_id),+ "recording_start_time_s": float(kwargs["time_origin"]),+ "event_score_hz": float(score), "residual_limit_hz": float(limit),+ "support_fraction": diagnostics[0].get("support_fraction"), "reason": reason})+ elif classification == "unknown":+ screen_counts["unknown"] += 1+ return frame.loc[keep], {+ "checked": screen_counts["checked"] - initial_checked,+ "rejected": screen_counts["rejected"] - initial_rejected,+ "unknown": screen_counts["unknown"] - initial_unknown,+ "budget_exhausted": screen_counts["budget_exhausted"] and not exhausted_before,+ "rejections": list(screen_counts["rejections"][rejection_start:]),+ }++ # CPA rows are created below, so resolve receiver/track identities+ # after all rows are available but before association enumeration.+ lookup = {row.point_id: row for row in points.itertuples()}+ track_lookup = {track.id: track for track in tracks}candidates, counts = association_candidates(table, events, **kwargs,min_events=filters.get("min_events", 1), max_events=filters.get("max_events") or len(events),- max_candidates=budget.max_candidates_per_tile)+ max_candidates=budget.max_candidates_per_tile, pair_screen=pair_screen)+ if pair_screen is not None:+ counts["fixed_clock_event_pair_screen"] = {"recording_start_time_s": float(kwargs["time_origin"]),+ **screen_counts, "rejections": list(screen_counts["rejections"])}else:# Count the same inclusive clock-boundary passages as pair_candidates.per_event = [filter_association_event(table, e, kwargs["offset_tolerance_s"],@@ -371,6 +436,17 @@ def _record_support(output, stage, counts, summary):for key in ("unclassified_score_candidates", "bounded_score_candidates", "unbounded_score_candidates","evaluated_trials", "rejected_trials", "unknown_trials", "unreported_trial_envelopes"):summary[key] += counts.get(key, 0)+ pair_screen = counts.get("fixed_clock_event_pair_screen")+ if pair_screen:+ for key in ("checked", "rejected", "unknown"):+ summary[f"fixed_clock_event_pairs_{key}"] = (+ summary.get(f"fixed_clock_event_pairs_{key}", 0) + pair_screen[key])+ summary["fixed_clock_event_pair_screen_budget_exhausted"] = (+ summary.get("fixed_clock_event_pair_screen_budget_exhausted", False)+ or pair_screen["budget_exhausted"])+ (output / "support").mkdir(exist_ok=True)+ write_json(output / "support" / (stage.replace(":", "-") + "-event-pair-screen.json"),+ {"stage": stage, **pair_screen})if counts.get("unsupported_cpa_tracks") or counts.get("unclassified_candidate_assessments"):(output / "support").mkdir(exist_ok=True)write_json(output / "support" / (stage.replace(":", "-") + ".json"),diff --git a/tests/test_real_fixed_clock_pair_screen.py b/tests/test_real_fixed_clock_pair_screen.pynew file mode 100644index 0000000..d9203df--- /dev/null+++ b/tests/test_real_fixed_clock_pair_screen.py@@ -0,0 +1,66 @@+"""Fixed-clock event-pair screening check against the uploaded real recording."""+import json+import os+from pathlib import Path++import pandas as pd+import pytest++from dopplergeist import matching, tiled_search+from dopplergeist.finite_search import RetentionLedger+from dopplergeist.matching import prepare_events+from dopplergeist.tracks import load_tracks+++def test_real_fixed_clock_screen_preserves_retained_modes(monkeypatch, tmp_path):+ root = os.environ.get("DOPPLERGEIST_REAL_REFERENCE_ROOT")+ discovery_path = os.environ.get("DOPPLERGEIST_REAL_REFERENCE_DISCOVERY")+ if not root or not discovery_path:+ pytest.skip("set the real reference root and uploaded-audio discovery paths")+ root, discovery_path = Path(root), Path(discovery_path)+ reference = json.loads((root / "results/reference-local/ranked.json").read_text())[0]+ clock = reference["recording_start_time_s"]+ detected = json.loads(discovery_path.read_text())["events"]+ events, measurements = prepare_events(detected)+ tracks, _ = load_tracks(root / "data/adsb/2026-09-08/reference-region.parquet",+ time_range=(clock - 120, clock + 3720))+ points = pd.DataFrame([{key: reference[key] for key in+ ("point_id", "lat", "lon", "elev_m", "x", "y")}])+ parameters = {"mode": "robust_ridge", "time_origin": clock, "time_sweep_s": 0}+ filters = {"association": "subsets", "offset_tolerance_s": 5, "time_tolerance_s": 5}+ original = matching.association_candidates++ def run(name, disable_screen):+ if disable_screen:+ def unfiltered(*args, **kwargs):+ kwargs.pop("pair_screen", None)+ return original(*args, **kwargs)+ monkeypatch.setattr(matching, "association_candidates", unfiltered)+ else:+ monkeypatch.setattr(matching, "association_candidates", original)+ ledger = RetentionLedger(tmp_path / f"{name}.sqlite", "real-fixed-clock-pair-screen",+ "matched_group_support_minus_normalized_residual")+ return tiled_search._score(points, tracks, events, measurements, tiled_search.SearchBudget(),+ parameters, filters, ledger=ledger, stage="coarse:real-fixed-clock")++ baseline, baseline_counts = run("baseline", True)+ screened, counts = run("screened", False)+ evidence = counts["fixed_clock_event_pair_screen"]+ assert baseline == screened+ assert baseline_counts["candidates"] == 575+ assert counts["candidates"] == 95+ assert evidence["checked"] == 10 and evidence["rejected"] == 3+ assert not evidence["unknown"] and not evidence["budget_exhausted"]+ assert all(row["support_fraction"] == 1.0 and row["reason"] == "association_residual_limit"+ and -row["event_score_hz"] > row["residual_limit_hz"]+ for row in evidence["rejections"])+ support = tmp_path / "support-output"+ support.mkdir()+ summary = {key: 0 for key in ("unsupported_cpa_track_evaluations", "unclassified_score_candidates",+ "bounded_score_candidates", "unbounded_score_candidates", "evaluated_trials",+ "rejected_trials", "unknown_trials", "unreported_trial_envelopes")}+ tiled_search._record_support(support, "coarse:real-fixed-clock", counts, summary)+ receipt = support / "support/coarse-real-fixed-clock-event-pair-screen.json"+ persisted = json.loads(receipt.read_text())+ assert persisted["rejections"] == evidence["rejections"]+ assert summary["fixed_clock_event_pairs_rejected"] == 3