Package 'besthr'

Title: Generating Bootstrap Estimation Distributions of HR Data
Description: Creates plots showing scored HR experiments and plots of distribution of means of ranks of HR score from bootstrapping.
Authors: Dan MacLean [aut, cre]
Maintainer: Dan MacLean <[email protected]>
License: MIT + file LICENSE
Version: 0.4.0
Built: 2026-05-17 08:54:39 UTC
Source: https://github.com/cran/besthr

Help Index

Apply besthr theme consistently

Description

Applies the besthr theme and color scales to a ggplot object based on configuration settings. This ensures consistent theming across all plot components.

Usage

apply_besthr_theme(p, config, include_fill = TRUE, include_color = TRUE)

Arguments

p

A ggplot object
config

A besthr_plot_config object
include_fill

Logical, whether to apply fill scale (default TRUE)
include_color

Logical, whether to apply color scale (default TRUE)

Value

The ggplot object with theme and scales applied

Examples

library(ggplot2)
p <- ggplot(mtcars, aes(mpg, wt, color = factor(cyl))) +
  geom_point()
cfg <- besthr_plot_config(theme_style = "modern", color_palette = "okabe_ito")
apply_besthr_theme(p, cfg)

Create a unified data view for besthr plotting

Description

Extracts and organizes data from an hrest object for plotting. Computes unified axis limits that ensure alignment between observation and bootstrap panels.

Usage

besthr_data_view(hrest, config = NULL)

Arguments

hrest

An hrest object from estimate
config

A besthr_plot_config object (optional). If NULL, uses defaults.

Value

An object of class "besthr_data_view" containing ranked data, original data, bootstrap samples, group means, confidence intervals, group sample sizes, unified rank limits, group column symbol, column info, control group name, and quantile values.

Examples

d <- make_data()
hr <- estimate(d, score, group)
dv <- besthr_data_view(hr)

besthr color palettes

Description

Returns a color palette suitable for besthr visualizations. The default palette uses Okabe-Ito colorblind-safe colors.

Usage

besthr_palette(palette = "default", n = NULL)

Arguments

palette

Character string specifying the palette. Options are:

  • "default" - Original besthr colors

  • "okabe_ito" - Colorblind-safe Okabe-Ito palette

  • "viridis" - Viridis color scale

n

Number of colors to return. If NULL, returns all colors in palette.

Value

A character vector of hex color codes

Examples

besthr_palette()
besthr_palette("okabe_ito", 3)

Create a besthr plot configuration

Description

Creates a configuration object that controls the appearance and behavior of besthr plots. All parameters have defaults that reproduce the original besthr appearance for backward compatibility.

Usage

besthr_plot_config(
  panel_widths = c(1, 1),
  panel_spacing = grid::unit(0.5, "cm"),
  y_limits = NULL,
  y_expand = 0.05,
  point_size_range = c(2, 8),
  point_alpha = 0.8,
  mean_line_type = 3,
  mean_line_width = 1,
  density_alpha = 0.7,
  density_style = "points",
  theme_style = "modern",
  color_palette = "okabe_ito"
)

Arguments

panel_widths

Numeric vector of relative panel widths for patchwork layout.
panel_spacing

A grid unit specifying spacing between panels.
y_limits

Numeric vector of length 2 for y-axis limits, or NULL for auto.
y_expand

Numeric giving proportional expansion of y-axis limits.
point_size_range

Numeric vector of length 2 for min/max point sizes.
point_alpha

Numeric between 0 and 1 for point transparency.
mean_line_type

Line type for mean indicator lines.
mean_line_width

Line width for mean indicator lines.
density_alpha

Numeric between 0 and 1 for density plot transparency.
density_style

Character: "points" (default, jittered bootstrap points), "gradient" (density with CI shading), or "solid" (single color density).
theme_style

Character: "classic" or "modern".
color_palette

Character: "default", "okabe_ito", or "viridis".

Value

An object of class "besthr_plot_config" containing all plot settings.

Examples

