API reference

TransmissionLinelist.analyse Method

analyse(
;
    data,
    output,
    figures,
    samples,
    chains,
    seed,
    progress,
    plots,
    backend
) -> Tuple{Any, NamedTuple{(:μ_inc, :σ_inc, :μ_δ, :σ_δ, :k, :log_R_chain, :mean_gi_si, :sd_gi_si, :p_pre), <:Tuple{Any, Any, Any, Any, Any, Any, Any, Any, Dict{Float64, Vector{Float64}}}}}

Load the line list, fit the joint model, save the posterior summary to output/posterior.csv, and (unless plots = false) write all figures into figures/. Returns (chain, post).

Keyword Arguments

• data: path to the line-list CSV.

• output: directory for posterior.csv.

• figures: directory for the figure PNGs.

• samples: NUTS samples per chain.

• chains: number of parallel chains.

• seed: random seed.

• progress: show a NUTS progress bar.

• plots: skip all figure generation when false.

• backend: Makie backend module to activate before saving figures (default CairoMakie). Pass e.g. GLMakie to override; the caller is responsible for having loaded the module.

source

TransmissionLinelist.bin_edges_day Method

bin_edges_day(t0) -> Vector{Float64}

Return the weekly R(t) knot dates expressed as days relative to t0.

The knots span the outbreak in weekly steps; combined with log_R_at this defines the piecewise-linear log R(t) trajectory used by joint_model.

Arguments

• t0: the model's time origin (the t0 field of the tuple returned by build_data).

Returns

A Vector{Float64} of length length(BIN_EDGES) giving the knot positions in days.

source

TransmissionLinelist.bin_labels Method

bin_labels() -> Vector{String}

Return string labels for the weekly R(t) knots.

One entry per log_R element. Used to label plots and posterior summaries produced by summarise and plot_rt.

Returns

A Vector{String} of ISO-format knot dates.

source

TransmissionLinelist.build_data Method

build_data(
    ll
) -> NamedTuple{(:t0, :onset_lo_day, :onset_hi_day, :exp_lo_day, :exp_hi_day, :source_idx, :Zobs, :N), <:NTuple{8, Any}}

Build the model input from a line-list DataFrame.

Anchors all times in days relative to t0 = minimum(onset_date) - 60 d and encodes interval-censored onset and exposure windows as [lo, hi) pairs. Resolves the source_case column to integer indices into the line list (0 denotes a zoonotic index case with no human source) and reads observed offspring counts from the Z column.

Arguments

• ll: a DataFrame returned by load_linelist.

Returns

A named tuple (t0, onset_lo_day, onset_hi_day, exp_lo_day, exp_hi_day, source_idx, Zobs, N) ready to pass to joint_model.

Examples

ll = load_linelist()
d  = build_data(ll)
d.N

source

TransmissionLinelist.diagnostics Method

diagnostics(
    chn
) -> NamedTuple{(:rhat, :ess, :ndiv), <:Tuple{Float64, Float64, Any}}

Return convergence diagnostics for chn: (; rhat, ess, ndiv) — the maximum R̂ across scalar parameter entries, the minimum bulk ESS, and the divergent transition count.

Arguments

• chn: FlexiChain returned by sample_fit.

source

TransmissionLinelist.diagnostics_table Method

diagnostics_table(chn)

Single-row DataFrame summarising sampler diagnostics: maximum R̂, minimum bulk ESS, divergence count, and wall-clock sampling time in seconds. The runtime is read from FlexiChains' per-chain sampling_time metadata; under MCMCThreads chains run in parallel so the wall clock is approximated by the maximum over chains. Returns missing for the runtime if the chain carries no timing metadata.

Arguments

• chn: FlexiChain returned by sample_fit.

source

TransmissionLinelist.joint_model Method

joint_model(d, edges) -> Any

Joint Turing model for the Epuyén ANDV outbreak.

Estimates the incubation period (LogNormal), the per-pair transmission timing δ relative to source onset (Normal), a weekly piecewise-linear log-R(t) random walk, and the offspring dispersion k, from interval- censored exposure and onset windows. Each case has continuous latent infection and onset times; the positive generation-interval constraint T_inf[secondary] > T_inf[source] is enforced via a -Inf reject in the likelihood. The model is described in METHODS.md.

Arguments

• d: model data tuple as returned by build_data, with fields t0, onset_lo_day, onset_hi_day, exp_lo_day, exp_hi_day, source_idx, Zobs, and N.

• edges: knot positions in days from t0, as returned by bin_edges_day.

Returns

A DynamicPPL.Model ready to pass to Turing.sample. The sampled chain contains the population parameters μ_inc, σ_inc, μ_δ, σ_δ, phi_inv_sqrt, σ_rw, the derived k and log_R, the random-walk innovations ε and initial value log_R_init, and the per-case latent vectors T_onset and T_inf.

Examples

ll    = load_linelist()
d     = build_data(ll)
edges = bin_edges_day(d.t0)
m     = joint_model(d, edges)

