---
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}
Sys.setenv(OMP_THREAD_LIMIT = 1) # Reducing core use, to avoid accidental use of too many cores
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 excess terms. 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, `EventAssignment()`, 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, eval=FALSE}
a_n <- c(0.1, 0.1)
model <- Pois(pyr, event) ~ loglinear(x, 0) + plinear(D, 1) + Multiplicative()
poisres <- PoisRun(model, df, a_n = a_n)
```

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 is the background rate multiplied by time, the remaining cases are excess, and the true number of background/excess cases is 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. This provides information on both the relative amount of background and excess cases, as well as differences between the expected and true number of cases.

```{r, eval=FALSE}
e <- EventAssignment(poisres, df)

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

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

`EventAssignment()` can also be used to calculate the number of cases over the confidence interval of a model parameter. The excess and background cases are evaluated at the midpoint, as well as the risk model optimized with the model parameter held constant at the boundary values. This produces three lists of matrices, for the lower limit, midpoint, and upper limit. At each point the standard matrices for observed and predicted events are produced. This method can also be applied to the results of a likelihood-based boundary regression to evaluate the distribution of cases at the likelihood-based confidence interval. In this case the parameter number and significance level are taken from the likelihood boundary result, and do not need to be provided.

```{r, eval=FALSE}
e <- EventAssignment(poisres, df, check_num = 2, z = 1.96)

e_lower <- e$lower_limit$caused
e_mid <- e$midpoint$caused
e_high <- e$upper_limit$caused

EX_low <- e_lower[, 2]
EX_mid <- e_mid[, 2]
EX_high <- e_high[, 2]

p_bound <- LikelihoodBound(poisres, df, para_number = 2, alpha = 0.05)
e <- EventAssignment(p_bound, df)
```
