TITLE: MicroMPN: Software for Automating Most Probable Number Estimates from Laboratory Microplates
AUTHORS: Adam R Rivers, Karla Franco Meléndez

[DESCRIPTION]
We developed a command-line Python package named "MicroMPN" to enable the automation of most probable number (MPN) value estimations from microplates of different formats and sample designs. In this protocol, we guide users on how to run MicroMPN from a Jupyter Notebook using simulated fluorescence data values. To run MicroMPN, the users must input two data files. Input file 1: the user provides a CSV file with the plate name, the well locations of each sample in a microplate, and the spectrofluorometric data. Input file 2: the user specifies the layout of a microplate with a Wellmap TOML-based format file. The second file contains the number of replicates, the dilution series, and the number of samples per plate. The Python package “wellmap” parses the information of a microplate from the TOML formatted file for downstream calculation of an MPN value. Additionally, users must specify a cutoff/threshold value, which is used to determine which wells are positive or negative for microbial growth. Output file: MicroMPN will calculate an MPN value, a bias-corrected MPN value, 95% confidence intervals, and a rarity index.

[BEFORE_START]
In this protocol we cover how to run MicroMPN from a Jupyter Notebook.


However, users that choose to run the package from a terminal can access MicroMPN through:


Github:

git clone git@github.com:USDA-ARS-GBRU/micrompn.git
cd micrompn
pip install .


PyPI:

pip install micrompn

docker:

docker pull ghcr.io/usda-ars-gbru/micrompn:main



[GUIDELINES]
The most probable number (MPN) assay is a culture-dependent method of quantification most commonly used to enumerate microbes from environmental samples 1. In the MPN assay, the density of viable microbes is determined by serially diluting to extinction in a culture medium. An MPN count (MPN/mL or MPN/g) is therefore based on the presence or absence of a measurable signal, such as media turbidity 2, color change 3,4, and luminescence 5-10. MPN calculations require two fixed quantities: sample volume and number of replicates at each dilution step. Calculations of an MPN value are based on probability theory and not on an absolute count  11. A Poisson distribution is used to evaluate the likelihood of microbes being transferred (or not) in a dilution step, based on the inoculum concentration. Given the probability of a transfer occurring, a binomial distribution is then used to evaluate the likelihood of observing a specific number of positive replicates in a dilution step 11. The initial concentration that maximizes the combined likelihood of all dilution steps is the most probable number of microbes in the sample. 

A portion of the code used in MicroMPN was derived from the “MPN” R package created by Ferguson and Ihrie (2019) 16. 

