epimodel / epimodelhiv

Network Models of HIV Transmission Dynamics among MSM and Heterosexuals

EpiModel

Tools for simulating mathematical models of infectious disease dynamics. Epidemic model classes include deterministic compartmental models, stochastic individual-contact models, and stochastic network models. Network models use the robust statistical methods of exponential-family random graph models (ERGMs) from the Statnet suite of software packages in R. Standard templates for epidemic modeling include SI, SIR, and SIS disease types. EpiModel features an easy application programming interface (API) for extending these templates to address novel scientific research aims.

Lead Authors

Samuel M. Jenness	Department of Epidemiology	Emory University
Steven M. Goodreau	Department of Anthropology	University of Washington
Martina Morris	Departments of Statistics and Sociology	University of Washington
Adrien Le Guillou	Department of Epidemiology	Emory University
Chad Klumb	Center for Studies in Demography and Ecology	University of Washington

Additional contributors to EpiModel are listed on the contributors page.

Installation

The current release version can be found on CRAN and installed with:

install.packages("EpiModel", dependencies = TRUE)

To install this development version, use the remotes package:

if (!require("remotes")) install.packages("remotes")
remotes::install_github("EpiModel/EpiModel")

Documentation and Support

Website. The main website for EpiModel, with tutorials and other supporting files, is here: http://www.epimodel.org/.

Methods Paper. A good place to start learning about EpiModel is the main methods paper published in the Journal of Statistical Software. It is available at: https://doi.org/10.18637/jss.v084.i08.

Summer Course. Network Modeling for Epidemics is our annual 5-day course at the University of Washington where we teach the statistical theory, software tools, and applied modeling methods using EpiModel. Our course materials are open-source and updated annually around the time of the course.

Getting Help. Users are encouraged to use Github issues on this repository as a place to ask questions (both technical coding questions and conceptual modeling questions), report bugs, and request new features & functionality. Broader modeling questions can be posted on the Discussions board here.

The EpiModel Gallery

The EpiModel Gallery contains templates of extensions to EpiModel, for now focused on network-based mathematical modeling class. We will be continuing to add new examples the gallery, and encourage users to either file requests for new examples or else to contribute them directly.

Citation

If using EpiModel for teaching or research, please include a citation our main methods paper:

Jenness SM, Goodreau SM and Morris M. EpiModel: An R Package for Mathematical Modeling of Infectious Disease over Networks. Journal of Statistical Software. 2018; 84(8): 1-47. doi: 10.18637/jss.v084.i08

Please also send us an email if you have used EpiModel in your work so we can add the citation below.

Funding

The primary support for the development of these software tools and statistical methods has been by two National Institutes of Health (NIH) grants. Our applied research projects using EpiModel have received funding from the NIH and Centers for Disease Control and Prevention (CDC). Our team also receives institutional support through center-level NIH grants. A full list of our funding support can be found here.

EpiModel in the Scientific Literature

EpiModel and its extension packages have been used in the following scientific journal articles. A list of these articles can be accessed in a wiki page or on Zotero. (If you are aware of others, send us an email at [email protected] to be included in this list.)

Copyright

These materials are distributed under the GPL-3 license, with the following copyright and attribution requirements listed in the LICENSE document above.

epimodelhiv's Issues

Hard return of roxygen code

Preferred margin for roxygen parameter definitions is 80 spaces. You can add a light margin line with Tools --> General options --> code --> display --> ✔️ Show margin, Margin column = 80.

Then add a hard return, especially in the params.R file.

het-test-script.R error: $ operator is invalid for atomic vectors

Hello,

I get this error when running the het-test-script.R that occurs in line 21 and after:

param <- param_het()
Error: $ operator is invalid for atomic vectors
init <- init_het(i.prev.male = 0.25, i.prev.feml = 0.25)
control <- control_het(nsteps = 2600)

sim <- netsim(est, param, init, control)
Error in UseMethod("as.control.list") :
no applicable method for 'as.control.list' applied to an object of class "control.net"

Would this be due to version problem? My sessionInfo() is the following:

