#+TITLE: Microsimulation package for R

#+OPTIONS: toc:nil #+OPTIONS: num:nil #+OPTIONS: html-postamble:nil

Babel settings

+PROPERTY: session R-microsimulation

+PROPERTY: cache yes

+PROPERTY: results output graphics

+PROPERTY: exports both

+PROPERTY: tangle yes

+PROPERTY: exports both

[[http://www.gnu.org/licenses/gpl-3.0.html][http://img.shields.io/:license-gpl3-blue.svg]]

• News

• The microsimulation package now allows for in-line use and provides a new SummaryReport class. See the in-line example below for a demonstration of both of these facilities.
• The C++ application programming interface is now [[https://htmlpreview.github.io/?https://github.com/mclements/microsimulation/blob/master/inst/doc/html/index.html][described]] using Doxygen.

• Background [[https://en.wikipedia.org/wiki/Microsimulation][Microsimulation]] is a form of individual-based stochastic simulation. In continuous time, microsimulation is closely related to [[https://en.wikipedia.org/wiki/Discrete_event_simulation][discrete event simulation]], and in discrete time it is closely related to [[https://en.wikipedia.org/wiki/Agent-based_model][agent-based models]]. In econometrics and health care, microsimulation is often used to model policy changes. Our implementation is in continuous time and uses event-based discrete event simulation for the model specification.

The package provides several approaches for microsimulation and event-based, discrete event simulation. The package includes an R implementation of discrete event simulation, building on several R5 classes. This implementation is useful from a pedagogical perspective, but it is slow for larger microsimulations. For speed, we also provide C++ classes for discrete event simulation, building on several well established libraries, including the [[http://www.inf.usi.ch/carzaniga/ssim/index.html][SSIM]] C++ discrete event simulation library, the [[http://www.iro.umontreal.ca/~lecuyer/myftp/streams00/][RngStream]] C library for common random numbers, the [[http://www.boost.org/][Boost]] libraries for making many C++11 tools available to C++98, and [[http://www.rcpp.org/][Rcpp]] for providing glue between R, R's C API and C++.

We specifically developed this package for modelling the cost-effectiveness of cancer screening, where there are many (e.g. 10^7) individuals who are followed from birth to death. Notably, we provide a complete prostate cancer screening model, including tools for cost-effectiveness analysis.

• Installing the package

• 1 Installation through CRAN: :: To install the microsimulation package from CRAN, just run the following in R: #+BEGIN_SRC R :session R-microsimulation :exports code :eval never install.packages("microsimulation") #+END_SRC

For compiling from source, use steps 2--3.

• 2 Dependencies: :: The microsimulation package requires [[http://www.rcpp.org/][Rcpp]]. A convenient, but not required, way of installing github-packages in R is to use [[https://cran.r-project.org/web/packages/devtools/README.html][devtools]]. Since both of the dependencies and [[https://cran.r-project.org/web/packages/devtools/README.html][devtools]] are available on [[https://cran.r-project.org/][CRAN]] just run the following in R. #+BEGIN_SRC R :session R-microsimulation :exports code :eval never install.packages("Rcpp") install.packages("devtools") #+END_SRC

• 3a Installation with devtools: :: To install the microsimulation using [[https://cran.r-project.org/web/packages/devtools/README.html][devtools]] just run the following in R: #+BEGIN_SRC R :session R-microsimulation :exports code :eval never require(devtools) install_github("mclements/microsimulation") #+END_SRC

• 3b Alternative installation from shell: ::

Some thing OS-specific?

If you prefer the shell over [[https://cran.r-project.org/web/packages/devtools/README.html][devtools]], just run the following to download the microsimulation R-package: #+BEGIN_SRC shell :exports code :eval never git clone https://github.com/mclements/microsimulation.git #+END_SRC

To install the microsimulation R-package run this in your shell: #+BEGIN_SRC shell :exports code :eval never R CMD INSTALL path_to_microsimulation #+END_SRC

• Running the simulation

** Simple examples

#+name: commentify #+begin_src emacs-lisp :var result="" :exports none (concat "#> "(mapconcat 'identity (split-string result "\n") "\n#> ")) #+end_src

#+BEGIN_SRC R :session R-microsimulation :post commentify(this) :results output :exports both :eval never-export require(microsimulation) sim1 <- callSimplePerson2(n = 1e5) summary(sim1$events) #+END_SRC

#+RESULTS: : #> state event age number : #> Healthy:338 toOtherDeath :142 Min. : 1.00 Min. : 1.0 : #> Cancer : 0 toCancer :100 1st Qu.: 37.00 1st Qu.: 74.0 : #> Death : 0 toCancerDeath: 96 Median : 58.00 Median : 325.0 : #> Mean : 56.98 Mean : 445.1 : #> 3rd Qu.: 79.00 3rd Qu.: 721.8 : #> Max. :100.00 Max. :1722.0 : #>

#+BEGIN_SRC R :session R-microsimulation :post commentify(this) :results output :exports both :eval never-export sim2 <- callIllnessDeath(n = 1e5, cure = 0.2) summary(sim2$prev) #+END_SRC

#+RESULTS: : #> state age number : #> Healthy:200 Min. : 0.00 Min. : 1 : #> Cancer : 0 1st Qu.: 25.75 1st Qu.: 2030 : #> Median : 50.50 Median : 8096 : #> Mean : 50.49 Mean : 34914 : #> 3rd Qu.: 75.25 3rd Qu.: 79029 : #> Max. :100.00 Max. :100000 : #>

** In-line example: Sick-Sicker example from Krijkamp et al (2018)

We have provided a continuous-time re-implementation of the discrete-time Markov model developed by Krijkamp et al (2018).

The example demonstrates:

• Passing data between R and C++.
• Development of a =SickSicker= class in C++ that inherits from =ssim::cProcess=. This requires the specification of a =void init()= method and a =void handleMessage(const ssim::cMessage* msg)= method.
• Reporting using the new =SummaryReport= class, which allows for utilities, point and interval costs and discounting. The class also allows for reporting individual costs and utilities to calculate the Monte Carlo error.

For the specific example, the transformation from discrete to continuous time showed that the discrete time formulation could have been improved. In particular, the discrete time formulation assumes no transitions between Healthy and Sicker over one year, while the approximate probability of that event is the one-year probability of moving from Healthy to Sick times the probability of moving from Sick to Sicker. We have included that probability in the transition matrix and using matrix logarithms to calculate the transition probabilities.

#+BEGIN_SRC R :session R-microsimulation :results output wrap :exports both

+BEGIN_SRC R :session R-microsimulation :results output wrap :exports both :eval never-export

library(expm) # logm library(Rcpp) # sourceCpp library(microsimulation) # Rcpp::depends and include files library(ascii); options(asciiType="org")

set up the parameters

param <- within(list(), { ## Transition probabilities (per cycle) and rates p.HD = 0.005 # probability to die when healthy p.HS1 = 0.15 # probability to become sick when healthy p.S1H = 0.5 # probability to become healthy when sick p.S1S2 = 0.105 # probability to become sicker when sick rr.S1 = 3 # rate ratio of death when sick vs healthy rr.S2 = 10 # rate ratio of death when sicker vs healthy r.HD = -log(1-p.HD) # rate of death when healthy r.S1D = rr.S1 * r.HD # rate of death when sick r.S2D = rr.S2 * r.HD # rate of death when sicker p.S1D = 1-exp(-r.S1D) # probability to die when sick p.S2D = 1-exp(-r.S2D) # probability to die when sicker ## Cost and utility inputs c_H = 2000 # cost of remaining one cycle healthy c_S1 = 4000 # cost of remaining one cycle sick c_S2 = 15000 # cost of remaining one cycle sicker c_Trt = 12000 # (additional) cost of treatment (per cycle) u_H = 1 # utility when healthy u_S1 = 0.75 # utility when sick u_S2 = 0.5 # utility when sicker u_Trt = 0.95 # utility when sick (as per the code) and being treated ## new parameters discountRate = 0.03 # discount rate partitionBy = 1.0 # partition used in the report Trt = FALSE # Treatment? debug = FALSE })

For converting from discrete to continuous time: p.HS2 should be non-zero

param = within(param, { p.HS2 = p.HS1p.S1S2 }) Pmat = with(param, matrix(c(1-p.HD-p.HS1-p.HS2,p.HS1,p.HS2,p.HD, p.S1H,1-p.S1H-p.S1S2-p.S1D,p.S1S2,p.S1D, 0,0,1-p.S2D,p.S2D, 0,0,0,1), 4, byrow=TRUE)) stopifnot(all(abs(rowSums(Pmat)-1)<10.Machine$double.eps)) Qmat = expm::logm(Pmat) # matrix logarithm stopifnot(all(abs(rowSums(Qmat))<10*.Machine$double.eps))

update the rates in param

param = within(param, { r_HS1 = Qmat[1,2]; r_HD = Qmat[1,4] r_S1H = Qmat[2,1]; r_S1S2 = Qmat[2,3]; r_S1D = Qmat[2,4] r_S2D = Qmat[3,4] })

sourceCpp(code=" // [[Rcpp::depends(BH)]] // [[Rcpp::depends(RcppArmadillo)]] // [[Rcpp::depends(microsimulation)]] #include <microsimulation.h> enum state_t {Healthy, Sick, Sicker, Dead}; enum event_t {toS1, toS2, toH, toD, toEOF}; typedef ssim::SummaryReport<short,short> Report; /** Utility: Random exponential using rate parameterisation / template<class T> double rexpRate(T rate) { return R::rexp(1.0/as<double>(rate)); } /* Utility: Run a set of simulations for a single process / void runSimulations(ssim::cProcess process, int n) { for (int i = 0; i < n; i++) { ssim::Sim::create_process(process); ssim::Sim::run_simulation(); ssim