API

AssaySentinel

Know when the measurement changed before the science does.

AssaySentinel.jl is a high-performance analytical quality and drift-detection framework for repeated quantitative measurements. It monitors the measurement process itself — instruments, reagent lots, calibrations, batches, and controls — rather than diagnosing patients.

Safety boundary

This software is intended for research, analytical-quality assessment, method development, and scientific decision support. It is not a diagnostic medical device and must not independently determine patient diagnosis or treatment.

Example

using AssaySentinel
using Dates

stream = AssayStream(analyte = :glucose, unit = "mg/dL", instrument = "Analyzer-A")
push!(stream, Measurement(value = 101.2, timestamp = now(), batch = "B104", lot = "R22", control = true))
report = analyze(stream)
explain(report)

AbstractDetector

Generic detector API for research extensions.

fit!(detector, baseline)
update!(detector, measurement)
result(detector)

AbstractEvent

Alert

Analytical alert. Severity is one of :info, :watch, :warning, :critical. These are analytical-process severities, not clinical interpretations.

Assay

AssayPanel

Simultaneous monitoring of many analytes.

AssaySentinelError

Base error type for AssaySentinel.

AssayStream{T}

Ordered stream of measurements for one analyte / measurement system.

AttributionResult

Temporal association between a detected change and nearby operational events. Never claims causation from association alone.

Baseline

Reference window against which incoming measurements are compared.

Batch

BatchEffectResult

Calibration

CalibrationCurve

ChangePointResult

ComparisonResult

ControlSample

ControlSeries

DistributionComparison

DriftEvent

DriftResult

Event

Generic operational event on the measurement system.

EventTimeline

Experiment

HierarchicalSiteResult

Study-level random-effects summary. Attribution is statistical (global vs site-specific vs mixed), not causal.

IncrementalCUSUM

Page CUSUM with Welford moments. O(1) update.

IncrementalEWMA

Roberts (1959) EWMA with incremental variance.

Instrument

InsufficientDataError

Raised when a method cannot be applied because too few valid observations remain after missing/NaN handling.

Measurement{T}

A single quantitative observation with provenance metadata.

Keyword lot is accepted as an alias for reagent_lot. Missing values and NaN must be represented explicitly; they are never coerced to zero.

Method

OutlierResult

PanelReport

Frozen multi-analyte product: per-analyte QualityReports plus a panel reconstruction. Schema version is stored for reload compatibility.

.panel is an alias of .name so older analyze(panel) NamedTuple accessors keep working.

PartitionResult

ProvenanceRecord

QCRule

QCRuleResult

QCSpec

QualityReport

ReagentLot

Reconstruction

A defensible reconstruction of how the measurement system behaved: ordered story beats, uncertainty, lot/instrument evidence, SVG charts, and a provenance graph. Produced by analyze / reconstruct.

ReferenceInterval

Sentinel

Streaming monitor over a baseline. Incremental detectors, alert callbacks, persistence, and cooldown are first-class.

SentinelScore

Composite analytical-stability score on 0–100. This is not a patient-risk score. Components are always retained and never hidden.

Site

SiteEffect

Empirical-Bayes site location after hierarchical shrinkage.

StoryBeat

One dated chapter in an analytical reconstruction.

Study

Hierarchical monitoring container: Study → Site → Instrument.

StudyReport

Frozen study-level product: per-site QualityReports plus the hierarchical combine. Schema version is stored for reload compatibility.

StudySentinel

Streaming monitor for several sites. A study-level alert fires when enough sites alarm inside the concordance window (default: 2 sites within 7 days). Concordance alerts themselves respect concordance_cooldown so a persistent shared signal is not re-emitted on every subsequent observation.

UncertaintyBudget

How measurement uncertainty and analytical scatter combine. This is analytical-process uncertainty, not a clinical interval.

UnitMismatchError

Raised when two quantities are compared or combined without an explicit unit conversion. mg/dL is never treated as equivalent to mmol/L.

analyze(panel::AssayPanel; parallel=false, rng)

Analyze each analyte stream independently and return a PanelReport with a panel reconstruction (status chart, story, provenance). Per-analyte RNGs are independent. Units are never pooled. .panel remains an alias of .name for older NamedTuple-style access.

analyze(stream::AssayStream; rng, outlier_policy=:annotate, parallel=false)

Combine change-point, drift, QC, distribution, outlier, and attribution evidence into a QualityReport.

analyze(study, streams; rng)

Analyze each site stream and combine them with hierarchical_sites. streams maps site name → AssayStream. The study reconstruction (forest plot, sharing narrative, uncertainty budget) is attached to the StudyReport.

