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

## Styling Plots

You can style plots to your own taste. The object returned from `plot()` is a `patchwork` [https://patchwork.data-imaginist.com/](https://patchwork.data-imaginist.com/) object that composes two separate plots, the dot plot and the bootstrap percentile plot, which are themselves `ggplot` objects. So you can use a mixture of `patchwork` annotations functions for whole plot labels and `ggplot` themes for individual elements. 

### Adding annotations.

You can use the `patchwork` `plot_annotation()` function to add titles

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

p <- plot(hr_est_1)

p + plot_annotation(title = 'A stylish besthr plot', 
                    subtitle = "better than ever", 
                    caption = 'Though this example is not meaningful')
p


```


### Targetting a subplot to make theme changes

You can change the style of the individual plot elements using subsetting syntax `[[]]` . The dot plot can be addressed within the `patchwork` object using index 1 within the `patchwork` object `p[[1]]`, and the percentile plot using `p[[2]]`. You must add to the existing subplot then assign the result back to see the difference in the plot. Here's an example that uses `theme()` to restyle the y-axis text of the dot plot

```{r, fig.width=8, fig.height=6}
library(ggplot2)
p[[1]] <- p[[1]] + theme(axis.title.y = element_text(family = "Times", colour="blue", size=24))
p
```


### Changing the scale colours of a subplot

You can change the colours used by the scales in the same way using the `scale` functions, though as the type of scale is different for the dot plot and bootstrap plot you will need to apply a different scale for each.

For the dot plot, use a discrete scale e.g `scale_colour_manual()`, `scale_colour_viridis_d()` or `scale_colour_brewer(type = "qual")`

```{r, fig.width=8, fig.height=6}
p[[1]] <- p[[1]] + scale_colour_manual(values = c("blue", "#440000"))
p

p[[1]] <- p[[1]] + scale_colour_viridis_d()
p

p[[1]] <- p[[1]] + scale_colour_brewer(type="qual", palette="Accent")
p
```

For the percentile plot, use only `scale_colour_manual()` with specified colours. Annoyingly, this rewrites the other values associated with the scale each time, so you'll need to replace those.

```{r, fig.width=8, fig.height=6}
p[[2]] <- p[[2]] + scale_fill_manual(
  values = c("blue", "pink", "yellow"),
  name = "bootstrap percentile", labels=c("lower", "non-significant", "higher"),
  guide = guide_legend(reverse=TRUE)
  )
p
```