source

TransmissionLinelist.load_linelist Function

load_linelist() -> DataFrames.DataFrame
load_linelist(path) -> DataFrames.DataFrame

Load and clean the Epuyén line list from a CSV file.

Reads the CSV at path, drops any duplicated rows with patient IDs ending in _alt, parses exposure_lower, exposure_upper, onset_date, onset_lower, and onset_upper as Dates (defaulting onset_lower and onset_upper to onset_date when absent), and sorts the rows by integer-valued patient_id. Used by build_data to produce the model input tuple.

Arguments

• path: path to a line-list CSV. Defaults to the bundled data/linelist.csv shipped with the package.

Returns

A DataFrame with one row per case and parsed date columns ready for build_data.

Examples

using TransmissionLinelist
ll = load_linelist()
first(ll, 3)

source

TransmissionLinelist.log_R_at Method

log_R_at(
    t::Real,
    knots::AbstractVector{<:Real},
    log_R
) -> Any

Piecewise-linear interpolation of log R(t) between weekly knots.

Linearly interpolates log_R against knots at the time t, clamping to the endpoint values outside the knot range.

Arguments

• t: time (in days from t0) at which to evaluate log R.

• knots: knot positions in days, as returned by bin_edges_day.

• log_R: vector of log R values at each knot.

Returns

The interpolated log R value at t.

source

TransmissionLinelist.plot_data Method

plot_data(ll)

Two-panel view of the raw line list: epicurve by ISO week of onset (left) and exposure windows against onset dates (right). Returns a Makie.Figure.

Arguments

• ll: line-list DataFrame from load_linelist.

source

TransmissionLinelist.plot_delta_sense_check Method

plot_delta_sense_check(chn, data)

Sense-check the per-pair posterior of δ against the fitted population Normal(μ_δ, σ_δ). For each sourced pair, take the posterior of δ_pair = T_inf[secondary] − T_onset[source] and reduce to its median; then plot the histogram of those per-pair medians with the population density overlaid. Returns a Makie.Figure.

Arguments

• chn: FlexiChain returned by sample_fit.

• d: model data tuple from build_data.

source

TransmissionLinelist.plot_inc_sense_check Method

plot_inc_sense_check(chn, data; n_density_draws = 200)

Sense-check the per-case posterior of the incubation period against the fitted population LogNormal(μ_inc, σ_inc). For each case, takes the posterior of inc_i = T_onset[i] − T_inf[i] and reduces to its median; plots the histogram of those per-case medians with the median PDF (and 95% pointwise ribbon) of the population LogNormal overlaid. Returns a Makie.Figure.

Arguments

• chn: FlexiChain returned by sample_fit.

• data: model data tuple from build_data.

Keyword Arguments

• n_density_draws: number of posterior draws used for the density ribbon.

source

TransmissionLinelist.plot_pair Method

plot_pair(chn; thin = 2)

Corner plot of the population scalars μ_inc, σ_inc, μ_δ, σ_δ, k via PairPlots.jl. Returns a Makie Figure.

Arguments

• chn: FlexiChain returned by sample_fit.

Keyword Arguments

• thin: keep every thin-th draw before plotting.

source

TransmissionLinelist.plot_predictive_distributions Method

plot_predictive_distributions(chn; rng = Random.MersenneTwister(1))

Two-by-two panel of the implied population distributions under the posterior for incubation period, transmission timing δ, generation interval, and serial interval. Each panel shows draws from p(y_new | data) = ∫ p(y_new | θ) p(θ | data) dθ, i.e. what a new case or transmission pair would look like under the fitted parameters.

This is not a posterior-predictive check against observed data; for that, see plot_z_ppc, plot_delta_sense_check, and plot_inc_sense_check.

Inc and δ panels overlay the parametric density (median PDF with a 95% pointwise ribbon across draws) and a histogram of one predictive sample per draw. GI and SI show the predictive-sample histogram only. Returns a Makie.Figure.

Arguments

• chn: FlexiChain returned by sample_fit.

Keyword Arguments

• rng: RNG used to draw the per-draw predictive samples.

source

TransmissionLinelist.plot_prior_predictives Method

plot_prior_predictives(; n = 5000, rng = Random.MersenneTwister(0))

Prior-predictive panel: histograms of Inc, δ, and GI/SI drawn from the package's independent priors on μ_inc, σ_inc, μ_δ, σ_δ. Returns a Makie.Figure.

Three histograms faceted by quantity is the kind of plot AoG was built for: one long-form data frame, mapping(:value, layout = :panel), visual(Hist). Each panel still has its own viewing window so long tails don't squash the bars; rather than per-facet axis limits, the input is pre-clipped to the window for each panel.

Keyword Arguments

• n: number of prior draws to simulate.

• and any other keyword arguments forwarded to the panel construction.

source

TransmissionLinelist.plot_rt Method

plot_rt(chn; n_draws_plot = 100, ymax = 4.0)

