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. Your numbers will differ — the point is how to read them.

Traffic is dense, not the bottleneck. ~275 new aircraft/day, 10 000 in 37 days, 79 % return at least once (one regular logged 148 visits ≈ 4×/day). At a site like this, selection matters more than opportunity.

The honest "serious candidate" rate is small. Of all aircraft ever seen, ~9 % came within 0.5° of the Sun or Moon. The funnel against the ≥30°-overhead subset reads much higher (~46 %) 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. Projected closest separations look tight — half of recorded episodes project <0.3°. But only a fraction are time-confirmed that tight, because the projection drifts (next point). The report shows both columns side by side; the confirmed one is reality.

Time is predicted superbly; separation drifts. Closest-approach time error: median ~1.5 s (p95 ~27 s). Separation drift |final − best|: median ~0.32° — large against a 0.5° disc. Don't trust an early "0.05°!" projection; expect it ~0.3° wider by transit time. This single 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 than low, maneuvering traffic.

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°). Low elevation = worse seeing/haze; the sharpest images come from the high-elevation tail. Filter by elevation, not only by separation.

Genuine disc transits are ~3/day (confirmed on-disc <0.27°), with ~16 imminent-stage arms/day. Sun vs Moon ≈ 56/44. Best local hour here: ~10:00. 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.