---
title: "Package Introduction"
package: RobinCar2
output:
  rmarkdown::html_vignette:
          toc: true
vignette: |
  %\VignetteIndexEntry{Package Introduction}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

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

RobinCar2 provides robust covariate adjustment methods for estimating and
inferring treatment effects through generalized linear models (glm) under
different randomization schema.

# Common Usage
A minimal call of `robin_lm()` and `robin_glm()`, consisting of only formula,
data arguments and the randomization scheme, will produce an object of class
`treatment_effect`.

```{r}
library(RobinCar2)
head(glm_data)
```

## Data Introduction

In the `glm_data`, we have the following columns:

1. `id` is the patient identifier.
1. `treatment` is the treatment assignment.
1. `s1` is the first stratification factor.
1. `s2` is the second stratification factor.
1. `covar` is the continuous covariate.
1. `y` is the continuous outcome.
1. `y_b` is the binary outcome.

## Obtain Treatment Effect for Continuous Outcomes Using the General Variance

For the continuous outcome `y`, the linear model includes `covar` as a covariate,
`s1` as a stratification factor. The randomization scheme is a permuted-block
randomization stratified by `s1`. The model formula also includes the treatment
by stratification interaction as `y ~ treatment * s1 + covar`.

```{r}
robin_lm(y ~ treatment * s1 + covar,
  data = glm_data,
  treatment = treatment ~ pb(s1)
)
```

We can also use the Huber-White variance estimator by setting `vcov = "vcovHC"`.
Please note that in this case, the model formula should not contain the
treatment by stratification (covariate) interaction.

```{r}
robin_lm(y ~ treatment + s1 + covar,
  data = glm_data,
  treatment = treatment ~ pb(s1),
  vcov = "vcovHC"
)
```

Note that `robin_glm` can also handle continuous outcomes using the default
family and the default link function `family = gaussian()`.

## Obtain Treatment Effect for Binary Outcomes

For binary outcomes, the logistic model includes `covar` as a covariate,
`s1` as a stratification factor. The randomization scheme is a permuted-block
randomization stratified by `s1`. The model formula also includes the treatment
by stratification interaction as `y_b ~ treatment * s1 + covar`. Note here we need
to specify `family` to be `binomial(link = "logit")`.

```{r}
robin_glm(y_b ~ treatment * s1 + covar,
  data = glm_data,
  treatment = treatment ~ pb(s1),
  family = binomial(link = "logit")
)
```

## Obtain Treatment Effect for Counts

For counts, the log link model includes `covar` as a covariate,
`s1` as a stratification factor. The randomization scheme is a permuted-block
randomization stratified by `s1`. The model formula also includes the treatment
by stratification interaction as `y_count ~ treatment * s1 + covar`. Note here
we need to specify `family` to be `poisson(link = "log")` to use the Poisson
model or to be `MASS::negative.binomial(theta = NA)` to use the negative
binomial model. A fixed `theta` could be provided if it is known.

```{r}
glm_data$y_count <- rpois(nrow(glm_data), lambda = 20)
robin_glm(
  y_count ~ treatment * s1 + covar,
  data = glm_data,
  treatment = treatment ~ pb(s1),
  family = MASS::negative.binomial(theta = 1)
)
```

## Using Different Covariate-Adaptive Randomization Schema

If the randomization schema is not permuted-block randomization, we can use
other randomization schema. Currently RobinCar2 supports `sr` for the simple
randomization (this was previously called `sp`), `pb` for the permuted-block 
randomization, and `ps` for the Pocock-Simon randomization.

```{r}
robin_glm(y_b ~ treatment * s1 + covar,
  data = glm_data,
  treatment = treatment ~ ps(s1),
  family = binomial(link = "logit")
)
```

## Obtain the Confidence Intervals for the Marginal Means and contrast

To obtain the confidence interval, we can use `confint` function.

Given the following model
```{r}
robin_res <- robin_glm(y_b ~ treatment * s1 + covar,
  data = glm_data,
  treatment = treatment ~ ps(s1),
  family = binomial(link = "logit"),
  contrast = "log_risk_ratio"
)
robin_res
```

It is easy to obtain the confidence interval matrix for the marginal mean, at specified level.
If `parm` is not provided, the complete matrix (all treatment groups) will be provided.

```{r}
confint(robin_res$marginal_mean, parm = 1:2, level = 0.7)
confint(robin_res$marginal_mean, level = 0.7)
```

Similarly for the contrast, however it has an additional argument `transform` to provide the confidence interval at transformed level.
Thus, standard error is removed because it does not make sense anymore.
By default, if the `log_risk_ratio` or `log_odds_ratio` is used as contrast, the `confint` will transform it back using exponential function.
You can also specify the `transform` to be `identity` to avoid the transformation.

```{r}
confint(robin_res$contrast)
confint(robin_res$contrast, transform = identity)
```