# basic-use

## Citation

Please cite as

> Dan MacLean. (2019). TeamMacLean/besthr: Initial Release (0.3.0). Zenodo. https://doi.org/10.5281/zenodo.3374507

## Simplest Use Case - Two Groups, No Replicates

With a data frame or similar object, use the `estimate()` function to get the bootstrap estimates of the ranked data.

`estimate()` has a basic function call as follows:

`estimate(data, score_column_name, group_column_name, control = control_group_name)`

The first argument after the

    library(besthr)

    hr_data_1_file <- system.file("extdata", "example-data-1.csv", package = "besthr")
    hr_data_1 <- readr::read_csv(hr_data_1_file)
    #> Rows: 20 Columns: 2
    #> ── Column specification ────────────────────────────────────────────────────────
    #> Delimiter: ","
    #> chr (1): group
    #> dbl (1): score
    #>
    #> ℹ Use `spec()` to retrieve the full column specification for this data.
    #> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
    head(hr_data_1)
    #> # A tibble: 6 × 2
    #>   score group
    #>   <dbl> <chr>
    #> 1    10 A
    #> 2     9 A
    #> 3    10 A
    #> 4    10 A
    #> 5     8 A
    #> 6     8 A

    hr_est_1 <- estimate(hr_data_1, score, group, control = "A")
    hr_est_1
    #> besthr (HR Rank Score Analysis with Bootstrap Estimation)
    #> =========================================================
    #>
    #> Control: A
    #>
    #> Unpaired mean rank difference of A (14.9, n=10) minus B (6.1, n=10)
    #>  8.8
    #> Confidence Intervals (0.025, 0.975)
    #>  3.92375, 8.4525
    #>
    #> 100 bootstrap resamples.

    plot(hr_est_1)
    #> Confidence interval: 2.5% - 97.5%

### Setting Options

You may select the group to set as the common reference control with `control`.

    estimate(hr_data_1, score, group, control = "B" ) %>%
      plot()
    #> Confidence interval: 2.5% - 97.5%

You may select the number of iterations of the bootstrap to perform with `nits` and the quantiles for the confidence interval with `low` and `high`.

    estimate(hr_data_1, score, group, control = "A", nits = 1000, low = 0.4, high = 0.6) %>%
      plot()
    #> Confidence interval: 40.0% - 60.0%

## Extended Use Case - Technical Replicates

You can extend the `estimate()` options to specify a third column in the data that contains technical replicate information, add the technical replicate column name after the sample column. Technical replicates are automatically merged using the `mean()` function before ranking.

    hr_data_3_file <- system.file("extdata", "example-data-3.csv", package = "besthr")
    hr_data_3 <- readr::read_csv(hr_data_3_file)
    #> Rows: 36 Columns: 3
    #> ── Column specification ────────────────────────────────────────────────────────
    #> Delimiter: ","
    #> chr (1): sample
    #> dbl (2): score, rep
    #>
    #> ℹ Use `spec()` to retrieve the full column specification for this data.
    #> ℹ Specify the column types or set `show_col_types = FALSE` to quiet this message.
    head(hr_data_3)
    #> # A tibble: 6 × 3
    #>   score sample   rep
    #>   <dbl> <chr>  <dbl>
    #> 1     8 A          1
    #> 2     9 A          1
    #> 3     8 A          1
    #> 4    10 A          1
    #> 5     8 A          2
    #> 6     8 A          2

    hr_est_3 <- estimate(hr_data_3, score, sample, rep, control = "A")

    hr_est_3
    #> besthr (HR Rank Score Analysis with Bootstrap Estimation)
    #> =========================================================
    #>
    #> Control: A
    #>
    #> Unpaired mean rank difference of A (5, n=3) minus B (2, n=3)
    #>  3
    #> Confidence Intervals (0.025, 0.975)
    #>  1, 3
    #>
    #> Unpaired mean rank difference of A (5, n=3) minus C (8, n=3)
    #>  -3
    #> Confidence Intervals (0.025, 0.975)
    #>  7, 8.84166666666666
    #>
    #> 100 bootstrap resamples.

    plot(hr_est_3)
    #> Confidence interval: 2.5% - 97.5%

### Alternate Plot Options