cfg <- besthr_plot_config()
cfg <- besthr_plot_config(panel_widths = c(2, 1), theme_style = "modern")

Get a preset plot style

Description

Returns a pre-configured besthr_plot_config object with sensible defaults for common use cases. This is the easiest way to customize besthr plot appearance without understanding all the configuration options.

Usage

besthr_style(style = "default")

Arguments

style

Character string specifying the style preset:

  • "default" - Modern theme with colorblind-safe colors (recommended)

  • "classic" - Original besthr appearance for backward compatibility

  • "publication" - Clean style suitable for journal figures

  • "presentation" - Larger elements for slides

  • "density" - Uses gradient density instead of points for bootstrap

Value

A besthr_plot_config object

Examples

d <- make_data()
hr <- estimate(d, score, group)

# Quick styling with presets
plot(hr, config = besthr_style("publication"))
plot(hr, config = besthr_style("presentation"))
plot(hr, config = besthr_style("density"))

# Same as default
plot(hr, config = besthr_style("default"))

Generate a summary table from besthr results

Description

Creates a publication-ready summary table containing group statistics, confidence intervals, and optionally effect sizes and significance.

Usage

besthr_table(
  hrest,
  format = "tibble",
  digits = 2,
  include_significance = FALSE
)

Arguments

hrest

An hrest object from estimate
format

Output format: "tibble" (default), "markdown", "html", or "latex"
digits

Number of decimal places for rounding (default 2)
include_significance

Logical, whether to include significance stars (default FALSE)

Value

A tibble (if format = "tibble") or character string (other formats)

Examples

d <- make_data()
hr <- estimate(d, score, group)
besthr_table(hr)
besthr_table(hr, format = "markdown")

Build the bootstrap distribution panel

Description

Creates a ggplot showing ridge density plots of bootstrap distributions with confidence interval shading.

Usage

build_bootstrap_panel(data_view, config)

Arguments

data_view

A besthr_data_view object
config

A besthr_plot_config object

Value

A ggplot object

Examples

d <- make_data()
hr <- estimate(d, score, group)
dv <- besthr_data_view(hr)
cfg <- besthr_plot_config()

build_bootstrap_panel(dv, cfg)

Build the observation panel

Description

Creates a ggplot showing either ranked observations (averaged tech reps) or raw scores with technical replicates displayed.

Usage

build_observation_panel(data_view, config, which = "rank_simulation")

Arguments

data_view

A besthr_data_view object
config

A besthr_plot_config object
which

Character specifying panel type: "rank_simulation" for averaged ranked data, or "just_data" for raw scores with tech reps.

Value

A ggplot object

Examples

d <- make_data()
hr <- estimate(d, score, group)
dv <- besthr_data_view(hr)
cfg <- besthr_plot_config()

build_observation_panel(dv, cfg, "rank_simulation")

Compose besthr panels

Description

Combines observation and bootstrap panels using patchwork with proper alignment and shared legends.

Usage

compose_besthr_panels(panels, config)

Arguments

panels

A list of ggplot objects to compose
config

A besthr_plot_config object

Value

A patchwork object

Examples

d <- make_data()
hr <- estimate(d, score, group)
dv <- besthr_data_view(hr)
cfg <- besthr_plot_config()

p1 <- build_observation_panel(dv, cfg)
p2 <- build_bootstrap_panel(dv, cfg)
compose_besthr_panels(list(p1, p2), cfg)

Compute effect sizes from bootstrap distributions

Description

Calculates the effect size (difference from control) for each treatment group with bootstrap confidence intervals.

Usage

compute_effect_size(hrest)

Arguments

hrest

An hrest object from estimate

Value

A data frame with columns: group, effect, effect_ci_low, effect_ci_high

Examples

d <- make_data()
hr <- estimate(d, score, group, nits = 500)
compute_effect_size(hr)

Compute significance from bootstrap distributions

Description

Determines statistical significance by checking if the bootstrap confidence interval for each treatment group overlaps with the control group's mean rank.

Usage

compute_significance(hrest)

Arguments

