Design, Analysis and Breedbase Storage of Plant Breeding Trials • breedtools

Design and analysis of augmented plant breeding trials.

Augmented row-column designs (Piepho and Williams, 2016): unreplicated entries plus replicated checks in rows, columns and superimposed blocks. Row and column groups can be unequal, blocks can hold any number of check plots, and checks are placed by a D-optimal search (or covering Latin rectangles for regular layouts). Analyses can use random blocks, random entries (BLUPs), or a ‘SpATS’ spatial model.
Augmented p-rep designs (Williams, Piepho and Whitaker, 2011): multi-location, partially replicated trials in incomplete blocks where pairs of entries share a block at most once. Choose the construction with method: a flexible randomized "search", the paper’s partial alpha-array construction ("alpha"), or its augmented alpha(2)-array construction ("alpha2"). augmented_prep_parameters() lists the feasible settings, and every design reports its efficiency factor.
Resolvable row-column designs (Williams, John and Whitaker, 2006): fully replicated trials with rows and columns within replicates, optimized for row-column and spatial (linear variance) efficiency, with latinized options; analyses with RC, LV + RC and AR + RC models by REML.
Analysis: ANOVA with degrees of freedom that are estimable from the observed plots, plus adjusted entry means (BLUEs) with standard errors, the mean SED and the 5% LSD. p-rep analyses fit replicates within locations and can add a fixed or random (REML) genotype-by-location interaction. A two-stage analysis (analyze_augmented_prep_two_stage()) handles heterogeneous error variances across locations and optional spatial adjustment with ‘SpATS’.
Field maps and ‘Breedbase’: a plot-level field book and upload files, or save the design directly into a Breedbase breeding program and folder through BrAPI with save_breedbase(), after checking the location and accessions with breedbase_check(). After harvest, save the phenotypic data by plot and trait name with save_breedbase_phenotypes() (sheet from phenotype_template()), and the analysis results: first-stage plot values as a trait of the field plots (save_breedbase_first_stage()) and second-stage genotype means as a Breedbase analysis (save_breedbase_analysis()).
agricolae designs: generate a design with the CRAN package agricolae, convert and record trial information with prepare_breedbase_trial(), then use the same save_breedbase() and phenotype_template() workflow.
Multi-environment tools: read ‘Breedbase’ phenotype files, run Hartley’s Fmax variance check, and group environments by GxE.

Installation

# install.packages("remotes")
remotes::install_github("solgenomics/breedtools")

Documentation

Website: https://solgenomics.github.io/breedtools/. The function reference groups every function by task and shows its arguments with examples you can run.
Tutorial: vignette("breedtools") walks through every design and analysis with simulated data.
In R: help(package = "breedtools") lists every help page. ?augmented_row_column_design opens one page, and example(augmented_row_column_design) runs its examples.
All functions are listed by task at the end of this page.

Find layout options from your entry count

library(breedtools)
design_options(n_entries = 100)  # field dimensions and checks not yet known
design_options(108, design = "augmented_row_column", n_checks = 4, rows = 12, cols = 12)
design_options(42, design = "resolvable", n_reps = 3, cols = 7)

Options report field size, checks, replication, plot counts, unused positions and nominal error degrees of freedom. Augmented row-column options expose rows_in_field, cols_in_field, rows_per_block, cols_per_block, checks_per_block, method and n_candidates for an explicit generator call. See ?design_options for selecting and generating one. These are parameter options to check with the generator, its summary and check_design().

Example

library(breedtools)

rc <- augmented_row_column_design(
  treatments = sprintf("LINE_%03d", 1:108),
  controls = c("CHECK_A", "CHECK_B", "CHECK_C", "CHECK_D"),
  rows_in_field = 12, cols_in_field = 12,
  rows_per_block = 4, cols_per_block = 4,
  seed = 2026
)
plot_augmented_row_column_design(rc)

field <- rc$design
field$yield <- rnorm(nrow(field), 60, 3)   # your phenotypes here
fit <- analyze_augmented_row_column_design(field, response = "yield")
fit                      # ANOVA and top adjusted means
fit$adjusted_means       # all entries ranked by adjusted mean

To see the full workflow, run vignette("breedtools"), or open the RStudio script:

file.edit(system.file("examples", "breedtools_workflow.R", package = "breedtools"))

Save an agricolae design as a new Breedbase trial

accessions <- c("G1", "G2", "G3", "CHECK_A")  # existing Breedbase accession names
randomized <- agricolae::design.rcbd(accessions, r = 3, seed = 2026)
trial <- prepare_breedbase_trial(
  randomized, trial_name = "RCBD_2026", year = 2026,
  location = "Ibadan", program = "Your breeding program",
  description = "RCBD with three complete blocks generated with agricolae",
  checks = "CHECK_A", prompt = FALSE
)

# Inspect the trial and plot payload without a connection.
payload <- save_breedbase(trial, dry_run = TRUE)

