Clarify what n_chains > 1 means in context of susceptible depletion vs lapply() over simulate_chains() with n_chains > 1

[jamesmbaazam]

From the MSc training this week, it seems it is still not clear what n_chains means in the context of susceptible depletion when n_chains > 1. @sbfnk and I have had a similar discussion here #242 (comment).

The current approach uses option 1 from the linked comment above, which I'll transfer here with some minor edits to the column names and emphasis in square brackets:

The simulations (n_chains) are replicates of the same situation [simulation]. The population size/depletion of susceptibles affects each of the n_chains separately, and the stat_max affects each independently. This is what we want if using the simulations for inference (i.e. for estimation in the likelihood function) and is the existing setup.

The current documentation of ?simulate_chains says

"It generates independent transmission chains starting with a single case per chain, using a simple branching process model (See details for definition of "chains" and assumptions). Offspring for each chain are generated with an offspring distribution, and an optional generation time distribution function.

The individual chain simulations are controlled by customisable stopping criteria, including a threshold chain size or length, and a generation time cut off. The function also optionally accepts population related inputs such as the population size (defaults to Inf) and percentage of the population initially immune (defaults to 0)."

There is a bit more information on the <epichains> object here in relation to an <epicontacts> object that can probably surfaced a bit more:

An <epichains> object contains multiple independent chains with their own unique infectee ids, so this does not work out of the box with make_epicontacts() unless you use a subset chain.

Tagging @avallecam @joshwlambert @Degoot-AM for feedback on how this can be clarified further in the context of the current documentation. Are there aspects of this that can be clarified further/consolidated/etc? It might mean moving some explanations from the Getting Started Vignette to the function documentation or vice versa.

[avallecam]

thanks @jamesmbaazam for registering this here. the three citations are clear and help me complement our chat today. The first one, which starts "The simulations (n_chains)...", connects the elements nicely and could be addded to the details section of ?simulate_chains. I can use it for the tutorials, too.

Based on this I can simplify the code at the tutorial, removing purrr::map() and looking forward to use aggregate for per-chain summaries #303