In the case where you have use technical replicates and want to see those plotted you can use an extra plot option `which`. Set `which` to `just_data` if you wish the left panel of the plot to show all data without ranking. This will only work if you have technical replicates.

    hr_est_3 %>%
      plot(which = "just_data")
    #> Confidence interval: 2.5% - 97.5%

## Built-in Themes and Color Palettes

besthr uses a modern, colorblind-safe appearance by default. You can customize the look using themes and color palettes.

### Theme Options

Use the `theme` parameter to change the overall visual style:

- `"modern"` (default) - A clean, contemporary style with refined typography
- `"classic"` - The original besthr appearance (for backward compatibility)

    # Modern theme (default)
    plot(hr_est_1)
    #> Confidence interval: 2.5% - 97.5%

    # Classic theme (original style)
    plot(hr_est_1, theme = "classic")
    #> Confidence interval: 2.5% - 97.5%

### Color Palette Options

Use the `colors` parameter to change the color palette:

- `"okabe_ito"` (default) - Colorblind-safe Okabe-Ito palette
- `"default"` - Original besthr colors (for backward compatibility)
- `"viridis"` - Viridis color scale

    # Default is already colorblind-safe
    plot(hr_est_1)
    #> Confidence interval: 2.5% - 97.5%

    # Original colors
    plot(hr_est_1, colors = "default")
    #> Confidence interval: 2.5% - 97.5%

    # Viridis palette
    plot(hr_est_1, colors = "viridis")
    #> Confidence interval: 2.5% - 97.5%

### Quick Style Presets

For easy customization without understanding all options, use preset styles:

    # Publication-ready style
    plot(hr_est_1, config = besthr_style("publication"))
    #> Confidence interval: 2.5% - 97.5%

    # Presentation style (larger elements)
    plot(hr_est_1, config = besthr_style("presentation"))
    #> Confidence interval: 2.5% - 97.5%

    # Density style (gradient density instead of points)
    plot(hr_est_1, config = besthr_style("density"))
    #> Confidence interval: 2.5% - 97.5%
    #> Picking joint bandwidth of 0.414

    # See all available styles
    list_besthr_styles()
    #> Available besthr style presets:
    #>
    #>   'default'       Modern theme with colorblind-safe colors (recommended)
    #>   'classic'       Original besthr appearance
    #>   'publication'   Clean style for journal figures
    #>   'presentation'  Larger elements for slides
    #>   'density'       Gradient density display for bootstrap
    #>
    #> Usage: plot(hr, config = besthr_style('publication'))

### Using besthr Palettes Directly

The color palettes can also be used directly in your own ggplot2 code:

    # Get palette colors
    besthr_palette("okabe_ito", n = 4)
    #> [1] "#E69F00" "#56B4E9" "#009E73" "#F0E442"

    # Available palettes
    besthr_palette("default", n = 3)
    #> [1] "#F8766D" "#00BA38" "#619CFF"
    besthr_palette("viridis", n = 3)
    #> [1] "#482576FF" "#21908CFF" "#BBDF27FF"

## Styling Plots

### Using Built-in Themes and Colors

The easiest way to style your plots is using the `theme` and `colors` parameters:

    # Modern look with colorblind-safe colors (this is the default)
    plot(hr_est_1, theme = "modern", colors = "okabe_ito")
    #> Confidence interval: 2.5% - 97.5%

    # Classic appearance (original besthr style)
    plot(hr_est_1, theme = "classic", colors = "default")
    #> Confidence interval: 2.5% - 97.5%

    # Viridis color scheme
    plot(hr_est_1, colors = "viridis")
    #> Confidence interval: 2.5% - 97.5%

### Adding Titles and Annotations

The plot object is a `patchwork` composition. You can add titles using `plot_annotation()`:

    library(patchwork)

    p <- plot(hr_est_1)
    #> Confidence interval: 2.5% - 97.5%

    p + plot_annotation(
      title = 'HR Score Analysis',
      subtitle = "Control vs Treatment",
      caption = 'Generated with besthr'
    )

## Advanced Configuration

For users who need fine-grained control over plot appearance, besthr provides a configuration system.

### Using besthr_plot_config

