---
title: "basic-use"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{basic-use}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## 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 

```{r, fig.width=8, fig.height=6}
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)
head(hr_data_1)

hr_est_1 <- estimate(hr_data_1, score, group, control = "A")
hr_est_1

plot(hr_est_1)
```


### Setting Options

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

```{r, fig.width=8, fig.height=6}
estimate(hr_data_1, score, group, control = "B" ) %>%
  plot()
```

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`.

```{r, fig.width=8, fig.height=6}
estimate(hr_data_1, score, group, control = "A", nits = 1000, low = 0.4, high = 0.6) %>%
  plot()
```
  
## 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.

```{r, fig.width=8, fig.height=6}

hr_data_3_file <- system.file("extdata", "example-data-3.csv", package = "besthr")
hr_data_3 <- readr::read_csv(hr_data_3_file)
head(hr_data_3)

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

hr_est_3

plot(hr_est_3)

```

### 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.

```{r, fig.width=8, fig.height=6}

hr_est_3 %>%
  plot(which = "just_data")
```

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

```{r, fig.width=8, fig.height=6}
# Modern theme (default)
plot(hr_est_1)

# Classic theme (original style)
plot(hr_est_1, theme = "classic")
```

### 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

```{r, fig.width=8, fig.height=6}
# Default is already colorblind-safe
plot(hr_est_1)

# Original colors
plot(hr_est_1, colors = "default")

# Viridis palette
plot(hr_est_1, colors = "viridis")
```

### Quick Style Presets

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

```{r, fig.width=8, fig.height=6}
# Publication-ready style
plot(hr_est_1, config = besthr_style("publication"))

# Presentation style (larger elements)
plot(hr_est_1, config = besthr_style("presentation"))

# Density style (gradient density instead of points)
plot(hr_est_1, config = besthr_style("density"))

# See all available styles
list_besthr_styles()
```

### Using besthr Palettes Directly

The color palettes can also be used directly in your own ggplot2 code:
```{r}
# Get palette colors
besthr_palette("okabe_ito", n = 4)

# Available palettes
besthr_palette("default", n = 3)
besthr_palette("viridis", n = 3)
```

## Styling Plots

### Using Built-in Themes and Colors

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

```{r, fig.width=8, fig.height=6}
# Modern look with colorblind-safe colors (this is the default)
plot(hr_est_1, theme = "modern", colors = "okabe_ito")

# Classic appearance (original besthr style)
plot(hr_est_1, theme = "classic", colors = "default")

# Viridis color scheme
plot(hr_est_1, colors = "viridis")
```

### Adding Titles and Annotations

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

```{r, fig.width=8, fig.height=6}
library(patchwork)

p <- plot(hr_est_1)

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:

```{r}
# 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)
```

```{r, fig.width=8, fig.height=6}
# Use the configuration in plot
plot(hr_est_1, config = cfg)
```

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

```{r, fig.width=8, fig.height=6}
# Modify just one setting
cfg2 <- update_config(cfg, panel_widths = c(1, 2))
plot(hr_est_1, config = cfg2)
```

### 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:

```{r}
# Create a data view
dv <- besthr_data_view(hr_est_1)
print(dv)

# Access the data
head(dv$ranked)
head(dv$bootstrap)
dv$rank_limits
```

### Using Panel Builders

You can build individual panels and compose them yourself:

```{r, fig.width=10, fig.height=5}
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:

```{r, fig.width=6, fig.height=5}
plot_raincloud(hr_est_1)
```

```{r, fig.width=6, fig.height=5}
# 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:

```{r, fig.width=6, fig.height=5}
plot_bootstrap_raincloud(hr_est_1)
```

## CI Color Customization

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

```{r}
# Default CI colors
derive_ci_colors("default", "classic")

# Okabe-Ito derived CI colors
derive_ci_colors("okabe_ito", "modern")

# Viridis derived CI colors
derive_ci_colors("viridis", "classic")
```


## Significance and Effect Size

```{r}
# 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:

```{r, fig.width=8, fig.height=6}
plot(hr_effect, show_significance = TRUE)
```

### Effect Size Annotation

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

```{r, fig.width=8, fig.height=6}
plot(hr_effect, show_effect_size = TRUE)
```

### Computing Statistics Directly

You can access the significance and effect size calculations directly:

```{r}
# Compute significance
compute_significance(hr_effect)

# Compute effect sizes
compute_effect_size(hr_effect)
```

## Summary Tables

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

```{r}
# Default tibble format
besthr_table(hr_effect)

# With significance stars
besthr_table(hr_effect, include_significance = TRUE)

# Markdown format
besthr_table(hr_est_1, format = "markdown")
```

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

## Publication Export

Save plots directly to publication-quality files:

```{r, eval=FALSE}
# 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