---
title: "Dose Response Formula Terms"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Dose Response Formula Terms}
  %\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)
```

## Dose Response Formula

Colossus features a term composed of the sum of multiple linear and non-linear elements which can be used to define many dose-response curves used in radiation epidemiology. These terms are referred to as dose-response terms, but there is nothing prohibiting them from being used for non-dose covariates. The following formulae are available, reproduced from the starting description vignette.

<p class="text-center" style="background-color: aliceblue">
$$
\begin{aligned}
    S_{NL}=\sum_i (\alpha_i \times \exp(x_i \cdot \beta_i)) + \sum_i (\beta_i \cdot (x_i)^2) + \sum_i F_{LT} + \sum_i F_{STP} + \sum_i F_{LQ} + \sum_i F_{LEXP}\\
    F_{LT} = \begin{cases} \alpha_i \cdot (x-\beta_i) & (x>\beta_i) \\ 0 &\text{else} \end{cases}\\
    F_{STP} = \begin{cases} \alpha_i & (x>\beta_i) \\ 0 &\text{else} \end{cases}\\
    F_{LQ} = \begin{cases} \beta_i \cdot x & (x>\alpha_i) \\ \lambda_i \cdot x^2 + \nu_i &\text{else} \end{cases}\\
    F_{LEXP} = \begin{cases} \beta_i \cdot x & (x>\alpha_i) \\ \lambda_i - \exp{(\nu_i + \mu \cdot x)} &\text{else} \end{cases}\\
    T_j=S_{LL,j} \times S_{L,j} \times S_{PL,j} \times S_{NL,j}
\end{aligned}
$$
</p>

For every subterm type, there are between 1 and 3 parameters that fully define the curve. The Linear-Quadratic and Linear-Exponential curves are continuously differentiable, so there are only 2-3 parameters that can be set.

<p class="text-center" style="background-color: aliceblue">
$$
\begin{aligned}
    \lambda_{LQ} = \beta_{LQ}/(2\alpha_{LQ})\\
    \nu_{LQ} = (\beta_{LQ}*\alpha_{LQ})/2\\
    \nu_{LEXP} = \ln(\beta_{LEXP})-\ln(\mu_{LEXP})+\mu_{LEXP}*\alpha_{LEXP}\\
    \lambda_{LEXP} = \beta_{LEXP}*\alpha_{LEXP}+exp(\nu_{LEXP}-\mu_{LEXP}*\alpha_{LEXP})
\end{aligned}
$$
</p>

## Using The Different subterms

These subterms are used like any other subterm in the model, except that multiple parameters are defined. The following table lists the model subterms used:

| Subterm Type | Equivalent Aliases |
| :---------: | :----------: |
| Exponential | "loglin-dose", "loglinear-dose", "log-linear-dose" |
| Linear Threshold | "lin-dose", "linear-dose", "linear-piecewise" |
| Quadratic | "quadratic", "quad", "quad-dose", "quadratic-dose" |
| Step Function | "step-dose", "step-piecewise" |
| Linear-Quadratic | "lin-quad-dose", "linear-quadratic-dose", "linear-quadratic-piecewise" |
| Linear-Exponential | "lin-exp-dose", "linear-exponential-dose", "linear-exponential-piecewise" |

When applied to a model and used for a regression, each parameter will be listed in the result table. The following table covers what subterm type is listed for each special parameter:

| Subterm | Table Result Entry | Description |
| :---------: | :----------: |  :----------: |
| Exponential | loglin_top | parameter in the exponent of the term, $\beta_i$ |
| Exponential | loglin_slope | parameter multiplied by the exponential assumed to be 1 if not given, $\alpha_i$ |
| Linear Threshold | lin_slope | slope for the linear term, $\alpha_i$ |
| Linear Threshold | lin_int | intercept for the linear term, $\beta_i$ |
| Step Function | step_slope | step function value, $\alpha_i$ |
| Step Function | step_int | step function intercept, $\beta_i$ |
| Quadratic | quad_slope | parameter multiplied by the squared value, $\beta_i$ |
| Linear-Exponential | lin_exp_slope | Linear slope term, $\beta_i$  |
| Linear-Exponential | lin_exp_int | Intercept between linear to exponential, $\alpha_i$|
| Linear-Exponential | lin_exp_exp_slope | Slope term in the exponential, $\mu_i$ |
| Linear-Quadratic | lin_quad_slope | Linear slope term, $\beta_i$|
| Linear-Quadratic | lin_quad_int | Intercept between linear to quadratic, $\alpha_i$ |

The linear-exponential and linear-quadratic curves must be either completely fixed or completely free. In contrast, the exponential, linear threshold, and step-function curves can be partially fixed. The exponential term can be provided with only the covariate in the exponent and assume the magnitude to be 1. The linear threshold and step functions can be provided a fixed threshold covariate, which can be used to define a linear-no-threshold model or a combination of linear and step functions with known thresholds.