The `besthr_plot_config()` function creates a configuration object that controls all aspects of plot appearance:

    # Create a custom configuration
    cfg <- besthr_plot_config(
      panel_widths = c(2, 1),        # Make data panel wider than bootstrap panel
      point_size_range = c(3, 10),   # Larger points
      point_alpha = 0.9,             # More opaque points
      mean_line_width = 1.5,         # Thicker mean lines
      theme_style = "modern",
      color_palette = "okabe_ito"
    )

    print(cfg)
    #> besthr plot configuration:
    #>   Panel widths: 2, 1
    #>   Y-axis limits: auto
    #>   Y-axis expand: 0.05
    #>   Point size range: 3 - 10
    #>   Point alpha: 0.9
    #>   Mean line type: 3
    #>   Mean line width: 1.5
    #>   Density alpha: 0.7
    #>   Density style: points
    #>   Theme: modern
    #>   Colors: okabe_ito

    # Use the configuration in plot
    plot(hr_est_1, config = cfg)
    #> Confidence interval: 2.5% - 97.5%

You can update an existing configuration with `update_config()`:

    # Modify just one setting
    cfg2 <- update_config(cfg, panel_widths = c(1, 2))
    plot(hr_est_1, config = cfg2)
    #> Confidence interval: 2.5% - 97.5%

### Configuration Options

Parameter | Default | Description
--- | --- | ---
`panel_widths` | `c(1, 1)` | Relative widths of observation and bootstrap panels
`y_limits` | `NULL` (auto) | Fixed y-axis limits, or NULL for automatic
`y_expand` | `0.05` | Proportional expansion of y-axis limits
`point_size_range` | `c(2, 8)` | Min/max point sizes based on count
`point_alpha` | `0.8` | Point transparency (0-1)
`mean_line_type` | `3` | Line type for mean indicators
`mean_line_width` | `1` | Line width for mean indicators
`density_alpha` | `0.7` | Bootstrap density transparency
`density_style` | `"points"` | Density display: “points” (jittered bootstrap), “gradient”, or “solid”
`theme_style` | `"modern"` | Theme: “classic” or “modern”
`color_palette` | `"okabe_ito"` | Colors: “default”, “okabe_ito”, or “viridis”

## Building Custom Plots

For maximum flexibility, you can build plots from individual components.

### Using besthr_data_view

The `besthr_data_view()` function extracts all plotting data from an hrest object with unified axis limits:

    # Create a data view
    dv <- besthr_data_view(hr_est_1)
    print(dv)
    #> besthr data view:
    #>   Groups: 2
    #>   Observations: 20
    #>   Bootstrap iterations: 100
    #>   Rank limits: 0.17 - 18.32
    #>   Control: A

    # Access the data
    head(dv$ranked)
    #> # A tibble: 6 × 3
    #>   score group  rank
    #>   <dbl> <chr> <dbl>
    #> 1    10 A      17.5
    #> 2     9 A      13
    #> 3    10 A      17.5
    #> 4    10 A      17.5
    #> 5     8 A       9
    #> 6     8 A       9
    head(dv$bootstrap)
    #> # A tibble: 6 × 3
    #>   group  mean iteration
    #>   <chr> <dbl>     <int>
    #> 1 B      3.9          1
    #> 2 B      5.8          2
    #> 3 B      6.65         3
    #> 4 B      6.55         4
    #> 5 B      7.45         5
    #> 6 B      6.4          6
    dv$rank_limits
    #> [1]  0.175 18.325

### Using Panel Builders

You can build individual panels and compose them yourself:

    library(patchwork)

    # Create panels
    cfg <- besthr_plot_config(theme_style = "modern", color_palette = "okabe_ito")
    dv <- besthr_data_view(hr_est_1, cfg)

    p1 <- build_observation_panel(dv, cfg, "rank_simulation")
    p2 <- build_bootstrap_panel(dv, cfg)

    # Custom composition with different widths
    p1 + p2 + plot_layout(widths = c(3, 1))

## Alternative Visualizations

### Raincloud Plots

The `plot_raincloud()` function provides an alternative visualization showing jittered data points with confidence intervals:

    plot_raincloud(hr_est_1)

    # With modern styling
    plot_raincloud(hr_est_1, theme = "modern", colors = "okabe_ito")

### Bootstrap Raincloud

The `plot_bootstrap_raincloud()` function shows the bootstrap distribution as jittered points:

    plot_bootstrap_raincloud(hr_est_1)