hrest

An hrest object from estimate

Value

A data frame with columns: group, significant (logical), p_value, stars

Examples

d <- make_data()
hr <- estimate(d, score, group, nits = 500)
compute_significance(hr)

Derive CI colors based on palette and theme

Description

Computes confidence interval fill colors that harmonize with the selected color palette and theme style. This ensures visual consistency between the observation panel colors and the bootstrap density shading.

Usage

derive_ci_colors(palette = "default", theme_style = "classic")

Arguments

palette

Character string specifying the color palette: "default", "okabe_ito", or "viridis"
theme_style

Character string specifying the theme: "classic" or "modern"

Value

A character vector of three hex colors with alpha for low, middle, and high CI regions

Examples

derive_ci_colors("default", "classic")
derive_ci_colors("okabe_ito", "modern")
derive_ci_colors("viridis", "classic")

Perform bootstrap estimation of confidence intervals of ranked HR scores

Description

estimate carries out estimation of bootstrap confidence intervals on ranked score data. Returns a hrest object of the result Proceeeds by calculating score ranks, then bootstrapping ranks in non-control groups retaining the mean for each bootstrap iteration. Calculates low and high quantiles of bootstrap mean distributions for each group. If technical replicates are provided in a second grouping column these will be averaged before proceeding.

Usage

estimate(df, ..., control = "A", nits = 100, low = 0.025, high = 0.975)

Arguments

df

data frame of score and group data. Contains minimally a score and group column
...

bare names of columns to use, minimally the score column and the group column in that order. Optionally a third technical replicate column can be provided
control

the value of the grouping column taken to be the control group
nits

the number of bootstap iterations to be done
low

the low probability value of the quantile
high

the high probability value of the quantile

Value

a list object of class "hrest"

Examples

d1 <- make_data()
 estimate(d1, score, group)

 d2 <- make_data2()
 estimate(d2, score_column_name, sample_column_name, rep_column_name )


 d3 <- make_data3()
 estimate(d3, score, sample, rep, nits = 1000)

Create bootstrap density layer

Description

Creates a ggplot2 layer showing ridge density plots of bootstrap distributions with confidence interval shading.

Usage

layer_bootstrap_density(data_view, config)

Arguments

data_view

A besthr_data_view object
config

A besthr_plot_config object

Value

A list of ggplot2 layers

Examples

d <- make_data()
hr <- estimate(d, score, group)
dv <- besthr_data_view(hr)
cfg <- besthr_plot_config()
# layer_bootstrap_density returns layers to add to a ggplot

Create group mean lines layer

Description

Creates a ggplot2 layer showing horizontal lines at group mean ranks.

Usage

layer_group_means(data_view, config)

Arguments

data_view

A besthr_data_view object
config

A besthr_plot_config object

Value

A ggplot2 layer

Examples

d <- make_data()
hr <- estimate(d, score, group)
dv <- besthr_data_view(hr)
cfg <- besthr_plot_config()
# layer_group_means returns a ggplot layer

Create ranked dots layer

Description

Creates a ggplot2 layer showing ranked observations as points, where point size indicates the count of observations at each rank/group combination.

Usage

layer_ranked_dots(data_view, config)

Arguments

data_view

A besthr_data_view object
config

A besthr_plot_config object

Value

A list of ggplot2 layers

Examples

d <- make_data()
hr <- estimate(d, score, group)
dv <- besthr_data_view(hr)
cfg <- besthr_plot_config()
# layer_ranked_dots returns layers to add to a ggplot

Create technical replicate dots layer

Description

Creates a ggplot2 layer showing raw score observations with technical replicates displayed separately. Points are sized by observation count.

Usage

layer_tech_rep_dots(data_view, config)

Arguments

data_view

A besthr_data_view object
config

A besthr_plot_config object

Value

A list of ggplot2 layers

List available style presets

Description

Shows all available preset styles that can be used with besthr_style().

Usage

list_besthr_styles()

Value

A character vector of style names (invisibly)

Examples

list_besthr_styles()

