---
title: "rule-check"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{rule-check}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

```{r setup}
library(delaydiscount)
```

The jb_rule_check function can be used to apply the rule check for the purpose of filtering out subjects who fail.

```{r}
remedi_rc_result <- jb_rule_check(remedi)
head(remedi_rc_result)
```

The resulting data frame has an observation for each subject-within-group, with variables corresponding to whether or not each rule was passed. A value of TRUE indicates that the rule check was passed.

C1 fails if there are two or more increases in the indifference point of 20\% of the total amount between consecutive time points. C2 fails if the difference in the indifference point between the first and last time points is not more than 10\% of the total amount.

In order to make use of the rule check results, after the data frame is prepared, the rule check data can be merged with the original dataframe, and then observations corresponding to subjects who failed the rule check can be removed from the data.

```{r}
remedi_with_rc <- merge(remedi, remedi_rc_result)
remedi_rc_pass <- dplyr::filter(remedi_with_rc, 
                                C1 == TRUE, C2 == TRUE)
```

After that, the remainder of the workflow proceeds as it would otherwise, starting from running the `prepare_data_frame` function on the dataset with rule check failures filtered out. The `prepare_data_frame` function performs helper 
calculations for our other functions.

```{r}
prep_remedi <- prepare_data_frame(remedi_rc_pass)
```

One of the things that the `prepare_data_frame` function does is transform the delay
and indifference variables to linearize the model.

Note that the hyperbolic model for the discounting curve is $D(t) = \frac{1}{1+kt}$.

Then we will have $\log(\frac{1}{D(t)} - 1) = \log(k) + \log(t)$.

We assume that the transformed observed indifference point $\tilde D(t_{ijc})$ will follow the model

$\log(\frac{1}{\tilde D(t_{ijc})} - 1) = \log(k_{ic}) + \log(t_{ijc}) + \epsilon_{ijc},$

where $\epsilon_{ijc} \sim N(0, \sigma^2)$, $i$ is an index for subject, $j$ an index for time point, and $c$ is an index for group, and

$\log(k_{ic}) \sim N(\theta_c, \frac{g\sigma^2}{T})$, where $\theta_c$ is the population mean of the $\log(k_{ic})$ for subjects in group $c$, and $T$ is the number of time points observed for each subject.

Using the prepared data frame, you can get estimates of the $log(k)$ values for
each subject using the `get_subj_est_ln_k` function.

```{r}
ln_k_ests <- get_subj_est_ln_k(prep_remedi)
head(ln_k_ests)
```

Our model treats the $\log(k)$ values for individual subjects as the result of a combination
of a fixed group effect and a random subject effect. To get the fit of the linearized
hyperbolic model, use the `dd_hyperbolic_model` function.

```{r}
model_fit <- dd_hyperbolic_model(prep_remedi)
```

The object produced by this method is a list containing several components.

The group mean $\log(k)$ estimates (i.e. the $\theta_c$) can be gotten from the `ln_k_mean` component.

```{r}
model_fit$ln_k_mean
```

These are estimates of the mean of the distribution from which the $\log(k_{ic})$ values for subjects in group $c$ have been realized.

The variance component estimates can be obtained from the `var` component.

```{r}
model_fit$var
```

`sigma_sq` is the estimate of the variance of the transformed indifference value
conditional on the subject effect.

`g` is related to the variance of the subject random effects: specifically, the
variance of the subject random effect is equal to $\frac{g\sigma^2}{T}$, where 
$T$ is the number of time points observed for each subject.

These mean and variance parameters are estimated through maximum likelihood 
estimation.

An overall F-test for the equality of all group mean parameters can be found in
the `model_test` component.

```{r}
model_fit$model_test
```

Pairwise F-tests for equality of group mean parameters can be obtained from the
`pairwise_f_tests` component. The data frame contains an F-test for each pair.

```{r}
model_fit$pairwise_f_tests
```

Note that, as with other R functions such as `lm` and `glm`, these p-values are not adjusted for multiplicity.
