Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
Exclude unsupported tracks outside the bounded event clock (#297)
Cinna Davis0fcdcf6fdc25
diff --git a/docs/MODEL_SUPPORT_COVERAGE.md b/docs/MODEL_SUPPORT_COVERAGE.mdindex 01800e9..dccdd2a 100644--- a/docs/MODEL_SUPPORT_COVERAGE.md+++ b/docs/MODEL_SUPPORT_COVERAGE.md@@ -9,6 +9,20 @@ evaluated, rejected, or covered by a validated score bound. Unsupported CPAtrajectories, unreported clock trials, and unbounded alternatives keep the searchpartial. A completed tile does not establish complete evidence.+For robust-ridge subset association with a bounded recording-start window and no+silence filter, an unsupported trajectory that starts strictly after every+possible event CPA arrival cannot participate in an association. Those tracks+are reported separately as `clock_excluded_unsupported_tracks` in stage+diagnostics and counted in `clock_excluded_unsupported_track_evaluations`; their+original motion failures and conservative clock bounds remain inspectable. The+bound includes the configured clock sweep, CPA and association tolerances, and+outward floating-point rounding. Overlap, missing or invalid clock information,+fixed-clock mode, other scoring modes, and silence filtering retain the usual+unsupported/partial behavior. This does not repair the source trajectory or+establish geographic coverage. The HTTP evidence verifier checks the recorded+inequality against the search clock and stage totals; it does not independently+reload the original aircraft index to verify the recorded first emission time.+The additive `model_support` report contains these integer work counts:- `unsupported_cpa_track_evaluations`: trajectory/stage CPA failures, includingdiff --git a/scripts/verify_upload_http.py b/scripts/verify_upload_http.pyindex 8287a2e..0f7ad1f 100644--- a/scripts/verify_upload_http.py+++ b/scripts/verify_upload_http.py@@ -322,6 +322,48 @@ def model_assessment_accounted_for(search):and finite["bounded_unknown_envelopes"] == support["bounded_score_candidates"])+def valid_clock_exclusion(item, configuration):+ """Check a recorded time bound, without reloading the source trajectory."""+ from decimal import Decimal, localcontext++ def number(value):+ if type(value) not in (int, float) or not math.isfinite(value):+ raise ValueError("invalid bound number")+ return Decimal.from_float(float(value))++ try:+ scoring, filters = configuration["scoring"], configuration["filters"]+ window = scoring["recording_start_window_s"]+ if (not isinstance(item, dict) or not isinstance(item["track_id"], str) or not item["track_id"]+ or not isinstance(item["reason"], str) or not item["reason"]+ or not isinstance(item["reported_intervals"], dict)+ or item["reported_intervals"].get("reason") != item["reason"]+ or scoring.get("mode") != "robust_ridge" or scoring.get("time_origin") is not None+ or filters.get("association", "subsets") != "subsets" or filters.get("silence")+ or not isinstance(window, list) or len(window) != 2):+ return False+ with localcontext() as ctx:+ # Enough digits to add arbitrary finite binary64 inputs without+ # losing a very small operand next to a very large one.+ ctx.prec = 1100+ lo, hi = map(number, window)+ sweep, offset = number(scoring.get("time_sweep_s", 5.0)), number(filters.get("offset_tolerance_s", 5.0))+ c = number(scoring.get("c", 343.0))+ if lo > hi or sweep < 0 or offset < 0 or c <= 0:+ return False+ bounds = []+ for event in configuration["events"]:+ event_tolerance = number(event.get("quality", {}).get("cpa_tolerance_s", 0))+ if event_tolerance < 0:+ return False+ bounds.append(hi + sweep + offset / 2 + event_tolerance + number(event["cpa_receive_s"]))+ saved = number(item["latest_event_receive_s"])+ first = number(item["earliest_emission_s"])+ return bool(bounds and saved >= max(bounds) and first > saved)+ except (KeyError, TypeError, ValueError, OverflowError):+ return False++def inspect_finite_search(artifact, read, search, configuration, refinement):"""Audit recorded retention read-only; physical trials are not recomputed."""import sqlite3@@ -362,7 +404,7 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):totals, names, originals = {}, {}, {}evaluated = discarded = coarse_unknown = 0coarse_trials = dict(evaluated_trials=0, rejected_trials=0, unknown_trials=0, unreported_trial_envelopes=0)- bounded_count = bounded_rejections = 0+ bounded_count = bounded_rejections = clock_excluded = 0bound = unknown_bound = Nonebound_fields = ("bounded_unknown_envelopes", "bounded_unknown_rejections", "best_unknown_score_upper_bound")bound_contract = any(name in finite for name in bound_fields) or "model_assessment_complete" in search@@ -512,7 +554,7 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):coarse_unknown += unknownif bound_contract and phase in {"coarse", "fine"}:support_path = path.parent / "support" / (name.replace(":", "-") + ".json")- details, unsupported = [], []+ details, unsupported, excluded = [], [], []if support_path.exists():support_record = read("search/support/" + support_path.name)details, unsupported = (support_record.get(key) for key in@@ -520,6 +562,9 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):require(support_record.get("stage") == name and isinstance(details, list)and all(isinstance(detail, dict) for detail in details) and isinstance(unsupported, list),"Finite support artifact has invalid stage or candidate evidence")+ excluded = support_record.get("clock_excluded_unsupported_tracks", [])+ require(isinstance(excluded, list) and all(valid_clock_exclusion(item, configuration) for item in excluded),+ "Invalid unsupported-track clock exclusion evidence")certificates = {"bound-" + digest(detail): detail for detail in detailsif bounded_finite_clock_assessment(detail, finite["max_event_groups"])}require(stage_bounds == certificates, "Finite bound ledger omits or invents a recorded candidate assessment")@@ -527,11 +572,13 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):counts = payload.get("counts", {})require(counts.get("unclassified_candidate_assessments", []) == detailsand counts.get("unsupported_cpa_tracks", []) == unsupported+ and counts.get("clock_excluded_unsupported_tracks", []) == excludedand counts.get("unclassified_score_candidates", 0) == len(details)and counts.get("bounded_score_candidates", 0) == len(stage_bounds)and counts.get("unbounded_score_candidates", 0) == len(details)-len(stage_bounds),"Coarse support counts differ from persisted candidate assessments")support_totals["unsupported_cpa_track_evaluations"] += len(unsupported)+ clock_excluded += len(excluded)support_totals["unclassified_score_candidates"] += len(details)support_totals["bounded_score_candidates"] += len(stage_bounds)support_totals["unbounded_score_candidates"] += len(details)-len(stage_bounds)@@ -584,6 +631,8 @@ def inspect_finite_search(artifact, read, search, configuration, refinement):for key, value in support_totals.items()) and unknown == support_totals["unclassified_score_candidates"]and finite.get("unsupported_cpa_track_evaluations") == support_totals["unsupported_cpa_track_evaluations"],"Finite model-support totals differ from persisted candidate assessments")+ require(support.get("clock_excluded_unsupported_track_evaluations", 0) == clock_excluded,+ "Clock-excluded unsupported-track totals differ from stage evidence")require(all(type(support.get(key)) is int and support[key] >= valuefor key, value in coarse_trials.items()),"Search model-support totals omit recorded coarse clock trials")diff --git a/src/dopplergeist/tiled_search.py b/src/dopplergeist/tiled_search.pyindex 6441f5c..de3eb23 100644--- a/src/dopplergeist/tiled_search.py+++ b/src/dopplergeist/tiled_search.py@@ -356,6 +356,42 @@ def _association_clock_window(start_window, sweep_s):return center, tolerance+def _latest_event_receive_time(events, parameters, filters, start_window):+ """Conservatively bound matchable CPA arrivals for the shared-clock path.++ None means that this optional exclusion is not justified. Silence filters+ can use passages that match no event, so they cannot use this bound.+ """+ if (not start_window or parameters.get("mode") != "robust_ridge"+ or parameters.get("time_origin") is not None+ or filters.get("association", "subsets") != "subsets" or filters.get("silence")):+ return None+ try:+ c = float(parameters.get("c", 343.0))+ offset = float(filters.get("offset_tolerance_s", 5.0))+ if not math.isfinite(c) or c <= 0 or not math.isfinite(offset) or offset < 0:+ return None+ center, clock_tolerance = _association_clock_window(start_window, parameters.get("time_sweep_s", 5.0))+ upper = math.nextafter(center + clock_tolerance, math.inf)+ latest = []+ for event in events:+ cpa = float(event["cpa_receive_s"])+ event_tolerance = float(event.get("quality", {}).get("cpa_tolerance_s", 0))+ if not math.isfinite(cpa) or not math.isfinite(event_tolerance) or event_tolerance < 0:+ return None+ margin = math.nextafter(event_tolerance + offset / 2, math.inf)+ bound = math.nextafter(math.nextafter(upper + margin, math.inf) + cpa, math.inf)+ # Association calculates receive_time - cpa before comparing clock+ # intervals. Extra ULPs cover that inverse floating-point rounding.+ bound += 4 * max(math.ulp(bound), math.ulp(center), math.ulp(cpa))+ if not math.isfinite(bound):+ return None+ latest.append(bound)+ return max(latest) if latest else None+ except (KeyError, TypeError, ValueError, OverflowError):+ return None++def _tile_anchor_window(tile_id, start_window, parameters, filters, events):"""Recover a deterministic half-open anchor partition from its tile ID."""path = [part for part in tile_id.split("~")[1:] if part.startswith("t")]@@ -488,7 +524,8 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, stobservers = ecef(points.lat.to_numpy(), points.lon.to_numpy(), points.elev_m.to_numpy())point_ids = points.point_id.to_numpy(dtype=int)cpa_batches, count = [], 0- unsupported = []+ unsupported, clock_excluded = [], []+ latest_receive = _latest_event_receive_time(events, parameters, filters, start_window)# Bound materialized CPA rows before pairing; one track at a time keeps the# national traffic count out of the CPA tensor/list allocation.for track in tracks:@@ -514,6 +551,12 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, sttrack_batches.append(np.array(rows, dtype=_CPA_DTYPE))del rowsexcept AcousticSupportError as error:+ if latest_receive is not None and track.time[0] > latest_receive:+ clock_excluded.append({"track_id": track.id, "reason": error.reason,+ "reported_intervals": _support_error(error),+ "earliest_emission_s": float(track.time[0]),+ "latest_event_receive_s": latest_receive})+ continue# The typed failure does not identify an exact bad interval. Keep# the entire track/stage as explicitly unassessed, and retain rows# from other tracks. Never repair or clip the source payload here.@@ -531,7 +574,8 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, stif not cpa_batches:if ledger is not None:ledger.record(stage, [], [], 0)- return [], {"cpa_rows": 0, "candidates": 0, "unsupported_cpa_tracks": unsupported}+ return [], {"cpa_rows": 0, "candidates": 0, "unsupported_cpa_tracks": unsupported,+ "clock_excluded_unsupported_tracks": clock_excluded}if parameters.get("mode") == "robust_ridge":from .matching import _prepare_score_inputsevents, measurements = _prepare_score_inputs(events, measurements)@@ -724,11 +768,16 @@ def _score(points, tracks, events, measurements, budget, parameters, filters, stretention_score_pruned_candidates=retention_pruned,bounded_score_candidates=len(bounds), unbounded_score_candidates=unclassified-len(bounds),evaluated_rejections=rejected, unsupported_cpa_tracks=unsupported,+ clock_excluded_unsupported_tracks=clock_excluded,unclassified_candidate_assessments=unclassified_assessments, **trial_counts)def _record_support(output, stage, counts, summary):summary["unsupported_cpa_track_evaluations"] += len(counts.get("unsupported_cpa_tracks", []))+ clock_excluded = len(counts.get("clock_excluded_unsupported_tracks", []))+ if clock_excluded:+ summary["clock_excluded_unsupported_track_evaluations"] = (+ summary.get("clock_excluded_unsupported_track_evaluations", 0) + clock_excluded)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)@@ -743,10 +792,12 @@ def _record_support(output, stage, counts, summary):(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"):+ if (counts.get("unsupported_cpa_tracks") or counts.get("unclassified_candidate_assessments")+ or counts.get("clock_excluded_unsupported_tracks")):(output / "support").mkdir(exist_ok=True)write_json(output / "support" / (stage.replace(":", "-") + ".json"),{"stage": stage, "unsupported_cpa_tracks": counts.get("unsupported_cpa_tracks", []),+ "clock_excluded_unsupported_tracks": counts.get("clock_excluded_unsupported_tracks", []),"unclassified_candidate_assessments": counts.get("unclassified_candidate_assessments", [])},compact=True)diff --git a/tests/test_real_unsupported_clock.py b/tests/test_real_unsupported_clock.pynew file mode 100644index 0000000..63f8e8f--- /dev/null+++ b/tests/test_real_unsupported_clock.py@@ -0,0 +1,140 @@+"""Optional regression using an archived real audio/aircraft regional run."""+import importlib.util+import json+import os+from pathlib import Path++import pytest++from dopplergeist.data_access import CachedTerrain, FlightIndex+from dopplergeist.matching import prepare_events+from dopplergeist.tiled_search import (SearchBudget, _expanded_bounds, _latest_event_receive_time,+ _score, _tracks_for_points, tile_points)+++def test_real_clock_excludes_late_unsupported_trajectories(tmp_path, monkeypatch):+ value = os.environ.get("DOPPLERGEIST_REAL_CLOCK_JOB")+ index_path = os.environ.get("DOPPLERGEIST_REAL_CLOCK_INDEX")+ terrain_path = os.environ.get("DOPPLERGEIST_REAL_CLOCK_TERRAIN")+ if not all((value, index_path, terrain_path)):+ pytest.skip("set the archived real job, aircraft index and terrain cache paths")+ job = Path(value)+ config = json.loads((job / "search/manifest.json").read_text())["configuration"]+ raw = json.loads((job / "discovery/discovery.json").read_text())["events"]+ params = dict(config["scoring"])+ window = params.pop("recording_start_window_s")+ filters = config["filters"]+ radius = max(event["slant_range_m"][1] for event in config["events"])+ events, measurements = prepare_events(raw, c=params["c"], max_distance_m=radius)+ assert events == config["events"]+ budget = SearchBudget(**config["budget"])+ terrain = CachedTerrain(terrain_path, offline=True)+ index = FlightIndex(index_path)+ spec = importlib.util.spec_from_file_location("verify_upload_http",+ Path(__file__).parents[1] / "scripts/verify_upload_http.py")+ verifier = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(verifier)+ support_files = sorted((job / "search/support").glob("coarse-*.json"))+ tested = 0+ for support_path in support_files:+ support = json.loads(support_path.read_text())+ failures = support.get("unsupported_cpa_tracks", [])+ if not failures:+ continue+ tile_id = support_path.stem.removeprefix("coarse-")+ payload = json.loads((job / "search" / f"tile-{tile_id}.json").read_text())["payload"]+ points = tile_points(payload["cells"], budget.spacing_m, config["bounds"], terrain, config["crs"])+ tracks = list(index.lookup([item["track_id"] for item in failures]))+ assert tracks+ latest = _latest_event_receive_time(events, params, filters, window)+ assert latest is not None and all(track.time[0] > latest for track in tracks)+ rows, counts = _score(points, tracks, events, measurements, budget, params, filters, window)+ assert rows == [] and not counts["unsupported_cpa_tracks"]+ assert {item["track_id"] for item in counts["clock_excluded_unsupported_tracks"]} == {t.id for t in tracks}+ for item in counts["clock_excluded_unsupported_tracks"]:+ assert verifier.valid_clock_exclusion(item, config)+ assert not verifier.valid_clock_exclusion({**item, "earliest_emission_s": item["latest_event_receive_s"]}, config)+ assert not verifier.valid_clock_exclusion({**item, "latest_event_receive_s": item["latest_event_receive_s"] - 1}, config)+ assert not verifier.valid_clock_exclusion(item, {**config, "filters": {**filters, "silence": {"edge_margin_s": 60}}})+ # A clock that reaches the same unmodified flight must not suppress it.+ shift = float(tracks[0].time[0] - latest + 1.0)+ overlapping = [window[0] + shift, window[1] + shift]+ _, unknown = _score(points, tracks, events, measurements, budget, params, filters, overlapping)+ assert any(item["track_id"] == tracks[0].id for item in unknown["unsupported_cpa_tracks"])+ assert _latest_event_receive_time(events, params, {**filters, "silence": {"edge_margin_s": 60}}, window) is None+ assert _latest_event_receive_time(events, params, filters, None) is None+ if not tested:+ # Probe the actual track against clock windows on both sides of its+ # first recorded emission, including the inclusive boundary.+ boundary_shift = float(tracks[0].time[0] - latest)+ before = [value + boundary_shift - 0.01 for value in window]+ after = [value + boundary_shift + 0.01 for value in window]+ assert tracks[0].time[0] > _latest_event_receive_time(events, params, filters, before)+ assert tracks[0].time[0] <= _latest_event_receive_time(events, params, filters, after)+ _, before_counts = _score(points, tracks, events, measurements, budget, params, filters, before)+ _, after_counts = _score(points, tracks, events, measurements, budget, params, filters, after)+ assert any(item["track_id"] == tracks[0].id for item in before_counts["clock_excluded_unsupported_tracks"])+ assert any(item["track_id"] == tracks[0].id for item in after_counts["unsupported_cpa_tracks"])+ tested += len(tracks)+ assert tested == 12++ # Compare full-tile scoring on original tracks and measurements with the+ # old conservative exclusion; every actual retained candidate must agree.+ supported_stages = [json.loads(path.read_text()) for path in support_files]+ supported_stages = [value for value in supported_stages if value.get("unsupported_cpa_tracks")]+ def ranked_count(value):+ tile_name = value["stage"].removeprefix("coarse:")+ return len(json.loads((job / "search" / f"tile-{tile_name}.json").read_text())["payload"]["ranked"])+ support = max(supported_stages, key=ranked_count)+ assert ranked_count(support) > 0+ tile_id = support["stage"].removeprefix("coarse:")+ cells = json.loads((job / "search" / f"tile-{tile_id}.json").read_text())["payload"]["cells"]+ points = tile_points(cells, budget.spacing_m, config["bounds"], terrain, config["crs"])+ tracks, points = _tracks_for_points([index], _expanded_bounds(cells, budget.spacing_m, radius, config["crs"]),+ config["time_range_s"], budget, points, terrain, radius, params["c"])+ import dopplergeist.tiled_search as tiled+ with monkeypatch.context() as patch:+ patch.setattr(tiled, "_latest_event_receive_time", lambda *args: None)+ previous_rows, previous_counts = _score(points, tracks, events, measurements, budget, params, filters, window)+ rows, counts = _score(points, tracks, events, measurements, budget, params, filters, window)+ assert rows and counts["candidates"] > 0+ assert rows == previous_rows+ assert counts["cpa_rows"] == previous_counts["cpa_rows"]+ assert counts["candidates"] == previous_counts["candidates"]+ assert counts["unclassified_candidate_assessments"] == previous_counts["unclassified_candidate_assessments"]+ assert len(previous_counts["unsupported_cpa_tracks"]) == len(counts["clock_excluded_unsupported_tracks"]) > 0+ assert not counts["unsupported_cpa_tracks"]+++def test_real_clock_exclusion_evidence_rejects_tampering():+ value = os.environ.get("DOPPLERGEIST_REAL_CLOCK_REPLAY_JOB")+ if not value:+ pytest.skip("set the completed real clock-exclusion upload job path")+ job = Path(value)+ spec = importlib.util.spec_from_file_location("verify_upload_clock_evidence",+ Path(__file__).parents[1] / "scripts/verify_upload_http.py")+ verifier = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(verifier)++ def read(name):+ return json.loads((job / name).read_text())++ artifact = lambda name: job / name+ search = read("search/search-report.json")+ config = read("search/manifest.json")["configuration"]+ refinement = read("refined-candidates.json")+ assert search["model_support"]["clock_excluded_unsupported_track_evaluations"] > 0+ report = verifier.inspect_finite_search(artifact, read, search, config, refinement)+ assert report["complete"] is True+ def read_with_damaged_bound(name):+ data = read(name)+ if name.startswith("search/support/") and data.get("clock_excluded_unsupported_tracks"):+ item = data["clock_excluded_unsupported_tracks"][0]+ item["earliest_emission_s"] = item["latest_event_receive_s"]+ return data+ with pytest.raises(ValueError, match="Invalid unsupported-track clock exclusion evidence"):+ verifier.inspect_finite_search(artifact, read_with_damaged_bound, search, config, refinement)+ changed = {**search, "model_support": {**search["model_support"],+ "clock_excluded_unsupported_track_evaluations": search["model_support"]["clock_excluded_unsupported_track_evaluations"] + 1}}+ with pytest.raises(ValueError, match="Clock-excluded unsupported-track totals"):+ verifier.inspect_finite_search(artifact, read, changed, config, refinement)