## CI Color Customization

The `derive_ci_colors()` function generates confidence interval colors that harmonize with the selected palette:

    # Default CI colors
    derive_ci_colors("default", "classic")
    #> [1] "#0000FFA0" "#A0A0A0A0" "#FF0000A0"

    # Okabe-Ito derived CI colors
    derive_ci_colors("okabe_ito", "modern")
    #> [1] "#0072B2AA" "#999999AA" "#D55E00AA"

    # Viridis derived CI colors
    derive_ci_colors("viridis", "classic")
    #> [1] "#440154AB" "#21908CAB" "#FDE725AB"

## Significance and Effect Size

    # Create example data with 3 groups and realistic variation
    set.seed(42)
    d_effect <- data.frame(
      score = c(
        sample(1:4, 12, replace = TRUE),   # Group A: low scores (control)
        sample(4:8, 12, replace = TRUE),   # Group B: medium-high scores
        sample(6:10, 12, replace = TRUE)   # Group C: high scores
      ),
      group = rep(c("A", "B", "C"), each = 12)
    )
    hr_effect <- estimate(d_effect, score, group, control = "A", nits = 1000)

### Significance Annotations

Add significance stars to groups where the bootstrap confidence interval does not overlap the control mean:

    plot(hr_effect, show_significance = TRUE)
    #> Confidence interval: 2.5% - 97.5%

### Effect Size Annotation

Display effect size (difference from control) with confidence intervals:

    plot(hr_effect, show_effect_size = TRUE)
    #> Confidence interval: 2.5% - 97.5%

### Computing Statistics Directly

You can access the significance and effect size calculations directly:

    # Compute significance
    compute_significance(hr_effect)
    #>   group significant p_value stars
    #> 1     A          NA      NA
    #> 2     B        TRUE       0   ***
    #> 3     C        TRUE       0   ***

    # Compute effect sizes
    compute_effect_size(hr_effect)
    #>   group   effect effect_ci_low effect_ci_high
    #> 1     A       NA            NA             NA
    #> 2     B 13.08333      9.830208       16.29271
    #> 3     C 21.79167     18.833333       24.83333

## Summary Tables

Generate publication-ready summary tables with `besthr_table()`:

    # Default tibble format
    besthr_table(hr_effect)
    #> # A tibble: 3 × 6
    #>   group     n mean_rank ci_low ci_high effect_size
    #>   <chr> <int>     <dbl>  <dbl>   <dbl>       <dbl>
    #> 1 A        12      6.88   NA      NA          NA
    #> 2 B        12     20.0    16.7    23.2        13.1
    #> 3 C        12     28.7    25.7    31.7        21.8

    # With significance stars
    besthr_table(hr_effect, include_significance = TRUE)
    #> # A tibble: 3 × 7
    #>   group     n mean_rank ci_low ci_high effect_size significance
    #>   <chr> <int>     <dbl>  <dbl>   <dbl>       <dbl> <chr>
    #> 1 A        12      6.88   NA      NA          NA   ""
    #> 2 B        12     20.0    16.7    23.2        13.1 "***"
    #> 3 C        12     28.7    25.7    31.7        21.8 "***"

    # Markdown format
    besthr_table(hr_est_1, format = "markdown")
    #> [1] "| group | n | mean_rank | ci_low | ci_high | effect_size |\n| --- | --- | --- | --- | --- | --- |\n| A | 10 | 14.9 | NA | NA | NA |\n| B | 10 |  6.1 | 3.92 | 8.45 | -8.8 |"

Other formats available: `"html"`, `"latex"`

## Publication Export

Save plots directly to publication-quality files:

    # Save to PNG (default 300 DPI)
    save_besthr(hr_est_1, "figure1.png")

    # Save to PDF
    save_besthr(hr_est_1, "figure1.pdf", width = 10, height = 8)

    # Save raincloud plot
    save_besthr(hr_est_1, "raincloud.png", type = "raincloud")

    # With custom options
    save_besthr(hr_est_1, "figure1.png",
                theme = "modern",
                colors = "okabe_ito",
                width = 10,
                height = 6,
                dpi = 600)

Supported formats: PNG, PDF, SVG, TIFF, JPEG