EpiModelHIV ‐ New Parameters and Attributes - EpiModel/EpiModeling GitHub Wiki

This page details the mandatory elements to take care of when modifying the behavior of EpiModelHIV. This would be true whether you modify an existing module to add some functionalities or create your own.

Adding New Parameters

When adding new interventions or features to a model we often need to create new parameters to govern their behavior.

In EpiModelHIV projects, the parameters are passed to netsim using EpiModel::params.net() as usual. But because of the amount of parameters required (more than 100), the default values are stored in an xlsx file in "data/input/model_parameters.xlsx" if you use the EpiModelHIV Template. (See the Parameters Input Via Table section of the vignette for details)

It is strongly recommended to add an entry for your new parameters in this file. The value on the xlsx file should correspond to a "no intervention" scenario. This way when you run your model with the default parameters, your new intervention will not be turned on.

Updating your EpiModelHIV-p Branch

Once new parameters are added to the xlsx file, you should copy it in the "inst/" folder of your EpiModelHIV-p repo and push to GitHub. This way the automated testing can validate the default behavior of your model.

Adding New Attributes

Similar to parameters, sometimes you will need to create new node attributes to keep track of the effects of your intervention.

These new attributes need to be initialized for every node on the model. EpiModelHIV now offers a unique initialization mechanism that takes care of the start of the model as well as the new nodes arrival.

Default Initializer - mandatory

The new attributes need to be initialized to a default value for new nodes. Usually 0 or NA and will be updated by the intervention as the model runs.

You need to go to the "R/default_attributes.R" files and edit the list within the get_default_attrs(dat) function. Simply add your new attributes with their respective values and you are all set.

get_default_attrs <- function(dat) {
  list(
    status = 0,
    #...
    your.new.attr = 10,
    another.new.attr = NA,
    #...
    tt.traj = 0
  )
}

This step is mandatory for attributes. Default value have to be provided.

Conditional Initialization - optional

In most cases the simple (and mandatory) approach above is enough. However, in some more complex models, the value of some attributes upon initialization or arrival in the model is conditional on either attributes or follow a stochastic process.

In such a case, you will need to edit the make_computed_attrs() function in the same "R/default_attributes.R" file. There you will need to update the n_attr

In the following simple example we add a new.attr attributes which is simply a random draw from a uniform distribution.

make_computed_attrs <- function(dat, n_new, post_init) {
  new_nodes_pid <- length(get_attr(dat, "active")) - n_new + seq_len(n_new)

  #...

  n_attr <- c(n_attr, list(
    late.tester = make_late_tester(dat, n_attr$race),
    circ        = make_circ(dat, n_attr$race, races),
    age.grp     = cut(age, age_breaks, labels = FALSE, right = FALSE),

##### your new attribute #####
    new.attr = runif(n_new),

    ins.quot    = make_ins_quot(n_attr$role.class),
    tt.traj     = make_tt_traj(dat, n_attr$race, races)
  ))

  for (attr_name in names(n_attr)) {
    dat <- set_attr(dat, attr_name, n_attr[attr_name](/EpiModel/EpiModeling/wiki/attr_name), posit_ids = new_nodes_pid)
  }

  return(dat)
}

For more complex examples, look at the make_ functions on this same file.