Skip to content

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

Screen fixed-clock event pairs before association expansion

Cinna Davis0156d83bbf6e
diff --git a/src/dopplergeist/matching.py b/src/dopplergeist/matching.py
index 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=No
Exceeding it fails visibly so the outer driver reports incomplete coverage.
An optional half-open anchor window selects the first matched passage's
implied 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_event
max_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=No
anchor_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 work
work += units
@@ -181,9 +186,20 @@ def association_candidates(table, events, offset_tolerance_s=5.0, time_origin=No
table = 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=No
return 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.py
index 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, st
if 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.py
new file mode 100644
index 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