Metrology

Metrology

Analysis metrics derived from a run's ground-truth event logs. The first metric is the alert-latency curve: for a transient caught in a live batch, how long after the event the whole look-back window of δ before it is on the ground — under the realized live-FIFO / archive-LIFO doctrine and under a counterfactual first-in, first-out drain that re-assigns the same service completions in content order. The second is the measurement-to-ground delay of every batch against a delivery requirement (the Definition Study Report's 24 hours). The third is derived from the delivered payload rather than the logs: a Welch estimate of its spectrum against the analytic model the synthesis drew it from. See alert_latency_table, plot_alert_latency, delivery_delay_table, plot_delivery_delay, and plot_payload_spectrum.

BatchDelivery

One batch in the delivery schedule: identity, content interval, generation (finalization) instant, realized ground availability (nothing when the batch never reached the ground), and the counterfactual FIFO availability (nothing when the FIFO drain never reaches it within the mission).

delivery_schedule(run_dir::String) -> Vector{BatchDelivery}

Per-batch delivery bookkeeping from events_tx.csv, events_rx.csv, and the batch metadata, sorted by content epoch. The realized availability is the first ingested record of the batch. The counterfactual FIFO availability re-assigns the realized service completions (the sorted ingested instants) to the batches in content order: each completion goes to the oldest batch that had been generated by then and is still undelivered under FIFO — the same link, the same slots, the opposite discipline, and no live priority. Batches without a recorded content epoch (pre-content_epoch metadata) take generation − batch span.

batch_containing(schedule, t::DateTime) -> Union{Nothing,BatchDelivery}

The batch whose content interval [content_epoch, content_end) contains t, or nothing (before the first batch, inside a generation gap, or after the last).

completion_curves(schedule, alert_idx, t_m, steps, span, first_epoch) -> (real, fifo)

Window-completeness latencies of one alert — the batch schedule[alert_idx] with event instant t_m — on the look-back grid δ = 0, span, …, steps·span: for each δ, the instant (hours after t_m) at which every batch overlapping [t_m − δ, t_m) plus the alert batch itself has reached the ground, under the realized deliveries (real) and the counterfactual FIFO drain (fifo). Entries are nothing once the window contains a batch that never arrived under that doctrine (each curve independently); the vectors stop where the window would reach before first_epoch, and are empty when the alert batch reached the ground under neither doctrine.

marker_latency_table(run_dir::String; lookback_hours = 72.0) -> DataFrame

Window-completeness latency of every event marker of the run (markers.csv): Label, Marker (the instant), Batch (the batch whose content span holds it; empty when none does), Lookback_Hours, and LIFO_Hours / FIFO_Hours — completion_curves evaluated with the marker instant as t_m, so the latency counts from the event itself. Missing values mark an undelivered alert batch or a window containing a batch that never arrived; one row with Lookback_Hours = 0 and missing latencies records a marker outside every batch. Empty when the run has no markers.

alert_latency_table(run_dir::String; lookback_hours = 72.0) -> DataFrame

Window-completeness latency curves over the look-back grid δ = 0, D, 2D, … (D = the batch content span) up to lookback_hours. Every live batch that reached the ground defines an alert whose event instant t_m is the batch's content end (the moment the transient's samples exist). The look-back window [t_m − δ, t_m), together with the alert batch itself, is complete on the ground once every batch overlapping it has arrived; the latency is that completion instant minus t_m — for the realized doctrine and for the counterfactual FIFO drain (delivery_schedule) — so δ ≤ D gives the delivery delay of the live batch itself and the curve is non-decreasing in δ. Alerts whose window reaches before the first recorded batch, and alerts whose window contains a batch that never arrived under either discipline, are excluded at that δ; N_Alerts counts the contributing alerts. Columns: Lookback_Hours, N_Alerts, and the median and 25 % / 75 % quantiles of the latency in hours for LIFO (realized) and FIFO.

plot_alert_latency(run_dir::String; lookback_hours = 72.0, processing_latency_hours = 1.0, style, plots_dir, formats, suffix, write_tables = true) -> Union{Nothing,String}

