README.md

In bmdavid2/DispenseFormulatrix: What the Package Does (One Line, Title Case)

DispenseFormulatrix

Contents

Description \ Installing DispenseFormulatrix \ Using DispenseFormulatrix mantis_dispense function assign_wells function

Using Experimental Designs Generated by the RSM package\ Normalizing DNA Concentrations with Mantis

Description

R package for creating custom reagent dispense lists for Formulatrix liquid handlers. Currently supports dispense lists for the MANTIS instrument only.

Installing DispenseFormulatrix

To install DispenseFormulatrix run the following R code.

install.packages("devtools")
devtools::install_github("https://github.com/bmdavid2/DispenseFormulatrix")

Using DispenseFormulatrix

mantis_dispense function

mantis_dispense converts an experiment design into a MANTIS dispense list file.

mantis_dispense(design,"name",platetype="breakaway_pcr_96")

Arguments

• design: A dataframe where each column is a reagent and each row is a run. Each entry is the dispense volume in $\mu L$. Two additional columns "Row" and "Col" are required to specify the well for each run. For example Row="A" and Col=1 indicates that the run goes in well "A1". You can use the assign_wells function to automatically add "Row" and "Col" to the design Dataframe.

• name: Name of the experiment for the output file.

Optional Arguments

• platetype Specifies the type of plate for the experiment. allowed plates are:
  • "96-well": A standard 96 well plate
  • "384-well": A standard 394 well plate
  • "breakaway_pcr_96": A breakaway 96 well PCR plate (Secured to Mantis by placing it in a standard 96 well plate)

Output

• name.dl.txt dispense list file to the current working directory

Example Code

```R # Create an example experimental design with 96 runs and 3 factors test_design <- data.frame(A=matrix(0,96,1)) test_design$A <- rep(1,96) test_design$B <- rep(1,96) test_design$C <- rep(1,96) test_design$A[1:9] <- c(1:9) test_design$B[25:33] <- c(1:9)

assign the wells in order

test_design <- assign_wells(test_design,randomize=F)

Create a dispense list using test_design

mantis_dispense(test_design,"test1",platetype = "breakaway_pcr_96")

test1.dl.txt will be written to the current directory

## `assign_wells` function 

Use `assign_wells` to add the "Row" and "Col" columns to an experimental design dataframe. 

```R 
assign_wells(design,randomize=F)

Arguments

• design: A dataframe where each column is a reagent and each row is a run. Each entry is the dispense volume in $\mu L$.

• randomize: A Boolean variable. Experiments can either be placed in order or placed randomly on the plate.

Output

• a design dataframe that includes the well location information.

Using Designs Generated by the rsm Package

The rsm package provides tools to create coded experimental designs. Here we provide a framework to automatically process these designs into dispense lists. This can save a lot of time in excel formatting spreadsheets.

The following code generates a central composite design with four factors (A, B, C, D). Each factor has 5 coded levels (-2,-1,0,+1,+2)

library(rsm)
design <- ccd(Y~A+B+C+D,
              n0=c(3,0),
              randomize=FALSE,
              oneblock=TRUE,
              alpha='rotatable')

Using the assign_wells function, we can assign each experiment a well on the plate

design <- assign_wells(design)

This coded design needs to be processed into a volume based design in order to create a dispense list. We can use the process_design function to peform the conversion. First, we need to supply process_design with some additional information:

1) reagent_names: The process_design function needs to know which of the four factors should be included in the dispense lists. Perhaps factor D is a time based variable, so we only need to include factors A, B, and C in the liquid handler's dispense list.

reagent_names <- c("A", "B", "C")

2) volume_levels : For each of the relevant factors, we need to provide a mapping between the coded level and the volume that the coded level represents. We use a list of vectors to create the mapping. Each entry in the list corresponds to one of the factors, and each vector entry is a level. In this example, our list will contain 3 vectors of 5 elements.

volume_levels <- list(
    c(1,1,1,1,1), # Factor A. Notice it has the same volume for each level. 
    c(1,2,3,4,5), # Factor B
    c(2,4,6,8,10)) # Factor C 

3) separate_stocks: Sometimes, the difference between levels of a factor isn't a volume but rather a reagent concentration. In our Example, factor A might be the concentration of an enzyme in a reaction. It may be easier to create separate reagent stocks for each concentration in order to preserve the total reaction volume or achieve a wider range of concentrations. We can inform process_design that these particular factors are in reality separate reagents using a boolean vector.

separate_stocks <- c(T,F,F) 

4) dispense_group: Some experiemnts may have multiple steps, where certain reagents should be dispensed in one step, while others may occur later in the process. We can inform process_design that we would like our dispense lists to be broken up into multiple stages (i.e. 1,2,3)

dispense_group <- c(1,1,2) # Factor C is dispensed in a later step

We can now run the process_design function using this information.

new_design <- process_design(design, reagent_names, volume_levels, separate_stocks,dispense_group) 

This new design includes two dispense list stages, one for each dispense group. We can use multi_dispense to create the final dispense list files.

mulit_dispense(new_design, "./name",platetype="breakaway_pcr_96)

This function works just like mantis_dispense, except that it outputs multiple dispense list files, named "name_x.dl.txt", with x being the dispense group number.

Normalizing DNA Concentrations with Mantis

The mantis_normalize function allows one to normalize the concentration of DNA solutions with water using Mantis.

mantis_normalize requires the following information in the form of a .csv file. We provide a template for users:

| sampleID | concentration (ng/uL) | volume (uL) | final_concentration (ng/uL or nM) | amplicon_length (bp) | Row | Col | | -------- | ------- | --------| ------| --------| -------- | --------- | | sample_1 | 50 | 50 | 30 | 127 | A | 1 | sample_2 | 38 | 50 | 30 | 149 | A | 2

...

Call mantis_normalize as follows:

out -> mantis_normalize(filepath,
platetype="breakaway_pcr_96",
maxvol=200,
usenanomolar=FALSE 
)

mantis_normalize writes a mantis dispense list and returns a dataframe with information about the feasibility of normalizing. Some samples will be either too concentrated or too dilute to normalize in the given maximum volume. The user receives a warning if some of the samples cannot be normalized. These samples are discarded from the dispense list but remain in the output dataframe

Arguments

• filepath: path to the .csv file with sample information
• platetype: type of plate Mantis will be dispensing water into
• maxvol: Maximum well volume allowed. Dilutions that would exceed the volume are not performed
• usenanomolar: Standard output concentration is ng/uL. User may use nM as an output, which is based on the amplicon lengths provided. ex 40 fmol/uL = 40 nM

bmdavid2/DispenseFormulatrix documentation built on Feb. 8, 2025, 5:24 p.m.