return a sample data set of random values for two groups

Description

return a sample data set of random values for two groups

Usage

make_data()

Value

tibble of random values for two groups

Examples

d1 <- make_data()

return a sample data set of random values for two groups with three technical reps per group

Description

return a sample data set of random values for two groups with three technical reps per group

Usage

make_data2()

Value

tibble of random values for two groups with three technical reps per group

Examples

d2 <- make_data2()

return a sample data set of random values for three groups with three technical reps per group

Description

@examples

Usage

make_data3()

Details

d3 <- make_data3()

Value

tibble of random values for three groups with three technical reps per group

Raincloud plot showing bootstrap distributions

Description

Creates a raincloud plot specifically for bootstrap distributions, showing the distribution of bootstrap mean ranks with jittered points and summary statistics.

Usage

plot_bootstrap_raincloud(
  hrest,
  theme = "modern",
  colors = "okabe_ito",
  config = NULL
)

Arguments

hrest

An hrest object from estimate
theme

the visual theme to use. Either "modern" (default) or "classic"
colors

the color palette to use. Either "okabe_ito" (default), "default", or "viridis"
config

an optional besthr_plot_config object

Value

A ggplot object

Examples

d <- make_data()
hr <- estimate(d, score, group, nits = 100)
plot_bootstrap_raincloud(hr)

Raincloud plot for hrest objects

Description

Creates a unified raincloud visualization combining:

  • Jittered raw data points

  • Half-violin density plots

  • Mean with confidence interval as pointrange

Usage

plot_raincloud(
  hrest,
  theme = "modern",
  colors = "okabe_ito",
  config = NULL,
  show_bootstrap = TRUE,
  jitter_width = 0.15,
  point_size = 1.5
)

Arguments

hrest

An hrest object from estimate
theme

the visual theme to use. Either "modern" (default) or "classic"
colors

the color palette to use. Either "okabe_ito" (default), "default", or "viridis"
config

an optional besthr_plot_config object for advanced customization. If provided, theme and colors parameters are ignored.
show_bootstrap

Ignored (kept for backward compatibility).
jitter_width

Numeric width of jitter for data points. Default 0.15.
point_size

Numeric size for jittered points. Default 1.5.

Details

This provides an alternative to the standard two-panel besthr plot, combining all information in a single comprehensive visualization.

Value

A ggplot object

Examples

d <- make_data()
hr <- estimate(d, score, group)
plot_raincloud(hr)

plots the hrest object

Description

returns a ggplot object representing the hrest object from estimate. The content of left panel varies according to the value of the which parameter. If which = "rank_simulation" is used a plot of rank score values will be plotted in the left panel. In this case technical replicates will be averaged if provided. If which = "just_data" a plot of scores only is created and technical replicates are displayed as is. In each case, the right hand panel shows the rank bootstrap distribution and confidence interval boundaries for all non- control groups.

Usage

## S3 method for class 'hrest'
plot(
  x,
  ...,
  which = "rank_simulation",
  theme = "modern",
  colors = "okabe_ito",
  config = NULL,
  show_significance = FALSE,
  show_effect_size = FALSE
)

Arguments

x

the hrest object from estimate
...

Other parameters (ignored)
which

the type of left hand panel to create. Either "rank_simulation" or "just_data"
theme

the visual theme to use. Either "modern" (default, cleaner contemporary style) or "classic" (original besthr appearance)
colors

the color palette to use. Either "okabe_ito" (default, colorblind-safe), "default" (original colors), or "viridis"
config

an optional besthr_plot_config object for advanced customization. If provided, theme and colors parameters are ignored.
show_significance

Logical, whether to show significance stars on groups where CI doesn't overlap control (default FALSE)
show_effect_size

Logical, whether to show effect size annotation (default FALSE)

Value

ggplot object

Examples

d1 <- make_data()
 hr_est <- estimate(d1, score, group)
 plot(hr_est)

 # Use modern theme with colorblind-safe palette
 plot(hr_est, theme = "modern", colors = "okabe_ito")

 # Advanced configuration
 cfg <- besthr_plot_config(
   panel_widths = c(2, 1),
   point_size_range = c(3, 10)
 )
 plot(hr_est, config = cfg)