# Check against your database, then save as a new trial.
con <- breedbase_login("https://your-breedbase.org", "your_username")
save_breedbase(trial, con, dry_run = TRUE)
save_breedbase(trial, con)

prepare_breedbase_trial() records the required trial information once and converts the field book. In an interactive RStudio session, it can ask for missing name, year, location, program and description. Use phenotype_template(trial) to make a field sheet with the recorded trial’s plot names. Preparation is offline; saving uses your existing connection.

The converter preserves the randomization. It recognizes CRD, RCBD, alpha, lattice, augmented block, split-plot and strip-plot types. For a field book alone, including agricolae::zigzag() output, supply design_type. For multiple treatment factors, select the accession column explicitly, e.g. accession = "genotype". Other factors and the main-plot/subplot hierarchy remain in trial$book; the save function uploads individual plots. See ?as_breedbase_design for column mapping and other design types.

The complete tour in scripts/validate_designs.R includes a second analyzed trait added to existing analysis projects (A11), an independent single-stage analysis (run A1-A6, then A12), and the full agricolae workflow (Part I). Part H reads existing Breedbase trials and lets you choose "single", "two_stage" or "both" through breedbase_analysis_route; multiple traits are stored in the same analysis projects.

All functions

Each function has a help page with runnable examples: ?function_name, then example(function_name). Functions that connect to Breedbase have examples in \dontrun{}. To run them, you need a server and an account.

1. Choose a design

Function	What it does
`design_options()`	Suggests layouts for any design from the number of entries and the field size, if you know it
`augmented_row_column_capacity()`	Counts the entries and checks that fit in an augmented row-column field
`augmented_row_column_layouts()`	Lists the analyzable block layouts of an augmented row-column field
`augmented_prep_parameters()`	Lists feasible settings for the alpha and alpha(2) p-rep constructions

design_options(n_entries = 100)
augmented_row_column_layouts(rows_in_field = 12, cols_in_field = 12)
augmented_prep_parameters(n_treatments = 20, n_locations = 2)

2. Augmented row-column designs (one plot per entry, replicated checks)

Function	What it does
`augmented_row_column_design()`	Generates the design with D-optimal or Latin check placement
`plot_augmented_row_column_design()`	Draws the field map
`analyze_augmented_row_column_design()`	ANOVA and adjusted means using fixed or random blocks, random entries (BLUPs), or a SpATS model

rc <- augmented_row_column_design(paste0("G", 1:108), paste0("C", 1:4),
                                  rows_in_field = 12, cols_in_field = 12,
                                  rows_per_block = 4, cols_per_block = 4, seed = 1)
plot_augmented_row_column_design(rc)
d <- rc$design; d$yield <- rnorm(nrow(d), 50, 3)
fit <- analyze_augmented_row_column_design(d, "yield")
fit$adjusted_means

3. Augmented p-rep designs (several locations, part of the entries repeated)

Function	What it does
`augmented_prep_design()`	Generates the design (`method = "search"`, `"alpha"` or `"alpha2"`)
`augmented_prep_concurrence()`	Counts how often each pair of entries shares a block
`plot_augmented_prep_design()`	Draws the field map of each location
`analyze_augmented_prep_design()`	Single-stage analysis with optional genotype-by-location interaction
`analyze_augmented_prep_two_stage()`	Two-stage analysis with heterogeneous error variances and optional SpATS

prep <- augmented_prep_design(paste0("G", 1:60), locations = c("North", "South"),
                              block_size = 6, field_cols = 10, seed = 1)
plot_augmented_prep_design(prep)
d <- prep$design; d$yield <- rnorm(nrow(d), 25, 3)
analyze_augmented_prep_design(d, "yield")
analyze_augmented_prep_two_stage(d, "yield")

4. Resolvable row-column designs (fully replicated)

Function	What it does
`resolvable_row_column_design()`	Generates a spatially optimized design, including latinized options
`resolvable_row_column_efficiency()`	Calculates row-column, linear variance and AR efficiencies of a design
`plot_resolvable_row_column_design()`	Draws the field map
`analyze_resolvable_row_column()`	Fits RC, LV + RC or AR + RC models by REML

rr <- resolvable_row_column_design(paste0("T", 1:42), n_reps = 3,
                                   rows_per_rep = 6, cols_per_rep = 7, seed = 1)
resolvable_row_column_efficiency(rr)
plot_resolvable_row_column_design(rr)
d <- rr$design; d$yield <- rnorm(nrow(d), 40, 4)
analyze_resolvable_row_column(d, "yield", model = "rc")   # or "lv", "ar"

5. Analysis for any design

Function	What it does
`plot_trait()`	Plots a trait’s distribution and field map
`find_outliers()` / `remove_outliers()`	Flags or removes outlying plots with the IQR rule
`analyze_two_stage()`	Two-stage analysis of several trials of any design
`analyze_single_stage()`	Single-stage analysis of several trials, as an alternative
`compare_first_stage()`	Compares raw and first-stage adjusted plot values
`first_stage_values()`	Returns the adjusted plot values to store as a trait
`second_stage_values()`	Returns the genotype values to store as a Breedbase analysis
`prediction_accuracy()`	Correlates adjusted means with known (simulated) genotype values