sessionInfo()
R version 4.1.2 (2021-11-01)
Platform: x86_64-apple-darwin17.0 (64-bit)
Running under: macOS Monterey 12.2.1

Matrix products: default
LAPACK: /Library/Frameworks/R.framework/Versions/4.1/Resources/lib/libRlapack.dylib

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

attached base packages:
[1] stats graphics grDevices utils datasets methods base

other attached packages:
[1] ARTnet_2.5.0 ARTnetData_1.1 EpiModelHIV_1.5.0
[4] tergmLite_2.5.5 EpiModelHPC_2.1.2 EpiModel_2.2.1
[7] statnet.common_4.5.0 tergm_4.0.2 ergm_4.1.2
[10] networkDynamic_0.11.0 network_1.17.1 deSolve_1.30
[13] tictoc_1.0.1 forcats_0.5.1 stringr_1.4.0
[16] dplyr_1.0.7 purrr_0.3.4 readr_2.1.2
[19] tidyr_1.2.0 tibble_3.1.6 ggplot2_3.3.5
[22] tidyverse_1.3.1 readxl_1.3.1 rlang_1.0.1
[25] assertthat_0.2.1 truncnorm_1.0-8 ensurer_1.1
[28] gtools_3.9.2

loaded via a namespace (and not attached):
[1] colorspace_2.0-2 ellipsis_0.3.2
[3] class_7.3-19 rprojroot_2.0.2
[5] fs_1.5.2 rstudioapi_0.13
[7] proxy_0.4-26 remotes_2.4.2
[9] fansi_1.0.2 mvtnorm_1.1-3
[11] lubridate_1.8.0 xml2_1.3.3
[13] codetools_0.2-18 doParallel_1.0.17
[15] cachem_1.0.6 robustbase_0.93-9
[17] pkgload_1.2.4 jsonlite_1.7.2
[19] broom_0.7.12 dbplyr_2.1.1
[21] compiler_4.1.2 httr_1.4.2
[23] backports_1.4.1 Matrix_1.3-4
[25] fastmap_1.1.0 lazyeval_0.2.2
[27] cli_3.1.1 prettyunits_1.1.1
[29] tools_4.1.2 coda_0.19-4
[31] gtable_0.3.0 glue_1.6.1
[33] Rcpp_1.0.8 rle_0.9.2
[35] cellranger_1.1.0 vctrs_0.3.8
[37] ape_5.6-1 nlme_3.1-153
[39] iterators_1.0.14 ps_1.6.0
[41] testthat_3.1.1 trust_0.1-8
[43] rvest_1.0.2 lifecycle_1.0.1
[45] devtools_2.4.3 DEoptimR_1.0-10
[47] MASS_7.3-54 scales_1.1.1
[49] hms_1.1.1 parallel_4.1.2
[51] RColorBrewer_1.1-2 memoise_2.0.1
[53] stringi_1.7.6 desc_1.4.0
[55] foreach_1.5.2 e1071_1.7-9
[57] pkgbuild_1.3.1 pkgconfig_2.0.3
[59] lpSolveAPI_5.5.2.0-17.7 lattice_0.20-45
[61] processx_3.5.2 tidyselect_1.1.1
[63] magrittr_2.0.2 R6_2.5.1
[65] generics_0.1.2 DBI_1.1.2
[67] pillar_1.7.0 haven_2.4.3
[69] withr_2.4.3 bindata_0.9-20
[71] modelr_0.1.8 crayon_1.4.2
[73] utf8_1.2.2 tzdb_0.2.0
[75] usethis_2.1.5 grid_4.1.2
[77] callr_3.7.0 reprex_2.0.1
[79] munsell_0.5.0 sessioninfo_1.2.2

Check that time.unit control/param works

Rename functions to be HIV or STI specific

For example, tx_msm would become hiv_tx_msm and ept_msm would become sti_ept_msm

Represent persistent partnership ID in disclosure and partnership matrices

Instead of retaining two columns in these matrices with uid[id1], uid[id2], form the unique partnership id and store as

