GRCFE: Generate row-column factorial experiments

Description

Tools for constructing row-column factorial experiment layouts for estimating main effects and two-factor interactions. The main entry point is generate_2fi_rowcol(), which chooses theorem-based, heuristic, or search-based construction depending on the number of factor levels and the requested fraction size.

Design notation

Let s be the number of levels, p the number of row blocking factors, q the number of column blocking factors, and n the number of treatment factors. The run size is s^(p + q) and k = n - (p + q) indicates the degree of fractionation used by the construction wrappers.

Author(s)

Maintainer: Sukanta Dash sukanta.iasri@gmail.com

Authors:

• Amrit Kumar Paul apaul_66@yahoo.com

• Med Ram Verma drmrverma@gmail.com

• Anurag Rawat anuragrawat5683@gmail.com

Construct a reverse-identity matrix

Description

Construct a reverse-identity matrix

Usage

H_matrix(p)

Arguments

Value

A p by p reverse-identity matrix.

Compute a D-optimality aliasing objective

Description

Computes the negative log determinant of the information matrix for a row-column model containing row effects, column effects, main effects, and all two-factor treatment interactions.

Usage

alias_objective_Dopt(design_mat, s)

Arguments

Value

Numeric scalar. Smaller values indicate better D-optimality. Returns Inf if the regularized information matrix is not positive definite.

Build a generator matrix for theorem-based row-column designs

Description

Dispatches to the implemented theorem-based generator-matrix construction for full designs and one-replicate fractions.

Usage

build_G(s, p, q, n)

Arguments

Value

Integer generator matrix with p + q rows and n columns.

See Also

generate_row_column_design

Examples

G <- build_G(s = 3, p = 1, q = 1, n = 2)
G
stopifnot(nrow(G) == 2, ncol(G) == 2)

Build a one-replicate-fraction generator matrix for odd prime levels

Description

Constructs the generator matrix used for one-replicate fractional row-column designs when s is an odd prime and n = p + q + 1.

Usage

build_G_frac_oddprime(s, p, q)

Arguments

Value

Integer generator matrix with p + q rows and p + q + 1 columns.

Build a one-replicate-fraction generator matrix for two levels

Description

Build a one-replicate-fraction generator matrix for two levels

Usage

build_G_frac_twolevel(p, q)

Arguments

Value

Integer generator matrix for the implemented two-level fractional construction.

Build a full-design generator matrix for odd prime levels

Description

Constructs the generator matrix used for full row-column factorial designs when s is an odd prime and n = p + q.

Usage

build_G_full_oddprime(s, p, q)

Arguments

Value

Integer generator matrix with p + q rows and p + q columns.

Canonicalize a projective-space vector

Description

Scales a nonzero vector over GF(s) so that its first nonzero entry is equal to 1.

Usage

canonicalize_vec(v, s)

Arguments

Value

Integer vector in canonical projective form.

Evaluate unconfounded main effects and two-factor interactions

Description

Checks whether treatment main effects are unconfounded with the remaining model terms and counts the number of unconfounded two-factor interactions in a row-column factorial design.

Usage

eval_2fi_from_design(design_df, s, tol = 1e-08)

Arguments

Value

A list with components main_ok, a logical flag indicating whether all main effects are unconfounded, and unconf_2fi_num, the number of unconfounded two-factor interactions.

Examples

res <- generate_2fi_rowcol(s = 3, p = 1, q = 1, n = 2)
ev <- eval_2fi_from_design(res$design, s = 3)
ev
stopifnot(is.logical(ev$main_ok), length(ev$main_ok) == 1)

Extend a base generator matrix using projective-space points

Description

Adds projective-space columns so that generator-column multiplicities satisfy the near-balanced requirements used by the implemented theorem-based constructions.

Usage

extend_with_pg_points(base, d, s, n_total)

Arguments

Value

Matrix of additional generator columns. May have zero columns if no extension is needed.

Generate a 2FI-optimal row-column factorial design

Description

Constructs a row-column design for estimating main effects and two-factor interactions (2FIs). For prime s, theorem-based generator matrices are used when available. For composite s, and for the full two-level case, the function falls back to a D-optimality heuristic.

Usage

generate_2fi_optimal_rowcol(
  s,
  p,
  q,
  n = p + q,
  max_iter_nonprime = 5000,
  n_starts_nonprime = 5,
  verbose_nonprime = FALSE
)

Arguments

Details

The function supports p + q <= n. The heuristic path currently supports k = n - (p + q) in 0:3. The theorem-based path supports prime s when the corresponding generator-matrix construction is implemented.

Value

A list with components s, p, q, n, G, design, and construction metadata. For theorem-based designs, G is the generator matrix. For heuristic designs, G = NULL and D_opt_objective is included.

