Extract and Pad a Sub-Trial from a Field Trial Layout

Given a field trial data frame that mixes multiple plot types (e.g. test lines, checks, guard rows), padTrial() extracts the rectangular sub-trial occupied by a target plot type and, optionally, inserts placeholder rows for any missing grid positions within that rectangle.

Steps performed per group (block):

1. Check for duplicate Row × Column positions and stop with an informative error if any are found.

2. Identify the bounding box (min/max of the two spatial coordinates) for all plots matching match.

3. Subset the data to that bounding rectangle (dropping checks and guards that fall outside it).

4. If pad = TRUE, detect any Row × Column cells that are absent within the bounding box and insert placeholder rows for them, carrying identifier columns specified in keep and writing fill_value into every other character or factor column.

An add column is appended to the result, taking the value "old" for original rows and "new" for inserted padding rows.

Usage

padTrial(
  data,
  pattern = "Row:Column",
  match = "DH",
  split = "Block",
  pad = TRUE,
  keep = split,
  fill_value = "Blank",
  type_col = "Type",
  verbose = FALSE
)

Arguments

data

Data frame containing the trial layout.

pattern

Character string of the form "Var1:Var2" naming the two spatial coordinate columns (rows and columns of the field grid). Default "Row:Column".

match

Character vector of values in type_col that define the target sub-trial (e.g. test lines). The bounding box is computed from these plots only. Default "DH".

split

Character vector of one or more column names used to define independent groups (blocks) for extraction and padding. Pass NULL to treat the entire dataset as a single block. Default "Block".

pad

Logical. If TRUE (default), missing grid cells within the bounding box are inserted as placeholder rows.

keep

Character vector of column names whose values should be carried into the padding rows (must be constant within each group). Defaults to split. Ignored when split = NULL.

fill_value

Character string written into every character or factor column of the padding rows, except for columns named in keep and the two spatial coordinate columns. Numeric columns always remain NA. Default "Blank".

type_col

Name of the column in data that identifies plot types (e.g. "DH", "Check", "Guard"). Default "Type".

verbose

Logical. If TRUE, prints a per-group message reporting the detected bounding box and the number of cells padded. Default FALSE.

Value

A data frame with the same columns as data plus an add column ("old" / "new"), ordered by the first then second spatial coordinate. The spatial coordinate columns are re-levelled as factors in ascending numeric order across the combined output. When multiple split columns are supplied the temporary grouping key column is dropped before returning.

Examples

if (FALSE) { # \dontrun{
# Single blocking column
result <- padTrial(trial_df,
                   pattern    = "Row:Column",
                   match      = "DH",
                   split      = "Block",
                   fill_value = "Blank",
                   verbose    = TRUE)

# No blocking -- treat whole dataset as one group
result <- padTrial(trial_df, split = NULL)

# Multi-environment: process each Site x Block independently
result <- padTrial(trial_df, split = c("Site", "Block"))

# Custom type column name
result <- padTrial(trial_df, type_col = "PlotType", match = "Line")

table(result$add)             # count original vs padded rows
subset(result, add == "new")  # inspect the inserted blank plots
} # }