The Home page when wpm is started

Parameters Panel

3.4.1 Step 1: Upload the dataset

First, you need to upload aComma-separated values (.CSV) or a text (.txt) file.This file contains at least one piece of information: the list of the sample names.

It is also possible to provide a file containing several other variables describingthe data, as in the example below:

IMPORTANT Please make sure the data in the CSV file respect the following SPECIFIC ORDER of columns:Sample names in thefirst column, and other variables in the other columns,like the example below (if there are rownames, then theSamples Column must bethe second in the file.):

Sample;Type;Treatments1;A;trt1s2;A;trt1s3;B;Ctrls4;C;Ctrl

If this is your first time using the WPM, we recommend that you test thecapabilities of the WPM using thedemo dataset (“Load the demo dataset” tab).

Second, you have to specify if there are quotes in your file or not(If you are using the demo dataset, this is not a requested parameter.):

The default isnone, meaning that there is no" or’ characters in your file.If you select the appropriate quote, then you will be able to:

• check if your file does have aheader androw names.
• select the appropriateseparator field. Default is semicolon (“;”)

Then, you can select one of the variables that you want to use as the groupingfactor for WPM.
This column will be renamed “Group” in the final dataset.

Choose the grouping factor

The names you give to columns in your CSV file do not matter, because the WPM will createa new dataset having 3 fields:“Sample” ,“Group” and“ID”.

You will see your dataset on the right hand side of the window, as well as another datasetwhich will be used by WPM to generate the map(s).
Each sample is assigned a unique ID, which will be used to name itonto the plate maps (for more details on the ID see theResults section ).

Dataset vizualisation

IMPORTANT Please ensure that the dataset is correctly displayed in the rightwindow and that the number of samples / groups is correct.
If you see that the total number of samples is wrong, this means that you havenot chosen the appropriate options among those described above, so that corrections are needed.

3.4.2 Step 2: Choose a Project name

This step is mandatory. It will be used in the plot titles as well as in the outputfile names. Moreover, it be concatenated with sample IDs to limit confusions.

3.4.3 Step 3: Plate(s) dimensions

Here you have to specify the plate dimensions and their number. Currently, WPMsupports plate dimensions of 6, 24, 48, 96, 386, 1534 wells; as well as custom dimensions(where you manually specify the number of rows and columns).

To the right of step 2 you can see an information box, warning you that WPMwill distribute the samples in a balanced manner within the plates (if thereare several of them).

balanced way message

If you select a plate size compatible with the total number of samples, youwill see two blue boxes and a plate plan appear on the right hand side. They summarize allthe elements of your configuration.In the example below, we selected the pre-defined dimension of 96 wells and onlyone plate:

plate dimensions example

The right side of the panel will summarize all these parameters:

parameters summary

This plot updates with each modification of the parameters, thus making itpossible to see if one has made an error.

IMPORTANT: If the WPM detects a problem or incompatibility between parameters,you will see an error message instead of the plate map, providing hints on the possible origin of the problem.

Example of error message

3.4.4 Step 4: Forbidden wells

In this step are listed theForbidden wells, if any (optional):

AForbidden well will not be filled with any kind of sample, eitherbecause the user does not want to (e.g. plate corners in case of non-uniformheat distribution), or because of material constraints (e.g. dirty wells, brokenpipettes).

You fill the text input with the coordinates of the wells (a combination ofletters and numbers, as in the example below):

Example of forbidden wells listed in the text input

You will see the plot updated in the right section:

Updated plot with forbidden wells

The wells filled with forbidden wells will have the“forbidden” ID in thefinal dataset. On the resulting map, these wells will be colored in red.

3.4.5 Step 5: Buffers

At this stage you can specify the wells which correspond to buffers, if thereare any.

Abuffer well corresponds to a well filled filled with solution but without biological material (e.g. to avoid/check for cross-contamination).

Five patterns are available for placing the buffers:

1)no buffers: there will be no buffer on the plate(s).

2)Per line: Automatically places buffers every other row.You can choose to start placing in even or odd row.

Per line mode example with even option

3)Per column: Automatically places buffers every other column.You can choose to start placing in even or odd column.

Per Column mode example with even option

