diff --git a/.Rbuildignore b/.Rbuildignore index cd88645..fcc3de8 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -22,6 +22,7 @@ codemeta.json ^Meta$ ^CODE_OF_CONDUCT\.md$ ^doc$ +^\.dir-locals\.el$ \.[Rr][Dd]ata$ \.[Rr]ds$ \.[Xx]lsx$ diff --git a/DESCRIPTION b/DESCRIPTION index ca3e23c..3794a64 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -2,7 +2,7 @@ Type: Package Package: speed Title: Generate Spatially Efficient Experimental Designs Version: 0.0.11 -Authors@R: +Authors@R: c(person(given = "Sam", family = "Rogers", role = c("aut", "cre"), @@ -15,18 +15,26 @@ Authors@R: family = "Taylor", role = "aut", email = "julian.taylor@adelaide.edu.au"), + person(given = "Kai", + family = "Bagley", + email = "kai.bagley@curtin.edu.au", + role = "aut", + comment = c(ORCID = "0009-0004-6579-6959")), person(given = "University of Adelaide", role = c("cph", "fnd"), comment = "https://adelaide.edu.au/"), person(given = "Grains Research and Development Corporation", role = c("cph", "fnd"), - comment = "https://grdc.com.au/")) -Description: The Speed package optimises spatial experimental designs by rearranging - treatments to improve statistical efficiency while maintaining statistical validity. - It employs customisable optimisation metrics, with a default approach that balances - minimising treatment adjacency and maintaining spatial balance. Users can supply their - own optimisation metrics to tailor designs to specific experimental requirements. - The package also includes visualisation tools that allow users to inspect + comment = "https://grdc.com.au/"), + person(given = "Curtin University", + role = c("cph"), + comment = c("http://www.curtin.edu.au/", ROR = "02n415q13"))) +Description: The Speed package optimises spatial experimental designs by rearranging + treatments to improve statistical efficiency while maintaining statistical validity. + It employs customisable optimisation metrics, with a default approach that balances + minimising treatment adjacency and maintaining spatial balance. Users can supply their + own optimisation metrics to tailor designs to specific experimental requirements. + The package also includes visualisation tools that allow users to inspect optimised designs. License: MIT + file LICENSE URL: https://biometryhub.github.io/speed/ diff --git a/NAMESPACE b/NAMESPACE index 5668d18..8cb2cfe 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -11,7 +11,11 @@ export(calculate_balance_score) export(calculate_ed) export(calculate_efficiency_factor) export(calculate_nb) +export(compute_L_projection) +export(cor_ar1) +export(cor_ar1_ar1) export(create_pair_mapping) +export(factorial_contrast_matrix) export(get_edges) export(get_vertices) export(initialise_design_df) @@ -19,6 +23,7 @@ export(initialise_split_design_df) export(initialize_design_df) export(objective_function) export(objective_function_factorial) +export(objective_function_info) export(objective_function_piepho) export(objective_function_signature) export(optim_params) diff --git a/R/objective_fisher.R b/R/objective_fisher.R new file mode 100644 index 0000000..ed3bbf7 --- /dev/null +++ b/R/objective_fisher.R @@ -0,0 +1,728 @@ +#' Objective function using the treatment information matrix +#' +#' Creates an objective function that optimises experimental designs using the +#' Fisher information for treatment contrasts after adjusting for nuisance +#' effects, and takes an optional spatial covariance structure for spatial +#' optimisation. +#' +#' @param layout_df Data frame representing the spatial layout of the +#' experiment. +#' @param swap Column name to swap, usually the treatment. +#' @param spatial_cols Column name of the spatial factors. +#' @param criterion Either \code{"A"} or \code{"D"}, representing A or D +#' optimality. +#' - A-optimality: Minimises \eqn{\mathrm{tr} \left( \mathcal{I}^- +#' \right)}{tr(I⁻)}. +#' - D-optimality: Minimises \eqn{-\log \left| \mathcal{I} \right|}{- +#' log(|I|)} +#' @param L_matrix Optional precomputed projection matrix in grid order, as +#' returned by [compute_L_projection()]. Cannot be supplied with `Sigma`. +#' @param Sigma Optional covariance matrix in grid order (see Details). If both +#' `Sigma` and `L_matrix` are `NULL`, identity covariance is assumed. +#' @param contrast_matrix Named numeric contrast matrix with one column per +#' treatment level. Column names must match the treatment levels exactly once; +#' columns are matched by name, not position. Only these contrasts are required +#' to be estimable and contribute to the optimality criterion. The default +#' targets the complete treatment-contrast space. +#' @param block_column Column name of the design's block factor, with at least +#' two observed blocks. Used when neither `nuisance_formula` nor `L_matrix` +#' is supplied. +#' @param nuisance_formula Optional one-sided formula describing nuisance +#' effects. Used when \code{L_matrix} is not supplied. If omitted, +#' \code{block_column} is treated as a factor. +#' @param tolerance Relative numerical tolerance for rank and estimability +#' checks. +#' @param current_score_obj The current objective result supplied by [speed()] +#' after the initial call. Used to reuse invariant matrix calculations. +#' @param swapped_items The treatments swapped by [speed()]. Changed plot rows +#' are identified from the cached and proposed allocations so repeated +#' treatments and multi-swaps are handled exactly. +#' @inheritParams calculate_adjacency_score +#' @param by Optional column name grouping plots into grids (e.g. `"site"`). +#' `NULL` treats the design as one grid. +#' @param grid_index Optional pre-built list from [grid_indices()], supplied by +#' [speed()] to reuse coordinate validation. Leave `NULL` for direct calls. +#' @param ... Extra parameters passed from \code{speed}. +#' +#' @details +#' The default nuisance model requires a blocked design with at least two +#' observed blocks and no missing block labels. An explicit `nuisance_formula` +#' or `L_matrix` can instead specify a different nuisance model. +#' +#' `Sigma` and `L_matrix` have one row and column per observed plot, ordered by +#' numeric row position and then column position (columns vary fastest), +#' regardless of the row order of `layout_df`. This matches [cor_ar1_ar1()]. +#' For multiple grids, plots are grouped by the factor levels of `by` (sorted +#' labels otherwise) before ordering within each grid. For missing plots, +#' subset the covariance to the observed positions in this order. The +#' projection is cached during optimisation while the covariance and nuisance +#' effects remain unchanged. +#' +#' D-optimality uses a log determinant, so negative scores are valid and do not +#' indicate that the optimum has been reached. +#' +#' Non-estimable requested contrasts receive an infinite score, so invalid +#' designs cannot be preferred to designs with large finite scores. +#' +#' This function computes the treatment information matrix: +#' \deqn{I = X_1^\intercal L X_1}{I = X₁ᵀ L X₁} +#' Where \eqn{X_1}{X₁} is the treatment design matrix, and \eqn{L} is the +#' projection that removes nuisance fixed effects from the GLS's inverse +#' covariance: +#' \deqn{L = \Sigma^{-1} - \Sigma^{-1} X_2 \left( X_2^\intercal \Sigma^{-1} X_2 +#' \right)^{-1} X_2^\intercal \Sigma^{-1}}{L = Σ⁻¹ - Σ⁻¹ X₂ +#' (X₂ᵀ Σ⁻¹ X₂)⁻¹ X₂ᵀ Σ⁻¹} +#' The user specifies the spatial covariance \eqn{\Sigma}{Σ} they intend to use +#' at the time of analysis, e.g. lag-1 autoregressive \eqn{\text{AR}_1 \otimes +#' \text{AR}_1}{AR₁ ⊗ AR₁}, and this objective will optimise under that +#' structure. +#' +#' @examples +#' # Small RCBD layout: 6 treatments in 4 blocks of 6 plots +#' df <- initialise_design_df( +#' items = 6, nrows = 4, ncols = 6, +#' block_nrows = 1, block_ncols = 6 +#' ) +#' +#' # Non-spatial: identity covariance +#' result <- speed( +#' df, +#' swap = "treatment", +#' swap_within = "block", +#' obj_function = objective_function_info, +#' criterion = "A", +#' seed = 42, +#' quiet = TRUE +#' ) +#' +#' # Spatial: AR(1) x AR(1) +#' Sigma <- cor_ar1_ar1( +#' n_rows = 4, n_cols = 6, +#' rho_row = 0.6, rho_col = 0.3 +#' ) +#' result_spatial <- speed( +#' df, +#' swap = "treatment", +#' swap_within = "block", +#' obj_function = objective_function_info, +#' Sigma = Sigma, +#' criterion = "A", +#' optimise_params = optim_params(random_initialisation = TRUE), +#' seed = 42, +#' quiet = TRUE +#' ) +#' +#' @return A named list with \code{score}, \code{info_matrix}, +#' \code{eigenvalues}, contrast diagnostics, and \code{criterion}. +#' +#' @export +objective_function_info <- function( + layout_df, + swap, + spatial_cols, + criterion = c("A", "D"), + L_matrix = NULL, + Sigma = NULL, + contrast_matrix = NULL, + block_column = "block", + nuisance_formula = NULL, + tolerance = 1e-9, + current_score_obj = NULL, + swapped_items = NULL, + row_column = "row", + col_column = "col", + by = NULL, + grid_index = NULL, + ... +) { + criterion <- match.arg(criterion) + + if (!is.null(Sigma) || !is.null(L_matrix)) { + plot_order <- .fisher_plot_order( + layout_df, row_column, col_column, by, grid_index + ) + layout_df <- layout_df[plot_order, , drop = FALSE] + } + + fisher_cache <- NULL + if (!is.null(swapped_items)) { + fisher_cache <- attr(current_score_obj, "fisher_cache", exact = TRUE) + } + ci <- .compute_info( + layout_df, + swap, + Sigma, + L_matrix, + block_column, + nuisance_formula, + tolerance, + fisher_cache + ) + diagnostics <- .information_criteria( + ci$info, ci$trt_levels, contrast_matrix, tolerance + ) + score <- diagnostics[[paste0(criterion, "_value")]] + + result <- list( + score = score, + info_matrix = ci$info, + eigenvalues = diagnostics$eigenvalues, + contrast_matrix = diagnostics$contrast_matrix, + contrast_covariance = diagnostics$contrast_covariance, + estimable = diagnostics$estimable, + rank = diagnostics$rank, + criterion = criterion, + A_value = diagnostics$A_value, + D_value = diagnostics$D_value + ) + attr(result, "fisher_cache") <- ci$cache + return(result) +} + +#' Order observed plots to match spatial covariance matrices +#' @noRd +.fisher_plot_order <- function( + layout_df, row_column, col_column, by, grid_index +) { + grid_index <- grid_index %||% + grid_indices(layout_df, row_column, col_column, by) + plot_order <- unlist(lapply(grid_index, function(g) { + return(g$rows[order(g$index$idx[, 1], g$index$idx[, 2])]) + }), use.names = FALSE) + if (!identical(sort(plot_order), seq_len(nrow(layout_df)))) { + stop("`grid_index` must include every plot exactly once.", call. = FALSE) + } + return(plot_order) +} + +#' Build the treatment indicator matrix X1 +#' @noRd +.build_treatment_matrix <- function(treatments, trt_levels, n, v) { + X1 <- matrix(0, n, v) + trt_idx <- match(treatments, trt_levels) + if (anyNA(trt_idx)) { + stop("Treatment allocations cannot contain missing values.", call. = FALSE) + } + X1[cbind(seq_len(n), trt_idx)] <- 1 + return(X1) +} + +#' Build an orthonormal factorial contrast matrix +#' +#' Constructs a contrast basis for selected factorial effects while treatments +#' remain encoded as atomic combinations during optimisation. The returned rows +#' are orthonormal, so A-optimality is invariant to the particular contrast +#' coding used by [stats::model.matrix()]. +#' +#' @param treatment_df One row per treatment combination, containing the +#' component factor columns. +#' @param formula One-sided formula selecting factorial effects, for example +#' \code{~ (stage + cultivar + inoculum)^2}. +#' @param treatment_column Column containing the atomic treatment labels. +#' @param tolerance Numerical rank tolerance. +#' +#' @return A numeric contrast matrix with columns named by treatment level. +#' +#' @export +factorial_contrast_matrix <- function( + treatment_df, + formula, + treatment_column = "treatment", + tolerance = 1e-10 +) { + if (!is.data.frame(treatment_df)) { + stop("`treatment_df` must be a data frame.", call. = FALSE) + } + if (!inherits(formula, "formula") || length(formula) != 2L) { + stop("`formula` must be a one-sided formula.", call. = FALSE) + } + if (!treatment_column %in% names(treatment_df)) { + stop("Treatment column `", treatment_column, "` not found.", call. = FALSE) + } + + treatment_levels <- as.character(treatment_df[[treatment_column]]) + if (anyNA(treatment_levels) || anyDuplicated(treatment_levels)) { + stop( + "`treatment_df` must contain one non-missing row per treatment.", + call. = FALSE + ) + } + + formula_vars <- all.vars(formula) + missing_vars <- setdiff(formula_vars, names(treatment_df)) + if (length(missing_vars) > 0L) { + stop( + "Formula variable(s) not found: ", paste(missing_vars, collapse = ", "), + call. = FALSE + ) + } + + model_data <- treatment_df + for (column in formula_vars) { + if (is.character(model_data[[column]])) { + model_data[[column]] <- factor(model_data[[column]]) + } + } + + effect_matrix <- stats::model.matrix(formula, model_data) + effect_matrix <- sweep(effect_matrix, 2L, colMeans(effect_matrix), "-") + decomposition <- qr(effect_matrix, tol = tolerance) + effect_rank <- decomposition$rank + if (effect_rank == 0L) { + stop("`formula` does not define any treatment contrasts.", call. = FALSE) + } + + basis <- qr.Q( + decomposition, + complete = FALSE + )[, seq_len(effect_rank), drop = FALSE] + contrasts <- t(basis) + rownames(contrasts) <- paste0("contrast_", seq_len(nrow(contrasts))) + colnames(contrasts) <- treatment_levels + return(contrasts) +} + +#' Prepare a requested contrast space +#' @noRd +.prepare_contrast_matrix <- function(contrast_matrix, trt_levels, tolerance) { + v <- length(trt_levels) + if (is.null(contrast_matrix)) { + if (v < 2L) { + return(matrix(numeric(0), nrow = 0L, ncol = v)) + } + basis <- qr.Q(qr(stats::contr.helmert(v)), complete = FALSE) + contrast_matrix <- t(basis) + colnames(contrast_matrix) <- trt_levels + } else { + if (!is.matrix(contrast_matrix) || !is.numeric(contrast_matrix)) { + stop("`contrast_matrix` must be a numeric matrix.", call. = FALSE) + } + if (any(!is.finite(contrast_matrix))) { + stop("`contrast_matrix` must contain only finite values.", call. = FALSE) + } + if (ncol(contrast_matrix) != v) { + stop( + "`contrast_matrix` must have one column per treatment.", + call. = FALSE + ) + } + if (is.null(colnames(contrast_matrix))) { + stop( + "`contrast_matrix` must have column names matching the treatment levels.", + call. = FALSE + ) + } + missing <- setdiff(trt_levels, colnames(contrast_matrix)) + extra <- setdiff(colnames(contrast_matrix), trt_levels) + if (length(missing) > 0L || length(extra) > 0L) { + stop( + "Contrast columns must match the treatment levels.", + call. = FALSE + ) + } + contrast_matrix <- contrast_matrix[, trt_levels, drop = FALSE] + } + + if ( + nrow(contrast_matrix) > 0L && + qr(t(contrast_matrix), tol = tolerance)$rank < nrow(contrast_matrix) + ) { + stop( + "Rows of `contrast_matrix` must be linearly independent.", + call. = FALSE + ) + } + return(contrast_matrix) +} + +#' Calculate information criteria for a requested contrast space +#' @noRd +.information_criteria <- function( + info, trt_levels, contrast_matrix, tolerance +) { + info <- (info + t(info)) / 2 + eig <- eigen(info, symmetric = TRUE) + scale <- max(abs(eig$values)) + keep <- if (scale == 0) { + rep(FALSE, length(eig$values)) + } else { + eig$values > scale * tolerance + } + rank <- sum(keep) + pos_eig <- sort(eig$values[keep], decreasing = TRUE) + + info_inverse <- matrix(0, nrow(info), ncol(info)) + if (rank > 0L) { + vectors <- eig$vectors[, keep, drop = FALSE] + info_inverse <- vectors %*% + diag(1 / eig$values[keep], nrow = rank) %*% t(vectors) + } + + contrasts <- .prepare_contrast_matrix(contrast_matrix, trt_levels, tolerance) + projection <- info_inverse %*% info + estimable <- TRUE + if (nrow(contrasts) > 0L) { + # Contrast weights affect the score, but not estimability. + scaled_contrasts <- sweep(contrasts, 1L, apply(abs(contrasts), 1L, max), "/") + residual <- scaled_contrasts - scaled_contrasts %*% projection + estimable <- max(abs(residual)) <= tolerance + } + + contrast_covariance <- matrix(numeric(0), nrow = 0L, ncol = 0L) + A_value <- Inf + D_value <- Inf + if (estimable) { + contrast_covariance <- contrasts %*% info_inverse %*% t(contrasts) + contrast_covariance <- (contrast_covariance + t(contrast_covariance)) / 2 + if (nrow(contrasts) == 0L) { + A_value <- 0 + D_value <- 0 + } else { + contrast_eig <- eigen( + contrast_covariance, symmetric = TRUE, only.values = TRUE + )$values + contrast_scale <- max(abs(contrast_eig)) + if (all(contrast_eig > contrast_scale * tolerance)) { + A_value <- sum(diag(contrast_covariance)) + D_value <- sum(log(contrast_eig)) + } + } + } + + return(list( + eigenvalues = pos_eig, + rank = rank, + contrast_matrix = contrasts, + contrast_covariance = contrast_covariance, + estimable = estimable, + A_value = A_value, + D_value = D_value + )) +} + +#' Build the nuisance design matrix X2 +#' @noRd +.build_nuisance_matrix <- function(layout_df, block_column, nuisance_formula) { + if (is.null(nuisance_formula)) { + blocks <- layout_df[[block_column]] + if (length(unique(blocks[!is.na(blocks)])) < 2L) { + stop( + "A blocked design with at least two blocks in `", block_column, + "` is required when `nuisance_formula` is not supplied.", + call. = FALSE + ) + } + if (anyNA(blocks)) { + stop( + "Block labels in `", block_column, "` cannot contain missing values.", + call. = FALSE + ) + } + return( + stats::model.matrix(~ 0 + block, data.frame(block = factor(blocks))) + ) + } + if ( + !inherits(nuisance_formula, "formula") || length(nuisance_formula) != 2L + ) { + stop("`nuisance_formula` must be a one-sided formula.", call. = FALSE) + } + return(stats::model.matrix(nuisance_formula, layout_df)) +} + +#' Invert nuisance information independently of covariate and covariance scale +#' @noRd +.fisher_nuisance_inverse <- function(info, tolerance) { + scales <- sqrt(diag(info)) + scales[scales == 0] <- 1 + scale_matrix <- outer(scales, scales) + return(pseudo_inverse(info / scale_matrix, tolerance) / scale_matrix) +} + +#' Build a projection under identity covariance +#' @noRd +.build_L_from_df <- function( + layout_df, block_column, n, nuisance_formula = NULL, tolerance = 1e-10 +) { + X2 <- .build_nuisance_matrix(layout_df, block_column, nuisance_formula) + crossprod_inverse <- .fisher_nuisance_inverse(crossprod(X2), tolerance) + return(diag(n) - X2 %*% crossprod_inverse %*% t(X2)) +} + +#' Check whether a cached projection matches the requested projection +#' @noRd +.fisher_projection_matches <- function( + cache, + source, + input, + block_column, + nuisance_formula, + nuisance_data, + tolerance, + n +) { + matches <- is.list(cache) && + identical(cache$projection_source, source) && + identical(cache$projection_input, input) && + identical(cache$block_column, block_column) && + identical(cache$nuisance_formula, nuisance_formula) && + identical(cache$nuisance_data, nuisance_data) && + identical(cache$tolerance, tolerance) && + is.matrix(cache$L_matrix) && + identical(dim(cache$L_matrix), c(n, n)) + return(isTRUE(matches)) +} + +#' Check whether an information-matrix cache can be updated +#' @noRd +.fisher_cache_is_valid <- function(cache, swap, trt_levels, L_matrix, n, v) { + valid <- is.list(cache) && + identical(cache$swap, swap) && + identical(cache$trt_levels, trt_levels) && + length(cache$treatments) == n && + all(cache$treatments %in% trt_levels) && + is.matrix(cache$LX_matrix) && + identical(dim(cache$LX_matrix), c(n, v)) && + identical(cache$L_matrix, L_matrix) + return(isTRUE(valid)) +} + +#' Function for computing and caching the information matrix +#' @noRd +.compute_info <- function( + layout_df, + swap, + Sigma, + L_matrix, + block_column, + nuisance_formula = NULL, + tolerance = 1e-10, + cache = NULL +) { + treatments <- layout_df[[swap]] + trt_levels <- levels(factor(treatments)) + v <- length(trt_levels) + n <- nrow(layout_df) + treatment_labels <- as.character(treatments) + + if (!is.null(Sigma) && !is.null(L_matrix)) { + stop("Only one of `Sigma` and `L_matrix` can be supplied.", call. = FALSE) + } + + nuisance_data <- NULL + if (is.null(L_matrix)) { + nuisance_data <- if (is.null(nuisance_formula)) { + layout_df[[block_column]] + } else { + # Evaluation captures `.` and variables in the formula's environment. + .build_nuisance_matrix(layout_df, block_column, nuisance_formula) + } + } + + if (!is.null(L_matrix)) { + projection_source <- "L_matrix" + projection_input <- L_matrix + } else if (!is.null(Sigma)) { + projection_source <- "Sigma" + projection_input <- Sigma + if (.fisher_projection_matches( + cache, + projection_source, + projection_input, + block_column, + nuisance_formula, + nuisance_data, + tolerance, + n + )) { + L_matrix <- cache$L_matrix + } else { + L_matrix <- .build_L_from_Sigma( + layout_df, + Sigma, + block_column, + nuisance_formula, + tolerance + ) + } + } else { + projection_source <- "identity" + projection_input <- NULL + if (.fisher_projection_matches( + cache, + projection_source, + projection_input, + block_column, + nuisance_formula, + nuisance_data, + tolerance, + n + )) { + L_matrix <- cache$L_matrix + } else { + L_matrix <- .build_L_from_df( + layout_df, + block_column, + n, + nuisance_formula, + tolerance + ) + } + } + + if (!is.matrix(L_matrix) || !identical(dim(L_matrix), c(n, n))) { + stop("`L_matrix` must be an n by n matrix for `layout_df`.", call. = FALSE) + } + + X1 <- .build_treatment_matrix(treatment_labels, trt_levels, n, v) + if (.fisher_cache_is_valid(cache, swap, trt_levels, L_matrix, n, v)) { + changed <- which(cache$treatments != treatment_labels) + LX <- cache$LX_matrix + if (length(changed) > 0L) { + old_index <- match(cache$treatments[changed], trt_levels) + new_index <- match(treatment_labels[changed], trt_levels) + delta <- matrix(0, nrow = length(changed), ncol = v) + delta[cbind(seq_along(changed), old_index)] <- -1 + delta[cbind(seq_along(changed), new_index)] <- 1 + LX <- LX + L_matrix[, changed, drop = FALSE] %*% delta + } + } else { + LX <- L_matrix %*% X1 + } + + info <- crossprod(X1, LX) + info <- (info + t(info)) / 2 + dimnames(info) <- list(trt_levels, trt_levels) + + cache <- list( + swap = swap, + treatments = treatment_labels, + trt_levels = trt_levels, + L_matrix = L_matrix, + LX_matrix = LX, + projection_source = projection_source, + projection_input = projection_input, + block_column = block_column, + nuisance_formula = nuisance_formula, + nuisance_data = nuisance_data, + tolerance = tolerance + ) + + return(list( + info = info, + v = v, + trt_levels = trt_levels, + cache = cache + )) +} + +# Covariance utilities + +#' Compute L projection +#' +#' Removes nuisance fixed effects from the inverse covariance matrix used in +#' generalised least squares (GLS). +#' +#' @param layout_df Data frame representing the spatial layout of the +#' experiment. +#' @param Sigma Covariance matrix in numeric row-then-column grid order, +#' regardless of the row order of `layout_df`. +#' @inheritParams objective_function_info +#' @param block_column Column name of the design's block factor, with at least +#' two observed blocks. Used when `nuisance_formula` is not supplied. +#' @param nuisance_formula Optional one-sided formula describing nuisance +#' effects. If omitted, `block_column` is treated as a factor. +#' @param tolerance Numerical tolerance used for generalized inverses. +#' +#' @details +#' A blocked design with at least two observed blocks and no missing block +#' labels is required unless `nuisance_formula` is supplied. See +#' [objective_function_info()] for the covariance ordering convention, +#' including multiple grids and missing plots. +#' +#' @return \eqn{(n \times n)} numeric matrix in the same grid order as `Sigma`, +#' suitable for the `L_matrix` argument to [objective_function_info()]. +#' +#' @export +compute_L_projection <- function( + layout_df, + Sigma, + block_column = "block", + nuisance_formula = NULL, + tolerance = 1e-10, + row_column = "row", + col_column = "col", + by = NULL, + grid_index = NULL +) { + plot_order <- .fisher_plot_order( + layout_df, row_column, col_column, by, grid_index + ) + layout_df <- layout_df[plot_order, , drop = FALSE] + return(.build_L_from_Sigma( + layout_df, Sigma, block_column, nuisance_formula, tolerance + )) +} + +#' Build a projection for data already aligned with Sigma +#' @noRd +.build_L_from_Sigma <- function( + layout_df, Sigma, block_column, nuisance_formula, tolerance +) { + n <- nrow(layout_df) + + if (!is.matrix(Sigma)) { + stop("`Sigma` must be a matrix.", call. = FALSE) + } + if (!identical(dim(Sigma), c(n, n))) { + stop( + "`Sigma` dimensions must match the number of rows in `layout_df`.", + call. = FALSE + ) + } + if (!isSymmetric(Sigma, tol = 1e-8)) { + stop("`Sigma` must be symmetric.", call. = FALSE) + } + X2 <- .build_nuisance_matrix(layout_df, block_column, nuisance_formula) + + Sigma_inv <- solve(Sigma) + SiX2 <- Sigma_inv %*% X2 + nuisance_inverse <- .fisher_nuisance_inverse(crossprod(X2, SiX2), tolerance) + L <- Sigma_inv - SiX2 %*% nuisance_inverse %*% t(SiX2) + return((L + t(L)) / 2) +} + + +# Convenience correlation structure constructors + +#' Construct a 1 dimensional lag-1 autoregressive covariance +#' +#' @param n Number of observations. +#' @param rho Correlation parameter +#' +#' @return A symmetric \eqn{(n \times n)} correlation matrix. +#' +#' @export +cor_ar1 <- function(n, rho) { + return(rho^abs(outer(seq_len(n), seq_len(n), "-"))) +} + + +#' Construct a 2 dimensional lag-1 autoregressive covariance +#' +#' @param n_rows Number of rows in the design. +#' @param n_cols Number of columns in the design. +#' @param rho_row Correlation parameter along the row direction. +#' @param rho_col Correlation parameter along the column direction. +#' +#' @return A symmetric \eqn{(\text{n_rows} \cdot \text{n_cols}) \times +#' (\text{n_rows} \cdot \text{n_cols})} correlation matrix in row-then-column +#' grid order (columns vary fastest). +#' +#' @export +cor_ar1_ar1 <- function(n_rows, n_cols, rho_row, rho_col) { + return(kronecker( + cor_ar1(n_rows, rho_row), + cor_ar1(n_cols, rho_col) + )) +} diff --git a/R/optim_params.R b/R/optim_params.R index 81fdf8a..a72353f 100644 --- a/R/optim_params.R +++ b/R/optim_params.R @@ -22,10 +22,10 @@ #' the best score is used as an initial design (default: 0). #' @param adj_weight,bal_weight Deprecated. Weights for the adjacency and balance scores. Pass #' them to [speed()] directly or through a level's `obj_args` in `optimise` instead. -#' @param stop_at_optimal Logical; if `TRUE`, stops the level as soon as the best score reaches the lowest score -#' its layout allows (default: `TRUE`). The bound is only derivable for the default [objective_function()] -#' with non-negative weights and no `relationship` matrix; otherwise the level runs to its usual stopping -#' rules regardless of this setting. +#' @param stop_at_optimal Logical; if `TRUE`, stops the level when the best score reaches its +#' lower bound (default: `TRUE`). +#' @param lower_bound Lower bound of the score from the objective, used by `stop_at_optimal` (default: `NULL`, +#' derived for the default [objective_function()] with non-negative weights and no `relationship` matrix). #' #' @returns A named list of optimization parameters. #' @@ -41,7 +41,8 @@ optim_params <- function( random_initialisation = 0, adj_weight = NULL, bal_weight = NULL, - stop_at_optimal = TRUE + stop_at_optimal = TRUE, + lower_bound = NULL ) { params <- list( swap_count = swap_count, @@ -52,7 +53,8 @@ optim_params <- function( random_initialisation = random_initialisation, adj_weight = adj_weight, bal_weight = bal_weight, - stop_at_optimal = stop_at_optimal + stop_at_optimal = stop_at_optimal, + lower_bound = lower_bound ) # check legacy options diff --git a/R/speed.R b/R/speed.R index 49ab589..7f7a83f 100644 --- a/R/speed.R +++ b/R/speed.R @@ -38,9 +38,8 @@ #' with names matching `swap`. #' @param early_stop_iterations Number of iterations without improvement before #' early stopping (default: 2000). For hierarchical designs, can be a named -#' list with names matching `swap`. Optimisation also stops as soon as a level -#' reaches the lowest score its layout allows, which is only applicable for the -#' default [objective_function()]; see [summary()][summary.design()]. +#' list with names matching `swap`. Optimisation can also stop at a known lower +#' bound on the score; see `stop_at_optimal` and `lower_bound` in [optim_params()]. #' @param obj_function Objective function used to calculate score (lower is #' better) (default: [objective_function()]). For hierarchical designs, can #' be a named list with names matching `swap`. @@ -373,11 +372,12 @@ speed_hierarchical <- function(data, optimise, quiet, seed, ...) { stop("`score` from `objective_function` must be numeric.") } - # Lower bound on the score for this level; `NA` when none can be derived - optimal_score <- do.call(.optimal_score, c( - list(current_design, opt$swap, spatial_cols, opt$obj_function), - opt$obj_args - )) + # Lower bound on the score for this level; `NA` when none is known + optimal_score <- optimise_params$lower_bound %||% + do.call(.optimal_score, c( + list(current_design, opt$swap, spatial_cols, opt$obj_function), + opt$obj_args + )) all_optimal_scores[[level]] <- optimal_score best_score_obj <- current_score_obj @@ -440,7 +440,9 @@ speed_hierarchical <- function(data, optimise, quiet, seed, ...) { new_score <- new_score_obj$score # Decide whether to accept the new design - if (new_score < current_score || runif(1) < exp((current_score - new_score) / temp)) { + delta <- if (new_score == current_score) 0 else new_score - current_score + accept_prob <- if (delta == 0) 1 else exp(-delta / temp) + if (delta < 0 || runif(1) < accept_prob) { current_design <- new_design$design current_score <- new_score current_score_obj <- new_score_obj @@ -469,14 +471,11 @@ speed_hierarchical <- function(data, optimise, quiet, seed, ...) { "\n") } - # Zero is the most optimal score any design can reach. - reached_zero <- new_score < .Machine$double.eps - if (reached_zero || iter - last_improvement_iter >= opt$early_stop_iterations) { + if (iter - last_improvement_iter >= opt$early_stop_iterations) { if (!quiet) { - cat(if (reached_zero) "Optimal score reached at iteration" else "Early stopping at iteration", - iter, "for level", level, "\n") + cat("Early stopping at iteration", iter, "for level", level, "\n") } - stop_reason <- if (reached_zero) "optimal" else "no_improvement" + stop_reason <- "no_improvement" # Record final score and temperature before breaking if (iter < opt$iterations) { scores[iter + 1] <- current_score diff --git a/R/utils.R b/R/utils.R index 70acb7b..ef31f26 100644 --- a/R/utils.R +++ b/R/utils.R @@ -34,7 +34,7 @@ pseudo_inverse <- function(a_matrix, tolerance = 1e-10) { if (rank_a > 0) { diag_values <- numeric(ncol(svd_a$v)) diag_values[1:rank_a] <- 1 / svd_a$d[1:rank_a] - return(svd_a$v %*% diag(diag_values) %*% t(svd_a$u)) + return(svd_a$v %*% diag(diag_values, nrow = length(diag_values)) %*% t(svd_a$u)) } else { matrix_name <- deparse(substitute(a_matrix)) stop(paste0(matrix_name, " has rank 0 - design may be invalid")) diff --git a/R/verify_utils.R b/R/verify_utils.R index a4ee20d..c75ac9b 100644 --- a/R/verify_utils.R +++ b/R/verify_utils.R @@ -396,7 +396,8 @@ random_initialisation, adj_weight, bal_weight, - stop_at_optimal + stop_at_optimal, + lower_bound ) { verify_positive_whole_number(swap_count) verify_non_negative_whole(start_temp) @@ -410,6 +411,13 @@ verify_numeric(bal_weight) } + if (!is.null(lower_bound)) { + verify_numeric(lower_bound) + if (is.complex(lower_bound) || !is.finite(lower_bound)) { + stop("`lower_bound` must be a finite real number.", call. = FALSE) + } + } + if (!(random_initialisation %in% c(TRUE, FALSE))) { verify_non_negative_whole(random_initialisation) } diff --git a/_pkgdown.yml b/_pkgdown.yml index b357082..d82eb15 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -21,6 +21,13 @@ reference: - get_edges - get_vertices - prep_relationship + - subtitle: Fisher information utilities + desc: Functions for constructing contrast and covariance inputs for Fisher information objectives + - contents: + - factorial_contrast_matrix + - compute_L_projection + - cor_ar1 + - cor_ar1_ar1 - title: Output desc: Functions for checking designs. - contents: diff --git a/man/compute_L_projection.Rd b/man/compute_L_projection.Rd new file mode 100644 index 0000000..c96795d --- /dev/null +++ b/man/compute_L_projection.Rd @@ -0,0 +1,58 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/objective_fisher.R +\name{compute_L_projection} +\alias{compute_L_projection} +\title{Compute L projection} +\usage{ +compute_L_projection( + layout_df, + Sigma, + block_column = "block", + nuisance_formula = NULL, + tolerance = 1e-10, + row_column = "row", + col_column = "col", + by = NULL, + grid_index = NULL +) +} +\arguments{ +\item{layout_df}{Data frame representing the spatial layout of the +experiment.} + +\item{Sigma}{Covariance matrix in numeric row-then-column grid order, +regardless of the row order of \code{layout_df}.} + +\item{block_column}{Column name of the design's block factor, with at least +two observed blocks. Used when \code{nuisance_formula} is not supplied.} + +\item{nuisance_formula}{Optional one-sided formula describing nuisance +effects. If omitted, \code{block_column} is treated as a factor.} + +\item{tolerance}{Numerical tolerance used for generalized inverses.} + +\item{row_column}{Name of the column representing rows (default \code{"row"}).} + +\item{col_column}{Name of the column representing columns +(default \code{"col"}).} + +\item{by}{Optional column name grouping plots into grids (e.g. \code{"site"}). +\code{NULL} treats the design as one grid.} + +\item{grid_index}{Optional pre-built list from \code{\link[=grid_indices]{grid_indices()}}, supplied by +\code{\link[=speed]{speed()}} to reuse coordinate validation. Leave \code{NULL} for direct calls.} +} +\value{ +\eqn{(n \times n)} numeric matrix in the same grid order as \code{Sigma}, +suitable for the \code{L_matrix} argument to \code{\link[=objective_function_info]{objective_function_info()}}. +} +\description{ +Removes nuisance fixed effects from the inverse covariance matrix used in +generalised least squares (GLS). +} +\details{ +A blocked design with at least two observed blocks and no missing block +labels is required unless \code{nuisance_formula} is supplied. See +\code{\link[=objective_function_info]{objective_function_info()}} for the covariance ordering convention, +including multiple grids and missing plots. +} diff --git a/man/cor_ar1.Rd b/man/cor_ar1.Rd new file mode 100644 index 0000000..7fed8c5 --- /dev/null +++ b/man/cor_ar1.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/objective_fisher.R +\name{cor_ar1} +\alias{cor_ar1} +\title{Construct a 1 dimensional lag-1 autoregressive covariance} +\usage{ +cor_ar1(n, rho) +} +\arguments{ +\item{n}{Number of observations.} + +\item{rho}{Correlation parameter} +} +\value{ +A symmetric \eqn{(n \times n)} correlation matrix. +} +\description{ +Construct a 1 dimensional lag-1 autoregressive covariance +} diff --git a/man/cor_ar1_ar1.Rd b/man/cor_ar1_ar1.Rd new file mode 100644 index 0000000..ea71f03 --- /dev/null +++ b/man/cor_ar1_ar1.Rd @@ -0,0 +1,25 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/objective_fisher.R +\name{cor_ar1_ar1} +\alias{cor_ar1_ar1} +\title{Construct a 2 dimensional lag-1 autoregressive covariance} +\usage{ +cor_ar1_ar1(n_rows, n_cols, rho_row, rho_col) +} +\arguments{ +\item{n_rows}{Number of rows in the design.} + +\item{n_cols}{Number of columns in the design.} + +\item{rho_row}{Correlation parameter along the row direction.} + +\item{rho_col}{Correlation parameter along the column direction.} +} +\value{ +A symmetric \eqn{(\text{n_rows} \cdot \text{n_cols}) \times + (\text{n_rows} \cdot \text{n_cols})} correlation matrix in row-then-column +grid order (columns vary fastest). +} +\description{ +Construct a 2 dimensional lag-1 autoregressive covariance +} diff --git a/man/create_speed_input.Rd b/man/create_speed_input.Rd index 3e01f11..112a3e4 100644 --- a/man/create_speed_input.Rd +++ b/man/create_speed_input.Rd @@ -58,9 +58,8 @@ with names matching \code{swap}.} \item{early_stop_iterations}{Number of iterations without improvement before early stopping (default: 2000). For hierarchical designs, can be a named -list with names matching \code{swap}. Optimisation also stops as soon as a level -reaches the lowest score its layout allows, which is only applicable for the -default \code{\link[=objective_function]{objective_function()}}; see \link[=summary.design]{summary()}.} +list with names matching \code{swap}. Optimisation can also stop at a known lower +bound on the score; see \code{stop_at_optimal} and \code{lower_bound} in \code{\link[=optim_params]{optim_params()}}.} \item{obj_function}{Objective function used to calculate score (lower is better) (default: \code{\link[=objective_function]{objective_function()}}). For hierarchical designs, can diff --git a/man/factorial_contrast_matrix.Rd b/man/factorial_contrast_matrix.Rd new file mode 100644 index 0000000..e120179 --- /dev/null +++ b/man/factorial_contrast_matrix.Rd @@ -0,0 +1,33 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/objective_fisher.R +\name{factorial_contrast_matrix} +\alias{factorial_contrast_matrix} +\title{Build an orthonormal factorial contrast matrix} +\usage{ +factorial_contrast_matrix( + treatment_df, + formula, + treatment_column = "treatment", + tolerance = 1e-10 +) +} +\arguments{ +\item{treatment_df}{One row per treatment combination, containing the +component factor columns.} + +\item{formula}{One-sided formula selecting factorial effects, for example +\code{~ (stage + cultivar + inoculum)^2}.} + +\item{treatment_column}{Column containing the atomic treatment labels.} + +\item{tolerance}{Numerical rank tolerance.} +} +\value{ +A numeric contrast matrix with columns named by treatment level. +} +\description{ +Constructs a contrast basis for selected factorial effects while treatments +remain encoded as atomic combinations during optimisation. The returned rows +are orthonormal, so A-optimality is invariant to the particular contrast +coding used by \code{\link[stats:model.matrix]{stats::model.matrix()}}. +} diff --git a/man/objective_function_info.Rd b/man/objective_function_info.Rd new file mode 100644 index 0000000..c82f46f --- /dev/null +++ b/man/objective_function_info.Rd @@ -0,0 +1,165 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/objective_fisher.R +\name{objective_function_info} +\alias{objective_function_info} +\title{Objective function using the treatment information matrix} +\usage{ +objective_function_info( + layout_df, + swap, + spatial_cols, + criterion = c("A", "D"), + L_matrix = NULL, + Sigma = NULL, + contrast_matrix = NULL, + block_column = "block", + nuisance_formula = NULL, + tolerance = 1e-09, + current_score_obj = NULL, + swapped_items = NULL, + row_column = "row", + col_column = "col", + by = NULL, + grid_index = NULL, + ... +) +} +\arguments{ +\item{layout_df}{Data frame representing the spatial layout of the +experiment.} + +\item{swap}{Column name to swap, usually the treatment.} + +\item{spatial_cols}{Column name of the spatial factors.} + +\item{criterion}{Either \code{"A"} or \code{"D"}, representing A or D +optimality. +\itemize{ +\item A-optimality: Minimises \eqn{\mathrm{tr} \left( \mathcal{I}^- + \right)}{tr(I⁻)}. +\item D-optimality: Minimises \eqn{-\log \left| \mathcal{I} \right|}{- + log(|I|)} +}} + +\item{L_matrix}{Optional precomputed projection matrix in grid order, as +returned by \code{\link[=compute_L_projection]{compute_L_projection()}}. Cannot be supplied with \code{Sigma}.} + +\item{Sigma}{Optional covariance matrix in grid order (see Details). If both +\code{Sigma} and \code{L_matrix} are \code{NULL}, identity covariance is assumed.} + +\item{contrast_matrix}{Named numeric contrast matrix with one column per +treatment level. Column names must match the treatment levels exactly once; +columns are matched by name, not position. Only these contrasts are required +to be estimable and contribute to the optimality criterion. The default +targets the complete treatment-contrast space.} + +\item{block_column}{Column name of the design's block factor, with at least +two observed blocks. Used when neither \code{nuisance_formula} nor \code{L_matrix} +is supplied.} + +\item{nuisance_formula}{Optional one-sided formula describing nuisance +effects. Used when \code{L_matrix} is not supplied. If omitted, +\code{block_column} is treated as a factor.} + +\item{tolerance}{Relative numerical tolerance for rank and estimability +checks.} + +\item{current_score_obj}{The current objective result supplied by \code{\link[=speed]{speed()}} +after the initial call. Used to reuse invariant matrix calculations.} + +\item{swapped_items}{The treatments swapped by \code{\link[=speed]{speed()}}. Changed plot rows +are identified from the cached and proposed allocations so repeated +treatments and multi-swaps are handled exactly.} + +\item{row_column}{Name of the column representing rows (default \code{"row"}).} + +\item{col_column}{Name of the column representing columns +(default \code{"col"}).} + +\item{by}{Optional column name grouping plots into grids (e.g. \code{"site"}). +\code{NULL} treats the design as one grid.} + +\item{grid_index}{Optional pre-built list from \code{\link[=grid_indices]{grid_indices()}}, supplied by +\code{\link[=speed]{speed()}} to reuse coordinate validation. Leave \code{NULL} for direct calls.} + +\item{...}{Extra parameters passed from \code{speed}.} +} +\value{ +A named list with \code{score}, \code{info_matrix}, +\code{eigenvalues}, contrast diagnostics, and \code{criterion}. +} +\description{ +Creates an objective function that optimises experimental designs using the +Fisher information for treatment contrasts after adjusting for nuisance +effects, and takes an optional spatial covariance structure for spatial +optimisation. +} +\details{ +The default nuisance model requires a blocked design with at least two +observed blocks and no missing block labels. An explicit \code{nuisance_formula} +or \code{L_matrix} can instead specify a different nuisance model. + +\code{Sigma} and \code{L_matrix} have one row and column per observed plot, ordered by +numeric row position and then column position (columns vary fastest), +regardless of the row order of \code{layout_df}. This matches \code{\link[=cor_ar1_ar1]{cor_ar1_ar1()}}. +For multiple grids, plots are grouped by the factor levels of \code{by} (sorted +labels otherwise) before ordering within each grid. For missing plots, +subset the covariance to the observed positions in this order. The +projection is cached during optimisation while the covariance and nuisance +effects remain unchanged. + +D-optimality uses a log determinant, so negative scores are valid and do not +indicate that the optimum has been reached. + +Non-estimable requested contrasts receive an infinite score, so invalid +designs cannot be preferred to designs with large finite scores. + +This function computes the treatment information matrix: +\deqn{I = X_1^\intercal L X_1}{I = X₁ᵀ L X₁} +Where \eqn{X_1}{X₁} is the treatment design matrix, and \eqn{L} is the +projection that removes nuisance fixed effects from the GLS's inverse +covariance: +\deqn{L = \Sigma^{-1} - \Sigma^{-1} X_2 \left( X_2^\intercal \Sigma^{-1} X_2 +\right)^{-1} X_2^\intercal \Sigma^{-1}}{L = Σ⁻¹ - Σ⁻¹ X₂ +(X₂ᵀ Σ⁻¹ X₂)⁻¹ X₂ᵀ Σ⁻¹} +The user specifies the spatial covariance \eqn{\Sigma}{Σ} they intend to use +at the time of analysis, e.g. lag-1 autoregressive \eqn{\text{AR}_1 \otimes +\text{AR}_1}{AR₁ ⊗ AR₁}, and this objective will optimise under that +structure. +} +\examples{ +# Small RCBD layout: 6 treatments in 4 blocks of 6 plots +df <- initialise_design_df( + items = 6, nrows = 4, ncols = 6, + block_nrows = 1, block_ncols = 6 +) + +# Non-spatial: identity covariance +result <- speed( + df, + swap = "treatment", + swap_within = "block", + obj_function = objective_function_info, + criterion = "A", + seed = 42, + quiet = TRUE +) + +# Spatial: AR(1) x AR(1) +Sigma <- cor_ar1_ar1( + n_rows = 4, n_cols = 6, + rho_row = 0.6, rho_col = 0.3 +) +result_spatial <- speed( + df, + swap = "treatment", + swap_within = "block", + obj_function = objective_function_info, + Sigma = Sigma, + criterion = "A", + optimise_params = optim_params(random_initialisation = TRUE), + seed = 42, + quiet = TRUE +) + +} diff --git a/man/optim_params.Rd b/man/optim_params.Rd index 7d752e7..98a1d23 100644 --- a/man/optim_params.Rd +++ b/man/optim_params.Rd @@ -13,7 +13,8 @@ optim_params( random_initialisation = 0, adj_weight = NULL, bal_weight = NULL, - stop_at_optimal = TRUE + stop_at_optimal = TRUE, + lower_bound = NULL ) } \arguments{ @@ -42,10 +43,11 @@ the best score is used as an initial design (default: 0).} \item{adj_weight, bal_weight}{Deprecated. Weights for the adjacency and balance scores. Pass them to \code{\link[=speed]{speed()}} directly or through a level's \code{obj_args} in \code{optimise} instead.} -\item{stop_at_optimal}{Logical; if \code{TRUE}, stops the level as soon as the best score reaches the lowest score -its layout allows (default: \code{TRUE}). The bound is only derivable for the default \code{\link[=objective_function]{objective_function()}} -with non-negative weights and no \code{relationship} matrix; otherwise the level runs to its usual stopping -rules regardless of this setting.} +\item{stop_at_optimal}{Logical; if \code{TRUE}, stops the level when the best score reaches its +lower bound (default: \code{TRUE}).} + +\item{lower_bound}{Lower bound of the score from the objective, used by \code{stop_at_optimal} (default: \code{NULL}, +derived for the default \code{\link[=objective_function]{objective_function()}} with non-negative weights and no \code{relationship} matrix).} } \value{ A named list of optimization parameters. diff --git a/man/speed-package.Rd b/man/speed-package.Rd index 3acadc2..8a85ea4 100644 --- a/man/speed-package.Rd +++ b/man/speed-package.Rd @@ -25,12 +25,14 @@ Authors: \item Sam Rogers \email{sam.rogers@adelaide.edu.au} \item Wasin Pipattungsakul \email{wasin.pipattungsakul@adelaide.edu.au} \item Julian Taylor \email{julian.taylor@adelaide.edu.au} + \item Kai Bagley \email{kai.bagley@curtin.edu.au} (\href{https://orcid.org/0009-0004-6579-6959}{ORCID}) } Other contributors: \itemize{ \item University of Adelaide (https://adelaide.edu.au/) [copyright holder, funder] \item Grains Research and Development Corporation (https://grdc.com.au/) [copyright holder, funder] + \item Curtin University (\href{https://ror.org/02n415q13}{ROR}) (http://www.curtin.edu.au/) [copyright holder] } } diff --git a/man/speed.Rd b/man/speed.Rd index 1878b98..d49b5b8 100644 --- a/man/speed.Rd +++ b/man/speed.Rd @@ -62,9 +62,8 @@ with names matching \code{swap}.} \item{early_stop_iterations}{Number of iterations without improvement before early stopping (default: 2000). For hierarchical designs, can be a named -list with names matching \code{swap}. Optimisation also stops as soon as a level -reaches the lowest score its layout allows, which is only applicable for the -default \code{\link[=objective_function]{objective_function()}}; see \link[=summary.design]{summary()}.} +list with names matching \code{swap}. Optimisation can also stop at a known lower +bound on the score; see \code{stop_at_optimal} and \code{lower_bound} in \code{\link[=optim_params]{optim_params()}}.} \item{obj_function}{Objective function used to calculate score (lower is better) (default: \code{\link[=objective_function]{objective_function()}}). For hierarchical designs, can diff --git a/man/verify.Rd b/man/verify.Rd index 5da6d68..5796785 100644 --- a/man/verify.Rd +++ b/man/verify.Rd @@ -58,7 +58,8 @@ random_initialisation, adj_weight, bal_weight, - stop_at_optimal + stop_at_optimal, + lower_bound ) .verify_grid_factors(grid_factors) @@ -105,9 +106,8 @@ with names matching \code{swap}.} \item{early_stop_iterations}{Number of iterations without improvement before early stopping (default: 2000). For hierarchical designs, can be a named -list with names matching \code{swap}. Optimisation also stops as soon as a level -reaches the lowest score its layout allows, which is only applicable for the -default \code{\link[=objective_function]{objective_function()}}; see \link[=summary.design]{summary()}.} +list with names matching \code{swap}. Optimisation can also stop at a known lower +bound on the score; see \code{stop_at_optimal} and \code{lower_bound} in \code{\link[=optim_params]{optim_params()}}.} \item{obj_function}{Objective function used to calculate score (lower is better) (default: \code{\link[=objective_function]{objective_function()}}). For hierarchical designs, can @@ -147,10 +147,11 @@ the best score is used as an initial design (default: 0).} \item{adj_weight, bal_weight}{Deprecated. Weights for the adjacency and balance scores. Pass them to \code{\link[=speed]{speed()}} directly or through a level's \code{obj_args} in \code{optimise} instead.} -\item{stop_at_optimal}{Logical; if \code{TRUE}, stops the level as soon as the best score reaches the lowest score -its layout allows (default: \code{TRUE}). The bound is only derivable for the default \code{\link[=objective_function]{objective_function()}} -with non-negative weights and no \code{relationship} matrix; otherwise the level runs to its usual stopping -rules regardless of this setting.} +\item{stop_at_optimal}{Logical; if \code{TRUE}, stops the level when the best score reaches its +lower bound (default: \code{TRUE}).} + +\item{lower_bound}{Lower bound of the score from the objective, used by \code{stop_at_optimal} (default: \code{NULL}, +derived for the default \code{\link[=objective_function]{objective_function()}} with non-negative weights and no \code{relationship} matrix).} } \description{ Validates the arguments as the user passed them, dispatching to the checker diff --git a/tests/testthat/test-compute_L_projection.R b/tests/testthat/test-compute_L_projection.R new file mode 100644 index 0000000..31e0056 --- /dev/null +++ b/tests/testthat/test-compute_L_projection.R @@ -0,0 +1,73 @@ +test_that("compute_L_projection validates covariance inputs", { + df <- data.frame( + row = 1:4, + col = 1:4, + block = c(1, 1, 2, 2), + treatment = c("A", "B", "A", "B") + ) + + expect_error(compute_L_projection(df, 1:4), "matrix") + expect_error(compute_L_projection(df, diag(3)), "dimension") + expect_error(compute_L_projection(df, matrix(1:16, 4, 4)), "symmetric") +}) + +test_that("identity covariance matches the direct projection", { + df <- data.frame( + row = rep(1:3, each = 4), + col = rep(1:4, times = 3), + block = rep(1:3, each = 4), + treatment = rep(paste0("T", 1:4), 3) + ) + + spatial <- compute_L_projection(df, diag(12), block_column = "block") + direct <- .build_L_from_df(df, "block", 12) + + expect_equal(unname(spatial), unname(direct), tolerance = 1e-10) +}) + +test_that("compute_L_projection supports nuisance formulas", { + df <- data.frame( + row = rep(1:3, each = 4), + col = rep(1:4, times = 3), + treatment = rep(paste0("T", 1:4), 3) + ) + + spatial <- compute_L_projection( + df, + diag(12), + nuisance_formula = ~ row + col + ) + direct <- .build_L_from_df( + df, + "block", + 12, + nuisance_formula = ~ row + col + ) + + expect_equal(unname(spatial), unname(direct), tolerance = 1e-10) +}) + +test_that("compute_L_projection returns a projection in grid order", { + df <- initialise_design_df( + items = 6, nrows = 4, ncols = 6, + block_nrows = 1, block_ncols = 6 + ) + Sigma <- cor_ar1_ar1(4, 6, rho_row = 0.6, rho_col = 0.3) + X2 <- kronecker(diag(4), rep(1, 6)) + Sigma_inv <- solve(Sigma) + expected <- Sigma_inv - Sigma_inv %*% X2 %*% + solve(crossprod(X2, Sigma_inv %*% X2)) %*% t(X2) %*% Sigma_inv + + for (layout in list(df, df[rev(seq_len(nrow(df))), ])) { + result <- compute_L_projection(layout, Sigma) + expect_equal(unname(result), unname(expected), tolerance = 1e-10) + expect_equal(unname(result %*% X2), matrix(0, 24, 4), tolerance = 1e-10) + } +}) + +test_that("compute_L_projection requires at least two blocks by default", { + df <- data.frame(row = rep(1:2, each = 2), col = rep(1:2, 2)) + expect_error(compute_L_projection(df, diag(4)), "at least two blocks") + df$block <- factor(rep(1, 4), levels = 1:2) + expect_error(compute_L_projection(df, diag(4)), "at least two blocks") +}) diff --git a/tests/testthat/test-cor_ar1.R b/tests/testthat/test-cor_ar1.R new file mode 100644 index 0000000..96a8e0c --- /dev/null +++ b/tests/testthat/test-cor_ar1.R @@ -0,0 +1,15 @@ +test_that("cor_ar1 produces a valid correlation matrix", { + correlation <- cor_ar1(5, 0.7) + + expect_equal(dim(correlation), c(5, 5)) + expect_true(isSymmetric(correlation)) + expect_true(all(diag(correlation) == 1)) + expect_true(all(eigen(correlation, only.values = TRUE)$values > 0)) + expect_equal(correlation[1, 2], 0.7) + expect_equal(correlation[1, 3], 0.7^2) + expect_equal(correlation[1, 5], 0.7^4) +}) + +test_that("cor_ar1 with zero correlation gives identity", { + expect_equal(cor_ar1(4, 0), diag(4)) +}) diff --git a/tests/testthat/test-cor_ar1_ar1.R b/tests/testthat/test-cor_ar1_ar1.R new file mode 100644 index 0000000..6079926 --- /dev/null +++ b/tests/testthat/test-cor_ar1_ar1.R @@ -0,0 +1,14 @@ +test_that("cor_ar1_ar1 produces a valid separable correlation matrix", { + correlation <- cor_ar1_ar1(3, 5, 0.6, 0.4) + + expect_equal(dim(correlation), c(15, 15)) + expect_true(isSymmetric(correlation)) + expect_true(all(diag(correlation) == 1)) + expect_true(all(eigen(correlation, only.values = TRUE)$values > 0)) +}) + +test_that("cor_ar1_ar1 is the Kronecker product of marginal correlations", { + expected <- kronecker(cor_ar1(3, 0.6), cor_ar1(5, 0.4)) + + expect_equal(cor_ar1_ar1(3, 5, 0.6, 0.4), expected) +}) diff --git a/tests/testthat/test-design_utils.R b/tests/testthat/test-design_utils.R index c90055d..1a7130c 100644 --- a/tests/testthat/test-design_utils.R +++ b/tests/testthat/test-design_utils.R @@ -427,7 +427,7 @@ test_that("speed() records why each level stopped", { ) }) -test_that("speed() calls a score of zero optimal without a derived lower bound", { +test_that("speed() calls a score of zero optimal with a supplied lower bound", { df <- data.frame( row = rep(1:4, times = 5), col = rep(1:5, each = 4), @@ -435,8 +435,7 @@ test_that("speed() calls a score of zero optimal without a derived lower bound", stringsAsFactors = FALSE ) - # A custom objective, so no lower bound can be derived and `optimal_score` is - # `NA`. Reaching zero is still optimal rather than merely out of improvements. + # A custom objective, so its known lower bound must be supplied. obj_runs <- function(layout_df, swap, spatial_cols, ...) { trt <- as.character(layout_df[[swap]]) return(list(score = as.numeric(sum(trt[-1] == trt[-length(trt)])))) @@ -446,13 +445,14 @@ test_that("speed() calls a score of zero optimal without a derived lower bound", df, swap = "treatment", obj_function = obj_runs, + optimise_params = optim_params(lower_bound = 0), iterations = 5000, seed = 3, quiet = TRUE ) expect_equal(result$score, 0) - expect_true(is.na(result$metadata$per_level[[1]]$optimal_score)) + expect_equal(result$metadata$per_level[[1]]$optimal_score, 0) expect_equal(result$metadata$per_level[[1]]$stop_reason, "optimal") }) diff --git a/tests/testthat/test-factorial_contrast_matrix.R b/tests/testthat/test-factorial_contrast_matrix.R new file mode 100644 index 0000000..8f37241 --- /dev/null +++ b/tests/testthat/test-factorial_contrast_matrix.R @@ -0,0 +1,50 @@ +test_that("factorial_contrast_matrix builds an orthonormal effect space", { + treatments <- expand.grid( + stage = c("early", "late"), + cultivar = c("A", "B", "C") + ) + treatments$treatment <- with(treatments, paste(stage, cultivar, sep = ":")) + + contrasts <- factorial_contrast_matrix( + treatments, + ~ stage + cultivar + ) + + expect_equal(dim(contrasts), c(3, 6)) + expect_equal(colnames(contrasts), treatments$treatment) + expect_equal(unname(rowSums(contrasts)), rep(0, 3), tolerance = 1e-12) + expect_equal(unname(tcrossprod(contrasts)), diag(3), tolerance = 1e-12) +}) + +test_that("factorial_contrast_matrix supports interactions", { + treatments <- expand.grid( + stage = c("early", "late"), + cultivar = c("A", "B", "C") + ) + treatments$treatment <- with(treatments, paste(stage, cultivar, sep = ":")) + + contrasts <- factorial_contrast_matrix( + treatments, + ~ stage * cultivar + ) + + expect_equal(nrow(contrasts), nrow(treatments) - 1) + expect_equal(unname(tcrossprod(contrasts)), diag(5), tolerance = 1e-12) +}) + +test_that("factorial_contrast_matrix validates its inputs", { + treatments <- data.frame( + treatment = c("A", "B"), + factor_a = c("low", "high") + ) + + expect_error(factorial_contrast_matrix(1:2, ~factor_a), "data frame") + expect_error(factorial_contrast_matrix(treatments, factor_a ~ 1), "one-sided") + expect_error(factorial_contrast_matrix(treatments, ~missing), "not found") + + duplicated <- rbind(treatments, treatments[1, ]) + expect_error( + factorial_contrast_matrix(duplicated, ~factor_a), + "one non-missing row" + ) +}) diff --git a/tests/testthat/test-objective_fisher.R b/tests/testthat/test-objective_fisher.R new file mode 100644 index 0000000..3322bd9 --- /dev/null +++ b/tests/testthat/test-objective_fisher.R @@ -0,0 +1,611 @@ +# tests/testthat/test-objective_fisher.R + +default_sigma <- function(nrows = 4, ncols = 6) cor_ar1_ar1(nrows, ncols, rho_row = 0.6, rho_col = 0.3) +default_design <- function(nrows = 4, ncols = 6) { + initialise_design_df( + items = ncols, nrows = nrows, ncols = ncols, + block_nrows = 1, block_ncols = ncols + ) +} + +# ---- objective_function_info + +# all RCBDs are equally optimal +test_that("all valid RCBD randomisations produce the same score under identity covariance", { + set.seed(1) + n_treatments <- 4 + n_blocks <- 3 + + df <- data.frame( + row = rep(1:n_blocks, each = n_treatments), + col = rep(1:n_treatments, times = n_blocks), + block = rep(1:n_blocks, each = n_treatments), + treatment = NA_character_ + ) + + scores <- numeric(20) + for (i in seq_len(20)) { + for (b in 1:n_blocks) { + idx <- df$block == b + df$treatment[idx] <- paste0("T", sample(n_treatments)) + } + result <- objective_function_info( + df, + swap = "treatment", spatial_cols = c("row", "col"), + criterion = "A" + ) + scores[i] <- result$score + } + + expect_true(max(scores) - min(scores) < 1e-10) +}) + +# when there IS spatial correlation, two different arrangements of the same +# treatments must give different scores. df1 should be worse, since treatments +# are always in the same column position, but in df2 they're "randomised". +test_that("spatial designs differentiate between arrangements", { + n_treatments <- 4 + n_blocks <- 3 + + df <- data.frame( + row = rep(1:n_blocks, each = n_treatments), + col = rep(1:n_treatments, times = n_blocks), + block = rep(1:n_blocks, each = n_treatments) + ) + + Sigma <- cor_ar1_ar1(n_blocks, n_treatments, rho_row = 0.7, rho_col = 0.5) + + # Same treatment ordering in every block + df1 <- df + df1$treatment <- rep(paste0("T", 1:n_treatments), n_blocks) + + # Alternated ordering + df2 <- df + df2$treatment <- c( + paste0("T", c(1, 2, 3, 4)), + paste0("T", c(3, 4, 1, 2)), + paste0("T", c(4, 3, 2, 1)) + ) + + s1 <- objective_function_info( + df1, "treatment", c("row", "col"), + criterion = "A", Sigma = Sigma + )$score + + s2 <- objective_function_info( + df2, "treatment", c("row", "col"), + criterion = "A", Sigma = Sigma + )$score + + expect_false(abs(s1 - s2) < 1e-10) +}) + +# just make sure this works lel +test_that("D-optimality criterion works", { + df <- data.frame( + row = rep(1:3, each = 4), + col = rep(1:4, times = 3), + block = rep(1:3, each = 4), + treatment = rep(paste0("T", 1:4), 3) + ) + + result <- objective_function_info( + df, "treatment", c("row", "col"), + criterion = "D" + ) + + expect_true(is.finite(result$score)) + expect_equal(result$criterion, "D") + expect_equal(length(result$eigenvalues), 3) # v - 1 +}) + +# if treatments never exist in the same block together, you cant compare them, +# so the design is fully broken +test_that("disconnected designs have infinite scores", { + df <- data.frame( + row = 1:6, + col = c(1, 2, 1, 2, 1, 2), + block = c(1, 1, 2, 2, 3, 3), + treatment = c("A", "A", "B", "B", "C", "C") + ) + + result <- objective_function_info( + df, "treatment", c("row", "col"), + criterion = "A" + ) + + expect_equal(result$score, Inf) + expect_false(result$estimable) + expect_equal(result$A_value, Inf) + expect_equal(result$D_value, Inf) +}) + +test_that("large finite contrast variances are preferable to non-estimable targets", { + df <- data.frame( + row = rep(1:2, each = 4), col = rep(1:4, 2), + block = rep(1:2, each = 4), treatment = rep(c("A", "B"), 4) + ) + contrast <- matrix(c(1e6, -1e6), nrow = 1, dimnames = list(NULL, c("A", "B"))) + connected <- objective_function_info( + df, "treatment", c("row", "col"), contrast_matrix = contrast + ) + df$treatment <- rep(c("A", "B"), each = 4) + disconnected <- objective_function_info( + df, "treatment", c("row", "col"), contrast_matrix = contrast + ) + + expect_equal(connected$score, 5e11, tolerance = 1e-10) + expect_true(connected$estimable) + expect_equal(disconnected$score, Inf) + expect_false(disconnected$estimable) + expect_lt(connected$score, disconnected$score) +}) + +test_that("information matrix for an RCBD has the expected rank", { + df <- data.frame( + row = rep(1:3, each = 5), + col = rep(1:5, times = 3), + block = rep(1:3, each = 5), + treatment = rep(paste0("T", 1:5), 3) + ) + + result <- objective_function_info(df, "treatment", c("row", "col")) + + expect_equal(result$rank, 4) + expect_equal(result$eigenvalues, rep(3, 4), tolerance = 1e-10) + expect_equal(dim(result$info_matrix), c(5, 5)) + expect_equal(rownames(result$info_matrix), paste0("T", 1:5)) + expect_equal(colnames(result$info_matrix), paste0("T", 1:5)) +}) + +test_that("a requested estimable contrast does not require full connectedness", { + df <- data.frame( + row = 1:6, + col = rep(1:2, 3), + block = rep(1:3, each = 2), + treatment = c("A", "B", "A", "B", "C", "C") + ) + contrast <- matrix(c(1, -1, 0), nrow = 1) + colnames(contrast) <- c("A", "B", "C") + + full <- objective_function_info(df, "treatment", c("row", "col")) + targeted <- objective_function_info( + df, + "treatment", + c("row", "col"), + contrast_matrix = contrast + ) + + expect_false(full$estimable) + expect_true(targeted$estimable) + expect_true(is.finite(targeted$score)) +}) + +test_that("custom contrasts require treatment column names", { + df <- default_design(2, 10) + Sigma <- default_sigma(2, 10) + contrast <- matrix(c(1, -1, rep(0, 8)), nrow = 1) + + expect_error( + objective_function_info( + df, "treatment", c("row", "col"), + Sigma = Sigma, contrast_matrix = contrast + ), + "must have column names" + ) +}) + +test_that("named contrasts match treatments rather than column positions", { + df <- default_design(2, 10) + df <- df[order(df$row, df$col), ] + treatments <- paste0("T", 1:10) + df$treatment <- factor(df$treatment, levels = treatments) + Sigma <- default_sigma(2, 10) + contrast <- matrix( + c(1, -1, rep(0, 8)), nrow = 1, + dimnames = list("T1 - T2", treatments) + ) + + # T2's coefficient is T2 - T1 in this full-rank reference model. + model <- model.matrix(~ factor(block) + treatment, df) + covariance <- solve(crossprod(model, solve(Sigma, model))) + variance <- covariance["treatmentT2", "treatmentT2"] + df$treatment <- as.character(df$treatment) + reordered <- df[rev(seq_len(nrow(df))), ] + reordered$treatment <- factor(reordered$treatment, levels = rev(treatments)) + + for (layout in list(df, reordered)) { + for (columns in list(seq_along(treatments), rev(seq_along(treatments)))) { + result <- objective_function_info( + layout, "treatment", c("row", "col"), + Sigma = Sigma, contrast_matrix = contrast[, columns, drop = FALSE] + ) + expect_equal(result$A_value, variance, tolerance = 1e-10) + expect_equal(result$D_value, log(variance), tolerance = 1e-10) + expect_equal(unname(result$contrast_matrix[, "T2"]), -1) + expect_equal(unname(result$contrast_matrix[, "T10"]), 0) + } + } +}) + +test_that("contrast columns identify each treatment exactly once", { + treatments <- c("T1", "T2", "T10") + contrast <- matrix(c(1, -1, 0), nrow = 1, + dimnames = list(NULL, treatments)) + + expect_error( + .prepare_contrast_matrix(cbind(contrast, T2 = 0), treatments, 1e-9), + "one column per treatment" + ) + for (last_name in c("T2", "unknown", "", NA_character_)) { + colnames(contrast) <- c("T1", "T2", last_name) + expect_error( + .prepare_contrast_matrix(contrast, treatments, 1e-9), + "must match the treatment levels" + ) + } +}) + +test_that("incremental calculation matches full recalculation", { + df <- data.frame( + row = rep(1:3, each = 4), + col = rep(1:4, times = 3), + block = rep(1:3, each = 4), + treatment = rep(LETTERS[1:4], 3) + ) + Sigma <- default_sigma(3, 4) + current <- objective_function_info( + df, + "treatment", + c("row", "col"), + Sigma = Sigma + ) + + proposal <- df + proposal$treatment[c(1, 2, 7, 8)] <- proposal$treatment[c(2, 1, 8, 7)] + incremental <- objective_function_info( + proposal, + "treatment", + c("row", "col"), + Sigma = Sigma, + current_score_obj = current, + swapped_items = c("A", "B", "C", "D") + ) + full <- objective_function_info( + proposal, + "treatment", + c("row", "col"), + Sigma = Sigma + ) + + expect_equal(incremental$info_matrix, full$info_matrix, tolerance = 1e-12) + expect_equal(incremental$score, full$score, tolerance = 1e-12) + + # Reuse the original score object as if the first proposal was rejected. + second_proposal <- df + second_proposal$treatment[c(3, 4)] <- second_proposal$treatment[c(4, 3)] + second_incremental <- objective_function_info( + second_proposal, + "treatment", + c("row", "col"), + Sigma = Sigma, + current_score_obj = current, + swapped_items = c("C", "D") + ) + second_full <- objective_function_info( + second_proposal, + "treatment", + c("row", "col"), + Sigma = Sigma + ) + + expect_equal( + second_incremental$info_matrix, + second_full$info_matrix, + tolerance = 1e-12 + ) +}) + +test_that("covariance matrices remain aligned when layout rows are reordered", { + df <- default_design() + Sigma <- default_sigma() + sorted <- df[order(df$row, df$col), ] + reordered <- df[rev(seq_len(nrow(df))), ] + L <- compute_L_projection(df, Sigma) + + for (criterion in c("A", "D")) { + original <- objective_function_info( + sorted, "treatment", c("row", "col"), + criterion = criterion, Sigma = Sigma + ) + for (layout in list(df, reordered)) { + result <- objective_function_info( + layout, "treatment", c("row", "col"), + criterion = criterion, Sigma = Sigma + ) + incremental <- objective_function_info( + layout, "treatment", c("row", "col"), + criterion = criterion, Sigma = Sigma, + current_score_obj = original, swapped_items = unique(df$treatment) + ) + precomputed <- objective_function_info( + layout, "treatment", c("row", "col"), + criterion = criterion, L_matrix = L + ) + + expect_equal(result$info_matrix, original$info_matrix, tolerance = 1e-12) + expect_equal(result$score, original$score, tolerance = 1e-12) + expect_equal(incremental$info_matrix, original$info_matrix, tolerance = 1e-12) + expect_equal(precomputed$info_matrix, original$info_matrix, tolerance = 1e-12) + } + } +}) + +test_that("spatial scoring uses numeric coordinates and custom grid columns", { + df <- default_design() + Sigma <- default_sigma() + original <- objective_function_info(df, "treatment", c("row", "col"), Sigma = Sigma) + names(df)[names(df) == "row"] <- "x" + names(df)[names(df) == "col"] <- "y" + df$x <- factor(df$x, levels = 4:1) + df$y <- factor(df$y, levels = 6:1) + + for (index in list(NULL, grid_indices(df, "x", "y"))) { + result <- objective_function_info( + df, "treatment", c("x", "y"), Sigma = Sigma, + row_column = "x", col_column = "y", grid_index = index + ) + expect_equal(result$info_matrix, original$info_matrix, tolerance = 1e-12) + } +}) + +test_that("spatial scoring orders multiple grids consistently", { + df <- default_design(3, 4) + df <- rbind(transform(df, site = "A"), transform(df, site = "B")) + df$block <- interaction(df$site, df$block, drop = TRUE) + df$treatment[c(13, 16)] <- df$treatment[c(16, 13)] + Sigma <- kronecker(diag(c(1, 2)), default_sigma(3, 4)) + original <- objective_function_info( + df, "treatment", c("row", "col"), Sigma = Sigma, by = "site" + ) + site_a <- objective_function_info( + df[1:12, ], "treatment", c("row", "col"), Sigma = Sigma[1:12, 1:12] + ) + site_b <- objective_function_info( + df[13:24, ], "treatment", c("row", "col"), Sigma = Sigma[13:24, 13:24] + ) + expect_equal(original$info_matrix, site_a$info_matrix + site_b$info_matrix, tolerance = 1e-12) + reordered <- df[rev(seq_len(nrow(df))), ] + for (index in list(NULL, grid_indices(reordered, by = "site"))) { + result <- objective_function_info( + reordered, "treatment", c("row", "col"), Sigma = Sigma, + by = "site", grid_index = index + ) + expect_equal(result$info_matrix, original$info_matrix, tolerance = 1e-12) + } + + result <- speed( + reordered, + swap = "treatment", + swap_within = "block", + grid_factors = list(dim1 = "row", dim2 = "col", by = "site"), + obj_function = objective_function_info, + Sigma = Sigma, + iterations = 20, + early_stop_iterations = 100, + optimise_params = optim_params(random_initialisation = 2), + seed = 1, + quiet = TRUE + ) + final <- objective_function_info( + result$design_df, "treatment", c("row", "col"), Sigma = Sigma, by = "site" + ) + expect_equal(result$score, final$score, tolerance = 1e-10) + expect_lte(result$score, original$score) +}) + +test_that("spatial scoring accepts covariance for observed plots only", { + df <- default_design(3, 4) + df <- df[order(df$row, df$col), ] + observed <- setdiff(seq_len(nrow(df)), c(2, 7)) + df <- df[observed, ] + Sigma <- default_sigma(3, 4)[observed, observed] + original <- objective_function_info(df, "treatment", c("row", "col"), Sigma = Sigma) + reordered <- objective_function_info( + df[rev(seq_len(nrow(df))), ], "treatment", c("row", "col"), Sigma = Sigma + ) + + expect_true(original$estimable) + expect_equal(reordered$info_matrix, original$info_matrix, tolerance = 1e-12) + expect_equal(reordered$score, original$score, tolerance = 1e-12) +}) + +test_that("cached projections are rebuilt when nuisance effects change", { + df <- default_design() + Sigma <- default_sigma() + + for (covariance in list(NULL, Sigma)) { + original <- objective_function_info(df, "treatment", c("row", "col"), Sigma = covariance) + proposal <- df + proposal$block[c(1, 6)] <- proposal$block[c(6, 1)] + incremental <- objective_function_info( + proposal, "treatment", c("row", "col"), Sigma = covariance, + current_score_obj = original, swapped_items = unique(df$treatment) + ) + full <- objective_function_info(proposal, "treatment", c("row", "col"), Sigma = covariance) + + expect_false(isTRUE(all.equal(full$info_matrix, original$info_matrix))) + expect_equal(incremental$info_matrix, full$info_matrix, tolerance = 1e-12) + expect_equal(incremental$score, full$score, tolerance = 1e-12) + } +}) + +test_that("formula expansion and environment changes invalidate the projection", { + df <- default_design(3, 4) + df <- df[order(df$row, df$col), ] + df$block <- factor(df$block) + Sigma <- default_sigma(3, 4) + + for (covariance in list(NULL, Sigma)) { + nuisance <- ~ . - treatment - row - col + original <- objective_function_info( + df, "treatment", c("row", "col"), + Sigma = covariance, nuisance_formula = nuisance + ) + proposal <- df + proposal$block[c(1, 6)] <- proposal$block[c(6, 1)] + cached <- objective_function_info( + proposal, "treatment", c("row", "col"), + Sigma = covariance, nuisance_formula = nuisance, + current_score_obj = original, swapped_items = unique(df$treatment) + ) + full <- objective_function_info( + proposal, "treatment", c("row", "col"), + Sigma = covariance, nuisance_formula = nuisance + ) + expect_false(isTRUE(all.equal(original$info_matrix, full$info_matrix))) + expect_equal(cached$info_matrix, full$info_matrix, tolerance = 1e-10) + expect_equal(cached$score, full$score, tolerance = 1e-10) + + adjustment <- rep(c(0, 1, 0, 1), 3) + nuisance <- ~ block + adjustment + original <- objective_function_info( + df, "treatment", c("row", "col"), + Sigma = covariance, nuisance_formula = nuisance + ) + adjustment <- rep(c(0, 0, 1, 1), 3) + cached <- objective_function_info( + df, "treatment", c("row", "col"), + Sigma = covariance, nuisance_formula = nuisance, + current_score_obj = original, swapped_items = unique(df$treatment) + ) + full <- objective_function_info( + df, "treatment", c("row", "col"), + Sigma = covariance, nuisance_formula = nuisance + ) + expect_false(isTRUE(all.equal(original$info_matrix, full$info_matrix))) + expect_equal(cached$info_matrix, full$info_matrix, tolerance = 1e-10) + } +}) + +test_that("the default nuisance model requires at least two blocks", { + df <- data.frame(treatment = rep(c("A", "B"), 2)) + expect_error(objective_function_info(df, "treatment", character()), "at least two blocks") + df$block <- factor(rep(1, 4), levels = 1:2) + expect_error(objective_function_info(df, "treatment", character()), "at least two blocks") + df$block <- rep(NA_integer_, 4) + expect_error(objective_function_info(df, "treatment", character()), "at least two blocks") + df$block <- c(1, 1, 2, NA) + expect_error(objective_function_info(df, "treatment", character()), "missing") +}) + +test_that("explicit nuisance models can replace the block model", { + df <- default_design(3, 4) + Sigma <- default_sigma(3, 4) + original <- objective_function_info(df, "treatment", c("row", "col"), Sigma = Sigma) + L <- compute_L_projection(df, Sigma) + + for (blocks in list(NULL, rep(1, nrow(df)))) { + df$block <- blocks + custom <- objective_function_info( + df, "treatment", c("row", "col"), Sigma = Sigma, + nuisance_formula = ~ factor(row) + ) + precomputed <- objective_function_info( + df, "treatment", c("row", "col"), L_matrix = L + ) + expect_equal(custom$info_matrix, original$info_matrix, tolerance = 1e-12) + expect_equal(precomputed$info_matrix, original$info_matrix, tolerance = 1e-12) + } +}) + +test_that("intercept-only nuisance formulas produce the expected information", { + df <- data.frame(row = 1:4, col = 1L, treatment = c("A", "B", "A", "B")) + for (covariance in list(NULL, diag(4))) { + result <- objective_function_info( + df, "treatment", c("row", "col"), + Sigma = covariance, nuisance_formula = ~ 1 + ) + expect_equal(unname(result$info_matrix), matrix(c(1, -1, -1, 1), 2, 2)) + expect_equal(result$A_value, 0.5, tolerance = 1e-10) + } +}) + +test_that("Sigma and L_matrix are mutually exclusive", { + df <- data.frame( + row = 1:4, + col = 1:4, + treatment = rep(c("A", "B"), 2) + ) + + expect_error( + objective_function_info( + df, + "treatment", + c("row", "col"), + Sigma = diag(4), + L_matrix = diag(4) + ), + "Only one" + ) +}) + + +# ---- Test with speed function + +test_that("speed() optimises with D-optimality", { + df <- default_design() + Sigma <- default_sigma() + + result <- speed( + df, + swap = "treatment", + swap_within = "block", + obj_function = objective_function_info, + criterion = "D", + Sigma = Sigma, + iterations = 100, + early_stop_iterations = 200, + seed = 1, + quiet = TRUE + ) + final <- objective_function_info( + result$design_df, "treatment", c("row", "col"), + criterion = "D", Sigma = Sigma + ) + + expect_lt(result$score, 0) + expect_equal(result$iterations_run, 100) + expect_identical(result$metadata$per_level[[1]]$stop_reason, "iterations") + expect_equal(result$score, final$score, tolerance = 1e-10) +}) + +# Actually test by passing to speed +test_that("speed() optimises an RCBD with the info objective under AR1xAR1", { + df <- default_design() + Sigma <- default_sigma() + + result <- speed( + df, + swap = "treatment", + swap_within = "block", + spatial_factors = ~ block + row + col, + obj_function = objective_function_info, + Sigma = Sigma, + criterion = "A", + optimise_params = optim_params(random_initialisation = TRUE), + seed = 42, + quiet = TRUE + ) + + expect_lt(result$score, Inf) + + info <- objective_function_info( + result$design_df, + "treatment", + c("row", "col"), + Sigma = Sigma + ) + expect_equal(info$rank, 5) + expect_true(is.finite(info$A_value)) +}) diff --git a/tests/testthat/test-optim_params.R b/tests/testthat/test-optim_params.R index 16f4eca..6c72a86 100644 --- a/tests/testthat/test-optim_params.R +++ b/tests/testthat/test-optim_params.R @@ -8,7 +8,8 @@ test_that("optim_params works with no arguments", { "random_initialisation", "adj_weight", "bal_weight", - "stop_at_optimal" + "stop_at_optimal", + "lower_bound" ) optimize_params <- optim_params() @@ -27,7 +28,8 @@ test_that("optim_params works with arguments", { "random_initialisation", "adj_weight", "bal_weight", - "stop_at_optimal" + "stop_at_optimal", + "lower_bound" ) optimize_params <- optim_params(swap_count = 2) @@ -57,7 +59,8 @@ test_that("optim_params works with arguments", { random_initialisation = 3, adj_weight = 2, bal_weight = 3, - stop_at_optimal = FALSE + stop_at_optimal = FALSE, + lower_bound = -10 ) optimize_params <- do.call(optim_params, optimize_params_expected) @@ -77,7 +80,8 @@ test_that("optim_params works with legacy options", { "random_initialisation", "adj_weight", "bal_weight", - "stop_at_optimal" + "stop_at_optimal", + "lower_bound" ) withr::with_options( @@ -151,3 +155,13 @@ test_that("optim_params throws error for invalid inputs", { expect_error(optim_params(stop_at_optimal = "TRUE")) expect_error(optim_params(stop_at_optimal = 1)) }) + +test_that("optim_params validates lower_bound", { + expect_null(optim_params()$lower_bound) + for (bound in c(-1, 0, 1)) { + expect_identical(optim_params(lower_bound = bound)$lower_bound, bound) + } + for (bound in list("0", TRUE, numeric(0), c(0, 1), NA_real_, NaN, Inf, -Inf, 1i)) { + expect_error(optim_params(lower_bound = bound), "`lower_bound`") + } +}) diff --git a/tests/testthat/test-speed-layouts.R b/tests/testthat/test-speed-layouts.R index bcea375..a9f4c52 100644 --- a/tests/testthat/test-speed-layouts.R +++ b/tests/testthat/test-speed-layouts.R @@ -94,6 +94,7 @@ test_that("speed works with a custom objective function", { swap = "treatment", spatial_factors = ~ row + col, obj_function = custom_obj_function(), + optimise_params = optim_params(lower_bound = 0), iterations = 1000, seed = 42, quiet = TRUE diff --git a/tests/testthat/test-speed.R b/tests/testthat/test-speed.R index 8ef3462..3e1c571 100644 --- a/tests/testthat/test-speed.R +++ b/tests/testthat/test-speed.R @@ -71,6 +71,116 @@ test_that("speed returns correct output structure", { vdiffr::expect_doppelganger("speed_small", autoplot(result)) }) +test_that("annealing traverses invalid designs before reaching a valid design", { + initial_treatment <- LETTERS[1:4] + objective <- function(layout_df, swap, spatial_cols, ...) { + moved <- as.character(layout_df$treatment) != initial_treatment + return(list(score = if (all(moved)) 0 else Inf)) + } + design <- data.frame( + row = rep(1:2, each = 2), + col = rep(1:2, times = 2), + treatment = initial_treatment + ) + + result <- speed( + design, + swap = "treatment", + obj_function = objective, + iterations = 30, + early_stop_iterations = 100, + optimise_params = optim_params(stop_at_optimal = FALSE), + seed = 1, + quiet = TRUE + ) + + # No single swap can move all four treatments; an invalid step is necessary. + expect_equal(result$scores[1:2], c(Inf, Inf)) + expect_equal(result$score, 0) + expect_true(all(as.character(result$design_df$treatment) != initial_treatment)) +}) + +test_that("annealing rejects an invalid proposal from a finite design", { + initial_treatment <- LETTERS[1:4] + objective <- function(layout_df, swap, spatial_cols, ...) { + score <- if (identical(as.character(layout_df$treatment), initial_treatment)) 0 else Inf + return(list(score = score)) + } + design <- data.frame( + row = rep(1:2, each = 2), + col = rep(1:2, times = 2), + treatment = initial_treatment + ) + + result <- speed( + design, + swap = "treatment", + obj_function = objective, + iterations = 1, + early_stop_iterations = 10, + optimise_params = optim_params(stop_at_optimal = FALSE), + seed = 1, + quiet = TRUE + ) + + expect_equal(result$scores, 0) + expect_equal(result$score, 0) + expect_identical(as.character(result$design_df$treatment), initial_treatment) +}) + +test_that("all-invalid annealing runs finish without NaN acceptance", { + objective <- function(layout_df, swap, spatial_cols, ...) { + return(list(score = Inf)) + } + design <- data.frame( + row = rep(1:2, each = 2), + col = rep(1:2, times = 2), + treatment = LETTERS[1:4] + ) + + result <- speed( + design, + swap = "treatment", + obj_function = objective, + iterations = 5, + early_stop_iterations = 10, + optimise_params = optim_params(random_initialisation = 2, stop_at_optimal = FALSE), + seed = 1, + quiet = TRUE + ) + + expect_equal(result$iterations_run, 5) + expect_equal(result$score, Inf) + expect_true(all(is.infinite(result$scores))) +}) + +test_that("annealing accepts equal scores at zero temperature", { + design <- data.frame( + row = rep(1:2, each = 2), + col = rep(1:2, times = 2), + treatment = LETTERS[1:4] + ) + + for (value in c(0, 1, Inf)) { + objective <- function(layout_df, swap, spatial_cols, ...) { + return(list(score = value)) + } + result <- speed( + design, + swap = "treatment", + obj_function = objective, + iterations = 1, + optimise_params = optim_params(start_temp = 0, stop_at_optimal = FALSE), + seed = 1, + quiet = TRUE + ) + + expect_equal(result$score, value) + expect_setequal(as.character(result$design_df$treatment), design$treatment) + expect_false(identical(as.character(result$design_df$treatment), design$treatment)) + } +}) + test_that("speed throws error for missing columns", { test_data <- data.frame( row = rep(1:5, times = 4), @@ -214,6 +324,55 @@ test_that("speed keeps running when stop_at_optimal is FALSE", { expect_equal(result$iterations_run, 500) }) +test_that("speed uses supplied lower bounds and respects stop_at_optimal", { + test_data <- expand.grid(row = 1:2, col = 1:2) + test_data$treatment <- LETTERS[1:4] + + for (value in c(-1, 0)) { + objective <- function(layout_df, swap, spatial_cols, ...) { + return(list(score = value)) + } + for (bound in list(NULL, value - 1, value)) { + for (stop_at_optimal in c(TRUE, FALSE)) { + result <- speed( + test_data, + swap = "treatment", + obj_function = objective, + optimise_params = optim_params(lower_bound = bound, stop_at_optimal = stop_at_optimal), + iterations = 5, + early_stop_iterations = 10, + seed = 1, + quiet = TRUE + ) + + reached_bound <- stop_at_optimal && !is.null(bound) && bound == value + expect_equal(result$iterations_run, if (reached_bound) 1 else 5) + expect_equal(result$metadata$per_level[[1]]$optimal_score, bound %||% NA_real_) + expect_identical(result$metadata$per_level[[1]]$stop_reason, + if (reached_bound) "optimal" else "iterations") + } + } + } +}) + +test_that("a supplied lower bound overrides the derived bound", { + test_data <- expand.grid(row = 1:5, col = 1:4) + test_data$treatment <- LETTERS[1:4] + + result <- speed( + test_data, + swap = "treatment", + optimise_params = optim_params(lower_bound = 0), + iterations = 5, + seed = 1, + quiet = TRUE + ) + + expect_equal(result$metadata$per_level[[1]]$optimal_score, 0) + expect_equal(result$iterations_run, 5) + expect_false(result$stopped_early) +}) + test_that("speed keeps running when the optimal score is out of reach", { # having high rep for 1 treatment makes optimal score out of reach test_data <- expand.grid(row = 1:3, col = 1:4) diff --git a/tests/testthat/test-utils.R b/tests/testthat/test-utils.R index 711742c..31ef982 100644 --- a/tests/testthat/test-utils.R +++ b/tests/testthat/test-utils.R @@ -13,6 +13,13 @@ test_that("pseudo_inverse calculates Moore-Penrose inverse correctly", { expect_equal(A_inv, solve(A), tolerance = 1e-10) }) +test_that("pseudo_inverse handles 1x1 matrices", { + for (value in c(2, 0.5)) { + A <- matrix(value, nrow = 1, ncol = 1) + expect_equal(pseudo_inverse(A), matrix(1 / value, nrow = 1, ncol = 1)) + } +}) + test_that("pseudo_inverse handles singular matrices", { # Test with a rank-deficient matrix (singular) singular_matrix <- matrix(c(1, 2, 2, 4), nrow = 2, ncol = 2)