References

Zhang, Y., Pan, J. and Shi, L. (2025). Construction of 2fi-optimal row-column designs. Journal of Statistical Planning and Inference, 234, 106192. ISSN 0378-3758. doi:10.1016/j.jspi.2024.106192

See Also

generate_2fi_rowcol, build_G

Examples

res <- generate_2fi_optimal_rowcol(s = 3, p = 1, q = 1, n = 2)
head(res$design)
stopifnot(nrow(res$design) == 3^(1 + 1))

Generate a row-column design for main effects and two-factor interactions

Description

Main user-facing wrapper for generating row-column factorial layouts. The function automatically chooses between theorem-based constructions, heuristic D-optimal search, and random generator-matrix search depending on s, p, q, n, and mode.

Usage

generate_2fi_rowcol(
  s,
  p,
  q,
  n,
  mode = c("auto", "theorem", "search"),
  max_iter_nonprime = 5000,
  n_starts_nonprime = 5,
  verbose_nonprime = FALSE,
  max_tries_search = 5000,
  N_max_runs_search = 10000,
  verbose_search = FALSE
)

Arguments

Details

Let k = n - (p + q). For non-prime s, this wrapper currently supports k in 0:3 through the heuristic path. For prime s, theorem mode is available for k = 0 or k = 1; search mode is intended for k = 2 or k = 3.

Value

A list containing the generated design and associated construction information. The design component is a data frame with columns Row, Col, and treatment factors F1, F2, ..., Fn.

See Also

generate_2fi_optimal_rowcol, search_2fi_optimal_G_k23, eval_2fi_from_design

Examples

# A small theorem-based row-column layout using the auto wrapper
res <- generate_2fi_rowcol(s = 3, p = 1, q = 1, n = 2, mode = "auto")
dim(res$design)
head(res$design)
stopifnot(is.data.frame(res$design))

Generate projective-space points over GF(s)

Description

Generate projective-space points over GF(s)

Usage

generate_pg_points(d, s)

Arguments

Value

Matrix whose rows are canonical representatives of the points in PG(d - 1, s).

Generate the row-column treatment layout from a generator matrix

Description

Converts a generator matrix G into a row-column design by combining the row-generator and column-generator parts over GF(s).

Usage

generate_row_column_design(G, s, p, q)

Arguments

Value

A list containing s, p, q, n, G, design, Gc, and Gr. The design component is a data frame with columns Row, Col, and F1, ..., Fn.

Examples

G <- build_G(s = 3, p = 1, q = 1, n = 2)
res <- generate_row_column_design(G, s = 3, p = 1, q = 1)
head(res$design)
stopifnot(all(c("Row", "Col", "F1", "F2") %in% names(res$design)))

Heuristic row-column layout for composite or unsupported cases

Description

Uses random starts and coordinate exchange to select a run subset and assign treatments to a row-column array by minimizing a D-optimality aliasing objective.

Usage

heuristic_rowcol_composite(
  s,
  p,
  q,
  n,
  max_iter = 5000,
  n_starts = 5,
  verbose = FALSE,
  max_full = 1e+07
)

Arguments

Value

A list containing the heuristic design, objective value, and metadata.

Multiplicative inverse in GF(s)

Description

Multiplicative inverse in GF(s)

Usage

inv_mod_scalar(a, s)

Arguments

Value

Integer scalar giving the multiplicative inverse of a modulo s.

Test whether an integer is prime

Description

Test whether an integer is prime

Usage

is_prime(s)

Arguments

Value

Logical scalar. TRUE if s is prime and FALSE otherwise.

Reduce values modulo s

Description

Reduce values modulo s

Usage

modp(x, s)

Arguments

Value

x reduced to the range 0, ..., s - 1.

Search for prime-level generator matrices for k = 2 or k = 3

Description

Performs a random search over generator matrices for prime-level designs when k = n - (p + q) is 2 or 3, retaining the design with the largest number of unconfounded two-factor interactions among candidates with unconfounded main effects.

Usage

search_2fi_optimal_G_k23(
  s,
  p,
  q,
  n,
  max_tries = 5000,
  N_max_runs = 10000,
  verbose = FALSE
)

Arguments

Value

A list containing the best generator matrix, design, number of unconfounded two-factor interactions, and search metadata.

Examples

# The search is random, so a deliberately small number of tries may or may
# not find a feasible design on every platform. The example is therefore
# written to be executable and checkable without requiring stochastic success.
set.seed(1)
res <- try(
  search_2fi_optimal_G_k23(
    s = 5, p = 1, q = 1, n = 4,
    max_tries = 25, N_max_runs = 25, verbose = FALSE
  ),
  silent = TRUE
)
stopifnot(is.list(res) || inherits(res, "try-error"))