Writes <run_dir>/alert_latency.csv (alert_latency_table) and, when the run has markers, alert_latency_markers.csv (marker_latency_table); renders <run_dir>/plots/alert_latency.png (with a vector PDF twin): the median window-completeness latency with the interquartile band (thin full-hue edges on both quartiles) against the look-back, realized doctrine solid in the archive color, counterfactual FIFO drain dotted in PlotTheme.COLOR_COUNTERFACTUAL, one PlotTheme.COLOR_MARKER curve per event marker, the medians at the largest tabulated look-back annotated together with the ground processing budget processing_latency_hours. Returns the PNG path, or nothing when the run holds no delivered live batch.

QUARTILE_BAND_ALPHA

Fill alpha of the interquartile bands of the alert-latency figure, shared by the realized and the counterfactual series and by their legend patches.

ANNOTATION_BLOCK_TOP

Relative height of the delivery-delay figure's corner annotation: four lines of text rising this far up the axis from the bottom. The requirement rule stops here and its label starts here, so neither crosses the block.

ANNOTATION_BLOCK_LEFT

Relative abscissa the delivery-delay figure's corner annotation reaches left to. A requirement rule beyond it would pass behind the block (ANNOTATION_BLOCK_TOP).

delivery_delay_table(run_dir::String) -> DataFrame

Measurement-to-ground delay of every generated batch: Batch, Live, ContentEnd, AvailableAt (missing when the batch never reached the ground), Delay_Hours = availability minus content end (missing when undelivered), and LowLatency — whether the batch reached the ground inside a low-latency period of the run's contact model. Built on delivery_schedule; rows sorted by content epoch.

delivery_compliance(table::DataFrame, requirement_hours::Float64) -> NamedTuple

Summary of a delivery_delay_table against a delivery requirement: generated, delivered, within (delivered within requirement_hours of measurement), via_low_latency (delivered inside a low-latency period), fraction_within (of all generated batches — an undelivered batch is non-compliant), median_hours, and p95_hours of the delivered delays (NaN when nothing was delivered).

plot_delivery_delay(run_dir::String; requirement_hours = 24.0, style, plots_dir, formats, suffix, write_tables = true) -> Union{Nothing,String}

Writes <run_dir>/delivery_delay.csv (delivery_delay_table) and renders <run_dir>/plots/delivery_delay.png (vector PDF twin): the empirical distribution of the measurement-to-ground delay — the fraction of generated batches on the ground within a given delay, live and archive batches as separate curves plus the all-batches aggregate when both families exist — with the requirement marked and the compliance summary annotated. The legend lists exactly the curves drawn and is omitted when only one is. Returns the PNG path, or nothing when the run generated no batch.

payload_series(run_dir::String; max_batches = 40) -> Vector{Float64}

The delivered payload of a run as one continuous strain series: the longest stretch of consecutively numbered batches under ground/, in generation order, capped at max_batches. Consecutive identifiers matter — the LIFO backfill delivers the archive out of order, and splicing across a gap would put a discontinuity into a spectral estimate. Empty when nothing was delivered or the payloads were pruned by the retention custodian.

plot_payload_spectrum(run_dir::String; style, plots_dir, formats, suffix, max_batches = 40) -> Union{Nothing,String}

Renders <run_dir>/plots/payload_spectrum.png (vector twin): a Welch estimate (VirtualInstrument.welch_psd) of the delivered payload against the analytic model it was drawn from — the instrument term and the full S(f) of Robson, Cornish & Liu (2019). Returns the PNG path, or nothing for an external payload (there is no model to compare against) or when too little payload reached the ground.

The figure is a validation, not a measurement: nothing is fitted, and the estimate reproduces the model at the correct absolute level over the band the synthesis block resolves. Below the first resolved bin — 1/(2· segment_duration_sec) — the stream carries no power, so the estimate falls away from the model there; a segment length above about 2000 s is what makes the galactic-confusion foreground observable at all.

quantile_sorted(values::AbstractVector{<:Real}, p::Real) -> Float64

Quantile p ∈ [0, 1] of an ascending-sorted vector with linear interpolation between order statistics (the default definition of Statistics.quantile). NaN for an empty vector.