Feature/keep with

[rogerssam]

Adds the ability to keep specified columns together after treatment swaps.
Fixes #105

[wvjgsuhp]

Not sure if related to this change, but got these stray snaps when running tests locally.

[rogerssam]

Not sure if related to this change, but got these stray snaps when running tests locally.

Yeah, they were added a while ago, and then the tests were removed, so they keep getting trashed but then brought back. I think I've removed them in #120 so they should stop showing up when that's merged.

[rogerssam]

Also fixes #122 now.

I've reworked the way this operates to be more straight-forward.

[wvjgsuhp]

Somehow the warning is not emitted when swap_all cannot be made.
Tested with

df <- data.frame(
  row = rep(1:6, times = 2),
  col = rep(1:2, each = 6),
  block = c(1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2),
  site = c("a", "a", "a", "b", "b", "b", "a", "a", "a", "b", "b", "b"),
  lines = c("X", "X", "Z", "Y", "Y", "Z", "Y", "Y", "Z", "X", "X", "Z"),
  stringsAsFactors = FALSE
)
df$plot_id <- sprintf("P%02d", seq_len(nrow(df)))

a = speed(
  df,
  swap = "lines",
  optimise = list(
    lvl1 = list(swap_within = "block", swap_all = TRUE),
    lvl2 = list(swap_within = "site", swap_all = TRUE)
  ),
  linked_cols = "plot_id",
  iterations = 30,
  seed = 1,
  quiet = TRUE
)$design_df
table(a$site, a$lines)

[Copilot]

Pull request overview

This PR adds support for keeping “companion” columns aligned with the treatment column during optimisation via a new linked_cols argument, so descriptive metadata (e.g., variety names) stays paired with the swapped treatment codes. It also improves optimisation robustness and reporting by tracking why each optimisation level stopped and by avoiding unnecessary factor round-trips for unused columns.

Changes:

• Added linked_cols to speed() and integrated linked-column movement into neighbour generation and random initialisation.
• Refactored per-level argument resolution (create_speed_input() + .level_value()) and tightened validation around per-level columns and linked-column rules.
• Enhanced optimisation loop diagnostics: stop_reason metadata, warnings for frozen swap_all groups, and updated summary() output/tests.

Reviewed changes

Copilot reviewed 14 out of 30 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
R/speed.R	Adds linked_cols, normalises inputs earlier, limits factor conversion to optimised columns, records per-level stop reasons.
R/design_utils.R	Implements linked-column movement in swaps/shuffles; adds swappability precomputation + warnings.
R/utils.R	Updates to_factor() to be column-selective; adds .level_value() and per-level column helpers.
R/verify_utils.R	Adds unified .verify_inputs() and new resolved-list checks for per-level columns and linked columns.
R/summary.R	Surfaces per-level stop_reason in summary() and print output.
R/constants.R	Updates defaults to support per-level optimise param resolution.
tests/testthat/test-linked_cols.R	Adds comprehensive tests for linked_cols behaviour + validation rules.
tests/testthat/test-utils.R	Adds tests for selective factor conversion and per-level list resolution in create_speed_input().
tests/testthat/test-design_utils.R	Adds/updates tests for swappability and stop reasons/warnings.
tests/testthat/test-summary.R	Updates expectations to match new stop-reason wording/colouring.
tests/testthat/test-speed.R	Adds regression test ensuring unused columns remain untouched (e.g., Date).
vignettes/speed.qmd	Documents the new linked_cols feature with simple + hierarchical examples.
NEWS.md	Adds release notes for linked_cols and related optimisation/reporting changes.
man/*.Rd	Updates generated documentation for new/changed internal and exported APIs.
CLAUDE.md	Adds contributor guidance on keeping @param entries short.
.gitignore	Ignores vignette cache and .claude directory.

Files not reviewed (15)

• man/create_speed_input.Rd: Generated file
• man/dot-level_fixed_cols.Rd: Generated file
• man/dot-level_optimised_cols.Rd: Generated file
• man/dot-level_value.Rd: Generated file
• man/dot-warn_unequal_replication.Rd: Generated file
• man/exchange_linked.Rd: Generated file
• man/generate_multi_swap_neighbour.Rd: Generated file
• man/generate_neighbour.Rd: Generated file
• man/generate_single_swap_neighbour.Rd: Generated file
• man/shuffle_items.Rd: Generated file
• man/speed.Rd: Generated file
• man/summary.design.Rd: Generated file
• man/swappable_groups.Rd: Generated file
• man/to_factor.Rd: Generated file
• man/verify.Rd: Generated file

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.