serofoi 1.0.2

serofoi 1.0.2

New features

• Serological surveys simulation functionalities
  • Introduce enhanced data simulation functionalities to support a broader range of use cases for serosurvey analysis.
  • Add a dedicated vignette for data simulation to guide users on simulating data for serosurveys.

Now it is possible to simulate serological surveys using serofoi. This is done by specifying two separate aspects:

1. The serocatalytic model to be used (either "constant", "time", "age", "age-time"), including the FOI describing the disease transmission patterns (foi_df)
2. The features of the particular serological survey that are being used to uncover these dynamics

For example, consider a disease described by the following seroreversion rate and age-dependent FOI:

max_age <- 80
ages <- seq(1, max_age, 1)
foi_age_varying <- data.frame(
  age = ages,
  foi = 0.03 * exp(-0.03 * ages)
)
seroreversion_rate <- 0.01

Now, suppose that we carry out a serological survey which randomly samples the population. For simplicity, consider that all individual one-year group ages are sampled and the sample size in each age is the same: $n=15$. This can be specified as follows:

n_sample <- 15
survey_features <- data.frame(
  age_min = seq(1, max_age, 1),
  age_max = seq(1, max_age, 1),
  n_sample = rep(n_sample, max_age))

We then put these pieces together and simulate a serosurvey:

serosurvey_age <- simulate_serosurvey(
  model = "age",
  foi = foi_age_varying,
  seroreversion_rate = seroreversion_rate,
  survey_features = survey_features
)

Further details about serological survey simulation can be found in the website article Simulating Serosurveys.

• Enables the implementation of a wide variety of new models
  • Add forward random walk age-varying models with uniform and normal priors.
  • Improves previous implementation of forward random walk time-varying models.
  • Enables prior distributions specifications by means of package specific functions like sf_normal() and sf_uniform().
  • Support for seroreversion rate estimation for all models with uniform and normal priors.

serofoi now supports the implementation of a wide variety of constant, age-varying, and time-varying FOI models, including the possibility to estimate the seroreversion rate. We achieved this by allowing a flexible specification of the priors for each model. For example, to fit an age-dependent model to the previously simulated serosurvey considering a seroreversion prior normally distributed around the "real" value and setting the first FOI close to 0.03:

seromodel_age <- fit_seromodel(
  serosurvey = serosurvey_age,
  model_type = "age",
  foi_prior = sf_normal(3e-2, 1e-3),
  is_seroreversion = TRUE,
  seroreversion_prior = sf_normal(0.01, 1e-3),
  iter = 5000
)

So far, age and time dependent models only allow for forward random walk, meaning that the prior specifies the knowledge about the first age/year to be estimated, from which the next values are estimated recursively.

Breaking changes

• Replaced old modelling and visualization functions, making Bayesian model selection and specification more flexible.
• New models and functionalities include constant, time-varying, and age-varying models, as well as options for estimating seroreversion rates.
• Updated the R-hat convergence threshold for model convergence diagnostics to R-hat<1.01,
  following Vehtari et al. (2021).

Minor changes

• Remove the simdata_* datasets from the package and replaced them with code-based simulation in vignettes.
• Add missing examples to exported functions
• Add missing documentation entries

Internal changes

• Unit testing

  • Added unit tests for key package functionalities, including:
    • fit_seromodel() function (#213).
    • Visualization functionalities (#215).
    • build_stan_data and related functions (#232).
    • Validation functions (#235).
  • Test coverage increased to 100%

• Refactorization of simulation examples

  • Replaced static simulated datasets in tests and vignettes with dynamic examples using data simulation functions.

• Documentation improvements

  • Enhanced documentation for new functionalities and updated vignettes to reflect recent changes.