---
title: "Separating design gains from analysis-model gains with cwad"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Separating design gains from analysis-model gains with cwad}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## The problem

A design comparison in plant breeding usually changes two things at once: how
plots are allocated among genotypes, and whether the analysis borrows
information through a kinship matrix. The resulting gain in precision is then
reported as a property of the design, although most of it may belong to the
analysis model.

`cwad` keeps the two apart. Every allocation is scored under **both** analysis
models, so the attribution can be read off a two-way table.

## A worked example

```{r}
library(cwad)
sig2g <- 1; sig2e <- 2; alpha <- sig2e / sig2g
g <- make_fs_G(c(rep(12, 3), rep(4, 5), rep(1, 10)))
Ginv <- solve(g$G); N <- nrow(g$G)
N
```

Two allocations on the same plot budget: uniform replication, and the
A-optimal connectivity-weighted allocation.

```{r}
r_unif <- rep(2, N)
r_cwad <- greedy_alloc(Ginv, B = 2 * N, alpha = alpha, sig2e = sig2e)
table(r_cwad)
```

Replication tracks the complement of genetic connectivity: the isolated
founders are replicated more than the large-family sibs.

```{r}
tapply(r_cwad, g$connectivity, mean)
```

## The crossed comparison

```{r}
cmp <- compare_designs(g$G, alpha, sig2e,
                       list(`Uniform r=2` = r_unif, CWAD = r_cwad))
cmp[, c("allocation", "PEV_noG", "PEV_kin")]
```

Reading *across* a row isolates the analysis model; reading *down* a column
isolates the allocation. The decomposition of the naive gain is returned
directly:

```{r}
cmp[, c("allocation", "gain_analysis_pp", "gain_allocation_pp", "gain_total_pp")]
```

Almost all of the apparent gain is the kinship-based analysis, which costs
nothing to adopt; the allocation itself contributes very little. On the
200-genotype example of `inst/scripts/reproduce.R` the split is 22.94
percentage points against 0.34.

## Comparing against a feasible control

When the budget is not an integer multiple of the number of genotypes, a
"uniform r = B/N" allocation cannot be planted. `balanced_control()` returns
integer-feasible comparators so that the optimised allocation is judged against
a design a breeder could actually use.

```{r}
B <- round(1.5 * N)
ctrl <- balanced_control(B, N, reps = 5)
mean(vapply(ctrl, function(r) pev_pairwise(r, Ginv, alpha, sig2e), numeric(1)))
pev_pairwise(greedy_alloc(Ginv, B, alpha, sig2e, check = FALSE),
             Ginv, alpha, sig2e)
```

## Stress tests

Both stress tests run every allocation under both analysis models, so the
contribution of reduced replication is never confounded with the contribution
of borrowing from relatives. See `?sim_transgressive` and `?sim_wrongG`, and
`inst/scripts/reproduce.R` for the full figures reported in the accompanying
article.