Python tool for aircraft Doppler audio geolocation using historical ADS-B flight data (Source-available)
Physical matching
The current target is up to 1,000 m point error acceptable, with 100–500 m or better preferred. Benchmark point error and model sensitivity are different quantities. A boundary-truncated 500 m profile is not relabelled a valid 1 km envelope; it needs a larger declared search budget or remains limited.
matching.prepare_events(detected_events) adapts the shared detected-event
records into the existing (events, measurements) search arguments. It uses
subsonic speed and a declared maximum audible distance rather than excluding
tracks using a straight-pass speed/slant estimate. It does not filter aircraft
type. The 20 km default is an explicit search envelope, not guaranteed acoustic
coverage. The outer search must use these same bounds when acquiring tracks and
constructing corridors. Increasing a filter tolerance after corridor generation
cannot restore already excluded data.
Compatible integer harmonic ridges in a harmonic_group_id contribute to one
pass and one event clock. Each ridge has equal aggregate weight. Ratios must be
consistent with an integer multiple of the lowest observed ridge. Unsupported
groups fail explicitly; discovery should split them rather than invent a
fundamental or treat them as independent flyovers. event_ids on the prepared
internal record maps the merged evidence back to original contract events.
search.rank_candidates(..., mode="robust_ridge") fits the actual trajectory at
emission time. One recording start is swept for every event together. A bounded
linear source-frequency change can absorb modest engine drift, with a weak
zero-drift penalty; it cannot fit an arbitrary curve or a separate event clock.
The pseudo-Huber residual reduces the influence of tracing outliers. Every
positive-weight measured sample requires trajectory support. Results include
per-event RMSE, outlier fraction, drift parameters/boundary flags and support.
The score is negative penalized robust residual in Hz, summed over independent
event groups. Higher is better; values and gaps are not probabilities, nor are
they interchangeable with the legacy brightness/RMSE score scales.
Numeric quality settings used by matching are frequency_loss_scale_hz (default
1 Hz), source_drift_fraction (default 0.02 over the event, maximum 0.1),
cpa_tolerance_s, speed_tolerance_mps and slant_tolerance_m (default zero).
prepare_events sets CPA tolerance to span the detected window. These are
measurement/proposal settings, not post-hoc parameters selected using truth.
It consumes discovery's frequency_uncertainty_hz as a loss scale with a 1 Hz
floor when no explicit scale is supplied and preserves the diagnostic key;
this is not a calibrated noise model. frequency_sigma_hz remains a legacy
alias for explicitly supplied loss scales, without claiming statistical sigma.
Pairing intersects the permitted recording-start intervals of all events,
including any absolute-time constraint, so pairwise compatibility cannot
manufacture a joint clock. Legacy scoring modes are preserved for replay.
matching.refine_candidate(candidate, track_lookup, events, measurements, terrain) refines position and a shared recording clock in a bounded local
search. It repeats the fit over declared relative-height scenarios (default
-150/0/+150 m) and returns sensitivity profiles and boundary flags. This
tests vertical-datum/altitude degeneracy; it is neither a calibrated confidence
interval nor a complete spatial ambiguity assessment. The nominal result's
score remains evaluated at the actual terrain height. Missing profiles and
boundary optima must be considered by confidence handling. Competing flight
associations and distant spatial modes still need the outer search.
Pass recording_start_window_s=(lo, hi) from the trusted request to constrain
all nominal and sensitivity clocks. A point window fixes the clock exactly and
optimizes position only. The local clock radius is intersected with the window;
disjoint bounds fail explicitly. refinement_clock_bounds_s records the bounds
actually used. Spatial and nonzero-width clock boundary flags are separate.
Verification:
PYTHONPATH=src .venv/bin/python -m pytest -q
PYTHONPATH=src .venv/bin/python scripts/benchmark_matching.py \
--source-root /path/to/restored/data/source --output results/new-matching-run
The benchmark replays both original regional cases in the original scoring mode and robust mode. It refuses to overwrite its output directory, hashes inputs and implementation, and reads evaluation coordinates only after every search has finished. Those source-informed windows, bands, region and the faint event's derived clock remain development limitations. Both failures and successes must be reported. Automatic full-recording discovery and independent real/national acceptance are integration gates, not established by these replays.
Unmatched proposals
matching.association_candidates(table, events, ..., min_events=1, max_events=None, max_candidates=20000) proposes subsets instead of requiring every acoustic
proposal to be an aircraft. It examines subsets up to the declared event count
and defaults to all independent groups. Shared-clock intervals prune impossible
extensions before complete assignments are built. Index entries, branch visits
and stored assignments share a work/storage budget; candidate limits remain
explicit. An optional smaller event cap is reported as event_cap_limited, and
the outer driver must treat that cap as incomplete coverage. The hook fails
explicitly when candidate/work budgets are exceeded. The outer driver
must mark that search incomplete. All original proposals remain in the event
artifact. Each hypothesis carries ordered event_indices, and
score_candidate/refine_candidate consume the complete event/measurement lists
and select the corresponding subset internally. Scored rows expose matched and
unmatched event IDs; repeated approaches retain their separate emission times.
Partial associations use a separate score kind,
matched_group_support_minus_normalized_residual. A matched group contributes
1 - robust_loss/(3*frequency_loss_scale_hz) and must have loss below that threshold.
This rewards multiple consistent independent events without promoting a perfect
single-event fit over a good joint fit. It is an explicit ranking heuristic,
not a likelihood, probability or calibrated false-match test. Different score
kinds must not be mixed in a ranking. Confidence must still consider competing
locations, matched group count, omitted proposals, source coverage and residual
diagnostics. Single-event candidates remain available for a defensible known
clock, and do not by themselves establish a supported location.
Full sensitivity scenarios
matching.profile_candidate(candidate, track_lookup, all_events, all_measurements, terrain, recording_start_window_s=...) reruns the leading
association under declared perturbations. It returns the nominal refined
candidate with a sensitivity artifact containing every scenario, failed
scenario, boundary flag, tested source and maximum displacement from nominal.
It checks each matched ridge with positive/negative frequency offsets and
linear tilts at the declared loss scale, a constant-source alternative, allowed
clock endpoints, relative-height offsets (default 150 m), and sound-speed
offsets (default 5 m/s). Every scenario uses one shared clock and stays inside
the request window. An exact clock remains fixed. Defaults are declared
engineering ranges, not estimated meteorology, a survey, or statistical coverage.
complete requires finite support for every scenario and successful local
optimization. boundary_limited remains separate. A missing/failed scenario
cannot silently shrink the envelope; confidence must abstain when evidence is
incomplete or exceeds its declared precision. This finite envelope does not
cover every possible model error, and distant competing modes still require
the outer search. The bounded source-frequency solve uses the exact optimum
of its two-variable convex box problem; regression tests compare it against
SciPy's independent constrained solver, including boundary optima.
Altitude scenarios include both common observer-height shifts and independent positive/negative biases for every matched flight segment. A constant geodetic height bias adjusts the trajectory derivatives by the derivative of that height displacement, preserving the original measured motion and never mutating the source track. The receipt records each flight's altitude basis and bias. Unknown, barometric, unspecified or mixed non-geometric bases keep sensitivity incomplete; a generic height envelope cannot establish a common datum. The trusted terrain and flight heights must already share a defensible ellipsoidal datum. Geometric interpolation remains labelled and subject to the declared perturbation range. Terrain must expose an applied geoid conversion or an explicit ellipsoidal-datum declaration; an unlabelled constant/raster surface keeps the envelope incomplete.
predict_fitted_ridge(track, observer_ecef, absolute_receive_times_s, event_diagnostics) evaluates the frozen fitted model, including source drift at
emission time. Diagnostics retain source_reference_emission_time_s and
source_span_s; a drifting fit without its reference fails explicitly.
Unsupported times remain NaN. The legacy replay plotter uses this helper for
the scored curve. Older historical PNGs that drew only f0 * factor remain
unchanged and are approximations when their associated fit includes drift.