Allow multiple runs of simulations

[jamesmbaazam]

It would be helpful to have a wrapper function for running multiple realizations of the same simulations from simulate_tree(), etc.

[jamesmbaazam]

This can easily be done without need for an extra argument or a wrapper, so this issue will not be fixed.

[avallecam]

As commented in https://github.com/orgs/epiverse-trace/discussions/173 when iterating a function, there are non-obvious steps that are difficult to remember or are only memorable when used with high frequency.

As user, I expect to return to the documentation (vignette or tutorial) each time I need to iterate the function, according to my apply to purrr preference

The approach in {epidemics} of embedding the iteration and getting nested outputs in list-type columns is easier to handle when purrr +tidyr is already familiar to the user, like using unnest() when accounting for uncertainty

I would evaluate the benefit of adding an argument that differentiates between n_chains (index cases per simulation) and n_simulations (1 for a singular simulation as default), accounting for the most appropriate way to keep the readability of the function for the maintainers.

The pseudocode for this would be:

set.seed(32)
# Simulate chains
sim_chains <- simulate_chains(
  n_simulations = 1, # default option
  n_chains = 20,
  statistic = "size",
  offspring_dist = rpois,
  stat_threshold = 25,
  generation_time = function(n) {rep(3, n)}, # constant generation time of 3
  lambda = 1 # mean of the Poisson distribution
)
# View the head of the simulation
head(sim_chains)
#> simulation chain infector infectee generation time
#>          1     1       NA        1          1    0
#>        ...

[jamesmbaazam]

Thanks @avallecam. I will resolve it for the next release.

[avallecam]

just noticed that in {epidemics} in model_ebola() we have the replicates argument (reference manual), which is expressed in the replicate column

library(epidemics)

# create a population with 6 compartments
population <- population(
  contact_matrix = matrix(1),
  demography_vector = 14e6,
  initial_conditions = matrix(
    c(0.999998, 0.000001, 0.000001, 0, 0, 0),
    nrow = 1, ncol = 6L
  )
)

model_ebola(
  population = population,
  replicates = 1
)
#>       time demography_group  compartment    value replicate
#>      <int>           <char>       <char>    <num>     <int>
#>   1:     0     demo_group_1  susceptible 13999972         1
#>   2:     0     demo_group_1      exposed       14         1
#>   3:     0     demo_group_1   infectious       14         1
#>   4:     0     demo_group_1 hospitalised        0         1
#>   5:     0     demo_group_1      funeral        0         1
#>  ---                                                       
#> 602:   100     demo_group_1      exposed      187         1
#> 603:   100     demo_group_1   infectious      194         1
#> 604:   100     demo_group_1 hospitalised      145         1
#> 605:   100     demo_group_1      funeral       12         1
#> 606:   100     demo_group_1      removed      894         1

model_ebola(
  population = population,
  replicates = 100
)
#>         time demography_group  compartment    value replicate
#>        <int>           <char>       <char>    <num>     <int>
#>     1:     0     demo_group_1  susceptible 13999972         1
#>     2:     0     demo_group_1      exposed       14         1
#>     3:     0     demo_group_1   infectious       14         1
#>     4:     0     demo_group_1 hospitalised        0         1
#>     5:     0     demo_group_1      funeral        0         1
#>    ---                                                       
#> 60596:   100     demo_group_1      exposed      156       100
#> 60597:   100     demo_group_1   infectious      166       100
#> 60598:   100     demo_group_1 hospitalised       99       100
#> 60599:   100     demo_group_1      funeral       10       100
#> 60600:   100     demo_group_1      removed      685       100

^{Created on 2024-06-11 with reprex v2.1.0}

[sbfnk]

Related comment at #275 (comment)