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

[DESCRIPTION]
The most probable number assay is a commonly used method for estimating the concentration of viable microbes, such as bacteria and fungi (1, 2) present in environmental samples, including soil (3 - 6), sediment (7 - 10), water (11-15), and food (1, 16, 17).  An MPN count is based on the presence or absence of a measurable signal, such as media turbidity, relative fluorescence units or luminescence. MPN calculations require two components: the volumes of a sample used at each dilution step and the number of replicates per dilution. Results from consecutive dilutions are used to calculate the total cell density in the original sample. Although the MPN assay was originally designed to be run using culture tubes, it was later adapted to microplates to simplify data collection (18) and enable high-throughput screenings of samples (19). We developed a user-friendly command-line python package named "MicroMPN" to enable automation of MPN value estimations from microplates. Users can calculate an MPN estimate from microplates of different formats, arbitrary dilution factors, from samples spread across multiple plates or within the same plate. Users must input two data files for MicroMPN to work. Additionally, users must specify a cutoff/threshold value above which wells from a microplate are considered positive for growth of a microbial target. Input file 1: user specifies the layout of a microplate with a TOML-based format file. This file contains the number of replicates, dilution series, and the number of samples per plate. The python package “wellmap” (20) parses the information of a microplate from the TOML file for downstream calculation of an MPN value. Input file 2: user provides a CSV file with plate name, the well location in a microplate, and the spectrofluorometric data. Output file: MicroMPN will calculate an MPN value (21), a bias corrected MPN value (22), 95% confidence intervals (21), and a rarity index (23, 24). The calculation of MPN is modeled on code in the “MPN” R package created by Ferguson and Ihrie (2019).







[BEFORE_START]
Github repository:
https://github.com/USDA-ARS-GBRU/micrompn.git

Installation of "micrompn" via command line:

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

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

[GUIDELINES]

As an alternative to command line, there are web-based MPN calculators.  One is the Environmental Protection Agency MPN calculator (https://mostprobablenumbercalculator.epa.gov/mpnForm).  Another is MPNCalc created by M. Ferguson and J. Ihrie (galaxytrakr.org)https://mpncalc.galaxytrakr.org/).  We do not cover their usage in this protocol.  

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

[STEPS]
SECTION: Example of Input file 1: namefile.csv
1. Example of CSV file with relative fluorescence units (RFU) data  . In this example, a microplate contains 8 replicates by 11 10-fold serial dilutions. 

Column names:
plate_unique
plate_well
rfu


  

SECTION: Example of Input file 2: namefile.toml
2. 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.

  

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 or python shell.

* 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 jupyter notebook visit Installing Python Packages from a Jupyter Notebook.
SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.1. Download MicroMPN zipped files from the GitHub repo. 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.
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.

# 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.4. # In a new code cell, proceed to import micrompn. 
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.5. # To visualize the .toml file, run the following command:
wellmap.show("microplate.toml")

*Make sure the .toml file is located in the same directory as your jupyter notebook (nameofnotebook.ipynb).

# If for some reason this does not work, then install  the package "wellmap" before running the command wellmap.show()

! pip install wellmap
import wellmap


SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.6. # In a new code cell, run micrompn.
# CSV file name: protocols_io_RFU_example.csv
# TOML file name: microplate.toml

*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\protocols_io_RFU_example.csv" --cutoff 6 
--outfile "C:\location\of\CSV\output\file\OUTFILE_protocols_io_RFU_example.csv" 
--plate_name "plate_unique" 
--value_name "rfu"
 --well_name "plate_well" 
--trim_positives
SECTION: Example of how to run MicroMPN from a Jupyter Notebook
3.7. Example of output file  .

 
ABCDEFGHplatesamplempnmpn_adjupperlowerrarity0plate_33764678568859351831757831921970.63574