Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Python acoustic-geolocationads-baircraft-trackingairplaneaudio-forensicsdoppler-effectdoppler-shiftgeolocationosintsignal-processing
from copy import deepcopy
import pytest
from pyproj import Geod
from dopplergeist.confidence import DecisionPolicy, decide_location
from dopplergeist.contracts import validate_result
def evidence():
events = [{"event_id": f"e{i}", "start_s": i * 100, "end_s": i * 100 + 20,
"band_hz": [90, 200], "harmonic_group_id": f"g{i}",
"ridge": [{"time_s": i * 100 + t, "frequency_hz": 140 - t} for t in [0, 10, 20]]}
for i in range(2)]
candidate = {"lat": 40., "lon": -100., "score": -1., "score_kind": "negative_robust_ridge_loss_hz",
"event_ids": ["e0", "e1"], "flight_ids": ["a", "b"],
"recording_start_utc": "2026-09-21T14:13:20Z",
"uncertainty": {"radius_m": 70., "kind": "sensitivity", "method": "fixture_full_perturbation"}}
coverage = {"search_complete": True, "data_status": "available", "limitations": ["Aircraft capture is incomplete."]}
diagnostic = {"clock_locked": True, "alternatives_evaluated": True, "refinement_boundary_limited": False,
"sensitivity": {"complete": True, "boundary_limited": False, "radius_m": 70.,
"sources": ["frequency", "clock", "altitude", "sound_speed"]}}
for event in events:
diagnostic[event["event_id"]] = {"rmse_hz": 0.7, "outlier_fraction": 0.1,
"support_fraction": 1.0, "drift_at_bound": False}
return events, [candidate], coverage, diagnostic
def decide(bundle):
events, candidates, coverage, diagnostic = bundle
return decide_location(events, candidates, coverage, matching_diagnostics=diagnostic)
def test_complete_fixture_passes_without_probability_and_preserves_inputs():
bundle = evidence()
before = deepcopy(bundle)
result = decide(bundle)
assert result["status"] == "succeeded"
assert result["diagnostics"]["policy_version"] == "engineering-v3"
assert result["diagnostics"]["probability"] is None
assert result["diagnostics"]["calibration"] == "uncalibrated"
assert bundle == before
wire = {"schema_version": 1, "job_id": "example", "events": bundle[0], "candidates": bundle[1],
"coverage": bundle[2], **{k: v for k, v in result.items() if k != "diagnostics"}}
assert validate_result(wire)["status"] == "succeeded"
@pytest.mark.parametrize("kind,reason", [
("noise", "no_doppler_events"), ("missing", "missing_flight_data"),
("partial", "partial_flight_coverage"), ("incomplete", "search_incomplete"),
("harmonics", "insufficient_independent_events"), ("clock", "timing_not_established"),
("residual", "inconsistent_event_match"), ("support", "insufficient_track_support"),
("drift", "source_drift_unresolved"), ("altitude_only", "uncertainty_not_established"),
("no_alternatives", "alternatives_not_assessed"), ("wide", "location_uncertainty_too_large"),
("boundary", "refinement_boundary_limited"), ("no_tracks", "no_matching_flights")])
def test_insufficient_evidence_abstains(kind, reason):
events, candidates, coverage, diag = evidence()
if kind == "noise": events, candidates = [], []
elif kind == "missing": coverage["data_status"] = "unavailable"
elif kind == "partial": coverage["data_status"] = "partial"
elif kind == "incomplete": coverage["search_complete"] = False
elif kind == "harmonics":
events[1]["harmonic_group_id"] = events[0]["harmonic_group_id"]
candidates[0]["flight_ids"] = ["a", "a"]
elif kind == "clock": diag["clock_locked"] = False
elif kind == "residual": diag["e0"]["rmse_hz"] = 8
elif kind == "support": diag["e0"]["support_fraction"] = 0.5
elif kind == "drift": diag["e0"]["drift_at_bound"] = True
elif kind == "altitude_only": diag["sensitivity"]["sources"] = ["altitude"]
elif kind == "no_alternatives": diag["alternatives_evaluated"] = False
elif kind == "wide": candidates[0]["uncertainty"]["radius_m"] = 1500
elif kind == "boundary": diag["sensitivity"]["boundary_limited"] = True
elif kind == "no_tracks": candidates = []
result = decide((events, candidates, coverage, diag))
assert result["status"] == "inconclusive"
assert result["reason_code"] == reason
def test_distant_tie_and_same_location_different_flights():
events, candidates, coverage, diag = evidence()
alternative = dict(candidates[0], lat=45., score=-1.2)
result = decide((events, candidates + [alternative], coverage, diag))
assert result["reason_code"] == "ambiguous_locations"
alternative.update(lat=40., flight_ids=["x", "y"])
assert decide((events, candidates + [alternative], coverage, diag))["reason_code"] == "ambiguous_flight_match"
@pytest.mark.parametrize("separation_m,score,status", [
(60., -1.2, "succeeded"),
(90., -1.2, "inconclusive"),
(150., -1.2, "inconclusive"),
(90., -5., "succeeded"),
])
def test_near_tied_locations_fit_the_returned_envelope(separation_m, score, status):
events, candidates, coverage, diag = evidence()
best = candidates[0] # The returned radius is 70 m around this point.
lon, lat, _ = Geod(ellps="WGS84").fwd(best["lon"], best["lat"], 90., separation_m)
alternative = dict(best, lon=lon, lat=lat, score=score)
result = decide((events, candidates + [alternative], coverage, diag))
assert result["status"] == status
if status == "inconclusive":
assert result["reason_code"] == "ambiguous_locations"
def test_malformed_results_fail_instead_of_masquerading_as_insufficient_evidence():
events, candidates, coverage, diag = evidence()
candidates[0]["score"] = float("nan")
result = decide((events, candidates, coverage, diag))
assert result["status"] == "failed"
assert result["reason_code"] == "invalid_evidence"
with pytest.raises(ValueError):
DecisionPolicy(min_independent_events=1)
def test_w3_vertical_only_profile_is_not_a_100m_confidence_claim():
events, candidates, coverage, diag = evidence()
diag["sensitivity"] = {"radius_m": 0.0, "kind": "sensitivity", "method": "profiled_relative_altitude_offsets",
"complete": True, "boundary_limited": False, "profiles": []}
assert decide((events, candidates, coverage, diag))["reason_code"] == "uncertainty_not_established"
def test_known_clock_single_event_requires_full_trusted_window_sensitivity():
from dopplergeist.contracts import utc_timestamp
events, candidates, coverage, diag = evidence()
events = events[:1]
candidates[0].update(event_ids=["e0"], flight_ids=["a"])
start = utc_timestamp(candidates[0]["recording_start_utc"]).timestamp()
assert decide((events, candidates, coverage, diag))["reason_code"] == "insufficient_independent_events"
diag["recording_start_window_s"] = [start-1, start+1]
diag["sensitivity"]["settings"] = {"clock_bounds_s": [start, start]}
assert decide((events, candidates, coverage, diag))["reason_code"] == "insufficient_independent_events"
diag["sensitivity"]["settings"]["clock_bounds_s"] = [start-1, start+1]
result = decide((events, candidates, coverage, diag))
assert result["status"] == "succeeded"
assert result["diagnostics"]["known_clock_single_event"] is True
diag["recording_start_window_s"] = [start+1, start+2]
assert decide((events, candidates, coverage, diag))["reason_code"] == "recording_clock_mismatch"
def test_incomplete_decision_reports_clock_window_fit_without_changing_reason():
from dopplergeist.contracts import utc_timestamp
events, candidates, coverage, diag = evidence()
coverage["search_complete"] = False
start = utc_timestamp(candidates[0]["recording_start_utc"]).timestamp()
baseline = decide_location(events, candidates, coverage, matching_diagnostics=diag)
before = deepcopy(candidates)
assert "recording_start_window_fit" not in baseline["diagnostics"]
diag["recording_start_window_s"] = [start - 20, start + 20]
result = decide_location(events, candidates, coverage, matching_diagnostics=diag)
assert baseline["status"] == result["status"] == "inconclusive"
assert baseline["reason_code"] == result["reason_code"] == "search_incomplete"
assert result["diagnostics"]["recording_start_window_fit"] == {
"window_width_s": 40.0,
"fit_offset_from_midpoint_s": 0.0,
"fit_distance_to_nearest_edge_s": 20.0,
}
assert candidates == before
@pytest.mark.parametrize("side,expected_offset", [("lower", -20.0), ("upper", 20.0)])
def test_clock_window_fit_reports_exact_edges(side, expected_offset):
from dopplergeist.contracts import utc_timestamp
events, candidates, coverage, diag = evidence()
coverage["search_complete"] = False
start = utc_timestamp(candidates[0]["recording_start_utc"]).timestamp()
diag["recording_start_window_s"] = (
[start, start + 40] if side == "lower" else [start - 40, start]
)
result = decide_location(events, candidates, coverage, matching_diagnostics=diag)
assert result["reason_code"] == "search_incomplete"
assert result["diagnostics"]["recording_start_window_fit"] == {
"window_width_s": 40.0,
"fit_offset_from_midpoint_s": expected_offset,
"fit_distance_to_nearest_edge_s": 0.0,
}
def test_explicit_subset_keeps_unconfirmed_proposals_without_forcing_matches():
events, candidates, coverage, diag = evidence()
extra = deepcopy(events[1])
extra.update(event_id="e2", harmonic_group_id="g2")
events.append(extra)
candidates[0].update(score_kind="matched_group_support_minus_normalized_residual", score=1.8)
assert decide((events, candidates, coverage, diag))["reason_code"] == "unexplained_events"
diag["unmatched_event_ids"] = ["e2"]
result = decide((events, candidates, coverage, diag))
assert result["status"] == "succeeded"
assert result["diagnostics"]["unmatched_event_ids"] == ["e2"]
diag["supported_event_ids"] = ["e0", "e1", "e2"]
assert decide((events, candidates, coverage, diag))["reason_code"] == "unmatched_supported_events"
diag["supported_event_ids"] = ["e0", "e1"]
alternative = dict(candidates[0], lat=45., event_ids=["e0", "e2"], flight_ids=["a", "c"], score=1.7)
assert decide((events, candidates+[alternative], coverage, diag))["reason_code"] == "ambiguous_locations"
alternative["score"] = 0.5
assert decide((events, candidates+[alternative], coverage, diag))["status"] == "succeeded"
extra["harmonic_group_id"] = "g0"
assert decide((events, candidates, coverage, diag))["reason_code"] == "incomplete_harmonic_group"
def test_all_four_independent_flyovers_are_checked():
events, candidates, coverage, diag = evidence()
for i in (2, 3):
event = deepcopy(events[0])
event.update(event_id=f"e{i}", harmonic_group_id=f"g{i}", start_s=i*100, end_s=i*100+20)
event["ridge"] = [dict(point, time_s=point["time_s"]+i*100) for point in event["ridge"]]
events.append(event)
candidates[0]["event_ids"].append(event["event_id"])
candidates[0]["flight_ids"].append(f"flight-{i}")
diag[event["event_id"]] = deepcopy(diag["e0"])
assert decide((events, candidates, coverage, diag))["status"] == "succeeded"
diag["e3"]["rmse_hz"] = 8
assert decide((events, candidates, coverage, diag))["reason_code"] == "inconsistent_event_match"
def finite_evidence():
events, candidates, coverage, diag = evidence()
candidates.append(dict(candidates[0], lat=45., score=-4.))
diag.update(alternatives_evaluated=False, assessed_mode_ids=["a", "b"], candidate_mode_ids=["a", "b"],
finite_search_evidence={"schema_version": 1, "scope": "evaluated_finite_grid", "complete": True,
"score_kind": candidates[0]["score_kind"], "spacing_m": 1000., "refine_spacing_m": 100.,
"max_event_groups": 2, "retained_modes": [{"mode_id": "a", "score": -1., "event_groups": 2},
{"mode_id": "b", "score": -4., "event_groups": 2}],
"discarded_count": 7, "best_discarded_score": -5., "pruning_accounted_for": True,
"limitations": ["Evaluated grids only; no continuous-space uniqueness."]})
return events, candidates, coverage, diag
def test_finite_search_can_pass_without_claiming_continuous_exhaustion():
bundle = finite_evidence()
result = decide(bundle)
assert result["status"] == "succeeded"
assert result["diagnostics"]["policy_version"] == "engineering-v5-finite-envelope"
assert result["diagnostics"]["finite_search"]["continuous_space_uniqueness"] == "not established"
bundle[3]["sensitivity"]["sources"] = ["altitude"]
assert decide(bundle)["reason_code"] == "uncertainty_not_established"
@pytest.mark.parametrize("kind,reason", [("discard", "retention_may_hide_alternatives"),
("complete", "finite_search_incomplete"), ("pruning", "finite_search_incomplete"),
("assessed", "finite_modes_not_assessed"), ("mapping", "finite_candidate_mapping_incomplete"),
("lost_score", "finite_candidate_scores_inconsistent")])
def test_finite_search_cannot_hide_omitted_or_near_tied_modes(kind, reason):
bundle = finite_evidence()
diag = bundle[3]
finite = diag["finite_search_evidence"]
diag["alternatives_evaluated"] = True # Optimistic legacy flag cannot override evidence.
if kind == "discard": finite["best_discarded_score"] = -1.2
elif kind == "complete": finite["complete"] = False
elif kind == "pruning": finite["pruning_accounted_for"] = False
elif kind == "assessed": diag["assessed_mode_ids"] = ["a"]
elif kind == "mapping": diag["candidate_mode_ids"] = ["a", "a"]
elif kind == "lost_score": finite["retained_modes"][1]["score"] = 0.
result = decide(bundle)
assert result["status"] == "inconclusive"
assert result["reason_code"] == reason
def test_finite_retention_bound_uses_declared_subset_units():
events, candidates, coverage, diag = finite_evidence()
kind = "matched_group_support_minus_normalized_residual"
candidates[0].update(score=1.8, score_kind=kind)
candidates[1].update(score=0.1, score_kind=kind)
finite = diag["finite_search_evidence"]
finite.update(score_kind=kind, best_discarded_score=1.5)
for mode, score in zip(finite["retained_modes"], (1.8, 0.1)): mode["score"] = score
assert decide((events, candidates, coverage, diag))["reason_code"] == "retention_may_hide_alternatives"
finite["best_discarded_score"] = 1.2
assert decide((events, candidates, coverage, diag))["status"] == "succeeded"
def test_malformed_finite_flags_fail_instead_of_looking_like_insufficient_data():
bundle = finite_evidence()
bundle[3]["finite_search_evidence"]["complete"] = 1
result = decide(bundle)
assert result["status"] == "failed"
assert result["reason_code"] == "invalid_evidence"
def near_finite_points(distance_m=90.):
from pyproj import Geod
bundle = finite_evidence()
best, alternative = bundle[1]
alternative["lon"], alternative["lat"], _ = Geod(ellps="WGS84").fwd(best["lon"], best["lat"], 90., distance_m)
alternative["score"] = -1.2
bundle[3]["finite_search_evidence"]["retained_modes"][1]["score"] = -1.2
return bundle
def test_finite_near_cluster_returns_a_copied_honest_envelope():
bundle = near_finite_points()
before = deepcopy(bundle)
result = decide(bundle)
assert result["status"] == "succeeded"
returned = result["candidates"]
assert 159.999 < returned[0]["uncertainty"]["radius_m"] < 160.001
assert returned[0]["uncertainty"]["kind"] == "sensitivity"
assert returned[0]["uncertainty"]["method"] == "finite_mode_and_tested_profile_union"
assert result["diagnostics"]["finite_envelope"]["included_mode_ids"] == ["a", "b"]
for original, candidate in zip(before[1], returned):
assert {k: v for k, v in original.items() if k != "uncertainty"} == {k: v for k, v in candidate.items() if k != "uncertainty"}
assert bundle == before
assert validate_result({"schema_version": 1, "job_id": "finite-envelope", "status": "succeeded",
"events": bundle[0], "coverage": bundle[2], "candidates": returned})["candidates"] == returned
def test_finite_union_keeps_distant_and_different_association_vetoes():
distant = near_finite_points(2000.)
assert decide(distant)["reason_code"] == "ambiguous_locations"
different = near_finite_points(30.)
different[1][1]["flight_ids"] = ["x", "y"]
assert decide(different)["reason_code"] == "ambiguous_flight_match"
narrow = near_finite_points()
result = decide_location(*narrow[:3], matching_diagnostics=narrow[3], policy=DecisionPolicy(target_radius_m=100.))
assert result["status"] == "inconclusive"
assert result["reason_code"] == "ambiguous_locations"
@pytest.mark.parametrize("kind,reason", [("incomplete", "uncertainty_not_established"),
("boundary", "refinement_boundary_limited"), ("missing_sources", "uncertainty_not_established"),
("missing_uncertainty", "uncertainty_not_established"), ("ledger", "finite_search_incomplete")])
def test_union_cannot_repair_missing_or_clipped_leading_evidence(kind, reason):
bundle = near_finite_points()
if kind == "incomplete": bundle[3]["sensitivity"]["complete"] = False
elif kind == "boundary": bundle[3]["sensitivity"]["boundary_limited"] = True
elif kind == "missing_sources": bundle[3]["sensitivity"]["sources"] = ["altitude"]
elif kind == "missing_uncertainty": bundle[1][0].pop("uncertainty")
elif kind == "ledger": bundle[3]["finite_search_evidence"]["complete"] = False
result = decide(bundle)
assert result["status"] == "inconclusive"
assert result["reason_code"] == reason