---
title: "Nested resolvable designs and associated uniform designs: the 2013 paper, reproduced and generalised"
author: "Mohamed Laib, Abla Boudraa and Zebida Gheribi-Aoulmi"
output: rmarkdown::html_vignette
bibliography: PGM2.bib
vignette: >
  %\VignetteIndexEntry{Nested resolvable designs and associated uniform designs: the 2013 paper, reproduced and generalised}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette reproduces, with the current version of **PGM2**, all the
worked examples and both parameter tables of the paper that the package
implements [@boudraa2013]:

> A. Boudraa, Z. Gheribi-Aoulmi and M. Laib (2013). *Recursive method for
> construction of resolvable nested designs and uniform designs associated.*
> International Journal of Research and Reviews in Applied Sciences, 17(2),
> 167--176.

The paper states its theory for a projective geometry $PG(m, p)$ over a
Galois field $GF(p)$ of **any prime order** $p$, but versions $\le$ 1.2 of
the package implemented only $p = 2$. Version 2.0 implements the general
prime case, so both Table 1 ($p = 2$) and Table 2 ($p = 3$) of the paper
can now be regenerated by the package — as done at the end of this
vignette.

## The construction in brief

A balanced incomplete block design ($BIB$) with parameters
$(v, b, r, k, \lambda)$ arranges $v$ treatments into $b$ blocks of size
$k < v$ so that every treatment occurs in $r$ blocks and every pair of
treatments concurs in $\lambda$ blocks. The method of the paper identifies
treatments with the points of $PG(m, p)$ and blocks with its hyperplanes
[@dugue1958], and then recurses:

1. **Stage 1** — the hyperplanes of $PG(m,p)$ form a symmetric $BIB$ of the
   *first generation* (`BIB`).
2. **Next generations** — deleting a block (a sub-variety $V(i_1)$) and
   intersecting it with the remaining blocks yields the $BIB$ of
   $PG(m-1, p)$, the *second generation* (`Gen`), and so on recursively.
3. **Resolvable designs** — deleting a block together with its treatments
   leaves a resolvable $BIB$ (`Resolvable`): its blocks partition into $r$
   parallel classes of $p$ blocks each (this is the design of the affine
   geometry $AG(m,p)$ [@bose1942]).
4. **Uniform designs** — each resolvable design is converted into a
   symmetric uniform design $U(p^m, p^{r})$ by the correspondence of
   @fang2003 [see also @fang2004]: parallel classes become factors and
   block membership within a class gives the level (`Uniform`).

The driver `Steps` runs the whole recursion and returns the designs of all
stages.

## Example 1 of the paper: $PG(3,2)$

Step 1 gives the first-generation $BIB$ with parameters
$v_1 = b_1 = 15$, $r_1 = k_1 = 7$, $\lambda_1 = 3$; step 2 gives
second-generation designs with parameters $(7, 3, 1)$:

```{r}
X <- BIB(3)
c(V = X$V, B = X$B, R = X$R, K = X$K, Lambda = X$Lambda)

X2 <- Gen(1, X$BIB)
c(V = X2$V, B = X2$B, R = X2$R, K = X2$K)
```

## Example 2 of the paper: the chain $BIB \to RBIB \to UD$

The paper's Example 2 (its pages 174--175) builds, from $PG(3,2)$, the
$BIB(15, 7, 3)$, extracts the $RBIB(8, 14, 7, 4, 3)$ and converts it into
the uniform design $U(8, 2^7)$:

```{r}
bib <- BIB(3)$BIB
bib

resolvable <- Resolvable(1, bib)
resolvable$RBIB

Uniform(resolvable$RBIB)$UD
```

The matrices above coincide (up to the point numbering, which version 2.0
keeps identical to versions $\le$ 1.2 for $p = 2$) with the listings printed
in the paper.

## Example 3 of the paper: a more economic resolvable design

The paper's Example 3 unites the second-generation designs of $PG(3,2)$
obtained by deleting each block in turn, removes the treatments of a chosen
first-generation block, and converts the result — an $RBIB(8, 28, 7, 2, 1)$
— into the uniform design $U(8, (2^2)^7)$ with four-level factors:

```{r}
bib <- BIB(3)$BIB
mat <- NULL
for (i in 1:15) mat[[i]] <- Gen(i, bib)$BIB2
x <- Reduce("rbind", mat)
e <- dim(x)[1]; b <- dim(x)[2]
v <- bib[1, ]
for (i in 1:e) for (j in 1:b) if (any(x[i, j] == v)) x[i, j] <- 0
for (i in e:1) if (all(x[i, ] == 0)) x <- x[-i, ]
s <- x[1, ]; s <- s[s > 0]
x1 <- matrix(nrow = dim(x)[1], ncol = length(s))
for (i in 1:dim(x)[1]) x1[i, ] <- x[i, ][x[i, ] > 0]
A <- unique(x1)
A

ud <- Uniform(A)
ud$UD
```

## All stages at once: `Steps`

```{r}
s <- Steps(4, 1)
names(s)
sapply(s$UDs, function(u) c(runs = u$n, factors = u$F))
```

## Reproducing Table 1 ($p = 2$) and Table 2 ($p = 3$) of the paper

The helper below extracts, for each geometry $PG(m,p)$, the parameters of
the first-generation $BIB$, of the $RBIB$ and of the associated uniform
design — the first three rows of each table of the paper:

```{r}
table_rows <- function(p, ms) {
  out <- NULL
  for (m in ms) {
    X <- BIB(m, p)
    Y <- Resolvable(1, X$BIB)
    U <- Uniform(Y$RBIB)
    out <- rbind(out, data.frame(
      geometry = sprintf("PG(%d,%d)", m, p),
      BIB = sprintf("(%d, %d, %d)", X$V, X$K, X$Lambda),
      RBIB = sprintf("(%d, %d, %d, %d, %d)", Y$V, Y$B, Y$R, Y$K, X$Lambda),
      UD = sprintf("U(%d, %d^%d)", U$n, p, U$F)))
  }
  out
}

knitr::kable(table_rows(2, 2:4), caption = "Paper, Table 1 (p = 2)")
knitr::kable(table_rows(3, 2:4), caption = "Paper, Table 2 (p = 3)")
```

Both agree with the published tables: for $p=2$ the designs
$BIB(7,3,1)$, $BIB(15,7,3)$, $BIB(31,15,7)$ with resolvable designs
$(4,6,3,2,1)$, $(8,14,7,4,3)$, $(16,30,15,8,7)$; for $p=3$ the designs
$BIB(13,4,1)$, $BIB(40,13,4)$, $BIB(121,40,13)$ with resolvable designs
$(9,12,4,3,1)$, $(27,39,13,9,4)$, $(81,120,40,27,13)$.

## The reduced designs $Q^*_n$ directly: `Qn`

The manual juxtaposition of Example 3 is automated by `Qn(m, n, p)`,
which builds the reduced resolvable design $Q^*_n$ and its uniform
design $U(p^m, (p^n)^{r})$ for any stage. Its parameters match the
paper's tables, e.g. $Q^*_2(16, 140, 35, 4, 7)$ for $PG(4,2)$:

```{r}
Q <- Qn(4, 2)
c(V = Q$V, B = Q$B, R = Q$R, K = Q$K, Lambda = Q$Lambda)

identical(dim(Qn(3, 2)$UD), dim(ud$UD))  # the design of Example 3
```

Any two distinct runs of a `Qn` design coincide in exactly `Lambda`
factors (the designs are *equidistant*), so every stage attains the
discrete-discrepancy lower bound of Fang et al. (2003), and levels
refine coherently across stages.

## Beyond the paper: any prime order

Nothing restricts the recursion to the orders tabulated in the paper — any
prime works:

```{r}
Z <- BIB(2, p = 5)          # BIB(31, 6, 1): the projective plane of order 5
W <- Resolvable(1, Z$BIB)   # RBIB(25, 30, 6, 5, 1): AG(2, 5)
Uniform(W$RBIB)$UD          # U(25, 5^6)
```

## References