plot_trait(d, "yield")
find_outliers(d, "yield")
fit2 <- analyze_two_stage(met, "yield", stage1 = "design")  # met: trials stacked with a location column
second_stage_values(fit2, trait = "fresh root yield")

6. Design checks

Function	What it does
`check_setup()`	Checks that packages and the output folder are ready
`check_design()`	Runs the standard checks on any design, such as plot use, entry counts, check placement and estimable effects
`check_section()` / `check_result()`	Labels a section and records your own checks
`check_summary()` / `check_reset()`	Prints or clears the recorded checklist

check_reset(); check_design(rc); check_summary()

7. Breedbase: connect, look up and save designs

Function	What it does
`breedbase_login()`	Logs in to a Breedbase server through BrAPI
`breedbase_programs()` / `breedbase_folders()` / `breedbase_locations()`	Lists breeding programs, trial folders and locations
`breedbase_check()`	Checks the program, folder, location, accessions and trial name before you save
`prepare_breedbase_trial()`	Converts an agricolae design and records the trial information
`as_breedbase_design()`	Converts an agricolae field book only (column mapping)
`save_breedbase()`	Saves a design as a new trial with its plots (`dry_run = TRUE` previews it)
`breedbase_trial_plots()`	Reads the plots of a saved trial
`phenotype_template()`	Makes a phenotyping sheet with the Breedbase plot names

con <- breedbase_login("https://your-breedbase.org", "your_username")
breedbase_programs(con)
breedbase_check(con, accessions = rc, location = "Ibadan", program = "Cassava")
save_breedbase(rc, con, program = "Cassava", folder = "AYT 2026",
               trial_name = "AYT_2026_Ibadan", year = 2026, location = "Ibadan",
               description = "Advanced yield trial", dry_run = TRUE)
phenotype_template(rc, trial_name = "AYT_2026_Ibadan", traits = "fresh root yield")

8. Breedbase: phenotypes and analysis results

Function	What it does
`breedbase_phenotypes()`	Reads phenotypes of trials by trial and trait name
`save_breedbase_phenotypes()`	Saves phenotypes by plot and trait name
`save_breedbase_first_stage()`	Saves first-stage plot values as a trait of the field plots
`save_breedbase_analysis()`	Saves second-stage genotype values as a Breedbase analysis
`add_breedbase_analysis_values()`	Adds another trait to an existing analysis
`breedbase_statistics()`	Lists the statistic terms of the SGNSTAT ontology
`breedbase_adjusted_trait()`	Finds or creates the trait used for adjusted values
`breedbase_refresh()`	Refreshes the server’s phenotype cache

9. Multi-environment trials from Breedbase files

Function	What it does
`read_breedbase_file()` / `read_breedbase_excel()`	Reads Breedbase phenotype or design files (Excel, CSV, TSV)
`prepare_breedbase_pheno()`	Prepares phenotypes for multi-environment analysis
`run_breedbase_variance_check()`	Analyzes each environment, runs Hartley’s Fmax test and finds compatible groups
`run_environment_stratification()`	Groups environments by GxE using Lin (1982)
`run_breedbase_environment_stratification()`	Runs the same grouping directly from a Breedbase file
`read_locations()` / `map_environment_groups()`	Loads location coordinates and draws the groups on a map

pheno_file <- system.file("extdata", "breedbase_pheno.csv", package = "breedtools")
loc_file   <- system.file("extdata", "breedbase_locations.csv", package = "breedtools")
vc <- run_breedbase_variance_check(pheno_file, trait_col = "fresh root yield|CO_334:0000013")
vc$maximal_compatible_groups
st <- run_environment_stratification(pheno_file, trait = "fresh root yield")
map_environment_groups(st, read_locations(loc_file, phenotype_data = st))

10. Building blocks and helpers

The pipeline functions above call these lower-level functions. You can call them yourself to run one step at a time.

Group	Functions
Variance check	`analyze_environment_anova()`, `analyze_one_environment()`, `hartley_fmax_test()`, `hartley_critical_sim()`, `make_environment_groups()`, `get_compatible_groups()`, `get_maximal_groups()`, `harmonic_mean()`
Environment stratification	`prepare_environment_stratification_data()`, `detect_design()`, `prepare_design_factors()`, `calculate_environment_stratification_anova()`, `lin_group_environments()`, `lin_test_group()`, `lin_ss_ge()`, `lin_error_mse()`, `complete_environment_info()`, `add_environment_metadata()`, `add_pairwise_environment_metadata()`, `environment_summary_by_group()`
Columns and empty tables	`find_column()`, `guess_column()`, `normalize_column_name()`, `empty_anova()`, `empty_group_membership()`, `empty_group_summary()`, `empty_pairwise()`, `empty_ungrouped()`