TitrationAnalysis

A tool for high throughput binding kinetics data analysis

Notes

Compatibility with Mathematica versions above 13.1

The user needs to manually engage with PDF file generation when using the package on Mathematica 13.3 and above, due to changes in how the software handles dynamic updating. The page break needs to be calculated for a prolonged period of time and the users are prompted to confirm that they are waiting for the page break calculation to finish at least once during the process and they need to manually click a button to proceed.

Update 2025-05-22: Please execute this line of code before running the TitrationAnalysis command: "SetOptions[$FrontEnd, "DynamicEvaluationTimeout" -> 10000]". This will prolong the timeout for dynamic updating and prevent the prompt from the showing up.

The script as it stands will not will for Mathematica 14.1. This is due to changes in the grammar of non-linear fitting module. A Mathematica 14.1 compatible version will be uploaded here in the near future.

Overview

This repository contains the necessary files to install and execute the first version of TitrationAnalysis package (TitrationAnalysis v1.0).

Please cite the repository as the following: Li, Kan, & Dennison, S Moses. (2023). TitrationAnalysis tool (v1.0.0). Zenodo. https://doi.org/10.5281/zenodo.7998652

Alternatively, please cite: Li K, Huntwork RHC, Horn GQ et al. TitrationAnalysis: a tool for high throughput binding kinetics data analysis for multiple label-free platforms [version 1; peer review: awaiting peer review]. Gates Open Res 2023, 7:107 (https://doi.org/10.12688/gatesopenres.14743.1)

Description

The TitrationAnalysis tool is intended for the high-throughput analysis of binding kinetics data collected on multiple platforms. Currently, the TitrationAnalysis tool supports the analysis of data exported from Carterra LSA (SPRi), Biacore T200 (SPR) and ForteBio Octet Red384 (BLI).

The TitrationAnalysis tool is currently built as a Mathematica^:tm: package. The package was built on Mathematica 12.0 and adapted for Mathematica 13.0. After the package installation, most of the user interactions will be guided by pop-up windows within Mathematica.

Getting Started

Installation

Open the package file (with extension “.m”) in Mathematica^:tm:. Go to File → Install, and install the package as shown in the image below and click “OK”. For Mathematica 13.0 and above, please use the corresponding version contained in this repository. Some of the later updates in Mathematica 12th version, such as Mathematica 12.3, might require package adapted for Mathematica 13.0 as well.

Note 1: For successful installation, please open the package file first in Mathematica and then select the opened package file as “source” during installation. Although the package file can be selected through pop-up file explorer window without first opening the package in Mathematica first, the installation by this method was found not always successful.

Note 2: The version number the package file name ends in refers to the version of Mathematica the corresponding code is suitable for. For example, the package file with name ending in “V12” is suitable to be used in Mathematica V12.0 or similar versions.

Execution

Data Pre-processing

Typically, the user is expected to carry out data reference subtraction, zero analyte concentration cycle (blank cycle) subtraction and data smoothing using the commercial software paired with the data collection platform before exporting the pre-processed data for use in TitrationAnalysis.

Basic command

The command Get["KineticsToolkit`"] can be used to call the package. Then the module corresponding to one of the platforms can be called, as shown in the image below.

Upon executing the command for the desired module, the user will be asked to select the sample information sheet, as shown in the image blow. Click “Open” after selecting. The package will check if there is any necessary correction to be made in the information sheet. If all information appears to be correct, the module will proceed to the next step.

Example files

The example files are provided for each of the platform in the following directories: Example Files – Carterra, Example Files – T200 and Example Files – BLI.

Carterra Example Input Files

Sample Information Sheet: Example Data Info Sheet - Carterra.xlsx

Sample Exported Data: Example Exported Data - Carterra.xlsx (Currently in a multi-part zipped file due to the large file size, please use applications such as 7-zip to re-combine the zipped file and extract the excel file inside)

Carterra Example Output Files

Sample Fitted Sensorgrams Report: Titration AnalysisCarterraSensorgram_Example.pdf

Sample Kinetics Estimates Report: Titration AnalysisCarterraReport_Example.csv

T200 Example Input Files

Sample Information Sheet: Example T200 Data Info Sheet.xlsx

Sample Exported Data: Example T200 Chip 1 Channel 2.txt

T200 Example Output Files

Sample Fitted Sensorgrams Report: Titration AnalysisT200Sensorgram_Example.pdf

Sample Kinetics Estimates Report: Titration AnalysisT200Report_Example.csv

BLI Example Input Files

Sample Information Sheet: Example Data Info Sheet - BLI.xlsx

Sample Exported Data: BLI Example Tray 1 (Folder containing multiple text files, currently contained in a zipped file, please extract the folder inside)

BLI Example Output Files

Sample Fitted Sensorgrams Report: Titration AnalysisBLISensorgram_Example.pdf

Sample Kinetics Estimates Report: Titration AnalysisBLIReport_Example.csv

Running analysis for Carterra platform

After choosing the sample information sheet, the user will be asked to either keep ordering samples based on the information sheet or order the sample sequentially from A1 to H12 (96 well plate positions), as shown in the image below. Usually information sheet sorting is desired.

Then the user will be asked to select a file containing the exported Carterra data, as shown in the image below. Note that the content of the exported data needs to match what is indicated in the info sheet. Otherwise the module will not proceed.

After making a few more selections for global analysis settings, the module will proceed to automatically analyze each sensorgram and generate output files. For the example file, please use default selections for all settings.

Running analysis for T200 platform

After choosing the sample information sheet, the user will be asked to type in the prefix for all the chip – channel combinations. The prefix for the example data set is shown in the image below (Please type exactly as the image shows to match the example input file). The module will attempt to read in the data based on this prefix to find all the chip – channel combinations indicated in the information sheet. Note that the content of the exported data needs to match what is indicated in the info sheet. Otherwise the module will not proceed.

Then the user will be asked to provide the data collection frequency for appropriate data thinning. If “10Hz” is chosen, then only one data point per second will be chosen for further analysis. If “1Hz” is chosen, then no data thinning will occur.

After making a few more selections for global analysis settings, the module will proceed to automatically analyze each sensorgram and generate output files. For the example file, please use default selections for all settings. As shown in the example information sheet, for the same sensorgram, multiple fitting optimizations can be included in the information sheet and implemented during analysis.

Running analysis for BLI platform

After choosing the sample information sheet, the user will be asked to type in the prefix for all the tray – sensor combinations. The prefix for the example data set is shown in the image below (Please type exactly as the image shows to match the example input file). The module will attempt to read in the data based on this prefix to find all the tray – sensor combinations indicated in the information sheet. Note that the content of the exported data needs to match what is indicated in the info sheet. Otherwise the module will not proceed.

Then the user will be asked to provide the data collection frequency for appropriate data thinning. If “5Hz” is chosen, then only one data point per second will be chosen for further analysis. If “1Hz” is chosen, then no data thinning will occur.

After making a few more selections for global analysis settings, the module will proceed to automatically analyze each sensorgram and generate output files. For the example file, please use default selections for all settings. As shown in the example information sheet, for the same sensorgram, multiple fitting optimizations can be included in the information sheet and implemented during analysis.

Stopping analysis

If the analysis needs to be stopped for any reason, go to Evaluation → Abort Evaluation to stop code execution.

Version history

Version 1.0: initial release

Help

If you need help or have suggestions, feel free to contact Kan Li via email at kl122@duke.edu. You may also communicate through GitHub Discussions.

Author

Code was developed by Kan Li (kl122@duke.edu). Other contributors to code development include Georgia D. Tomaras, Gillian Q. Horn and S. Moses Dennison (moses.sekaran@duke.edu).

License

This project is licensed under the CC-BY-4.0 license. Please see LICENSE.md file for details.