Stats and Learnings

📊 Statistics & Learnings

The service records every near-miss, transit and prediction into a local SQLite history DB (data/history.db). From v0.41.0 you can turn that into a founded, all-time statistical report — in absolute and percentage terms — either in the browser or on the command line. The report also derives recommended default settings from your own data.

How to generate it

In the browser (no SSH): click 📊 Stats in the header. The report is generated on demand, shown as text, and downloadable as TXT / CSV / JSON.

On the Pi (CLI):

npm run analyze                 # text report
node scripts/analyze-history.js --csv > transit-stats.csv
node scripts/analyze-history.js --json > transit-stats.json

Both paths call the same core (src/stats.js) — the API endpoints are /api/stats/report, /api/stats/report.csv, /api/stats/report.txt.

What it answers

	Question	Key metric
a	How many aircraft come by regularly	visits ≥2 / ≥5 / ≥10, returned-on-another-day
b	What % of transits were serious candidates	projected and time-confirmed sep <0.1/0.2/0.3/0.5/1/2°
c	How often a capture would (theoretically) have triggered	imminent-stage episodes/day + actual arms/day
d	Typical computational drift of a candidate	sep |final−best| and closest-approach time shift
e	Aircraft per day	distinct ICAO in the corridor/day
f	Typical altitude / distance / elevation of a real candidate	medians + p10–p90
g	When the sep prediction is most exact	error at ≥90 s / 30–60 s / <15 s lead
h	Sun vs Moon, best hour, lead time, grazes, top routes/flights	—
i	Directional corridor (v0.42.0)	which compass axis (N-S/E-W/…) produces your transits — antenna-aiming insight
j	Capture yield (v0.42.0)	of the captures actually fired, what % hit a genuine on-disc transit

Apply & self-tune (v0.42.0)

The report's recommended defaults are interactive in the 📊 Stats modal: tick the ones you want and Apply selected — it writes them straight to the live SharpCap config (no Settings round-trip). The measure → recommend → apply loop, in two clicks.

For hands-off operation there are two opt-in self-tuning toggles in Settings → Scopes (default off):

• Self-tune drift window (sharpcap.adaptiveDrift) — every ~6 h, re-derives maxDriftS from your measured closest-approach time error (p95).
• Self-tune elevation floor (sharpcap.adaptiveElevation) — every ~6 h, lowers minElevationDeg to a site-specific floor that keeps ~90 % of your confirmed candidates (it only ever lowers it, never raises).

Both are strictly opt-in, clamped, and logged — a hand-set value is only ever changed while its toggle is on.

Example learnings (a real 37-day dataset, Rheine / NW-Germany)

A busy site directly under the NW-European corridor (10 093 distinct aircraft in 37 days). Your numbers will differ — the point is how to read them.

Traffic is dense, not the bottleneck. ~275 new aircraft/day, 79 % return at least once (median 4 visits; one regular logged 149). At a site like this, selection matters more than opportunity.

The honest "serious candidate" rate is small. Of all 10 093 aircraft ever seen, 9.1 % (917) came within 0.5° of the Sun or Moon. The funnel against the ≥30°-overhead subset reads much higher (45.9 %) but is apples-to-oranges — most real transits happen below 30° (see elevation, below), so that denominator doesn't match the numerator. Use the "of all seen" figure.

Projected ≠ confirmed — the single most important column. 1 132 episodes projected a separation <0.3°, but only 124 were time-confirmed that tight — a ~9× drop. That gap is the separation drift in action. Confirmed on-disc (<0.27°) transits: 119 in 37 days ≈ 3.2/day — the real photographable rate. Tightest confirmed: 0.009° (a 33-arcsec bullseye).

How rare is a really tight pass? Of all 10 093 detected aircraft, only 0.83 % (84) actually came confirmed within 0.2° — about 1 in 120, or ~2.3/day. The projection is far more optimistic: 688 episodes projected <0.2° (6.8 % of all detected), but only 84 (≈ 12 % of them) held that tight when timed. The denominator matters — the same 84 is 4.1 % of transit episodes, or 14.3 % of confirmed transits. Quote the one that fits the question.

Time is predicted superbly; separation drifts. Closest-approach time error: median 1.5 s (p95 26.4 s). Separation drift |final − best|: median 0.31° — large against a 0.5° disc. Don't trust an early "0.05°!" projection; expect it ~0.3° wider by transit time. This one fact drives most of the recommended defaults below.

Predictions sharpen toward the event, then plateau. Sep error ≥90 s = 0.20° → 30–60 s = 0.13° → <15 s = 0.13°. Past ~60 s out it's about as good as it gets; high-elevation cruise traffic is measurably steadier (0.17°) than low, maneuvering traffic (0.21°).

The typical real candidate is a cruising jet, fairly low in the sky. ~36 000 ft, ~27 km slant range, median elevation only 24° (p10 7°). 42 % of confirmed candidates were below 20°. Low elevation = worse seeing/haze, but also more opportunities — pick your floor by preference, not dogma.

Directional corridor (v0.42.0). Headings fold to a strongly E–W axis (50 %), then NW–SE (26 %) — the Amsterdam-Schiphol stream (the top routes are almost all …→AMS). N–S is only 4 %. So this site is an E–W corridor site; the ADS-B antenna most needs a clear E/W horizon. Other sites will differ — the report learns yours.

Rhythm. Sun vs Moon ≈ 56/44. Busiest local hour ~10:00. Slight mid-week bump (Wed busiest, Fri quietest). First-warning lead time: median ~8 min.

Recommended defaults the report derives from your data

The report ends with concrete suggestions (current → suggested + the rationale). The shipped v0.41.0 defaults were re-tuned on the data above:

Setting	Old	New (v0.41.0)	Why
sharpcap.preBufferS	10 s	5 s	Closest-approach time error is tiny (~1.5 s) — a long lead just wastes frames.
sharpcap.postBufferS	10 s	15 s	A late aircraft is the common miss; bias the window to the tail.
sharpcap.leadDriftFrac	0.5	0.25	0.5 doubled the clip for early arms; re-arming already corrects a moved prediction.
sharpcap.maxDriftS	45 s	30 s	Just above the measured time p95 (~27 s) — covers 95 %, the rest via re-arm.
sharpcap.minElevationDeg	20°	recommended per site	Many confirmed candidates sit below 20°; the report suggests a site-specific floor (e.g. 15°) so you re-include the 10–20° passes you like, best on clear days.

The elevation floor stays a recommendation, not a forced global default — it's site-specific. A south-facing site under an E-W corridor sees a very different elevation distribution than a site under an N-S corridor, so the report learns your floor from your confirmed candidates rather than imposing one number on everyone.

How an "episode" and the outcomes are defined

• Episode = one aircraft flyby, grouped across its radio → candidate → imminent stages (so a single transit isn't counted three times). ISS is excluded from episode stats.
• Projected separation = tightest value the tracker ever projected; confirmed = tightest value at the time-confirmed imminent stage.
• Capture arm (v0.41.0): every time the SharpCap trigger actually fired is logged to capture_arms, so arms/day and the re-arm rate are real history, not just the session counter in the header.

See also: ⚙️ Advanced → SharpCap capture trigger · 📚 Reference → Configuration.