4)Checkerboard: Automatically places buffers like a checkerboard.

Checkerboard mode

5)Choose by hand: It is the same procedure as for specifying forbiddenwells.

3.4.6 Step 6: Fixed samples

At this stage you can specify the wells which correspond to fixedsamples, if there are any.

Afixed sample corresponds to a quality control sample or standard.The precise location of these samples must be controlled by the researcher.

This step works in exactly the same way as theforbidden well step. The only difference is that the fixed sampleswill appear inblack on the plot.

The fixed samples will have the“fixed” ID inthe final dataset.

3.4.7 Number of iterations

Choose amaximum number of iterations to find a solution, then start theWPM by clicking the“start WPM” button. If the samples do not have a group, then the sampleswill be placed completely randomly on the plates. If there are groups, the WPM willuse an algorithm inspired by the backtracking algorithm (to place thesamples in the wells while respecting the specified constraints).

The default value is 20, but if your configuration is somewhat complex, thenit is advised to increase the number.

Aniteration corresponds to an attempt by the WPM to find a solution. Thealgorithm used is not fully backtracked: the WPM stops as soon as there are nomore possibilities to finalize the current solution; then, it starts back from scratchthe plate map, until a solution that fits all the constraints is found.With this approach, not all possible combinations are explored, but it doesreduce execution time.

When you start the computations, a progress bar appears.

If the WPM finds a solution, you will see this pop in the browser, inviting you togo to theResult Panel:

WPM succeeded

If the WPM fails, an error message will appear, prompting you to try again:

WPM failed

IMPORTANT If after launching WPM and generating the results, you realizethat one or more parameters do not work, you can always return to the“Parameters” tab and modify them. The data displayed in the “Results” tab willnot be automatically changed, you will have to click again on the “start WPM”button to take into account the new changes.

NOTE If you want to create a new plate plan for another project, pressctrl + f5, this will reset the application.

Final dataframe

Plate map

4.1.1 Starting from a CSV file:

imported_csv <- wpm::convertCSV("path-to-CSV-file")

4.1.2 Starting from anExpressionSet orMSnSet object

sample_names <- c("s1","s2","s3","s4", "s5")M <- matrix(NA, nrow = 4, ncol = 5)colnames(M) <- sample_namesrownames(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)my_MSnSet_object <- MSnbase::MSnSet(exprs = M,pData =  pd)

Then, runconvertESet by specifying the object and the variable to use asgrouping factor for samples:

df <- wpm::convertESet(my_MSnSet_object, "Environment")

4.1.3 Starting from aSummarizedExperiment

nrows <- 200ncols <- 6counts <- matrix(runif(nrows * ncols, 1, 1e4), nrows)colData <- data.frame(Treatment=rep(c("ChIP", "Input"), 3),                      row.names=LETTERS[1:6])se <- SummarizedExperiment::SummarizedExperiment(assays=list(counts=counts),                                                 colData=colData)df <- wpm::convertSE(se, "Treatment")

For more details about the functions, please use?wpm::<functionName> R command.

4.2.1 When using a CSV file

In the running toy example (see code shunks around), we do not specify any buffer well.

wpm_result <- wpm::wrapperWPM(user_df = imported_csv$df_wpm,            plate_dims = list(8,12),            nb_plates = 1,            forbidden_wells = "A1,A2,A3",            fixed_wells = "B1,B2",            spatial_constraint = "NS")

4.2.2 When using an R-structured dataset (ExpressionSet,MSnSet orSummarizedExperiment)

wpm_result <- wpm::wrapperWPM(user_df = df,            plate_dims = list(8,12),            nb_plates = 1,            forbidden_wells = "A1,A2,A3",            fixed_wells = "B1,B2",            spatial_constraint = "NS")

## 2025-10-31 20:51:41.82873 INFO::max_iteration: 20## 2025-10-31 20:51:41.844083 INFO:backtrack/map:nrow(c): 6## 2025-10-31 20:51:41.860245 INFO::plate number 1## 2025-10-31 20:51:41.876732 WARNING:fonctions.generateMapPlate:number of attempts: 1## 2025-10-31 20:51:41.879625 INFO:backtracking:class(new_df): data.frame

For more details, see?wpm::wrapperWPM