Package {beautils}

Type:	Package
Title:	Field Planning and Biostatistics Utilities
Version:	0.3.0
Maintainer:	Tiago Olivoto <tiagoolivoto@gmail.com>
Description:	A toolkit for agricultural trial planning, experimental design, and applied biostatistics. Supports generating field designs such as Latin Square, Alpha-Lattice (Patterson and Williams, 1976 <doi:10.2307/2335087>), and Factorial layouts, with automatic fieldbook creation and layout sketching. Includes a built-in QR Code engine (powered by the 'Nayuki' C library https://github.com/nayuki/QR-Code-generator) for generating printable plot labels in PDF. Also provides descriptive statistics utilities for quantitative variables following Field, Miles, and Field (2012, ISBN:978-1-4462-0045-2).
Encoding:	UTF-8
License:	MIT + file LICENSE
Depends:	R (≥ 4.1.0)
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Imports:	cli, dplyr, FielDHub, ggplot2, glue, grid, purrr, rlang, rstudioapi, tidyr
NeedsCompilation:	yes
Config/roxygen2/version:	8.1.0
Packaged:	2026-10-06 15:58:25 UTC; tiago
Author:	Tiago Olivoto [aut, cre]
Repository:	CRAN
Date/Publication:	2026-10-06 19:40:13 UTC

beautils: Field Planning and Biostatistics Utilities

Description

A toolkit for agricultural trial planning, experimental design, and applied biostatistics. Supports generating field designs such as Latin Square, Alpha-Lattice (Patterson and Williams, 1976 doi:10.2307/2335087), and Factorial layouts, with automatic fieldbook creation and layout sketching. Includes a built-in QR Code engine (powered by the 'Nayuki' C library https://github.com/nayuki/QR-Code-generator) for generating printable plot labels in PDF. Also provides descriptive statistics utilities for quantitative variables following Field, Miles, and Field (2012, ISBN:978-1-4462-0045-2).

Author(s)

Maintainer: Tiago Olivoto tiagoolivoto@gmail.com (ORCID)

Authors:

• Tiago Olivoto tiagoolivoto@gmail.com (ORCID)

Generate Alpha-Lattice Design with Fieldbook and Field Map

Description

This function generates an Alpha-Lattice design (Generalized Lattice) for experiments with a large number of treatments. It allows for the inclusion of checks, multiple locations, generates stable unique identifiers (UUID), and produces field maps (plots) with visual delimitation of incomplete blocks and repetitions.

Usage

alpha_lattice(
  trats,
  k,
  checks = NULL,
  reps = 3,
  seed = 123,
  serpentine = TRUE,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  layout_allocation = NULL,
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The Alpha-Lattice design is a resolvable incomplete block design. The function uses the FielDHub package engine for randomization but extends its functionality by:

• Validating the Layout: Ensures the provided layout_allocation is sufficient for the number of treatments.

• Visual Delimitation: In the map, thick black lines separate repetitions (resolvable blocks), while dashed red lines delimit incomplete blocks ($k$).

• UNIQUE_ID: Creates a unique ID based on metadata (YEAR, LOCATION, PLOT, etc.), facilitating traceability in databases.

Value

A list containing three elements:

Author(s)

Tiago Olivoto tiago.olivoto@ufsc.br

References

Patterson, H. D., & Williams, E. R. (1976). A new class of resolvable incomplete block designs. Biometrika, 63(1), 83-92. https://doi.org/10.2307/2335087

Examples

# Generate an alpha-lattice design
library(beautils)
design <- alpha_lattice(
  trats = paste0("T", 1:6),
  checks = c("CHECK1", "CHECK2"),
  k = 4,
  reps = 3,
  verbose = FALSE
)
design

Augmented Block Design with Fieldbook and Field Map

Description

Generates an augmented block design (Augmented RCBD) experiment, allowing for multiple locations, serpentine layout, field map (ggplot), and consolidated fieldbook.

Usage

augmented(
  lines,
  checks,
  blocks = 4,
  seed = 123,
  serpentine = TRUE,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  layout_allocation = NULL,
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The function is a wrapper around FielDHub::RCBD_augmented(), adding:

• Unique identifiers (UNIQUE_ID) per plot;

• Optional serpentine layout;

• Customized layout (⁠nrow x ncol⁠) when layout = "custom";

• Field map in ggplot with configurable colors and labels;

• Consolidated fieldbook for all locations. Main rules and validations:

• blocks must be a positive integer;

• exp_name must have length 1 or equal to locations;

• plot_start starting point for numbering (e.g., 100);

• For layout = "custom", nrow * ncol must be >= number of plots per block.

Value

A list containing three elements:

Examples

# Generate an augmented block design
library(beautils)
design <- augmented(
  lines = paste0("L", 1:4),
  checks = paste0("C", 1:2),
  blocks = 2,
  verbose = FALSE
)

Calculate Confidence Interval for the Mean

Description

Calculates the confidence interval for the mean of a quantitative variable, with or without a grouping factor. Computes sample size, mean, standard deviation, standard error, degrees of freedom, calculated t-statistic, tabulated/critical t-value, and the lower (LI) and upper (LS) confidence limits. Optionally generates an elegant horizontal confidence interval plot with the variable on the x-axis and the group on the y-axis.

Usage

conf_int(
  df,
  var,
  group = NULL,
  by = NULL,
  level = 0.95,
  mu = 0,
  na.rm = TRUE,
  plot = TRUE,
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  subtitle = NULL,
  color = "#2B6CB0",
  fill = "#4299E1",
  size = 3.5,
  linewidth = 0.8,
  width = 0.2,
  plot_theme = ggplot2::theme_minimal(),
  ...
)

Arguments

Value

A tibble data frame containing:

group

The grouping variable levels (if grouping is used).

n

Valid sample size.

media

Sample mean (\bar{x}).

desvio_padrao

Sample standard deviation (s).

se

Standard error of the mean (s / \sqrt{n}).

gl

Degrees of freedom (n - 1).

t_calc

Calculated t-statistic ((\bar{x} - \mu_0) / SE).

t_tab

Tabulated/critical t-value (t_{\alpha/2, gl}).

LI

Lower confidence limit (\bar{x} - t_{tab} \times SE).

LS

Upper confidence limit (\bar{x} + t_{tab} \times SE).

The returned object also has a "plot" attribute containing the ggplot2 plot object.

Examples

# Confidence interval for Sepal.Length grouped by Species
conf_int(iris, var = Sepal.Length, group = Species)

# Without grouping variable
conf_int(iris, var = Sepal.Length)

# Using character column names and custom confidence level (99%)
conf_int(iris, var = "Petal.Length", group = "Species", level = 0.99)

# Using a grouped data frame with dplyr pipe
library(dplyr)
iris |>
  group_by(Species) |>
  conf_int(Sepal.Width)

Create plot labels in PDF

Description

Create plot labels in PDF

Usage

create_label(
  width = 6,
  height = 2.5,
  page_size = NULL,
  page_width = 21,
  page_height = 29.7,
  top_mar = 1,
  bot_mar = 1,
  left_mar = 1,
  right_mar = 1,
  numrow = 10L,
  numcol = 3L,
  filename = file.path(tempdir(), "PlotLabel"),
  font_sz = 12,
  Treetag = FALSE,
  family = "sans",
  rounded = TRUE,
  print_across = TRUE,
  rect = TRUE,
  top_left_1 = NULL,
  top_left_2 = NULL,
  top_right_1 = NULL,
  top_right_2 = NULL,
  center_right_1 = NULL,
  center_right_2 = NULL,
  center_right_3 = NULL,
  bottom_left_1 = NULL,
  bottom_left_2 = NULL,
  unique_id = NULL,
  include_qr = TRUE,
  ec_level = 3,
  qr_size = NULL,
  lwd = 0.5,
  arc_size = 0.1,
  font_sz_tl1 = 12,
  font_sz_tl2 = 10,
  font_sz_tr1 = 12,
  font_sz_tr2 = 10,
  font_sz_cr1 = 8,
  font_sz_cr2 = 8,
  font_sz_cr3 = 8,
  font_sz_bl1 = 4,
  font_sz_bl2 = 8,
  verbose = TRUE,
  ...
)

Arguments

Value

No return value, called for side effects (writing labels to a PDF file).

Examples

# Creating a simple label manually
create_label(width = 6, height = 2.5,
             top_left_1 = "Trial 2026",
             top_right_1 = "P: 101",
             center_right_1 = "Treatment A",
             include_qr = FALSE,
             filename = file.path(tempdir(), "manual_label"))

# Creating labels with QR Code
create_label(width = 6, height = 2.5,
             top_left_1 = "Trial 2026",
             top_right_1 = "P: 102",
             center_right_1 = "G215",
             unique_id = "uuid-1234-5678",
             include_qr = TRUE,
             filename = file.path(tempdir(), "qr_label"))

Descriptive statistics

Description

• desc_stat() Computes the most used measures of central tendency, position, and dispersion.

• desc_wider() is useful to put the variables in columns and grouping variables in rows. The table is filled with a statistic chosen with the argument stat.

Usage

desc_stat(
  .data = NULL,
  ...,
  by = NULL,
  stats = "main",
  hist = FALSE,
  level = 0.95,
  digits = 4,
  na.rm = FALSE,
  verbose = TRUE,
  plot_theme = ggplot2::theme_minimal()
)

desc_wider(.data, which)

Arguments

Value

• desc_stats() returns a tibble with the statistics in the columns and variables (with possible grouping factors) in rows.

• desc_wider() returns a tibble with variables in columns and grouping factors in rows.

Author(s)

Tiago Olivoto tiagoolivoto@gmail.com

References

Field, A., Miles, J., & Field, Z. (2012). Discovering Statistics Using R. SAGE Publications Ltd. (ISBN: 978-1-4462-0045-2)

Examples

library(beautils)
#===============================================================#
# Example 1: main statistics (coefficient of variation, maximum,#
# mean, median, minimum, sample standard deviation, standard    #
# error and confidence interval of the mean) for all numeric    #
# variables in data                                             #
#===============================================================#

desc_stat(df_eucalipto())
#===============================================================#
# Example 5: Compute all statistics for all numeric variables   #
# by row.
#===============================================================#

df_eucalipto() |>
  group_by(fila) |>
  desc_stat(circunferencia, stats = c("min, max, n, mean, sd.amo, cv"))

Example of Eucalyptus Plant Data

Description

The data contains measurements of diameter at breast height (DBH) using both a caliper (dap_suta) and a tape measure (dap_trena), as well as the circumference of eucalyptus plants. A total of 70 eucalyptus plants were evaluated, distributed across 5 rows with 14 plants per row.

Usage

df_eucalipto()

Value

A data frame

Example of Flax Plant Data

Description

The data contains evaluations of flax plants sown at four different times (E1 to E4). The experiment involved sampling between 51 and 66 plants per sowing time. Various plant traits were analyzed, including:

Usage

df_linhaca()

Details

• ac: capsule height

• ap: plant height

• nc: number of capsules

• ng: number of grains

• areac: capsule area

• compg: grain length

• largg: grain width

• nr: number of branches

• mc: capsule mass

• rgpla: grain yield per plant

• icc: capsule harvest index

• ngcap: number of grains per capsule

• mmg: thousand-grain mass

Value

A data frame

Example of Normal data

Description

The data contains the length of 205.043 flax grains that follows a normal distribution

Usage

df_normal()

Value

A data frame

Example of Qualitative data

Description

The data contains the area (AF) and dry matter (MST) of chicory plants evaluated at different levels of solar radiation (50%, 70%, and 100%). The experiment was conducted in a randomized complete block design with four replications.

Usage

df_quali()

Value

A data frame

Example of Qualitative x Qualitative data (with significant interaction)

Description

The data contains two qualitative factors: sulfur (2 levels) and nitrogen splitting (3 levels), with significant interaction.

Usage

df_quali_quali_ci()

Value

A data frame

Example of Qualitative x Qualitative data (no significant interaction)

Description

The data contains two qualitative factors: evaluation days (3 levels) and solar radiation (3 levels), with no significant interaction.

Usage

df_quali_quali_ci2()

Value

A data frame

Example of Qualitative x Qualitative data (no significant interaction)

Description

The data contains two qualitative factors: evaluation days (3 levels) and solar radiation (3 levels), with no significant interaction.

Usage

df_quali_quali_si()

Value

A data frame

Example of Qualitative x Quantitative data (with significant interaction)

Description

The data contains two factors: hybrids (2 levels, qualitative) and nitrogen doses (5 levels, quantitative), with significant interaction.

Usage

df_quali_quanti_ci()

Value

A data frame

Example of Qualitative x Quantitative data (no significant interaction)

Description

The data contains two factors: hybrids (2 levels, qualitative) and nitrogen doses (5 levels, quantitative), with no significant interaction.

Usage

df_quali_quanti_si()

Value

A data frame

Example of Quantitative data (linear trend)

Description

The data contains maize yield evaluated at different nitrogen levels, showing a linear trend.

Usage

df_quanti_1()

Value

A data frame

Example of Quantitative data (quadratic trend)

Description

The data contains oat yield evaluated at different nitrogen levels, showing a quadratic trend.

Usage

df_quanti_2()

Value

A data frame

Full Factorial Design with Fieldbook and Plot Map

Description

Generates a full factorial experiment (CRD or RCBD) from a combination of factors and levels, with options for additional treatments, serpentine layout, reproducible unique identifiers, and returns a consolidated fieldbook and field maps (ggplot) per location.

Usage

full_factorial(
  factors,
  nlevels,
  levels,
  add_trats = NULL,
  reps = 4,
  design = c("CRD", "RCBD"),
  seed = 123,
  serpentine = TRUE,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  layout_allocation = NULL,
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The function is a convenience wrapper around FielDHub::full_factorial(), adding:

• Optional inclusion of extra treatments (add_trats) with appropriate resampling per design;

• Generation of a layout (default or customized) with or without serpentine;

• Creation of unique and reproducible identifiers per plot (UNIQUE_ID) considering ROW, COL, YEAR, LOCATION, PLOT, REP, and TRT_COMB;

• Production of a consolidated fieldbook (all locations) and field maps (ggplot) per location.

Main rules and validations:

• FACTORS <- rep(factors, nlevels) must have matching length(levels).

• For layout = "custom", nrow * ncol must be >= ntrats_total.

• In design = "RCBD", allocation is done by block (REP).

Value

A list containing three elements:

Examples

# Generate a full factorial design
library(beautils)
design <- full_factorial(
  factors = c("A", "B"),
  nlevels = c(2, 2),
  levels = c("a1", "a2", "b1", "b2"),
  reps = 3,
  design = "RCBD",
  verbose = FALSE
)

Generate plot labels from a fieldbook

Description

High-level wrapper around create_label(). This command processes automatic mappings between fieldbook columns and label fields.

Usage

labelize(dat, ...)

Arguments

Value

No return value, called for side effects (generating and saving PDF labels).

Examples

# Example usage with mapping
library(beautils)
df <- unifatorial(trats = paste0("T", 1:4))
labelize(df$fieldbook,
         top_left_1 = "TRAT: = TREATMENT",
         top_right_1 = "Rep: = REP",
         center_right_1 = "Plot: = PLOT",
         center_right_2 = "Row: = ROW",
         center_right_3 = "Col: = COL",
         bottom_left_1 =  "Location: = LOCATION",
         filename = file.path(tempdir(), "labels"))

Latin Square Design with Fieldbook and Field Map

Description

Generates a Latin Square experimental design with one or more replicate squares, using FielDHub::latin_square() as the randomisation engine. Returns a consolidated fieldbook and a ggplot field map where each square is stacked vertically, with thick lines separating squares and tiles coloured by treatment.

Usage

latin_square(
  trats = NULL,
  reps = 1,
  seed = 123,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  layout_allocation = NULL,
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  planter = c("serpentine", "cartesian"),
  data = NULL,
  verbose = TRUE,
  app = FALSE
)

Arguments

Value

A list containing three elements:

Author(s)

Tiago Olivoto tiago.olivoto@ufsc.br

Examples

# Generate a Latin Square design
library(beautils)
design <- latin_square(
  trats = paste0("T", 1:4),
  reps = 2,
  verbose = FALSE
)
design

Generate a QR code graphic object

Description

Converts an identifier into a QR code matrix and returns a grid::rasterGrob object. Uses a built-in C implementation (Nayuki QR Code generator) with zero external dependencies.

Usage

make_qrcode(my_id, ec_level = 2)

Arguments

Value

A grid::rasterGrob object.

Generate Partially Replicated (p-rep) Design with Fieldbook and Field Map

Description

This function generates a spatially optimized Partially Replicated (p-rep) experimental design. Treatments can be assigned different replication levels: unreplicated entries (trats), a subset of treatments replicated more than once (reps_trats / reps_n), and check treatments (checks / checks_reps). The function wraps FielDHub::partially_replicated() for randomization and spatial optimization, extending it with UNIQUE_ID generation and ggplot2 field maps.

Usage

prep_design(
  trats,
  nrows,
  ncols,
  checks = NULL,
  checks_reps = 2,
  reps_trats = NULL,
  reps_n = 2,
  spread_reps = TRUE,
  dist_method = c("euclidean", "manhattan"),
  border_penalization = 0.5,
  seed = 123,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  locations = 1,
  plot_start = 1,
  fill_color = TRUE,
  text_size = 3,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The Partially Replicated (p-rep) design is widely used in early-generation plant breeding trials where field space is limited. Unlike complete block designs, not all treatments are replicated: a portion appears once (unreplicated), a subset appears twice or more (partially replicated), and a few checks appear many times to allow spatial trend correction.

The function builds the entry list by combining:

• Checks (checks, checks_reps times each) - high-replication group.

• Partially replicated treatments (reps_trats, reps_n times each).

• Unreplicated treatments (trats, 1 time each).

The spatial arrangement is optimized by FielDHub::partially_replicated() to maximize the minimum pairwise distance between replicated entries.

The field map uses three fill colors to distinguish replication groups:

• Checks (high replication).

• Partially replicated entries.

• Unreplicated entries.

Value

A list containing:

Author(s)

Tiago Olivoto tiago.olivoto@ufsc.br

References

Cullis, S., B. R., & Coombes, N. E. (2006). On the design of early generation variety trials with correlated data. Journal of Agricultural, Biological, and Environmental Statistics, 11, 381-393. https://doi.org/10.1198/108571106X154443

Examples

# p-rep design: 80 unreplicated trats, 10 replicated twice, 2 checks x 5 reps
# Field: 12 rows x 10 cols = 120 plots (80 + 10*2 + 2*5 = 100, adjust nrows/ncols)
library(beautils)
design <- prep_design(
  trats      = paste0("T", 1:80),
  nrows      = 20,
  ncols      = 5,
  checks     = c("CHECK1", "CHECK2"),
  checks_reps = 5,
  reps_trats = paste0("T", 1:10),
  reps_n     = 2,
  seed       = 42,
  verbose    = FALSE,
  locations = 3
)
design$fieldbook

Generate Rectangular Lattice Design with Fieldbook and Field Map

Description

This function generates a Rectangular Lattice design for experiments where the total number of entries satisfies t = s*(s-1), with incomplete blocks of size k = s-1 per replicate. It allows for the inclusion of checks, multiple locations, generates stable unique identifiers (UUID), and produces field maps (plots) with visual delimitation of incomplete blocks and repetitions.

Usage

rectangular_lattice(
  trats,
  k,
  checks = NULL,
  reps = 3,
  seed = 123,
  serpentine = TRUE,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  layout_allocation = NULL,
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The Rectangular Lattice design is a resolvable incomplete block design where the number of treatments must satisfy t = s*(s-1) and the block size k = s-1 (i.e., s blocks of size k per replicate). The function uses the FielDHub package engine for randomization but extends its functionality by:

• Validating the Layout: Ensures the provided layout_allocation is sufficient for the number of treatments.

• Visual Delimitation: In the map, thick black lines separate repetitions (resolvable blocks), while dashed red lines delimit incomplete blocks (k).

• UNIQUE_ID: Creates a unique ID based on metadata (YEAR, LOCATION, PLOT, etc.), facilitating traceability in databases.

Value

A list containing three elements:

Author(s)

Tiago Olivoto tiago.olivoto@ufsc.br

References

Patterson, H. D., & Williams, E. R. (1976). A new class of resolvable incomplete block designs. Biometrika, 63(1), 83-92. https://doi.org/10.2307/2335087

Examples

# Generate a rectangular lattice design with t = 20 (s = 5, k = 4)
library(beautils)
design <- rectangular_lattice(
  trats = paste0("T", 1:18),
  checks = c("CHECK1", "CHECK2"),
  k = 4,
  reps = 3,
  verbose = FALSE
)
design

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

dplyr

arrange(), count(), filter(), group_by(), mutate(), select(), summarise(), ungroup()

ggplot2

aes(), ggplot()

Split-Plot Design with Fieldbook and Plot Map

Description

Generates a split-plot experiment in CRD or RCBD designs, allowing for multiple locations, serpentine layout, and export of a consolidated fieldbook and field maps (ggplot).

Usage

split_plot(
  wholeplot,
  subplot,
  reps = 4,
  design = c("CRD", "RCBD"),
  seed = 123,
  serpentine = TRUE,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  layout_allocation = NULL,
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The function is a convenience wrapper around FielDHub::split_plot(), with:

• Automatic design definition from design;

• Allocation of whole plots (WHOLE_PLOT) and sub-plots (SUB_PLOT);

• Customized layout (⁠nrow x ncol⁠ per repetition) when layout = "custom";

• Creation of unique and reproducible identifiers (UNIQUE_ID) considering YEAR, LOCATION, ROW, COL, PLOT, REP, and TRT_COMB;

• Generation of maps (ggplot) with WHOLE_PLOT and SUB_PLOT labels;

• Optional serpentine layout by row.

Main rules:

• reps must be a positive integer;

• exp_name must have length 1 or be equal to locations;

• plot_start starting point for numbering (e.g., 100);

• For design = "RCBD", allocation considers blocks (REP).

• For layout = "custom", nrow * ncol must be >= length(wholeplot) * length(subplot).

Value

A list containing three elements:

Examples

# Generate a split-plot design
library(beautils)
design <- split_plot(
  wholeplot = c("W1", "W2"),
  subplot = c("S1", "S2", "S3"),
  reps = 2,
  design = "RCBD",
  verbose = FALSE
)
design

Generate Square Lattice Design with Fieldbook and Field Map

Description

This function generates a Square Lattice design for experiments where the total number of entries is a perfect square (t = k^2). It allows for the inclusion of checks, multiple locations, generates stable unique identifiers (UUID), and produces field maps (plots) with visual delimitation of incomplete blocks and repetitions.

Usage

square_lattice(
  trats,
  k,
  checks = NULL,
  reps = 3,
  seed = 123,
  serpentine = TRUE,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  layout_allocation = NULL,
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The Square Lattice design is a special case of the resolvable incomplete block design where the number of treatments must be a perfect square (t = k^2, with k blocks of size k per replicate). The function uses the FielDHub package engine for randomization but extends its functionality by:

• Validating the Layout: Ensures the provided layout_allocation is sufficient for the number of treatments.

• Visual Delimitation: In the map, thick black lines separate repetitions (resolvable blocks), while dashed red lines delimit incomplete blocks (k).

• UNIQUE_ID: Creates a unique ID based on metadata (YEAR, LOCATION, PLOT, etc.), facilitating traceability in databases.

Value

A list containing three elements:

Author(s)

Tiago Olivoto tiago.olivoto@ufsc.br

References

Patterson, H. D., & Williams, E. R. (1976). A new class of resolvable incomplete block designs. Biometrika, 63(1), 83-92. https://doi.org/10.2307/2335087

Examples

# Generate a square lattice design with t = 16 (k = 4)
library(beautils)
design <- square_lattice(
  trats = paste0("T", 1:14),
  checks = c("CHECK1", "CHECK2"),
  k = 4,
  reps = 3,
  verbose = FALSE
)
design

Strip Plot (Experiments in Strips) with Fieldbook and Field Map

Description

Generates a strip plot (experiments in strips) design with multiple locations, serpentine layout, field map (ggplot) with visually distinct horizontal and vertical strips, and a consolidated fieldbook. This is a wrapper around FielDHub::strip_plot().

Usage

strip_plot(
  hstrips,
  vstrips,
  reps = 3,
  seed = 123,
  serpentine = TRUE,
  exp_year = format(Sys.Date(), "%Y"),
  exp_name = "Ressacada",
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  layout_allocation = NULL,
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  planter = c("serpentine", "cartesian"),
  randomizeH = TRUE,
  randomizeV = FALSE,
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The strip plot places each horizontal factor level as a full horizontal row (spanning all vertical strips) and each vertical factor level as a full vertical column (spanning all horizontal strips) within each replicate block. The field map highlights this structure: tiles are filled by H_STRIP, thick black lines separate replicate blocks, and vertical dashed lines separate the V_STRIP columns. For layout = "custom", the plots are mapped to a custom ⁠nrow x ncol⁠ layout per replication block.

Value

A list containing three elements:

Author(s)

Tiago Olivoto tiago.olivoto@ufsc.br

Examples

# Generate a strip-plot design
library(beautils)
design <- strip_plot(
  hstrips = c("H1", "H2", "H3"),
  vstrips = c("V1", "V2"),
  reps = 2,
  verbose = FALSE
)
design

Perform t-test between groups

Description

Performs an independent samples t-test for all combinations of groups in a given factor. Returns a data frame with test statistics and optionally generates a boxplot.

Usage

t_test(
  df,
  group,
  trait,
  var_equal = TRUE,
  plot = TRUE,
  show = c("signinf", "all"),
  plot_type = c("boxplot", "violin"),
  show_points = TRUE,
  signif_label = c("p_value", "asterisks"),
  xlab = NULL,
  ylab = NULL,
  fill = "salmon"
)

Arguments

Value

A data frame containing the combinations, means, variances, sample sizes, degrees of freedom, calculated t-values, tabulated t-values, p-values, and interpretations.

Examples

# Use the iris dataset
df_iris <- iris[iris$Species %in% c("setosa", "versicolor"), ]
# Drop unused levels
df_iris$Species <- droplevels(df_iris$Species)

# Perform t-test between the two species for Sepal.Length
res <- t_test(df_iris, group = Species, trait = Sepal.Length)
print(res)

Perform paired t-test

Description

Performs a paired samples t-test between exactly two groups in a given factor. It assumes that the observations are ordered and paired across the two groups. Returns a data frame with test statistics and optionally generates a paired boxplot.

Usage

t_test_paired(
  df,
  group,
  trait,
  plot = TRUE,
  show = c("signinf", "all"),
  plot_type = c("boxplot", "violin"),
  show_points = TRUE,
  signif_label = c("asterisks", "p_value"),
  xlab = NULL,
  ylab = NULL,
  fill = "salmon"
)

Arguments

Value

A data frame containing the groups, means, variances, paired sample size, calculated t-value, p-value, and interpretation.

Examples

# Create a paired dataset based on iris
df_paired <- iris[iris$Species %in% c("setosa", "versicolor"), ]
df_paired$Species <- droplevels(df_paired$Species)

# Perform paired t-test between the two species for Sepal.Length
# (Assuming they are paired sequentially for this example)
res_paired <- t_test_paired(df_paired, group = Species, trait = Sepal.Length)
print(res_paired)

Single Factor Design with Fieldbook and Plot Map

Description

Generates a single factor experiment (CRD or RCBD) with multiple locations, optional serpentine layout, plot map (ggplot), and consolidated fieldbook.

Usage

unifatorial(
  trats,
  reps = 4,
  design = c("CRD", "RCBD"),
  seed = 123,
  serpentine = TRUE,
  exp_name = "Ressacada",
  exp_year = format(Sys.Date(), "%Y"),
  fill_color = TRUE,
  text_size = 3,
  layout = c("default", "custom"),
  namespace = "7ac1a295-ef95-4f7c-8a35-3eed97cb256d",
  layout_allocation = NULL,
  locations = 1,
  plot_start = 1,
  legend = TRUE,
  text_size_row_col = 3,
  label_top = "Coluna",
  label_bottom = "",
  label_left = "Linha",
  label_right = "",
  verbose = TRUE,
  app = FALSE
)

Arguments

Details

The function is a wrapper around FielDHub::CRD() and FielDHub::RCBD(), adding:

• Unique identifiers (UNIQUE_ID) per plot;

• Optional serpentine layout;

• Customized layout (⁠nrow x ncol⁠) when layout = "custom";

• Plot map in ggplot with configurable colors and labels;

• Consolidated fieldbook for all locations.

Main rules and validations:

• reps must be a positive integer;

• exp_name must have length 1 or be equal to locations;

• plot_start starting point for numbering (e.g., 100);

• For layout = "custom", nrow * ncol must be >= number of treatments.

Value

A list containing three elements:

Examples

# Generate a single factor design
library(beautils)
design <- unifatorial(
  trats = paste0("T", 1:4),
  reps = 3,
  design = "RCBD",
  verbose = FALSE
)
design

Random Sampling

Description

• sample_random() performs Simple Random Sampling or Stratified Random Sampling

• sample_systematic() performs systematic sampling. In this case, a regular interval of size k (k = floor(N/n)) is generated considering the population size (N) and desired sample size (n). Then, the starting member (r) is randomly chosen between 1-k. The second element is r + k, and so on.

Usage

sample_random(data, n, prop, by = NULL, weight = NULL)

sample_systematic(data, n, r = NULL, by = NULL)

Arguments

Value

An object of the same type as data.

Examples

library(beautils)
sample_random(df_eucalipto(), n = 5)
sample_random(df_eucalipto(),
              n = 3,
              by = fila)

sample_systematic(df_eucalipto(), n = 6)

Utilities for set operations for many sets

Description

Provides alternative function to base::union(), base::intersect(), and base::setdiff().

• set_union(): Returns the union of the sets in ....

• set_intersect(): Returns the intersect of the sets in ....

• set_difference(): Returns the difference of the sets in ....

Usage

set_intersect(..., pairs = FALSE)

set_union(..., pairs = FALSE)

set_difference(..., pairs = FALSE)

Arguments

Value

A vector showing the desired operation of the sets. If pairs = TRUE, returns a list showing the pairwise operation of the sets.

Author(s)

Tiago Olivoto tiagoolivoto@gmail.com

Examples

library(beautils)
(A <- letters[1:4])
(B <- letters[2:5])
(C <- letters[3:7])

set_union(A, B)
set_intersect(A, B, C)
set_difference(B, C)

# Operations with data frames
# Add a row id for better understanding
sets <- df_eucalipto()

set_1 <- sets[1:5,]
set_2 <- sets[2:6,]
set_3 <- sets[3:7,]

set_intersect(set_1, set_2)
set_difference(set_2, set_3)
set_union(set_1, set_2, set_3)

Useful functions for computing descriptive statistics

Description

• The following functions compute descriptive statistics by levels of a factor or combination of factors quickly.

  • cv_by() For computing coefficient of variation.

  • max_by() For computing maximum values.

  • mean_by() For computing arithmetic means.

  • min_by() For compuing minimum values.

  • n_by() For getting the length.

  • sd_by() For computing sample standard deviation.

  • var_by() For computing sample variance.

  • sem_by() For computing standard error of the mean.

• Useful functions for descriptive statistics. All of them work naturally with ⁠\%>\%⁠, handle grouped data and multiple variables (all numeric variables from .data by default).

  • av_dev() computes the average absolute deviation.

  • ci_mean_t() computes the t-interval for the mean.

  • ci_mean_z() computes the z-interval for the mean.

  • cv() computes the coefficient of variation.

  • freq_table() Computes a frequency table for either numeric and categorical/discrete data. For numeric data, it is possible to define the number of classes to be generated.

  • ⁠hmean(), gmean()⁠ computes the harmonic and geometric means, respectively. The harmonic mean is the reciprocal of the arithmetic mean of the reciprocals. The geometric mean is the nth root of n products.

  • kurt() computes the kurtosis like used in SAS and SPSS.

  • range_data() Computes the range of the values.

  • n_valid() The valid (not NA) length of a data.

  • n_unique() Number of unique values.

  • n_missing() Number of missing values.

  • ⁠row_col_mean(), row_col_sum()⁠ Adds a row with the mean/sum of each variable and a column with the the mean/sum for each row of the data.

  • ⁠sd_amo(), sd_pop()⁠ Computes sample and populational standard deviation, respectively.

  • sem() computes the standard error of the mean.

  • skew() computes the skewness like used in SAS and SPSS.

  • ave_dev() computes the average of the absolute deviations.

  • sum_dev() computes the sum of the absolute deviations.

  • sum_sq() computes the sum of the squared values.

  • sum_sq_dev() computes the sum of the squared deviations.

  • ⁠var_amo(), var_pop()⁠ computes sample and populational variance.

desc_stat() is wrapper function around the above ones and can be used to compute quickly all these statistics at once.

Usage

cv_by(.data, ..., .vars = NULL, na.rm = FALSE)

max_by(.data, ..., .vars = NULL, na.rm = FALSE)

min_by(.data, ..., .vars = NULL, na.rm = FALSE)

mean_by(.data, ..., .vars = NULL, na.rm = FALSE)

mean_by(.data, ..., .vars = NULL, na.rm = FALSE)

n_by(.data, ..., .vars = NULL, na.rm = FALSE)

sd_by(.data, ..., .vars = NULL, na.rm = FALSE)

var_by(.data, ..., .vars = NULL, na.rm = FALSE)

sem_by(.data, ..., .vars = NULL, na.rm = FALSE)

sum_by(.data, ..., .vars = NULL, na.rm = FALSE)

av_dev(.data, ..., na.rm = FALSE)

ci_mean_t(.data, ..., na.rm = FALSE, level = 0.95)

ci_mean_z(.data, ..., na.rm = FALSE, level = 0.95)

cv(.data, ..., na.rm = FALSE)

hmean(.data, ..., na.rm = FALSE)

gmean(.data, ..., na.rm = FALSE)

kurt(.data, ..., na.rm = FALSE)

n_missing(.data, ..., na.rm = FALSE)

n_unique(.data, ..., na.rm = FALSE)

n_valid(.data, ..., na.rm = FALSE)

pseudo_sigma(.data, ..., na.rm = FALSE)

range_data(.data, ..., na.rm = FALSE)

row_col_mean(.data, na.rm = FALSE)

row_col_sum(.data, na.rm = FALSE)

sd_amo(.data, ..., na.rm = FALSE)

sd_pop(.data, ..., na.rm = FALSE)

sem(.data, ..., na.rm = FALSE)

skew(.data, ..., na.rm = FALSE)

sum_dev(.data, ..., na.rm = FALSE)

ave_dev(.data, ..., na.rm = FALSE)

sum_sq_dev(.data, ..., na.rm = FALSE)

sum_sq(.data, ..., na.rm = FALSE)

var_pop(.data, ..., na.rm = FALSE)

var_amo(.data, ..., na.rm = FALSE)

freq_table(.data, var, k = NULL, digits = 3)

freq_hist(
  table,
  xlab = NULL,
  ylab = NULL,
  fill = "gray",
  color = "black",
  ygrid = TRUE
)

Arguments

Details

The function freq_table() computes a frequency table for either numerical or categorical variables. If a variable is categorical or discrete (integer values), the number of classes will be the number of levels that the variable contains.

If a variable (say, data) is continuous, the number of classes (k) is given by the square root of the number of samples (n) if ⁠n =< 100⁠ or 5 * log10(n) if n > 100.

The amplitude (A) of the data is used to define the size of the class (c), given by

c = A / (n - 1)

The lower limit of the first class (LL1) is given by min(data) - c / 2. The upper limit is given by LL1 + c. The limits of the other classes are given in the same way. After the creation of the classes, the absolute and relative frequencies within each class are computed.

Value

• Functions ⁠*_by()⁠ returns a tbl_df with the computed statistics by each level of the factor(s) declared in ....

• All other functions return a named integer if the input is a data frame or a numeric value if the input is a numeric vector.

• freq_table() Returns a list with the frequency table and the breaks used for class definition. These breaks can be used to construct an histogram of the variable.

Author(s)

Tiago Olivoto tiagoolivoto@gmail.com

References

Ferreira, Daniel Furtado. 2009. Estatistica Basica. 2 ed. Vicosa, MG: UFLA.

Field, A., Miles, J., & Field, Z. (2012). Discovering Statistics Using R. SAGE Publications Ltd. (ISBN: 978-1-4462-0045-2)

Examples

library(beautils)
# means of all numeric variables by fila
mean_by(df_eucalipto(), fila, .vars = circunferencia)

# Coefficient of variation for all numeric variables
# by fila
cv_by(df_eucalipto(), fila, .vars = circunferencia)

# Skewness of a numeric vector
set.seed(1)
nvec <- rnorm(500, 10, 1)
skew(nvec)

# Confidence interval 0.95 for the mean
# All numeric variables
# Grouped by levels of fila
df_eucalipto() |>
  group_by(fila) |>
  ci_mean_t(circunferencia)


# Frequency table for variable circunferencia
df_eucalipto() |>
  freq_table(circunferencia)

Set and get the Working Directory quicky

Description

• get_wd_here() gets the working directory to the path of the current script.

• set_wd_here() sets the working directory to the path of the current script.

• open_wd_here() Open the File Explorer at the directory path of the current script.

• open_wd() Open the File Explorer at the current working directory.

Usage

set_wd_here(path = NULL)

get_wd_here(path = NULL)

open_wd_here(path = get_wd_here())

open_wd(path = getwd())

Arguments

Value

• get_wd_here() returns a full-path directory name.

• get_wd_here() returns a message showing the current working directory.

• open_wd_here() Opens the File Explorer of the path returned by get_wd_here().

Examples

if (interactive() && requireNamespace("rstudioapi", quietly = TRUE)) {
  get_wd_here()
  set_wd_here()
  open_wd_here()
}

Generate UUIDs

Description

uuid_random() generates UUID version 7 strings (timestamp-based + random) following RFC 9562, ensuring they are time-sortable.

uuid_deterministic() generates deterministic UUID version 5 strings (SHA-1 based) from a namespace and a character vector of names.

Usage

uuid_random(n = 1L)

uuid_deterministic(namespace, name)

Arguments

Details

Generate UUIDs natively using C implementations.

Value

A character vector of UUID strings.

Examples

library(beautils)
# Generate random UUID
uuid_random(5)

# Generate deterministic UUID using a namespace
ns <- "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
uuid_deterministic(ns, c("apple", "banana"))