---
title: "3: Stratified contrasts"
output: rmarkdown::html_vignette
bibliography: REFERENCES.bib
link-citations: true
vignette: >
  %\VignetteIndexEntry{3: Stratified contrasts}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

## Confidence intervals for stratified comparisons of independent binomial or Poisson rates

Stratified analysis might be required for combining results from multiple studies in a meta-analysis, or adjusting clinical trial results for factors used in a stratified randomisation. Associated tests against a null hypothesis of common effects over strata (homogeneity) can also be useful for examining subgroup effects in a clinical trial. The illustration below uses data from a meta-analysis of 9 trials studying the effectiveness of graduated compression stockings for prevention of postoperative deep vein thrombosis (DVT) [from @roderick2005]:

```{r}
data(compress, package = "ratesci")
strat_rd <- scoreci(x1 = compress$event.gcs, 
                   n1 = compress$n.gcs, 
                   x2 = compress$event.control, 
                   n2 = compress$n.control, 
                   contrast = "RD", 
                   stratified = TRUE)
strat_rd$estimates
```

```{r}
strat_rd$pval
```

The Qtest object provides a heterogeneity test and related quantities, including an assessment of qualitative heterogeneity (indicating whether treatment effects are in opposite directions in different strata). All of which are derived using the score statistic and its estimated variance, for a consistent approach - see [@laud2017 Supplementary Appendix S4].

```{r}
strat_rd$Qtest
```

````{=html}
<!--
```{r}
strat_rr <- scoreci(x1 = compress$event.gcs, 
                   n1 = compress$n.gcs, 
                   x2 = compress$event.control, 
                   n2 = compress$n.control, 
                   contrast = "RR", 
                   stratified = TRUE)
strat_rr$Qtest
```
-->
````

It is important to note that heterogeneity tests often have low power, so it is recommended to inspect the stratum-specific estimates as well[@greenland1982]. The stratdata object provides estimates and intervals for each stratum, along with details of stratum weights and contributions to the Q-statistic (these may be further examined using the `hetplot` argument).

```{r}
strat_rd$stratdata
```

### Random effects

In this instance, there is weak evidence ($p = 0.07$) that the treatment effect (on the RD scale) varies across strata. (Estimation on the RR contrast scale gives more consistency across strata.) For the sake of illustration, a random effects analysis of RD would be obtained as follows, giving a wider interval that incorporates the stratum variability. The `random = TRUE` option invokes the t-distribution asymptotic score (TDAS) method [@laud2017], which modifies the asymptotic score methodology using formulae from the Hartung-Knapp-Sidik-Jonkman (HKSJ) random effects meta-analysis method (with superior performance compared to the DerSimonian-Laird method).

```{r}
strat_rd_rand <- scoreci(x1 = compress$event.gcs, 
                   n1 = compress$n.gcs, 
                   x2 = compress$event.control, 
                   n2 = compress$n.control, 
                   contrast = "RD", 
                   stratified = TRUE,
                   random = TRUE,
                   prediction = TRUE)
strat_rd_rand$estimates
```

Note that the TDAS method does not include a skewness correction, so when `random = TRUE`, the `skew` argument only affects the `stratdata` output element.

A prediction interval for the treatment effect in a new study [@higgins2008] can be obtained using `prediction = TRUE`:

```{r}
strat_rd_rand$prediction
```

## References