uid[id1] * 1e7 + uid[id2]

and save in one column. This should also cut down on the computational time in creating these ids within each module.

Dual-site (or three-site?) infection to include syphilis

@smjenness, how far should we go with this? Build structure for each combo but set to the same relative risk?
Possible combos:

• rGC and rCT
• rGC and syphilis
• rCT and syphilis
• rGC, rCT, and syphilis
• uGC and uCT
• uGC and syphilis
• uCT and syphilis
• uGC, uCT, and syphilis

Optimize the riskhist module

Currently, this module is inefficient as it tracks the risk history of men over time because: 1) it calculates behavioral indication metrics for PrEP scenarios that it does not use; and 2) it stores this as a n by t matrix where t is the number of time steps looking backward over which risk is assessed. This can be addressed by limited the calculation to only those indications of interest; and storing not the history of indications but the last time of indication as a vector of length n.

Use stochastic draw for HIV testing default instead of deterministic interval

Tag MSM vs HET modules with roxygen keywords

And also do a close read of the docs

Initial distribution of syphilis by stages moved to initial conditions

Set ups for stage.syph.B.prob and stage.syph.W.prob should go into init_msm, and be drawn from there in the initialization module

Clean up of STI initialization submodule

These are mainly stylistic edits to make in the init_status_sti_msm function:

• Several "defined but not used" variables that may be removed from the function. In Rstudio, under tools --> global options --> code --> diagnostics, check all of the check boxes in this tab. Relatedly, make sure that the two check boxes under the code --> saving, make sure these two checkboxes are checked. If you had planned to use these but just not currently, then keep them.
• Are you actually using the stage.time.syph variable for progression, as it appears like you are basing progression based on time.since.inf.syph instead. If it's not being used outside this submodule, you shouldn't need to store it on dat$attr
• The time.since.inf variables (e.g., on ln 844) are not named usefully. Instead should be related to time since stage started.
• Insert section markers (code --> insert section) for each of the three diseases in this function
• Lines 754-805 set a large number of attributes to NA, and then they are never operated upon during the function, just written to dat$attr at the end. For clarity, just write each of these directly as dat$attr$X <- rep(NA, num) at the end of the function.
• I think we should write everything out to dat$attr at the end of the function to increase clarity. That includes existing code from me for GC and CT. You can set that as a separate section header to further create the distinction.

Change HIV testing interval parameter to 2x the parameter when using deterministic interval

Track number treated for STIs due to intervention

E.g. syph.tx.ept or syph.tx.test

Over counts based on multiple infections within timesteps

In the transmission module the transmission events and type defined by:

infected <- c(disc.ip[trans.ip == 1, 2],
              disc.rp[trans.rp == 1, 1])
inf.role <- c(rep(0, sum(trans.ip)), rep(1, sum(trans.rp)))
inf.type <- c(disc.ip[trans.ip == 1, "ptype"],
              disc.rp[trans.rp == 1, "ptype"])

These vectors are not unique which is not a problem when [infected] is used as an index but it results in over counts in the Epi summary statistics:

dat$epi$incid[at] <- length(infected)

dat$epi$trans.main[at] <- sum(inf.type == 1)
dat$epi$trans.casl[at] <- sum(inf.type == 2)
dat$epi$trans.inst[at] <- sum(inf.type == 3)

Access to .rda files

Hello, when I try running the msm-test-script.R file, it tries to read 3 .rda files that I can't find in the GitHub:

netstats <- readRDS(file.path(scr.dir, "data/artnet.NetStats.Atlanta.rda"))
epistats <- readRDS(file.path(scr.dir, "data/artnet.EpiStats.Atlanta.rda"))
est <- readRDS(file.path(scr.dir, "data/artnet.NetEst.Atlanta.rda"))

Would I be able to get access to these .rda files so I can run this script? Thank you!

Allow any infection to be initialized at 0

This would be for debugging and single epidemic models

Add unit tests for the simulation workflow in EpiModelHIV

Can use the presaved estimation and network statistics data. We can discuss further details...