As an alternative to our command-line tool, there are web-based MPN calculators where users manually input their values. One is the Environmental Protection Agency MPN calculator (https://mostprobablenumbercalculator.epa.gov/mpnForm). Another is MPNCalc v1.2.0 (https://mpncalc.galaxytrakr.org/) created by M. Ferguson and J. Ihrie at the Food and Drug Administration. 

Additionally, users can use the R package "MPN" (written by the same authors that created MPNCalc), whose code we transpiled to Python to run MicroMPN from the terminal. 

[STEPS]
SECTION: Example of Input file 1: namefile.csv
1. To run MicroMPN, users need an input CSV file with RFU data.

The column headers must include the following identifiers:
plate_unique
plate_well
rfu

*Additional column names in the input file will be ignored by MicroMPN.

As an example of a CSV file with relative fluorescence units (RFU) data, we provide users with  . The input file provided contains RFU data in a 12 (dilution series) by 8 (replicates) microplate layout. In this microplate, column 1 has 8 replicates of resuspended soil sample. Columns 2 - 12, contain 10-fold serially diluted samples. Values correspond to spectrofluorometric measurements collected 48 h after incubating the plate.  


 
SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3. Step-by-step example on how to run the command-line tool MicroMPN from a Jupyter Notebook.

* To run micrompn from a Jupyter Notebook use the symbol "!" before micrompn; micrompn was designed to run from the command-line not from a Jupyter Notebook.

* For ease of documentation and a user-friendly interface, we used Jupyter Notebooks for MPN calculations. For more information on Jupyter Notebooks users are referred to (Jupyter Project Documentation).

*For information on how to install packages in a Jupyter Notebook visit Installing Python Packages from a Jupyter Notebook.
SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.1. Outside of a notebook, clone or download the MicroMPN repository from GitHub (https://github.com/USDA-ARS-GBRU/micrompn).  Extract files locally.

  

SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.2. Launch a Jupyter Notebook from the Jupyter terminal or directly from the Anaconda Navigator. 

Once it launches, your project directory will be displayed in your browser. Make sure the data files needed to run MicroMPN are in your project directory. Then create a new Python notebook in the same directory were all your files are located.
SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.3. # In a Jupyter Notebook code cell, install MicroMPN by running the following line of code:

! pip install C:\Users\location_of_extracted_files\micrompn-main\micrompn-main

* In our case, "! pip install" worked because both the shell terminal and kernel are using the same python executable. However, this is not always the case. This is explained in detail in Installing Python Packages from a Jupyter Notebook. 

# Ignore this command when re-using the notebook.

SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.5. # In a new code cell, import "micrompn" into the notebook. 

import micrompn

# Check proper installation by running:
! micrompn --help

# If installation was successful, user should see the following output:
 
SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.8. Example of output file  .

 
ABCDEFGHplatesamplempnmpn_adjupperlowerrarity0plate_33764678568859351831757831921970.63574
 

SECTION: Example of Input file 2: namefile.toml (namefile.txt)
2. To run MicroMPN, users need a second input file which specifies the layout of samples across a microplate. A Wellmap file can be created using a text editor (e.g., notepad). The format of the file is TOML-based.

[col]
 1.dilution = 1e00
 2.dilution = 1e-01
 3.dilution = 1e-02
 4.dilution = 1e-03
 5.dilution = 1e-04
 6.dilution = 1e-05
 7.dilution = 1e-06
 8.dilution = 1e-07
 9.dilution = 1e-08
 10.dilution = 1e-09
 11.dilution = 1e-10
 12.dilution = 1e-11

[row]
 A.replicate = 1
 B.replicate = 2
 C.replicate = 3
 D.replicate = 4
 E.replicate = 5
 F.replicate = 6
 G.replicate = 7
 H.replicate = 8

[block.12x8.‘A1’]
 sample = 1


In this .toml file   , each row (A – H) was assigned a replicate value (1 – 8), while each column (1 – 12) represented a particular dilution factor (1e00 – 1e-11). For this reason, each plate was divided into a single 12x8 sample block, although multiple sample blocks on a plate are possible. A .toml file can be opened with a text editor (e.g., notepad).


SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.6. # To visualize the .toml or .txt file, run the following commands to first install "wellmap" and then import "wellmap" into the notebook:

! pip install wellmap #Ignore this command when re-using the notebook.

import wellmap

wellmap.show( )

  
SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.4. # Alternatively, users can install MicroMPN with the following lines of code:

import sys
print(sys.executable)

# Copy the output from "sys.executable", which should be the path to the Python executable active in the kernel.

# In a new code cell, run:
! {sys.executable output} -m pip install C:\Users\location_of_extracted_files\micrompn-main\micrompn-main
SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.7. # In a new code cell, run "micrompn".
#  CSV file name: input_protocols_io.csv
# TOML file name: microplate.toml (it could also be a .txt file)


*Make sure the .csv and .toml files are located in the same directory as your Jupyter Notebook (nameofnotebook.ipynb).


# run the following code in a single line
! micrompn --wellmap microplate.toml --data "C:\location\of\CSV\file\input_protocols_io.csv" 
--cutoff 6 
--outfile "C:\location\of\CSV\output\file\output_protocols_io.csv" 
--plate_name "plate_unique" 
--value_name "rfu"
 --well_name "plate_well" 
--trim_positives
SECTION: Additional resources
4. We provide users with 96-wells and 384-wells microplate layouts, input files with mock RFU data, MicroMPN output files, and copies of our Jupyter Notebooks in html format. 



SECTION: Additional resources
4.1. Microplate layout:   

96-well plate
3 samples
4 replicates
8 vertical dilutions

input:   
output:   
html:   



SECTION: Additional resources
4.2. Microplate layout:   

96-well plate
2 samples
6 replicates
8 vertical dilutions

input:   
output:   


Microplate layout:   

96-well plate
2 samples
4 replicates
12 horizontal dilutions

input:   
output:   



html:   

SECTION: Additional resources
4.3. Microplate layout:   

384-well plate
4 samples
8 replicates
12 horizontal dilutions

input:   
output:   
html:   

SECTION: Additional resources
4.4. Microplate layout:   

384-well plate
6 samples
8 replicates
8 vertical dilutions

input:   
output:   
html: