---
title: "Excess and Predicted Cases"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Excess and Predicted Cases}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(Colossus)
library(data.table)
```

## General Theory

In the field of radiation epidemiology, a common question is "How many additional cancer cases occurred due to radiation exposures?". This is often generalized to the question of how many cases are background cases and how many cases are excess cases. These are calculated by splitting a poisson model into a background term and an excess term. In Colossus the background term is assumed to be the first term, and every other term is assumed to be causing excess cases. Colossus has a function, RunPoissonEventAssignment, which calculates the number of background/excess cases for both average predicted counts and true counts. Let us assume we have the following  model for event rate:

<p class="text-center" style="background-color: aliceblue">
$$
\begin{aligned}
    R(\beta,x, \alpha, D)=\exp(\beta \cdot x)*(1 + \alpha \cdot D)
\end{aligned}
$$
</p>

```{r}
names <- c("x", "D")
term_n <- c(0, 1)
tform <- c("loglin", "lin")
modelform <- "M"
fir <- 0

a_n <- c(0.1, 0.1)
```

Our total rate ($R$) is composed of a background rate ($R_{BK}$) and excess rate ($R_{EX}$). The cases each row have a total ($c$) and background/excess count ($c_{BK}, c_{EX}$). Additionally, every row has a measure of person-time ($t$). Colossus also computes the predicted number of total, background, and excess cases ($P, P_{BK}. P_{EX}$). For every model we assume the average number of background cases are the background rate multiplied by time, the remaining cases are excess, and the true number of background/excess cases are proportional to the predicted cases.

<p class="text-center" style="background-color: aliceblue">
$$
\begin{aligned}
    R = \exp(\beta \cdot x)*(1 + \alpha \cdot D)\\
    R_{BK} = \exp(\beta \cdot x)\\
    P = P_{BK} + P_{EX}\\
    P = R * t\\
    P_{BK} = R_{BK} * t\\
    P_{EX} = P - P_{BK}\\
    c = c_{BK} + c_{EX}\\
    c_{BK} = c * \frac{P_{BK}}{P}\\
    c_{EX} = c * \frac{P_{EX}}{P}
\end{aligned}
$$
</p>

Colossus returns two matrices, one for the true cases and one for the predicted cases. Each matrix has three columns for the events assigned to background, excess, and total.

```{r, eval=FALSE}
names <- c("x", "D")
term_n <- c(0, 1)
tform <- c("loglin", "lin")
modelform <- "M"
fir <- 0
a_n <- c(0.1, 0.1)
keep_constant <- rep(0, length(names))
der_iden <- 0
control <- list("Ncores" = 2, "maxiters" = c(1, 1), "verbose" = F, "abs_max" = 0.1)
model_control <- list("strata" = FALSE, "basic" = FALSE, "single" = FALSE, "CR" = FALSE)
e <- RunPoissonEventAssignment(df, pyr, event, names, Term_n, tform, keep_constant, a_n, modelform, fir, der_iden, control)

e0 <- e$predict
e1 <- e$caused

BK <- e0[, 1]
EX <- e0[, 2]
Total <- e0[, 3]
```