Spaghetti plot of R(t) over the weekly knots. Each thinned posterior draw is a piecewise-linear trajectory through (knot_date[b], exp(log_R[b])). Knot dates come from BIN_EDGES (data.jl). Returns a Makie.Figure.

Per-draw spaghetti is built as a long-form DataFrame and drawn via AlgebraOfGraphics with group = :draw, which is the idiomatic way to spell "one line per draw" once the data is tidy.

Arguments

• chn: FlexiChain returned by sample_fit.

Keyword Arguments

• n_draws_plot: maximum number of draws to plot.

• ymax: upper y-axis limit.

source

TransmissionLinelist.plot_z_ppc Method

plot_z_ppc(chn, d; rng, edges) -> Figure

Posterior-predictive check for the offspring count Z. For each draw, simulates Z_rep[i] ~ NegativeBinomial(k, k/(k+R_i)) at the same draw's latents and overlays the replicated frequencies + test statistics (sum(Z), max(Z), count(Z=0)) on the observed values. Returns a Makie Figure.

Arguments

• chn: FlexiChain returned by sample_fit.

• d: model data tuple from build_data.

Keyword Arguments

• rng: RNG used to draw replicated Z_rep per posterior draw.

• edges: knot day offsets, defaults to bin_edges_day(d.t0).

source

TransmissionLinelist.prepare_model Method

prepare_model(
    ll
) -> Tuple{Any, NamedTuple{(:t0, :onset_lo_day, :onset_hi_day, :exp_lo_day, :exp_hi_day, :source_idx, :Zobs, :N), <:NTuple{8, Any}}, Vector{Float64}}

Build the joint model from a line-list ll.

Wraps build_data, bin_edges_day, and joint_model into a single call so the analysis walkthrough and CLI share the same model construction code path.

Arguments

• ll: a line-list DataFrame as returned by load_linelist.

Returns

A 3-tuple (model, d, edges): the Turing model, the augmented data named tuple from build_data, and the weekly knot edges from bin_edges_day.

source

TransmissionLinelist.sample_fit Method

sample_fit(model; samples=1000, chains=4, target_accept=0.95,
           seed=20260508, progress=false)

Run NUTS on model using the package's default Enzyme AD backend and InitFromPrior() chain initialisation. Returns the FlexiChain.

Arguments

• model: a Turing model, e.g. from joint_model.

Keyword Arguments

• samples: NUTS samples per chain.

• chains: number of parallel chains.

• target_accept: NUTS acceptance target.

• seed: random seed.

• progress: show a NUTS progress bar.

source

TransmissionLinelist.save_posterior Method

save_posterior(post, path) -> Any

Write the posterior summary post (as returned by summarise) to a CSV at path, one column per scalar parameter plus one column per log_R knot.

Arguments

• post: posterior named tuple from summarise.

• path: output CSV path.

source

TransmissionLinelist.summarise Method

summarise(
    chn
) -> NamedTuple{(:μ_inc, :σ_inc, :μ_δ, :σ_δ, :k, :log_R_chain, :mean_gi_si, :sd_gi_si, :p_pre), <:Tuple{Any, Any, Any, Any, Any, Any, Any, Any, Dict{Float64, Vector{Float64}}}}

Build the named-tuple of posterior draws consumed by save_posterior and print the headline summary table via summary_table.

Arguments

• chn: FlexiChain returned by sample_fit.

source

TransmissionLinelist.summary_table Method

summary_table(chn)

Posterior summary DataFrame for the headline quantities: incubation mean, 95th and 99th percentiles, transmission timing μ_δ / σ_δ, GI / SI mean and SD, and Negative-Binomial dispersion k. Columns: quantity, median, lower_95, upper_95.

Arguments

• chn: FlexiChain returned by sample_fit.

source

TransmissionLinelist.vector_chain Method

vector_chain(chn, name::Symbol) -> Any

Return a vector of pooled posterior samples for each entry of a vector-valued parameter (e.g. :T_inf, :log_R).

Arguments

• chn: FlexiChain returned by sample_fit.

• name: name of a vector-valued parameter in chn.

source

TransmissionLinelist.z_ppc_summary Method

z_ppc_summary(chn, d; rng = Random.MersenneTwister(1),
              edges = bin_edges_day(d.t0))

Companion to plot_z_ppc returning a DataFrame of numeric posterior-predictive summaries for three discrete test statistics — sum(Z), max(Z), and count(Z = 0). Replicates Z_rep jointly in (T_inf, log_R, k) to match plot_z_ppc. Columns: statistic, observed, rep_median, rep_lower_95, rep_upper_95, p_ppp, where p_ppp = 2 · min(P(T_rep ≥ T_obs), P(T_rep ≤ T_obs)) is the two-sided Bayesian posterior-predictive p-value.

Arguments

• chn: FlexiChain returned by sample_fit.

• d: model data tuple from build_data.

Keyword Arguments

• rng: RNG used to draw the replicated Z_rep per posterior draw.

• edges: knot day offsets, defaults to bin_edges_day(d.t0).

source