Check that models may be run on the backfill queue

VL module rewrite

Rewrite VL updates for treatment naive in more readable form than this:

  new.vl <- (inf.time.bp.tn <= vlard) * (vlap * inf.time.bp.tn / vlard) +
            (inf.time.bp.tn > vlard) * (inf.time.bp.tn <= vlard + vlafd) *
            ((vlsp - vlap) * (inf.time.bp.tn - vlard) / vlafd + vlap) +
            (inf.time.bp.tn > vlard + vlafd) * (inf.time.bp.tn <= vldo) * (vlsp) +
            (inf.time.bp.tn > vldo) * (vlsp + (inf.time.bp.tn - vldo) * vlds)

Instead, use conditional logic for each line to subset and update for each group

Remove all refs to attr$active throughout

Generate attribute codebook for EpiModelHIV

Change GC to NG in the codebase

Standardize order of new.edges matrix in same way as partnership list matrix

The partnership list matrix orders the new edgelist like so:

    highlow <- el[which(el[, 1] > el[, 2]), , drop = FALSE]
    lowhigh <- el[which(el[, 1] < el[, 2]), , drop = FALSE]
    part.el <- rbind(highlow[, 2:1], lowhigh)

That approach would make comparing within the disclose and condom modules simpler.

HIV progress module

Hello,

I am wondering if the new values for stage should be updated only at the end of the function?
https://github.com/statnet/EpiModelHIV/blob/CombPrev/R/mod.hivprogress.R

I could not test this specific function, but a similar version.
For example:
when getting the index for stage == 2
https://github.com/statnet/EpiModelHIV/blob/26ea27a0a89f5b78a2b0123fc74875b0f5b26b44/R/mod.hivprogress.R#L64

then in line 68, it could potentially be selected again. Although, it might not be selected again based on time.since.inf
https://github.com/statnet/EpiModelHIV/blob/26ea27a0a89f5b78a2b0123fc74875b0f5b26b44/R/mod.hivprogress.R#L68

Cheers,
Fabricia.

Clean up probabilities and beta coefficients for condom use

These are a mix of probs and logit coefficients, some for P(condom use) and others for P(UAI). Clean these up!

Numeric attributes for stage and tt.traj

Easier conversion to C++ code

Don't index on the active attribute

We use dat$attr$active now only as a placeholder mainly to count the population size. But through some historical coding practices, related to the fact that we allow inactive (aka dead) people to stay on the network in the broader EpiModel framework, we use the variable for indexing vectors. That can and should be removed from any indexes. Make sure to pre/post test this to ensure no negative consequences.

absdiffby summary statistic

Hi Sam, Hi all,

I want to use absdiffby than I need to compute the target.

I can't find any fully explicit help file of absdiffby term. (here is the actual help file right? https://github.com/statnet/EpiModelHIV/blob/master/R/ErgmTerms.R )

Could you please tell me what this summary stat is exactly?

Which is the ref category? (e.g. by arg is sex and coded 0/1)
What the arg assym stands for?
Is the term code is https://github.com/statnet/EpiModelHIV/blob/master/src/changestats.users.c ?

Thanks,
Damien

New Note - R_registerRoutines and R_useDynamicSymbols

New note during build and reload:

File 'EpiModelHIV/libs/x64/EpiModelHIV.dll':
  Found no calls to: 'R_registerRoutines', 'R_useDynamicSymbols'
It is good practice to register native routines and to disable symbol search

@smjenness - Wasn't sure about the best course/location of fixing it right now, so creating an issue rather than just trying to address it right now. Looks like a line or so might need to be added to any Cpp files

Suggested that a single call to this R file (https://raw.githubusercontent.com/stan-dev/rstantools/master/R/init_cpp.R) might address it

(RcppCore/Rcpp#636)
(RcppCore/Rcpp#651)
(https://stackoverflow.com/questions/42313373/r-cmd-check-note-found-no-calls-to-r-registerroutines-r-usedynamicsymbols)
(https://github.com/kevinushey/sourcetools/blob/master/R/register.R)