GitHub - HelBor/wpm: Well-Plate Maker (shiny application) (original) (raw)

Project Status R GitHub issues GitHub license

Bioconductor informations

platforms years in bioc
Release build release
Devel build devel

Brief introduction

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.

Getting started

Pre-requisites

R version >= 4.0.0OS tested : Windows, Fedora, Ubuntu,MacOSThe 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

How to install

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 theBioconductor page

How to use the WPM package

There are two ways to use the WPM:

Supported input formats

Input Format Command line WPM app
CSV / txt yes yes
ExpressionSet yes no
SummarizedExperiment yes no
MSnSet yes no

Types of samples

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.

Load the WPM package

For a complete Tutorial, please see the Vignette of the package.

Using the WPM with the command lines

The following steps must be performed in the correct order.

Prepare the dataset

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.

Run the WPM

The next step is to run the wrapperWPM function by giving it all the parameters needed:

Suppose 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

Plate map visualization

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

Using the WPM through a web interface

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:

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 likeListening on http://127.0.0.1:8000, and paste the URL in your web browser.

WPM has 4 main panels:

Parameters setting

Check the results

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

Example of a final plot (96 well-plate with 80 samples divided into 10 groups):

Pending Features

Citing Our work

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