Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Value

result of previous expression

calculate ranks of a score column and adds result to a dataframe

Description

add_rank returns a copy of the passed data frame containing a new column called rank which has the ranks of the named score column

Usage

add_rank(df, quo_score_col)

Arguments

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

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

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

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

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

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

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")

runs bootstrapping of ranks

Description

boostrap_dist runs multiple bootstrap resamplings using bstrap_sample to generate a data frame of bootstrap rank means of per group scores

Usage

bootstrap_dist(df, quo_score_col, quo_group_col, nits = 10, control = "A")

Arguments

resamples a rank column in a dataframe based on groups

Description

bstrap_sample performs a single iteration of bootstrapping of a rank column in a data frame. The rows matching control in the quoted quo_group_col column are removed. The remaining rows are grouped by quo_group_col and in each group the rank column is resampled with replacement and the mean rank of the resampling for each group is returned

Usage

bstrap_sample(iteration, quo_score_col, quo_group_col, df, control = "A")

Arguments

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

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

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")

Build the ranked observation panel

Description

Internal function to build the panel showing ranked observations.

Usage

build_ranked_panel(data_view, config)

Arguments

Value

A ggplot object

Build the technical replicate panel

Description

Internal function to build the panel showing raw scores with tech reps.

Usage

build_tech_rep_panel(data_view, config)

Arguments

Value

A ggplot object

Confidence interval fill colors

Description

Returns the fill colors used for confidence interval regions in bootstrap distribution plots.

Usage

ci_fill_colors(style = "default")

Arguments

Value

A named character vector of hex colors for low, middle, high regions

Compose besthr panels

Description

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

Usage

compose_besthr_panels(panels, config)

Arguments

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

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

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)

gets confidence interval limits for means of bootstrapped ranks

Description

conf_intervals calculates a low and a high quantile for the mean column of each group of a dataframe

Usage

conf_intervals(df, quo_group_col, low = 0.05, high = 0.95)

Arguments

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

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")

dot plot of ranked data without technical replicates

Description

dot_plot returns a ggplot object of ranked data with group on the x-axis and rank on the y-axis. Point size indicates the number of observations seen at that point. A per group horizontal line shows the group ranked mean

Usage

dot_plot(hrest, group_col, theme_style = "modern", color_palette = "okabe_ito")

Arguments

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

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)

Convert named columns to factors

Description

factorise_cols returns a copy of the passed data frame in which all explicitly named columns are converted to factors with as.factor All columns with only NA values are ommitted.

Usage

factorise_cols(df, col_list)

Arguments

Format table as string

Description

Internal function to convert tibble to markdown, html, or latex string.

Usage

format_table(tbl, format)

Arguments

Value

A character string

Get mean rank of groups in a data frame

Description

group_means groups the provided dataframe by a column and returns a summary dataframe with a mean column containing the mean of the group's rank column

Usage

group_means(df, quo_group_col)

Arguments

Get number of observations in a group in a data frame

Description

group_ns groups the provided dataframe by a column and returns a summary dataframe with an column n containg the number of observations in a group

Usage

group_ns(df, quo_group_col)

Arguments

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

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

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

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

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

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

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)

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

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

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)

Print method for besthr_data_view

Description

Print method for besthr_data_view

Usage

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

Arguments

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

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

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

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

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

Value

A ggplot2 discrete fill scale

Examples

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

dot plot of score data with technical replicates

Description

tech_rep_dot_plot returns a ggplot object of score data with group on technical replicate on the x-axis, score on the y-axis with point size representing the number of observations at that point. Facets represent individual groups

Usage

tech_rep_dot_plot(
  hrest,
  score_col,
  group_col,
  tech_rep_col,
  theme_style = "modern",
  color_palette = "okabe_ito"
)

Arguments

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

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

Value

A new besthr_plot_config object

Examples

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