More epidemic models to generate cases?

[joshwlambert]

The MVP of {simulist} uses a single-type branching process to simulate cases and the contacts between them. This model is imported from {bpmodels}.

The initial pitch of the {simulist} package on the Epiverse-TRACE discussions board stated (emphasis mine):

This R package would provide tools to simulate epidemic's raw case data in the form of line lists, using model outputs, such as compartmental models, branching processes, or network models.

For future development should we consider also including compartmental model or network models to generate epidemiological data (line list and contacts) using {simulist}?

[sbfnk]

On this, perhaps the transmission model could be separated from a function to generate the linelist? In the simplest case the linelist could be generated from a vector of infection times (if requiring contacts it might get slightly more complicated, but not necessarily much so) -- this could then be the input to a generate_linelist() function that generates the data frame with all the relevant delays etc.

[joshwlambert]

I'm not sure I fully understand the workflow you're describing. Would you mind sketching out (with some pseudo-code if possible) what it would look like.

Ideally we would be able to pass in something (e.g. vector of infection times) to sim_linelist() and it would produce a line list. By using ... we can set it up to accept named arguments such as infection_times to get around specifying the existing arguments.

infection_times <- c(2.5, 4, 7.8, 12)
sim_linelist(infection_times = infection_times)

In theory we could set this up to accept any number of alternative inputs (vectors and <data.frame>s) each with their own recognised argument passed via ....

I'd prefer not to introduce more functions, or offer alternative workflows for generating line list/outbreak data unless necessary.

[sbfnk]

The workflow I'm envisioning is one where {simulist} doesn't need to contain an infection generating model at all - or if it does it could serve as an example but users can use any model they like.

I think the most straightforward way of doing this would be one where {simulist} doesn't need to run any simulation of the infection process. Your suggested code would be one way of doing this and could generate a linelist of symptom onset dates, hospitalisation dates, etc. Maybe something like this

infection_times <- c(2.5, 4, 7.8, 12)
sim_linelist(
  infection_times = infection_times,
  origin_date = as.Date("2025-01-03"),
  delays = c(
    symptoms = function(n) 2 + rgamma(n, 1, 1), ## all symptomatic, minimum incubation period is 2
    hospitalisation = function(n) {
      hosp_delay <- numeric(0)
      ## 20% of symptomatic are hospitalised
      hosp_delay[runif(n) > 0.2] <- NA_numeric_
      ## lognormal delay
      hosp_delay[!is.na(hosp_delay)] <- rlnorm(3, 1)
    }
  )
)

Additional inputs could relate to e.g. uninfected contacts or anything else needed to generate the line list.

[joshwlambert]

Related discussion: In #127 it was decided to keep the sim_*() functions as single functions rather than exporting each internal function to allow users to compose pipelines to build custom simulated data, therefore, whatever we decide for possibly integrating more epidemic models, we should minimise breaking changes to the function signatures, not break simulation functions into multiple components, and keep the output consistent.

[joshwlambert]

I think I see where you're coming from @sbfnk. If I understand, using a different time series generator, the sim_linelist() function would just transform/decorate the time series into a line list. This relates to points raised in #43 so there seems to be a broad consensus, but we'll still need to sketch development roadmap.

The transform time series approach might also not generalise well to simulating contact tracing data (sim_contacts() and sim_outbreak()), whereas currently the internal branching process model is a single model called by all sim_*() functions.

This feature to accept more generating models is not planned to be worked on in the short-term. I think the next steps would be to define a data schema for what can be accepted by {simulist} to simulate line list and contact tracing data, then we can consider how the function signatures should be adapted to accommodate this change (e.g. using ... as suggested in #43). By defining our own data schema we are flexible to accept input from a wide range of model types and are not coupling development to other packages, any coupling can be localised to as_*() coercion functions where we decide interoperability is useful (e.g. {ringbp} as mentioned in #43).