annotate_outliers(x; kwargs...)

Alias of detect_outliers. Removal is never performed here.

assess_partitions(data; group, value)

Harris–Boyd style statistical partitioning evidence (Harris & Boyd 1990). Does not recommend clinical partitions.

calibrate(concentrations, responses; model=:linear, weights=nothing)

Fit a calibration curve.

Models: :linear, :weighted_linear, :polynomial, :robust, :spline, :fourpl.

calibration_diagnostics(curve)

Residual, runs, relative-error, and (when replicates exist) lack-of-fit diagnostics for a fitted calibration. Does not claim clinical impact.

check_units(a, b)

Throw UnitMismatchError unless a and b denote the same unit after alias normalization. Empty units are treated as unspecified and allowed.

compare_calibrations(curve1, curve2)

Report slope/intercept/nonlinearity/residual change. Does not claim a clinical impact.

compare_distribution(baseline, current; method=:auto)

compare_lots(data, lotcol; value=:value)

Estimate whether a lot transition corresponds to location, variance, or distributional change.

compare_methods(a, b; method=:ba)

Compare paired measurements from two methods.

Methods:

• :ba — Bland–Altman (Bland & Altman 1986)
• :deming — Deming regression (errors-in-variables)
• :passing_bablok — Passing & Bablok (1983)
• :ols — ordinary least squares
• :robust — Theil–Sen

compare_sites(data; site, value)

convert_unit(value, from, to; molar_mass=nothing, factor=nothing)

Explicit conversion only. Common clinical-chemistry conversions require molar_mass (g/mol) when moving between mass and molar concentration.

This function never guesses an analyte.

correct_batch_effects(X, batch; method=:combat, design=nothing)

Multi-feature ComBat. X is observations × features. Empirical-Bayes priors for each batch are estimated across features (Johnson et al. 2007).

correct_batch_effects(dataset; method=:median, batch, value, biological_group=nothing)

Optional correction. Always returns a new table-like vector of named tuples and never mutates the original. The transformation is intended to be stored in provenance by the caller.

Methods:

• :median — location centering to the grand mean
• :quantile — batch-wise quantile matching to the pooled empirical distribution
• :ruv — control-anchored unwanted-variation removal (RUV-lite)
• :combat — parametric empirical-Bayes location/scale adjustment (Johnson, Li & Rabinovic 2007). Batch location γ and scale δ² are shrunk toward hyperparameters estimated from the batch-level moments. When biological_group is set, that design is protected (not removed).

detect_batch_effects(dataset; batch, value, biological_group=nothing)

Distinguish likely technical variation from variation associated with an experimental grouping. Does not correct data.

detect_changes(data; method=:auto, timestamps=nothing, has_controls=false, rng)

Detect change points in a univariate series.

Methods:

• :cusum — Page (1954) two-sided CUSUM plus CUSUM-path localization
• :likelihood — Gaussian mean-change likelihood ratio / SIC scan
• :pelt — PELT for piecewise mean (Killick, Fearnhead & Eckley 2012)
• :robust_median — CUSUM on robustly standardized observations
• :rolling — rolling two-sample Welch tests
• :bayesian — Fearnhead (2006) product-partition posterior (multiple changes)
• :turing — MCMC via the Turing.jl extension (model=:single|:multiple|:hierarchical, ncuts for piecewise means, sampler=:mh|:nuts)
• :kernel — energy-distance scan (Székely & Rizzo)
• :auto — choose from sample size, tail weight, missingness, cadence

detect_drift(X::AbstractMatrix; method=:mahalanobis, timestamps=nothing)

X is observations × features. Methods:

• :mahalanobis — Hotelling-style distance from baseline mean/covariance
• :pca — Hotelling T² on leading principal components
• :covariance — Frobenius shift of correlation matrices
• :energy — multivariate energy distance between halves

detect_drift(data; kind=:auto, timestamps=nothing, baseline=nothing, rng)

Detect analytical drift of a specified kind.

Kinds: :linear, :nonlinear, :sudden, :cyclic, :variance, :distribution, :calibration, :auto.

detect_outliers(x; method=:mad, k=3.5)

Detect outliers without removing them.

Methods:

• :mad — robust z-score using normalized MAD (Rousseeuw & Croux 1993)
• :iqr — Tukey fences at Q1 − k IQR, Q3 + k IQR (Tukey 1977); default k=1.5
• :zscore — classical |z| > k
• :robust_z — alias of :mad

evaluate_detector(kind; nrep=20, n=800, rng)

