---
title: "Heterogeneity & Demographic Analysis"
date: "`r Sys.Date()`"
output:
  rmarkdown::html_vignette:
    toc: true
vignette: >
  %\VignetteIndexEntry{Heterogeneity & Demographic Analysis}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r, echo=FALSE, include=FALSE}
library(heemod)
```

```{r, echo = FALSE} 
NOT_CRAN <- identical(tolower(Sys.getenv("NOT_CRAN")), "true")
knitr::opts_chunk$set(
  screenshot.force = FALSE
)
```


```{r, include = FALSE}

param <- define_parameters(
    age_init = 60,
    sex = 0,
    # age increases with cycles
    age = age_init + model_time,
    
    # operative mortality rates
    omrPTHR = .02,
    omrRTHR = .02,
    
    # re-revision mortality rate
    rrr = .04,
    
    # parameters for calculating primary revision rate
    cons = -5.49094,
    ageC = -.0367,
    maleC = .768536,
    lambda = exp(cons + ageC * age_init + maleC * sex),
    gamma = 1.45367786,
    
    rrNP1 = .260677,
    
    # revision probability of primary procedure
    standardRR = 1 - exp(lambda * ((model_time - 1) ^ gamma -
                                     model_time ^ gamma)),
    np1RR = 1 - exp(lambda * rrNP1 * ((model_time - 1) ^ gamma - 
                                        model_time ^ gamma)),
    
    # age-related mortality rate
    sex_cat = ifelse(sex == 0, "FMLE", "MLE"),
    mr = get_who_mr(age, sex_cat, local = TRUE),
    
    # state values
    u_SuccessP = .85,
    u_RevisionTHR = .30,
    u_SuccessR = .75,
    c_RevisionTHR = 5294
)

mat_standard <- define_transition(
    state_names = c(
      "PrimaryTHR",
      "SuccessP",
      "RevisionTHR",
      "SuccessR",
      "Death"
    ),
    0, C, 0,          0, omrPTHR,
    0, C, standardRR, 0, mr,
    0, 0, 0,          C, omrRTHR+mr,
    0, 0, rrr,        C, mr,
    0, 0, 0,          0, 1
)

mat_np1 <- define_transition(
    state_names = c(
      "PrimaryTHR",
      "SuccessP",
      "RevisionTHR",
      "SuccessR",
      "Death"
    ),
    0, C, 0,          0, omrPTHR,
    0, C, np1RR,      0, mr,
    0, 0, 0,          C, omrRTHR+mr,
    0, 0, rrr,        C, mr,
    0, 0, 0,          0, 1
)

mod_standard <- define_strategy(
  transition = mat_standard,
  PrimaryTHR = define_state(
    utility = 0,
    cost = 394
  ),
  SuccessP = define_state(
    utility = discount(u_SuccessP, .015),
    cost = 0
  ),
  RevisionTHR = define_state(
    utility = discount(u_RevisionTHR, .015),
    cost = discount(c_RevisionTHR, .06)
  ),
  SuccessR = define_state(
    utility = discount(u_SuccessR, .015),
    cost = 0
  ),
  Death = define_state(
    utility = 0,
    cost = 0
  )
)

mod_np1 <- define_strategy(
  transition = mat_np1,
  PrimaryTHR = define_state(
    utility = 0,
    cost = 579
  ),
  SuccessP = define_state(
    utility = discount(u_SuccessP, .015),
    cost = 0
  ),
  RevisionTHR = define_state(
    utility = discount(u_RevisionTHR, .015),
    cost = discount(c_RevisionTHR, .06)
  ),
  SuccessR = define_state(
    utility = discount(u_SuccessR, .015),
    cost = 0
  ),
  Death = define_state(
    utility = 0,
    cost = 0
  )
)

res_mod <- run_model(
  standard = mod_standard,
  np1 = mod_np1,
  parameters = param,
  cycles = 60,
  cost = cost,
  effect = utility,
  method = "beginning"
)
```

## Introduction

Heterogeneity analysis is a way to explore how the results of a model can vary depending on the characteristics of individuals in a population, and demographic analysis estimates the average values of a model over an entire population.

In practice these two analyses naturally complement each other: heterogeneity analysis runs the model on multiple sets of parameters (reflecting different characteristics found in the target population), and demographic analysis combines the results.

For this example we will use the result from the assessment of a new total hip replacement previously described in `vignette("d-non-homogeneous", "heemod")`.

## Population characteristics

The characteristics of the population are input from a table, with one column per parameter and one row per individual. Those may be for example the characteristics of the indiviuals included in the original trial data.

```{r include = FALSE}
N <- 100

tab_indiv <- tibble::tibble(
  age = round(rnorm(N, mean = 60, sd = 10)),
  sex = sample(0:1, N, TRUE)
)
tab_indiv_w <- tibble::tibble(
  age = round(rnorm(N, mean = 60, sd = 10)),
  sex = sample(0:1, N, TRUE),
  .weights = runif(N)
)
```

For this example we will use the characteristics of `r N` individuals, with varying sex and age, specified in the data frame `tab_indiv`:

```{r, fig.align='center', fig.height=4, fig.width=6}
tab_indiv

library(ggplot2)
ggplot(tab_indiv, aes(x = age)) +
  geom_histogram(binwidth = 2)
```

## Running the analysis

`res_mod`, the result we obtained from `run_model()` in the *Time-varying Markov models* vignette, can be passed to `update()` to update the model with the new data and perform the heterogeneity analysis.

```{r}
res_h <- update(res_mod, newdata = tab_indiv)
```

## Interpreting results

The `summary()` method reports summary statistics for cost, effect and ICER, as well as the result from the combined model.

```{r}
summary(res_h)
```

The variation of cost or effect can then be plotted.

```{r, fig.align='center', fig.height=4, fig.width=6}
plot(res_h, result = "effect", binwidth = 5)
plot(res_h, result = "cost", binwidth = 50)
```

```{r, fig.align='center', fig.height=4, fig.width=6}
plot(res_h, result = "icer", type = "difference",
     binwidth = 500)
plot(res_h, result = "effect", type = "difference",
     binwidth = .1)
plot(res_h, result = "cost", type = "difference",
     binwidth = 30)
```

The results from the combined model can be plotted similarly to the results from `run_model()`.

```{r, fig.align='center', fig.height=4, fig.width=6}
plot(res_h, type = "counts")
```

## Weighted results

Weights can be used in the analysis by including an optional column `.weights` in the new data to specify the respective weights of each strata in the target population.

```{r}
tab_indiv_w
res_w <- update(res_mod, newdata = tab_indiv_w)
res_w
```

## Parallel computing

Updating can be significantly sped up by using parallel computing. This can be done in the following way:

  * Define a cluster with the `use_cluster()` functions (i.e. `use_cluster(4)` to use 4 cores).
  * Run the analysis as usual.
  * To stop using parallel computing use the `close_cluster()` function.
  
Results may vary depending on the machine, but we found speed gains to be quite limited beyond 4 cores.