Print method for besthr_data_view

Description

Print method for besthr_data_view

Usage

## S3 method for class 'besthr_data_view'
print(x, ...)

Arguments

x

A besthr_data_view object
...

Additional arguments (ignored)

Value

Invisibly returns x

Print method for besthr_plot_config

Description

Print method for besthr_plot_config

Usage

## S3 method for class 'besthr_plot_config'
print(x, ...)

Arguments

x

A besthr_plot_config object
...

Additional arguments (ignored)

Value

Invisibly returns x

print a summary of the hrest object

Description

print a summary of the hrest object

Usage

## S3 method for class 'hrest'
print(x, ...)

Arguments

x

hrest object
...

other parameters

Value

null

Examples

d1 <- make_data()
 hr_est <- estimate(d1, score, group)
 print(hr_est)

Save besthr plot to file

Description

Saves a besthr visualization to a file with sensible publication defaults. Supports PNG, PDF, SVG, and TIFF formats.

Usage

save_besthr(
  hrest,
  filename,
  type = "default",
  width = 8,
  height = 6,
  dpi = 300,
  ...
)

Arguments

hrest

An hrest object from estimate
filename

Output filename. Format is detected from extension.
type

Plot type: "default" (two-panel) or "raincloud"
width

Plot width in inches (default 8)
height

Plot height in inches (default 6)
dpi

Resolution in dots per inch (default 300)
...

Additional arguments passed to the plot function (e.g., theme, colors)

Value

The filename (invisibly)

Examples

## Not run: 
d <- make_data()
hr <- estimate(d, score, group)
save_besthr(hr, "figure1.png")
save_besthr(hr, "figure1.pdf", width = 10, height = 8)
save_besthr(hr, "figure1.png", type = "raincloud")

## End(Not run)

Discrete color scale for besthr

Description

A discrete color scale using besthr palettes.

Usage

scale_color_besthr(palette = "default", ...)

scale_colour_besthr(palette = "default", ...)

Arguments

palette

Character string specifying the palette (see besthr_palette)
...

Additional arguments passed to discrete_scale

Value

A ggplot2 discrete color scale

Examples

library(ggplot2)
ggplot(mtcars, aes(mpg, wt, color = factor(cyl))) +
  geom_point() +
  scale_color_besthr("okabe_ito")

Discrete fill scale for besthr

Description

A discrete fill scale using besthr palettes.

Usage

scale_fill_besthr(palette = "default", ...)

Arguments

palette

Character string specifying the palette (see besthr_palette)
...

Additional arguments passed to discrete_scale

Value

A ggplot2 discrete fill scale

Examples

library(ggplot2)
ggplot(mtcars, aes(factor(cyl), fill = factor(cyl))) +
  geom_bar() +
  scale_fill_besthr("okabe_ito")

besthr ggplot2 theme

Description

A custom theme for besthr plots. The "classic" theme matches the original besthr appearance, while "modern" provides a cleaner, more contemporary look.

Usage

theme_besthr(style = "classic", base_size = 11, base_family = "")

Arguments

style

Character string specifying the theme style. Options are:

  • "classic" - Original besthr theme (theme_minimal)

  • "modern" - Clean, contemporary style with refined typography

base_size

Base font size (default 11)
base_family

Base font family

Value

A ggplot2 theme object

Examples

library(ggplot2)
ggplot(mtcars, aes(mpg, wt)) +
  geom_point() +
  theme_besthr("modern")

Update a besthr plot configuration

Description

Creates a new configuration by updating specific fields of an existing one.

Usage

update_config(config, ...)

Arguments

config

An existing besthr_plot_config object
...

Named arguments to update

Value

A new besthr_plot_config object

Examples

cfg <- besthr_plot_config()
cfg2 <- update_config(cfg, theme_style = "modern", panel_widths = c(2, 1))