Compare detection delay, false-positive rate, and sensitivity on simulated streams. Useful as a research-platform harness for new detectors.

explain(result)

Human-readable reconstruction of why a conclusion was reached. Leads with the dated analytical story, then the uncertainty budget, then the evidence that assigned status. Distinguishes observed facts, statistical results, algorithmic inference, and user annotations.

forest_chart(result::HierarchicalSiteResult)

Makie forest plot of site means with a prediction-interval overlay. Requires the optional Makie.jl extension. The SVG counterpart svg_forest_chart is always available in core.

hierarchical_sites(data; site, value=:value, timestamps=:timestamp, method=:eb)

Random-effects site model (DerSimonian–Laird / empirical Bayes):

1. Per-site mean, SD, and standard error
2. Between-site τ² and within-site σ²
3. Shrink site means toward the grand mean
4. Higgins I² and a 95% prediction interval for a new site mean
5. Per-site and pooled drift
6. Cochran Q on site drift magnitudes → :global, :site_specific, :mixed, or :stable

method=:turing uses the Turing extension (hierarchical site intercepts + shared change). The default :eb path is stdlib-only.

Attribution is a statistical description of sharing, not a cause.

instrument_chart(data; instrument, value)

Makie instrument comparison chart. Requires the optional Makie.jl extension.

levey_jennings(...)

Makie control chart. Requires the optional Makie.jl extension.

levey_jennings_data(values, spec) / control_chart_data

Structured series for Levey–Jennings charts (Levey & Jennings 1950). Plotting is provided by the optional Makie extension.

lot_chart(data; lot, value)

Makie lot comparison chart. Requires the optional Makie.jl extension.

monitor(control, measurements; rules=westgard_rules())

Evaluate control material against target ± SD and the configured rule set.

online_series(stats...)

Build an OnlineStats.jl Series for streaming assay values. Requires using OnlineStats.

reconstruct(hierarchy, site_reports; rng_seed, name)

Study-level reconstruction: sharing narrative, between/within uncertainty, forest plot, and provenance. Called by analyze(study, streams).

reconstruct(stream, report_pieces; rng_seed)

Build the ordered analytical story, uncertainty budget, charts, and provenance graph from an already-run analysis. Called by analyze.

reconstruct(stream; rng)

Analyze a stream and return only the Reconstruction.

reconstruct(reports; rng_seed, name)

Panel-level reconstruction: per-analyte status narrative, score chart, and provenance. Called by analyze(panel). Units are never pooled.

reference_curve(covariate, values; quantiles=(0.025, 0.50, 0.975), span=0.3, method=:quantile)

Continuous reference curves. :quantile uses locally weighted empirical quantiles. :lms uses Cole LMS (global λ, local μ and σ) and back-transforms the requested probabilities. Not a clinical reference system.

reference_interval(values; method=:nonparametric, rng, α=0.05, unit="")

Methods:

• :nonparametric — 2.5th–97.5th percentiles (CLSI EP28-style)
• :parametric — mean ± 1.96 SD
• :robust — median ± 1.96 × normalized MAD
• :transformed — log-scale parametric, back-transformed
• :boxcox — Box–Cox profile-likelihood transform, then parametric limits
• :horn — Tukey fences then nonparametric limits on the remaining sample
• :lms — Cole LMS (λ, μ, σ) 2.5th–97.5th quantiles

report(result, path)

Write a professional analytical report. Alias of save for path targets.

result(r::PanelReport)

Snapshot of per-analyte status and scores. Analytical process, not clinical risk.

result(study::StudySentinel)

Snapshot of per-site sentinels and any study-level concordance alerts.

showcase_dataset(; rng)

12 months of synthetic measurements: 3 reagent lots, 2 instruments, one calibration event, gradual drift, variance shift, and control failures.

simulate_assay(; n, drift=:none, rng, ...)

Generate a synthetic measurement stream.

Drift kinds: :none, :linear, :step, :variance, :lot, :batch, :periodic, :failure, :outliers.

svg_forest_chart(result::HierarchicalSiteResult; title)

Forest plot of per-site means with 95% CIs (raw SE), shrunk means as filled markers, a diamond at the grand mean, and dashed prediction-interval guides.

svg_panel_chart(reports; title)

Horizontal Sentinel Score bars for each analyte in a PanelReport. Scores describe analytical-process stability, not patient risk.

Westgard-style multirule logic (Westgard, Barry, Hunt & Groth 1981) expressed as independent composable rules.

@qcrule name begin
    ...
end

Custom rule body sees values::Vector{Float64} and spec::QCSpec and must return a QCRuleResult.