MAP automates data processing and analysis for high-throughput and manual microdilution assays, efficiently calculating Minimum Inhibitory Concentration (MIC), Half-Maximal Hemolytic Concentration (HC50), and Half-Maximal Cytotoxic Concentration (CC50), and generating comprehensive experimental reports.
- Microdilution Assay Processor (MAP)
- Installation
- Dependencies
- Data Structure
- Input
- Assay Analysis
- Usage
- Example Command
To clone the MAP repository, use the following command:
git clone https://github.com/bcgsc/MAP.git
cd MAP
First, create a new Conda environment:
conda create --name map python=3.10
conda activate map
Once the environment is activated, install MAP using the following command at the root directory.:
pip install .
map --version
To ensure MAP works as intended, run the test files as follows:
chmod +x run_tests.sh
./run_tests.sh
The test results will be saved in the tests/test_results
directory. Compare the contents of this directory with the expected results in the tests/expected_results
directory to verify that MAP worked as expected.
MAP requires the following dependencies that are installed during installation:
- python 3.10+
- pandas
- numpy
- progress
- openpyxl
- xlsxwriter
MAP organizes its data using a hierarchical dictionary structure. This structure supports scalability and flexibility, allowing easy addition of plates, wells, or assay types. It reduces redundancy, speeds up data retrieval, and clearly defines relationships for analysis.
For more information about MAP implementation details, check out our wiki.
MAP requires two main input files in Excel format: raw data and matrix. Ensure your input files match the provided requirements. For reference templates, please check the template
directory.
For both manual and high-throughput assays, the Excel file must contain plate read data in the form of 96-well plates, where:
- 96-well plates must have column headers (1-12) and row identifiers (A-H).
In high-throughput assays, concentration changes across plates are expected:
- The first plate in the raw data should have the highest concentration, and the last plate should have the lowest concentration.
- For assays with technical replicates, the replicate groups should appear sequentially. Within each group, plates should be ordered from highest to lowest concentration.
In manual assays, concentration changes across rows where the concentration decrease from left to right in each row.
A single sheet with the following columns:
- well: Specifies the well location (e.g., A1, B12).
- synth_id: The synthesis identifier for the compound in the well.
- amc: The antimicrobial compound name or treatment name.
A single sheet with the following columns:
- well: Specifies the well range in a horizontal or vertical array of wells:
- In horizontal ranges, the row identifier remains unchanged and only the column header changes (e.g., A1-A12).
- In vertical ranges, the column header remains unchanged and only the row identifier changes (e.g., A12-H12).
- synth_id: The synthesis identifier for the compound in the well.
- amc: The antimicrobial compound name or treatment name.
Detailed methodologies for calculating MIC, CC50, and HC50 can be found in the methods
directory.
usage: map [-h] [--version] -a {ast,hc50,cc50} -o {manual,hts} [-p PREFIX] -d RAW_DATA -m MATRIX [-r NUM_TECH_REP] -s START_CON -f
FINAL_CON [-t THRESHOLD] [-e OUTPUT_DIR]
MAP: Microdilution Assay Processor
options:
-h, --help show this help message and exit
--version show program's version number and exit
-a {ast,hc50,cc50}, --assay {ast,hc50,cc50}
Assay type: antimicrobial susceptibility testing (ast), hemolysis assay (hc50), or AlamarBlue assay (cc50)
-o {manual,hts}, --operation_mode {manual,hts}
Operation mode: manual or high-throughput
-p PREFIX, --prefix PREFIX
Prefix for the output Excel file
-d RAW_DATA, --raw_data RAW_DATA
Excel file containing the raw plate reader data in format of 96-well plates
-m MATRIX, --matrix MATRIX
Excel file containing the matrix map, specifying the treatment name (amc) and ID (Synth ID)
-r NUM_TECH_REP, --num_tech_rep NUM_TECH_REP
Number of technical replicates used in high-throughput assay
-s START_CON, --start_con START_CON
Starting concentration (highest concentration) of the assay
-f FINAL_CON, --final_con FINAL_CON
Final concentration (lowest concentration) of the assay
-t THRESHOLD, --threshold THRESHOLD
Absorbance threshold for determination of minimum inhibitory concentration (Default = 0.4999)
-e OUTPUT_DIR, --output_dir OUTPUT_DIR
Directory for the output Excel file
map -a ast -o hts -p E.coli_ATCC_25922_Hts -d path/to/data.xlsx -m path/to/matrix.xlsx -r 2 -s 128 -f 1 -t 0.49 -e path/to/output
This command runs the MAP with the following options:
- -a ast: Specifies the assay type as Antimicrobial Susceptibility Testing (AST).
- -o hts: Sets the operation mode to high-throughput .
- -p E.coli_ATCC_25922_Hts: Prefixes the output file with "E.coli_ATCC_25922_Hts".
- -d path/to/data.xlsx: Path to the raw data Excel file.
- -m path/to/matrix.xlsx: Path to the matrix Excel file.
- -r 2: Number of technical replicates.
- -s 128: Starting concentration.
- -f 1: Final concentration.
- -t 0.4999: Absorbance threshold.
- -e path/to/output: Directory for the output Excel file.