Skip to content

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

Expose joint-fit evidence and reject unanalyzable frequency ranges

Cinna Davis5c3aa0ae3712
diff --git a/src/dopplergeist/discovery.py b/src/dopplergeist/discovery.py
index b4abc84..a7c422c 100644
--- a/src/dopplergeist/discovery.py
+++ b/src/dopplergeist/discovery.py
@@ -196,6 +196,8 @@ def _coverage(recording, settings):
if settings.max_frequency_hz > upper:
raise DiscoveryError("unsupported_frequency_coverage",
f"Requested {settings.max_frequency_hz:g} Hz exceeds usable decoded/source coverage {upper:g} Hz; decode at >= {required_sample_rate(settings)} Hz and check source rate")
+ if np.floor(settings.max_frequency_hz * settings.window_s) - np.ceil(settings.min_frequency_hz * settings.window_s) < 2:
+ raise DiscoveryError("unsupported_frequency_coverage", "Frequency range requires at least three spectral bins for a measured peak")
# Align frames and chunk boundaries to exactly representable sample hops.
if any(abs(value * sr - round(value * sr)) > 1e-7 for value in (settings.window_s, settings.hop_s)):
raise DiscoveryError("unsupported_time_grid", "Window and hop must be integer sample counts")
@@ -328,7 +330,7 @@ def _discover(recording, settings, report, detailed):
moving.append(ridge)
reconciled = reconcile(moving, settings, work)
events, accepted_groups, episodes = [], [], []
- for members, scales, orders in reconciled:
+ for members, scales, orders, group_model in reconciled:
metrics = [metrics_by_id[identifier("", r.points)] for r in members]
cells = intervals(np.concatenate([r.points[:, 0] for r in members]), settings.hop_s)
observed = sum(b - a for a, b in cells)
@@ -383,7 +385,7 @@ def _discover(recording, settings, report, detailed):
acceptance_path="sustained" if long else "brief_strong_evidence",
confidence="uncalibrated_supported" if long else "uncalibrated_brief_limited",
physical_source_multiplicity="unresolved", physical_motion_confirmed=False,
- model="constant frequency scales with pairwise supported common motion", integer_orders=orders,
+ model="constant frequency scales with pairwise supported common motion", group_evidence=group_model, integer_orders=orders,
limitations=["Common frequency evolution does not establish one physical source or aircraft identity"])
episodes.append(episode)
accepted_groups.append([r.points[:, :3] for r in members])
diff --git a/src/dopplergeist/episodes.py b/src/dopplergeist/episodes.py
index 7a80536..fa76b62 100644
--- a/src/dopplergeist/episodes.py
+++ b/src/dopplergeist/episodes.py
@@ -326,6 +326,7 @@ def reconcile(ridges, settings, work):
row[positions[y]], row[positions[x]] = 1., -1.
matrix.append(row[1:]); values.append(np.log(e["scale"]))
scales = np.exp(np.r_[0., np.linalg.lstsq(np.asarray(matrix),values,rcond=None)[0]])
+ checked_pairs, worst_residual = 0, 0.0
for ix,x in enumerate(indices):
for iy in range(ix+1,len(indices)):
y = indices[iy]
@@ -336,12 +337,17 @@ def reconcile(ridges, settings, work):
ratio = scales[iy]/scales[ix]
error = float(np.quantile(np.abs(shared[2]-ratio*shared[1]),.9))
sigma = uncertainty(ridges[y].points,settings)+ratio*uncertainty(ridges[x].points,settings)
+ checked_pairs += 1
+ worst_residual = max(worst_residual,error/(2*sigma))
if error > 2*sigma:
return None
- return scales.tolist()
+ return dict(scales=scales.tolist(), checked_overlap_pairs=checked_pairs,
+ worst_residual_fraction_of_limit=float(worst_residual),
+ min_resolved_motion_witnesses=min(sum(x==i or y==i for x,y,_ in internal) for i in indices))
groups = [{i} for i in range(len(ridges))]
owners = {i:g for g in groups for i in g}
- fitted = {frozenset(g):[1.] for g in groups}
+ fitted = {frozenset(g):dict(scales=[1.],checked_overlap_pairs=0,worst_residual_fraction_of_limit=None,
+ min_resolved_motion_witnesses=0) for g in groups}
ordered = sorted(edges.items(),key=lambda item:(item[1]["residual_q90_hz"]/item[1]["threshold_hz"],item[0]))
changed = True
while changed:
@@ -367,6 +373,7 @@ def reconcile(ridges, settings, work):
result = []
for group in groups:
indices = sorted(group)
- scales = fitted[frozenset(group)]
- result.append(([ridges[x] for x in indices],scales,family(scales)))
+ model = fitted[frozenset(group)]
+ scales = model["scales"]
+ result.append(([ridges[x] for x in indices],scales,family(scales),model))
return result
diff --git a/tests/test_episodes.py b/tests/test_episodes.py
index ba2fc55..aed15f5 100644
--- a/tests/test_episodes.py
+++ b/tests/test_episodes.py
@@ -46,8 +46,10 @@ def test_deterministic_complete_link_grouping_and_noninteger_scales():
for permutation in itertools.permutations(paths):
groups=reconcile(permutation,s,Associations(s))
assert len(groups)==1
- members,scales,orders=groups[0]
+ members,scales,orders,model=groups[0]
assert orders is None
+ assert model["checked_overlap_pairs"]==3
+ assert model["worst_residual_fraction_of_limit"]<=1
assert scales==pytest.approx([1,2,3.14159])
identities.append([identifier('',r.points) for r in members])
assert all(x==identities[0] for x in identities)
@@ -209,3 +211,21 @@ def test_repeated_reversals_are_not_a_single_supported_turn():
p[:,1]=200+2*np.abs((p[:,0]%20)-10)
_,reasons=motion(p,DiscoverySettings())
assert any(r['reason'] in {'repeated_modulation','wandering_or_modulation'} for r in reasons)
+
+
+def test_narrow_unanalyzable_band_is_an_explicit_failure(real_recording,tmp_path):
+ settings=DiscoverySettings(min_frequency_hz=100,max_frequency_hz=100.5)
+ with pytest.raises(DiscoveryError,match='three spectral bins'):
+ discover_events(real_recording,settings=settings,output_dir=tmp_path/'narrow')
+
+
+def test_unexpected_execution_error_cannot_leave_a_complete_negative(real_recording,tmp_path,monkeypatch):
+ from dopplergeist import discovery
+ def failure(*args):
+ raise RuntimeError('controlled execution failure')
+ monkeypatch.setattr(discovery,'_paths',failure)
+ with pytest.raises(RuntimeError):
+ discover_events(real_recording,output_dir=tmp_path/'error')
+ report=json.loads((tmp_path/'error/discovery.json').read_text())
+ assert report['status']=='failed'
+ assert report['failure']['code']=='discovery_execution_error'