---
title: "Transform microwell plates with `tidyplate`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Transform microwell plates with `tidyplate`}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

## Formating the input data

The input xlsx or csv should be formatted in a specific way:

-   Top left corner must hold the name for that plate.
-   Column names should be: 1, 2, 3, and so on and so forth.
-   Row names should be: A, B, C, and so on and so forth.
-   There must be an empty row between each plate.

## Usage

If the input file is an xlsx file it reads the first sheet by default. Users can specify sheet using the `sheet` argument for an xlsx file. Users can also specify the variable name of column where well ids will be stored (defaults to "well"). Please make sure that `well_id` argument does not match individual plate names in the input file.

Start by loading tidyplate:

```{r}
#| label: load
library(tidyplate)
```

First check if the input file is valid or not:

```{r}
#| label: check_plate-xlsx
#| error: true
library(tidyplate)
file <- system.file("extdata", 
                    "example_12_well.xlsx", 
                    package = "tidyplate")
check_plate(file) # No error for valid file

incorrect_file <- system.file("extdata",
                              "incorrect_format.csv",
                              package = "tidyplate")
check_plate(incorrect_file) # Error type displayed
```

As mentioned above, the formatting of the input file is very important. A csv or 
excel template for each plate type can be created using the `build_plate` function:

```{r}
#| label: build-plate-demo
#| echo: true
#| eval: false
build_plate(plate_type = 96, 
            n_plates = 2, 
            file_type = "xlsx") # default is csv
```

If you want to retrieve the names of individual plates:

```{r}
#| label: view-plate-names-xlsx
view_plate_names(file)
```

Read and import the file as a tibble:

```{r}
#| label: tidy_plate-xlsx
data <- tidy_plate(file)
head(data)
```

Conversely, a dataframe or tibble can be re-exported back to a plate shaped csv
or xlsx file:

```{r}
#| label: generate-plate
#| echo: true
#| eval: false
generate_plate(data, well_id = "well", plate_type = 12, file = "plate.csv")
```

For more information on how to use functions on multiple files or multi-sheet excel
files read the `vignette("advanced")`.