--- title: "Plate Randomization Vignette" author: "Olink DS team" date: "`r Sys.Date()`" output: html_vignette: toc: true toc_depth: 3 vignette: > %\VignetteIndexEntry{Plate Randomization Vignette} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, echo=FALSE,message=FALSE, eval=FALSE} library(OlinkAnalyze) ``` ```{r, echo=FALSE,message=FALSE} library(dplyr) library(ggplot2) ``` ```{r setup, include=FALSE} knitr::opts_chunk$set(warning = FALSE, fig.height=3, fig.width=6, message = FALSE) ``` ## Introduction This vignette describes how to use Olink® Analyze to randomize the samples with an option to keep subjects on the same plate. When a study is well randomized the experimental variables can be considered to be evenly distributed across each plate, even for a larger study. What variables to randomize for should be decided for each study as these vary with the study purpose. Correct sample randomization will empower your study and minimize the risk of introducing any bias that can confound downstream analyses. If at all possible, samples from the same subject that are taken at various times during a longitudinal research should all be placed on the same plate to further limit data fluctuation. In order to evenly disperse the remaining experimental variables between plates, the individuals should subsequently be distributed. If randomization is not performed true biological variation may be missed or misidentified as e.g. technical variations. However, it would be challenging for us to control every variable. Most of the time, a complete randomization will be carried out, and the outcomes can be assessed by visualizing the layout of the plates. In this vignette, you will learn how to achieve this using the `olink_plate_randomizer()` function. And on top of that, you will also learn how to use `olink_displayPlateLayout()` and `olink_displayPlateDistributions()` to evaluate the performed randomization based on a given grouping variable. ```{r Outlier_data, include=FALSE} library(OlinkAnalyze) data(manifest) ``` ## Sample randomization The input manifest should be a tibble/data frame in long format containing all sample ID's. Sample ID column must be named SampleID. An example manifest is shown in Table 1. ```{r manifest, echo = F, message=FALSE} manifest %>% head(10) %>% knitr::kable(format = "html", booktabs = T, linesep = "", digits = 4, longtable = T, row.names = F, caption = "Table 1. Example of Sample manifest", label = "manifest") ``` ### Complete randomization The simplest way to randomize the samples is to perform complete randomization. ```{r complete_randomization, message=FALSE, warning=FALSE,results='hide'} randomized.manifest <- olink_plate_randomizer(manifest, seed=123456) ``` ### Generate randomization scheme that keeps subjects on the same plate In the case of multiple samples per subject (e.g. in longitudinal studies), Olink recommends keeping each subject on the same plate to further reduce variation in the data. The individuals should then be distributed so that the remaining experimental variables of interest are evenly distributed across plates. This could be achieved by using the `SubjectColumn` argument. The `SubjectColumn` argument must correspond to a column within the manifest and cannot be SampleID. If `SubjectColumn` is specified, every SampleID must have a value in the subject column, even if there is only 1 sample for that subject. However, if there are to many samples per subject (>8), complete randomization is recommended. The number of samples on each plate could be specified via the `available.spots` argument. For example, the following code will lead to 78 samples on the first plate, and 30 samples on the second and the third plates. The number of iterations for fitting subjects on the same plate can be set by the `iterations` argument. ```{r subjects_randomization, message=FALSE,results='hide'} randomized.manifest <- olink_plate_randomizer(manifest, SubjectColumn="SubjectID", available.spots=c(48,48,42), iterations = 500, seed=123456) ``` The plate size can be either directly set to 48 or 96 using the `PlateSize` argument or can be inferred by setting the `Product` argument to "Target 96", "Target 48", "Explore 384","Explore 3072", or "Explore HT." The number of Olink external controls can be set using the `num_ctrl` argument, which defaults to 8 controls. The Olink external controls can also be set to be randomized throughout the plate using the `rand_ctrl` argument. ```{r randomize_controls, message = FALSE, eval = FALSE} randomized_manifest <- olink_plate_randomizer(manifest, Product = "Explore HT", SubjectColumn = "SampleID", num_ctrl = 10, rand_ctrl = TRUE) ``` ```{r, rand_ctrl_code, echo=FALSE, results='hide', message=FALSE, warning=FALSE} randomized_manifest <- olink_plate_randomizer(manifest, Product = "Explore HT", SubjectColumn = "SampleID", num_ctrl = 10, rand_ctrl = TRUE) ``` ```{r randomized_controls_table, echo=FALSE, message=FALSE, warning=FALSE} randomized_manifest %>% head(10) %>% knitr::kable(format = "html", booktabs = T, linesep = "", digits = 4, longtable = T, row.names = F, caption = "Table 2. Example of Randomized Sample manifest", label = "manifest") ``` ## Visualization To illustrate the goodness of randomization, both `olink_displayPlateLayout()` and `olink_displayPlateDistributions` functions could be used. ### Plate layouts The `olink_displayPlateLayout()` function could be used to visualize the layouts of the plate and specifying the color for the variable of interest using the `color_g` argument. The label of the colored variable could be shown in the plot via the `include.label` argument. ```{r figure_captions, message=FALSE, echo=FALSE} fcap1 <- "Figure 1. Randomized samples in 96 well plate format, colored by Subject ID." fcap2 <- "Figure 2. Randomized samples in 96 well plate format with labeled wells." fcap3 <- "Figure 3. Distribution of Subject ID across randomized plates." fcap4 <- "Figure 4. Distribution of Site across randomized plates." ``` ```{r, fig.height = 6, fig.width = 7.5, fig.align = "center", fig.cap= fcap1} olink_displayPlateLayout(randomized.manifest, fill.color = 'SubjectID', include.label = FALSE) ``` The label of the colored variable could be shown in the plot via the `include.label` argument. ```{r, fig.height = 6, fig.width = 7.5, fig.align = "center", fig.cap= fcap2} olink_displayPlateLayout(randomized.manifest, fill.color = 'SubjectID', include.label = TRUE) ``` ### Plate distribution The distribution of the given grouping variable on each plate could be visualized via a bar chart using function `olink_displayPlateDistributions`. By setting `fill.color = 'SubjectID'`, we could make sure all the samples from the same subject were put on the same plate. ```{r, fig.align = "center", fig.cap=fcap3} olink_displayPlateDistributions(randomized.manifest, fill.color = 'SubjectID') ``` We could also check the distribution of other variables. For examples, the distribution of the variable `Site` could be visualized by setting `fill.color = 'Site'`. ```{r, fig.align = "center", fig.cap= fcap4} olink_displayPlateDistributions(randomized.manifest, fill.color = 'Site') ``` In the case of the randomization is not performed well, the randomization could be performed again with different seed number and iterations number. ## Data Output The output of the randomization function would be a "tibble" including SampleID, SubjectID etc. assigned to well positions. Columns include same columns as Manifest with additional columns: - plate: Plate number - column: Column on the plate - row: Row on the plate - well: Well location on the plate The randomized manifest could be outputted as an Excel file using the `write_xlsx` function from Package `writexl`. ```{r, eval = FALSE} library(writexl) write_xlsx(randomized.manifest,"randomized.manifest.xlsx") ``` ## Contact Us! We are always happy to help. Email us with any questions: - biostat\@olink.com for statistical services and general stats questions - biostattools\@olink.com for Olink Analyze and Shiny app support - support\@olink.com for Olink lab product and technical support - info\@olink.com for more information