Bioconductor informations
The Well-Plate Maker (WPM) is a shiny application deployed as an R package. Functions for a command-line/script use are also available. The WPM allows users to generate well plate maps to carry out their experiments while improving the handling of batch effects. In particular, it helps controlling the "plate effect" thanks to its ability to randomize samples over multiple well plates. The algorithm for placing the samples is inspired by the backtracking algorithm: the samples are placed at random while respecting specific spatial constraints. The use of WPM as well as the definition of configurable spatial constraints are described in the following sections.
R version >= 4.0.0
OS tested : Windows
, Fedora
, Ubuntu
,MacOS
The application should also work on other platforms.
If problems are encountered on other OS, report them by
creating an issue.
WPM R package dependencies
CRAN dependencies: golem
, rlang
, shiny
, shinydashboard
, shinyWidgets
, dplyr
,
shinycustomloader
, DT
, RColorBrewer
, logging
, stringr
, ggplot2
Bioconductor dependencies: Biobase
, SummarizedExperiment
From GitHub (consider it a devel version):
devtools::install_github("HelBor/wpm", build_vignettes=TRUE)
From Bioconductor (release, stable version):
if (!requireNamespace("BiocManager", quietly = TRUE))
install.packages("BiocManager")
BiocManager::install("wpm")
Instructions can also be found on the Bioconductor page
There are two ways to use the WPM:
| Input Format | Command line | WPM app | | --------------------- |:------------:| :------:| | CSV / txt | yes | yes | | ExpressionSet | yes | no | | SummarizedExperiment | yes | no | | MSnSet | yes | no |
WPM identifies four different types of samples with decreasing priority:
This priority rule allows consistent distributions of samples into wells. For example, if a well is declared forbidden, then this well will no longer be considered for the other types of samples.
library(wpm)
For a complete Tutorial, please see the Vignette of the package.
browseVignettes("wpm")
The following steps must be performed in the correct order.
You can work with CSV/txt/TSV files, ExpressionSet, MSnSet, or SummarizedExperiment objects. The first step is to create a dataframe containing all the data necessary for the WPM to work correctly. Notably, it is needed to specify which column in the file corresponds to the grouping factor, if any.
# if you have a CSV file
df <- convertCSV("path-to-your-CSV", "grouping_factor")
# if you have an ExpressionSet or an MSnSet
df <- convertESet(myExpressionSet, "grouping_factor") # or convertESet(myMSnSet, "grouping_factor")
# if you have a SummarizedExperiment
df <- convertSE(mySummarizedExperiment, "grouping_factor")
For more details about the functions, please use ?wpm::<functionName>
R command.
The next step is to run the wrapperWPM
function by giving it all the parameters
needed:
convertXXX
functionsSuppose you have generated this (toy) dataframe:
# create a MSnSet toy example
sample_names <- c("s1","s2","s3","s4", "s5")
M <- matrix(NA, nrow = 4, ncol = 5)
colnames(M) <- sample_names
rownames(M) <- paste0("id", LETTERS[1:4])
pd <- data.frame(Environment = rep_len(LETTERS[1:3], 5),
Category = rep_len(1:2, 5), row.names = sample_names)
rownames(pd) <- colnames(M)
x <- MSnbase::MSnSet(exprs = M,pData = pd)
# convert it into a dataframe that is valid according to the WPM constraints
df <- convertESet(x, "Environment")
# example without buffer specification
wpm_res <- wrapperWPM(user_df = df,
plate_dims = list(8,12),
nb_plates = 1,
forbidden_wells = "A1,A2,A3",
fixed_wells = "B1,B2",
spatial_constraint = "NS")
For more details, see ?wpm::wrapperWPM
The final step is to create a visual output of the generated plate plan(s)
using the drawMap()
function :
drawned_map <- wpm::drawMap(df = wpm_res,
sample_gps = length(levels(as.factor(pd$Environment))),
gp_levels = gp_lvl <- levels(as.factor(pd$Environment)),
plate_lines = 8,
plate_cols = 12,
project_title = "my Project Title")
drawned_map
For more details, see ?wpm::drawMap
The WPM is accompanied with a GUI providing the necessary parameters for the application to work. No programming skills are required. Simply run in the console:
wpm()
If everything is in order, a new window will open in your default browser.
If not, find the line written in the R console that looks like
Listening on http://127.0.0.1:8000
, and paste the URL in your web browser.
WPM has 4 main panels:
1) Provide a CSV file containing the sample names and variable factors, if any.
2) Provide a Project title. It will be used for the plot(s) title and the identifiers in the final dataframe.
3) Specify the plate dimensions and their number (the user can choose between 6, 24, 48, 96, 386, 1534 as well as custom dimensions). The WPM checks that all the given settings are compatible)
4) Specify the Forbidden well: simply insert in LetterNumber format separated with comma (e.g. "A1,A2")
5) Specify the Buffers: You need to specify the pattern (rows, columns, checkerboard or manually defined) and give the neighborhood constraint between groups for randomization:
6) Specify the Fixed samples: in the same way as for forbidden wells, insert LetterNumber as is "A1,B3,C10,A5".
7) Choose a maximum number of iterations to find a solution, then start the WPM. If the samples do not have a group, then the samples will be placed completely randomly on the plates. If there are groups, the WPM will use an algorithm inspired by the backtracking algorithm (to place the samples in the wells while respecting the specified constraints).
The Result panel allows you to look at the final dataset containing the wells chosen for each sample and a plot of your final well-plate map. Dataframe and plots are downloadable separately.
Example of a final plot (96 well-plate with 80 samples divided into 10 groups):
Borges, H., Hesse, A. M., Kraut, A., Couté, Y., Brun, V., & Burger, T. (2021). Well Plate Maker: A user-friendly randomized block design application to limit batch effects in largescale biomedical studies. Bioinformatics (link to the publication).
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.