Document how to make simple, developer-side model edits

[pratikunterwegs]

This issue is to list developer-side edits that are relatively simple to make, and to request a vignette documenting how they should be made within the package code.

[adamkucharski]

Will be great to have this walkthrough available for users/developers.

For simplicity, I’d suggest we divide up based on what broad structural changes are required for common user needs, so if we walkthrough one example, the rest in that category should follow easily. The 3 main types of internal change I expect people might want:

1. Adding fix inflow/outflow parameters for specific compartments, with underlying compartment variables remaining the same. Whether adding static parameters (e.g. birth into S/deaths out of all; zoonotic spillover rate adding to S->I transition) or combinations of existing parameters/variables (e.g. waning immunity from R back into S).
2. Adding new compartment variables (e.g. additional E for multiple latent stages; additional V compartment for two dose vaccines; different clinical pathways with ICU etc). Plus accompanying rates of transition, i.e. same step as (1) above.
3. Adding time dependency in currently fixed parameters based on input time series (e.g. changes in vaccine rates over time; proportion of people wearing masks etc.). But perhaps some of this already possible by defining these functions outside Cpp in the current time-varying transmission and intervention functionality?

I'd anticipate two main user scenarios for making above edits:

1. Adapting a model for a specific use case for one-off project (e.g. MSc project, research paper - so people likely to have good experience with modelling concepts, but probably less with R package development, GitHub etc.). In this case, people wouldn't need to add to the main library, so could just fork the repo and edit an existing model (like model_default) to reduce overhead on having to update function names/namespace and deal with GitHub actions etc. Expect >80% of use cases will fall in this category. See related discussion on ringbp.
2. Adapting a model that can solve a range of problems, with view of adding to the library (e.g. teams that regularly produce modelling outputs and have higher development skillsets). Expect fewer use cases (<20%) to fall in this category.

[pratikunterwegs]

Thanks - just looking at the types of internal changes, I'd arrange them in ascending order of difficulty:

(3) Adding time dependency in currently fixed parameters based on input time series

This is fairly straightforward in terms of using the time-dependence functionality to simulate masking, or waning immunity, and is covered in the "Modelling time dependence" vignette. This doesn't need any changes to the model files. Note that waning immunity is ~currently only possible for the V2 compartment of the Vacamole model~ correction: it's possible for Vacamole V2, AND would also be possible if a new compartmental transition from $R \rightarrow S$ is added, with time-dependence on the rate parameter of this transition (so combines with below).

(1) Adding fix inflow/outflow parameters for specific compartments, with underlying compartment variables remaining the same.

This is fairly easy (as in the model-births branch). This includes births, deaths, and spillovers. Developers would have to take care that all wrapping code is appropriate to any new parameters added (e.g. re-infection rate), and that any tests added account for model changes (e.g. potential population fluctuations if $b \neq d$).

(2) Adding new compartment variables

This is where it starts to get more complex - as the wrapper code needs more modification to check that the user inputs are appropriate to the underlying compartments as well (e.g. vaccination has two doses for two vaccination compartments, as in Vacamole). Otherwise quite similar to modifying compartmental transitions.

(3) Changes in vaccine rates over time

This is actually more challenging, as the <vaccination> class are set up to accommodate multiple doses with age-specific delivery rates, but not multiple vaccination intervals for the same dose/compartment. This also came up in discussion with @sbfnk regarding modifications needed for using {epidemics} for submissions to a Scenario Hub. If this is an important feature to add, I'm happy to raise an issue and implement it.

[adamkucharski]

Thanks - agree above would be a nice structure for a walkthrough document, so users know what they're getting themselves into! Vaccine schedules can become quite fiddly in models, especially if variants involved (e.g. Fig 6 here), but perhaps there's a simplified version that would still fulfil scenario hub needs (not sure from above exactly what's needed).

[pratikunterwegs]

cc @bolthikaru for reference