Advanced topics

library(MicroMoB)

Writing new packages

Often the base way to extend Micro-MoB will be to write a new package that depends on it and which implements specific new models as needed, and depends on the bits of core computation provided by Micro-MoB.

The steps for writing a new package that depends on Micro-MoB are:

  1. Add MicroMoB to the Imports: list of your package’s DESCRIPTION
  2. If you want to depend on the latest version of Micro-MoB, rather than CRAN, add dd-harp/MicroMoB to the Remotes: list of DESCRIPTION
  3. To use methods from Micro-MoB we recommend importing using roxygen2 tags, for example @importFrom MicroMoB compute_q to import the generic method compute_q, rather than using the :: operator in every instance. Please note you only need to import the generic, and not the class-specific methods, as R’s namespace lookup will find the right function for you.

To see an example of an extension package, please take a look at MicroWNV, which adds a new host component, birds, for modeling of West Nile virus.

Writing new models

To write a model for a component means that one must write methods that fulfill each component’s interface, and ensure that those methods return the correct data structure. Information on the methods can be found in the function reference under each component. In addition, a new model must have a setup function, which takes in parameters, does argument checking, and attaches a new object with the correct name and class attached to the model object returned from make_MicroMoB().

For example, to make a new mosquito model, with class MyModel, one would need to do the following:

  1. Write a function setup_mosquito_MyModel which attaches an object (usually a list) to the model environment with the class attribute assigned to "MyModel".
  2. Write methods for the interface compute_f.MyModel, compute_q.MyModel, compute_Z.MyModel, and compute_oviposit.MyModel. Information on what each method is expected to compute and return can be found here.
  3. Write a step (updating) function, step_mosquitoes.MyModel. One can optionally allow the class attribute of the model list to have 2 elements to allow for dispatching on stochastic or deterministic step updates, in which case one would additionally write step_mosquitoes.MyModel_stochastic and step_mosquitoes.MyModel_deterministic. Please look at the source code of the Ross-Macdonald mosquito model to see how to do this.
  4. Write basic tests for your model, which go in tests/testthat. At a minimum, your tests should confirm that the model can be set up properly and produces correct results when updated over a time step.

Plumber web API

Micro-MoB includes some limited support for configuring and running models via web API, using the Plumber package.

All APIs are stored in inst/plumber/APINAME/plumber.R, where APINAME is the name of the specific API.

A simple API can be started up from within R by running the following code:

library(MicroMoB)
plumb_api(package = "MicroMoB", name = "mosquito") %>% pr_run()

The web APIs use JSON files to configure the model, please see the get_config_COMPONENT_MODEL function documentation for how those files should be specified. The web API functionality is highly unstable so please be aware there may be large changes from version to version.