| Title: | Reconstructing Antibody Dynamics to Estimate the Risk of Influenza Virus Infection |
|---|---|
| Description: | A Bayesian framework for inferring influenza infection status from serial antibody measurements. Jointly estimates season-specific infection probabilities, antibody boosting and waning after infection, and baseline hemagglutination inhibition (HAI) titer distributions via Markov chain Monte Carlo (MCMC). Supports multi-season analysis and subgroup comparisons via a group_by interface. See Tsang et al. (2022) <doi:10.1038/s41467-022-29310-8> for methodological details. |
| Authors: | Tim Tsang [aut, cre] (ORCID: <https://orcid.org/0000-0001-5037-6776>) |
| Maintainer: | Tim Tsang <[email protected]> |
| License: | GPL (>= 2) |
| Version: | 1.1.5 |
| Built: | 2026-06-03 09:50:02 UTC |
| Source: | https://github.com/timktsang/seroreconstruct |
Access an individual group fit by name or index.
## S3 method for class 'seroreconstruct_multi' x[[i, ...]]## S3 method for class 'seroreconstruct_multi' x[[i, ...]]
x |
A |
i |
Group name (character) or index (integer). |
... |
Additional arguments (ignored). |
A seroreconstruct_fit object for the requested group.
This is an example of the flu activity data used in the seroreconstruct function. This data frame specifies the format of the flu activity data.
data(flu_activity)data(flu_activity)
A data frame with 1 variable, where each row represents a date, and it should match the date in the input data:
This is the influenza activity from surveillance data. It can be on a relative scale, as the model includes a scale parameter to estimate infection probability.
Other example_data:
para1,
para2
This is an example of the input data used in the seroreconstruct function. This data frame illustrates the format of the input data.
data(inputdata)data(inputdata)
A data frame with 9 variables, where each row represents an individual:
0: children, 1: adults, 2: older adults
start of follow-up
end of follow-up
date of first serum collection
date of second serum collection
date of third serum collection
HAI titer for first serum collection
HAI titer for second serum collection
HAI titer for third serum collection
output_model_estimate is deprecated; use summary() instead.
output_model_estimate(fitted_MCMC, period)output_model_estimate(fitted_MCMC, period)
fitted_MCMC |
A |
period |
A vector indicating the start and the end of a season to compute the infection probabilities. If empty, the start and end of the season are inferred from the data. |
A data frame of model estimates (invisibly).
## Not run: a1 <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) fitted_result <- output_model_estimate(a1) # deprecated, use summary(a1) ## End(Not run)## Not run: a1 <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) fitted_result <- output_model_estimate(a1) # deprecated, use summary(a1) ## End(Not run)
This is an example of the parameter vector for the main model used in the seroreconstruct function. This data frame specifies the format of the parameter vector for the main model.
data(para1)data(para1)
A numeric vector with 10 elements (for a single-season model, S = 1).
The general length is 6 + 4*S where S is the number of seasons.
1) random measurement error, 2) 2-fold error, 3) boosting for children (log2), 4) waning for children (log2), 5) boosting for adults (log2), 6) waning for adults (log2).
infection risk scale parameters for children, adults, and older adults (3 per season).
log risk ratio of 2-fold increase in baseline HAI titer (1 per season).
Other example_data:
flu_activity,
para2
This is an example of the parameter vector for the baseline HAI titer for the main model used in the seroreconstruct function. This data frame specifies the format of the parameter vector for the baseline HAI titer for the main model.
data(para2)data(para2)
A numeric vector with 20 elements (for a single-season model, S = 1).
The general length is 20 * S where S is the number of seasons.
probability that the HAI titer is 0–9 for children
probability that the HAI titer is 0–9 for adults
For multi-season models, this pattern repeats for each season.
Other example_data:
flu_activity,
para1
Draws violin plots of the posterior fold-rise in antibody titer after infection, one violin per boosting parameter group. Matches the style of Figure 1C in Tsang et al. (2022).
plot_boosting(fit, cols = NULL, main = NULL, show_legend = TRUE, ...)plot_boosting(fit, cols = NULL, main = NULL, show_legend = TRUE, ...)
fit |
A |
cols |
Optional character vector of colors, one per group. |
main |
Optional plot title. |
show_legend |
Logical; whether to draw a legend. Default |
... |
Additional graphical parameters passed to |
Invisible NULL. Called for its side effect of producing a plot.
fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) plot_boosting(fit)fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) plot_boosting(fit)
Produces trace plots and posterior density plots for each model parameter. Trace plots show the MCMC chain with the posterior mean (red dashed line). Density plots show the marginal posterior with 95% credible interval bounds (blue dashed lines).
plot_diagnostics(fit, params = NULL)plot_diagnostics(fit, params = NULL)
fit |
A |
params |
Optional character vector of parameter names to plot. If
|
Invisible NULL. Called for its side effect of producing plots.
fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) # Plot selected parameters (use params = NULL for all) plot_diagnostics(fit, params = c("random_error", "twofold_error"))fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) # Plot selected parameters (use params = NULL for all) plot_diagnostics(fit, params = c("random_error", "twofold_error"))
Forest plot showing posterior infection probabilities with 95% credible intervals. Supports single fits, multi-group fits, and combining results from multiple fits with section headers.
plot_infection_prob( fits, labels = NULL, main = NULL, file = NULL, width = 8, height = NULL, xlim = NULL, cex = 0.85, ... )plot_infection_prob( fits, labels = NULL, main = NULL, file = NULL, width = 8, height = NULL, xlim = NULL, cex = 0.85, ... )
fits |
A |
labels |
Optional character vector of custom labels for the strata within each fit. For a named list of fits, use a list of character vectors. |
main |
Optional plot title. |
file |
Optional file path for PDF output. Default: |
width |
PDF width in inches. Default: 8. |
height |
PDF height in inches. Default: auto-calculated. |
xlim |
Numeric vector of length 2 for the x-axis range (probability
scale, e.g. |
cex |
Character expansion factor. Default: 0.85. |
... |
Additional graphical parameters passed to |
Invisible data frame of the plotted estimates (Stratum, Probability, Lower, Upper).
fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) plot_infection_prob(fit)fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) plot_infection_prob(fit)
For a single individual, draws posterior-sampled antibody trajectories overlaid on observed HAI titers. Red lines show trajectories where infection occurred; blue lines show trajectories without infection. Matches the visualization style of Figure 1B in Tsang et al. (2022).
plot_trajectory( fit, id = 1, subjects = NULL, n_samples = 100, main = NULL, col_infected = NULL, col_uninfected = NULL, show_legend = TRUE, ... )plot_trajectory( fit, id = 1, subjects = NULL, n_samples = 100, main = NULL, col_infected = NULL, col_uninfected = NULL, show_legend = TRUE, ... )
fit |
A |
id |
Row index (integer) or subject identifier to plot. Numeric values
in the valid row range (1 to N) are treated as 1-based row indices.
Numeric values outside that range are looked up in |
subjects |
Optional vector of subject identifiers aligned with fit rows.
Use this when |
n_samples |
Number of posterior samples to draw. Default 100. |
main |
Optional plot title. If |
col_infected |
Color for infected trajectories. Default semi-transparent red. |
col_uninfected |
Color for uninfected trajectories. Default semi-transparent blue. |
show_legend |
Logical; whether to draw a legend. Default |
... |
Additional graphical parameters passed to |
Invisible NULL. Called for its side effect of producing a plot.
fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) plot_trajectory(fit, id = 1)fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) plot_trajectory(fit, id = 1)
Shows the fraction of peak antibody remaining over time since infection, with posterior median and 95% credible band for each waning parameter group. Matches the style of Figure 1D in Tsang et al. (2022).
plot_waning(fit, days = 400, cols = NULL, main = NULL, show_legend = TRUE, ...)plot_waning(fit, days = 400, cols = NULL, main = NULL, show_legend = TRUE, ...)
fit |
A |
days |
Maximum number of days to plot on the x-axis. Default 400. |
cols |
Optional character vector of colors, one per group. |
main |
Optional plot title. |
show_legend |
Logical; whether to draw a legend. Default |
... |
Additional graphical parameters passed to |
Invisible NULL. Called for its side effect of producing a plot.
fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) plot_waning(fit)fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) plot_waning(fit)
Print method for seroreconstruct_fit
## S3 method for class 'seroreconstruct_fit' print(x, ...)## S3 method for class 'seroreconstruct_fit' print(x, ...)
x |
A |
... |
Additional arguments (ignored). |
The input object x, invisibly.
Print method for seroreconstruct_joint
## S3 method for class 'seroreconstruct_joint' print(x, ...)## S3 method for class 'seroreconstruct_joint' print(x, ...)
x |
A |
... |
Additional arguments (ignored). |
The input object x, invisibly.
Print method for seroreconstruct_multi
## S3 method for class 'seroreconstruct_multi' print(x, ...)## S3 method for class 'seroreconstruct_multi' print(x, ...)
x |
A |
... |
Additional arguments (ignored). |
The input object x, invisibly.
Print method for summary.seroreconstruct_fit
## S3 method for class 'summary.seroreconstruct_fit' print(x, digits = 2, ...)## S3 method for class 'summary.seroreconstruct_fit' print(x, digits = 2, ...)
x |
A |
digits |
Number of decimal places for rounding. Default 2. |
... |
Additional arguments (ignored). |
The input object x, invisibly.
Print method for summary.seroreconstruct_joint
## S3 method for class 'summary.seroreconstruct_joint' print(x, digits = 2, ...)## S3 method for class 'summary.seroreconstruct_joint' print(x, digits = 2, ...)
x |
A |
digits |
Number of decimal places for rounding. Default 2. |
... |
Additional arguments (ignored). |
The input object x, invisibly.
Print method for summary.seroreconstruct_multi
## S3 method for class 'summary.seroreconstruct_multi' print(x, digits = 2, ...)## S3 method for class 'summary.seroreconstruct_multi' print(x, digits = 2, ...)
x |
A |
digits |
Number of decimal places for rounding. Default 2. |
... |
Additional arguments (ignored). |
The input object x, invisibly.
The main function to run the MCMC for the Bayesian model, to obtain individual dynamics, model parameters such as infection probability, boosting, waning, and measurement error.
sero_reconstruct( inputdata, inputILI, n_iteration = 2000, burnin = 1000, thinning = 1, group_by = NULL, shared = NULL, subject_ids = NULL )sero_reconstruct( inputdata, inputILI, n_iteration = 2000, burnin = 1000, thinning = 1, group_by = NULL, shared = NULL, subject_ids = NULL )
inputdata |
The data for running MCMC, in dataframe format. It should be in the same format as the data in the package. It includes: 1) age_group (0: children, 1: adults, 2: older adults), 2) start_time: start of follow-up, 3) end_time: end of follow-up, 4) time1: date for first serum collection, 5) time2: date for second serum collection, 6) time3: date for third serum collection, 7) HAI_titer_1: HAI titer for first serum collection, 8) HAI_titer_2: HAI titer for second serum collection, 9) HAI_titer_3: HAI titer for third serum collection. |
inputILI |
The data for influenza activity used in the inference. The row number should match with the date in the inputdata. |
n_iteration |
The number of iterations of the MCMC. |
burnin |
The iteration for burn-in for MCMC. |
thinning |
The number of thinning in MCMC. |
group_by |
Optional formula specifying grouping variables (e.g., |
shared |
Optional character vector specifying which parameters to share across
groups when |
subject_ids |
Optional vector (character, numeric, or factor) of subject
identifiers, one per row of |
Multi-season support: If inputdata contains an optional integer
column named season (0-indexed, contiguous from 0 to
n_seasons - 1), the model fits season-specific infection risk and HAI
protection parameters. When no season column is present, all individuals
are assigned to a single season (n_seasons = 1) and behavior is identical
to previous versions. Validated with simulation recovery studies up to 7 seasons.
Shared parameters: When shared is provided together with
group_by, a single joint MCMC chain is run with all individuals pooled.
Measurement error and boosting/waning parameters are shared across groups
(informed by all data), while infection risk and HAI protection parameters
remain group-specific. This is more statistically efficient than independent
chains when groups share biological or measurement properties.
Single-group design: When using group_by without shared,
independent MCMCs are fit for each group. To compare children vs adults, fit
each group separately using group_by = ~age_group.
Current limitation: summary() is not yet implemented for fits
with n_seasons > 1. Multi-season posterior samples are accessible directly
from the fit object (e.g., fit$posterior_model_parameter).
A seroreconstruct_fit object (when group_by is NULL)
or a seroreconstruct_multi object (when group_by is provided).
Use summary() to extract model estimates.
a1 <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) summary(a1)a1 <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) summary(a1)
The function to simulate the dataset, for validation or other purpose.
simulate_data(inputdata, inputILI, para1, para2, n_groups = 3L)simulate_data(inputdata, inputILI, para1, para2, n_groups = 3L)
inputdata |
The data with the same format that for running MCMC, in dataframe format. |
inputILI |
The data for influenza activity used in the inference. The row number should match with the date in the inputdata. |
para1 |
Numeric vector of active model parameters. Length depends on the
number of seasons
Total length: |
para2 |
Numeric vector for baseline HAI titer distributions. Length
|
n_groups |
Number of groups for infection risk parameters (default 3 for the standard 3-age-group model). |
A simulated data based on the input parameter vectors, with the format equal to the input data.
simulated <- simulate_data(inputdata, flu_activity, para1, para2)simulated <- simulate_data(inputdata, flu_activity, para1, para2)
Computes estimates of infection probabilities, boosting, waning, and measurement error from a fitted MCMC object.
## S3 method for class 'seroreconstruct_fit' summary(object, period, ...)## S3 method for class 'seroreconstruct_fit' summary(object, period, ...)
object |
A |
period |
Optional numeric vector of length 2 specifying the start and end of a season to compute infection probabilities. If omitted, the full follow-up period is used. |
... |
Additional arguments (ignored). |
A summary.seroreconstruct_fit object with element $table.
Computes shared parameter estimates and per-group infection probabilities from a joint fit with shared parameters.
## S3 method for class 'seroreconstruct_joint' summary(object, period, ...)## S3 method for class 'seroreconstruct_joint' summary(object, period, ...)
object |
A |
period |
Optional numeric vector of length 2 specifying the start and end of a season to compute infection probabilities. |
... |
Additional arguments (ignored). |
A summary.seroreconstruct_joint object with element $table.
Computes estimates for each group and combines into a single table.
## S3 method for class 'seroreconstruct_multi' summary(object, period, ...)## S3 method for class 'seroreconstruct_multi' summary(object, period, ...)
object |
A |
period |
Optional numeric vector of length 2 specifying the start and end of a season to compute infection probabilities. |
... |
Additional arguments (ignored). |
A summary.seroreconstruct_multi object with element $table.
Summarizes posterior infection status, timing, and baseline titer for each individual in the dataset.
table_infections(fit)table_infections(fit)
fit |
A |
A data frame with one row per individual and columns:
Individual (row index), Infection_prob (posterior mean
probability of infection), Infection_time_mean (mean infection time
among infected samples), Baseline_titer_mean (mean imputed baseline
HAI titer).
fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) head(table_infections(fit))fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) head(table_infections(fit))
Extracts posterior summaries (mean, median, credible intervals) for all active model parameters.
table_parameters(fit, probs = c(0.025, 0.975))table_parameters(fit, probs = c(0.025, 0.975))
fit |
A |
probs |
Numeric vector of length 2 giving the lower and upper quantile
probabilities for the credible interval. Default |
A data frame with columns: Parameter, Mean, Median, Lower, Upper.
fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) table_parameters(fit)fit <- sero_reconstruct(inputdata, flu_activity, n_iteration = 2000, burnin = 1000, thinning = 1) table_parameters(fit)